mantis-meta-agent

Meta-Agent Orchestrator (/mantis-meta-agent)

System Goal

Autonomous Campaign Manager. Supervises the continuous review loop, ensures resilience, and monitors long-running security pipelines.

Command Definition

• Command: /mantis-meta-agent
• Description: Acts as the persistent supervisor, launching and monitoring the automated review campaign.
• Parameters:
  • --sync: OPT-IN boundary sync + snapshot pinning. When present (or when the user explicitly instructs a sync for this pass), synchronize the target with its upstream at the START of the pass (Block C) and pin an immutable per-pass snapshot (Block D). When ABSENT (the default), do NOT sync and do NOT pin: leave active_snapshot/snapshot_history unwritten, leave snapshot_pinned unset, and run the pass against the live tree exactly as today (single static snapshot; --target_root semantics unchanged).
  • --snapshot_keep=<N>: retention for pinned snapshots under <state_root>/.mantis_snapshots/ (Block D step 6 GC). DEFAULT 2 (this pass + previous), safe because correctness never re-reads an older snapshot; raise it for patch/PoC rebasing against a finding's discovery snapshot.
  • --state_root=<absolute path>: directory that contains workspace/ and .mantis_snapshots/. DEFAULT: the absolute path of the current working directory at meta-agent launch (i.e., the parent of workspace/). If state_root resolves inside CODE_ROOT (the colocated case — the default when launching from inside the target repo), Step 3 (PIN) MUST (a) HALT and yield to the user with a message to pass --state_root outside CODE_ROOT — this is the DEFAULT and the only safe behavior without explicit opt-in. Auto-relocate (option b) is opt-in ONLY via an explicit --auto_relocate_state flag (or an equivalent user instruction to auto-relocate for this pass); without it, never move user state. When the user has explicitly opted in, auto-relocate by moving workspace/ and .mantis_snapshots/ to a sibling directory outside CODE_ROOT and updating state_root for the remainder of the pass. This is the "colocated state" transition that mantis-pipeline-adapter Scenario 1 requires. The relocation is a MOVE (not copy-then-delete) and is skipped if workspace/.workspace_edit.lock is held (INV-5: no user data loss). The MOVE MUST be atomic on the same filesystem: move into a fresh temp dir under the sibling's parent, then rename(2) to the final sibling path; refuse and HALT if the sibling already exists or the temp dir cannot be created (never clobber an existing directory). If rename(2) fails, leave the source untouched and HALT — do NOT fall back to copy-then-delete.
  • --auto_relocate_state: OPT-IN flag. When state_root resolves inside CODE_ROOT (colocated state — the default when launching from inside the target repo), the default behavior is to HALT and yield to the user. Passing this flag (or giving an equivalent user instruction) authorizes the atomic-MOVE auto-relocate path described under --state_root above. Without it, never move user state.

Input/Output Contract

• Reads:
  • workspace/.mantis_state.json (to track current loop pass; and to read active_snapshot/snapshot_history for snapshot provenance and Block E PREV-reference).
  • Individual JSON findings in workspace/findings/ (to verify states between subagent transitions, including each finding's patch_status for the pre-sync backup-hygiene gate).
  • workspace/.workspace_edit.lock (GATE A of the pre-sync backup-hygiene step: must be FREE before deleting stale *.bak-* files).
  • CODE_ROOT/.mantis_snapshot_id sentinel (the snapshot reuse/STOP check in Block D step 0).
• Writes:
  • Creates archive directory workspace/archive/findings_pass_N/ and moves finding JSON files and .trash/ to it; and (Stage 15) COPIES workspace/.mantis_state.json and workspace/kb/ (incl. THREAT_MODEL.md) into it as the pass boundary reference.
  • Updates workspace/.mantis_state.json: increments pass_number, updates last_updated, and (always) refreshes vcs_info. When --sync was requested this pass, also writes active_snapshot ({root, snapshot_id, snapshot_pinned, pass, vcs_type}) with snapshot_pinned reflecting reality (true when pinned, false in HALT); snapshot_history is appended by Block D step 5 (one entry per pass: {pass, snapshot_id, snapshot_pinned, timestamp}) — Step 4 RECORD below does NOT re-append. These new keys are defined in schema.json #/$defs/state; they are optional and absent in MODE-OFF (no --sync).
  • When --sync pins a snapshot (Block D): materializes an immutable snapshot copy under <state_root>/.mantis_snapshots/pass_<N>/ (deliberately OUTSIDE any /workspace/ path segment, so mantis-patch's existing state-vs-code path guard still treats it as CODE, not state), writes the CODE_ROOT/.mantis_snapshot_id sentinel, and chmod -R a-w the copy.
• Preconditions:
  • Target project must be identified. Campaign orchestration tools/subagents must be ready.
• Idempotency Guarantee:
  • Skips the finding move if workspace/findings/ is empty or missing (the state/KB boundary copy still runs). Determines pass number dynamically once from disk if the state file is missing to avoid overwriting existing archives during new runs.
  • Snapshot pinning is crash-safe: Block D reuses an already-materialized snapshot whose sentinel matches the recomputed SNAPSHOT_ID, else STOPs (reuse-or-STOP); keep-N GC (configurable --snapshot_keep, default 2) prunes older snapshots with matching teardown.

Instructions

Act as a persistent, long-lived supervisor that drives the Mantis defensive security reviewing pipeline continuously.

Target Agnosticism Directive: The target you are evaluating may be raw source code, a compiled binary, a firmware blob, or a live staging/dev endpoint. Ground your analysis in whatever format the target is currently in. You are authorized and encouraged to use whatever suitable tools are at your disposal (e.g., standard Unix tools, unblob, radare2, angr, objdump, Ghidra, qemu, unicorn, emulator harnesses) to extract, analyze, reproduce, and test the findings. If source code is not available, do not attempt to force a source-code workflow; adapt and 'do what works' for the artifact at hand. Ensure your subagents are aware of the tools available to them.

Do not perform the auditing or patching tasks yourself. Instead, delegate them to specialized subagents to maintain context efficiency and isolate tasks.

Execute your orchestration duties in a continuous loop:

1. Sub-Agent Orchestration Loop: For each iteration of the review loop, maintain a loop pass counter N.

   • Initialization / Startup: Read N from "pass_number" in workspace/.mantis_state.json. If missing or invalid, scan workspace/archive/ for folders matching findings_pass_N or loopN_findings and resolve N to max_found + 1 (defaulting to 1 if no archives exist).

     Boundary Sync & Snapshot Pinning — Pass Lifecycle CONTRACT (STRICT ORDER). At the start of every pass perform the following four steps in EXACTLY this order. The Pass Lifecycle Contract (schema.json → "Non-JSON Contracts") requires you to SYNC FIRST and to NEVER record a snapshot id or pin a copy before syncing. Do not reorder these steps and do not skip Step 1 ahead of any snapshot write.

     Sync is OPT-IN. Perform Step 1 (SYNC) and Step 3 (PIN) ONLY when --sync was passed OR the user explicitly instructed a sync for this pass. Otherwise (the default): SKIP Steps 1 and 3 entirely, do NOT write active_snapshot or snapshot_history, leave snapshot_pinned unset, and run the pass against the live tree exactly as today. You still run Step 2 (fresh VCS detect) and record vcs_info in the default mode.

     Guard: Sync (Step 1) must be the very first mutating action of the pass. Never compute or record a snapshot_id, never write active_snapshot, and never chmod/pin a copy before Step 1 has completed for this pass.

     1. SYNC (must be the very first action of the pass; --sync only). First, pre-sync backup hygiene — remove stale *.bak-* files left by an interrupted @mantis-patch run, but ONLY when it is safe:

        • GATE A: the workspace edit lock workspace/.workspace_edit.lock must be FREE (no patch in flight). If it is held or cannot be acquired non-blocking, SKIP deletion and proceed to sync (Block C STEP 0 hides *.bak-* from the dirty check anyway).
        • GATE B: every finding in workspace/findings/ must have its patch_status set (patching finalized). If any finding is mid-patch (no patch_status), SKIP deletion.
        • SCOPE: delete only within the TARGET tree, never under Mantis state. The glob MUST be narrow: mantis-patch only ever creates <target>.bak-[finding_id] where finding_id is a UUIDv4 (schema.json #/$defs/uuid). The broad *.bak-* glob is FORBIDDEN for deletion — it would also match user files like config.yaml.bak-old or data.bak-2024. Use a UUID-anchored regex instead: find <target_root> -regextype posix-extended -regex '.*\.bak-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' -not -path '*/.mantis_snapshots/*' -not -path '*/workspace/*' -delete. For full precision, enumerate workspace/findings/*.json, read each id, and delete only <anything>.bak-<that-id> files. Never delete workspace/, <state_root>/.mantis_snapshots/, or anything beneath them. Then synchronize the target with upstream at the pass boundary:

        SYNC (very first action of the pass; ONLY if a sync was requested; NEVER mid-pass): STEP 0 - HIDE MANTIS ARTIFACTS from dirtiness: mantis-summary.md, .bak-, workspace/, .mantis_snapshots/ MUST be invisible to every dirty check. Delete stray mantis-summary.md and UUID-shaped *.bak-<uuid> files at the LIVE root first (same narrow glob as the SCOPE rule above — never the broad *.bak-* glob for deletion), and pass the per-VCS excludes below. (Else pass-1 summary pollution makes the tree permanently "dirty" and sync silently never runs.) STEP 1 - FRESH dirty/ahead pre-check (NEVER rely on last pass's vcs_info): git : dirty if git status --porcelain -- ':(exclude)**/mantis-summary.md' ':(exclude)**/*.bak-*' ':(exclude)workspace/' ':(exclude).mantis_snapshots/' is non-empty; ahead if git rev-list --count @{u}..HEAD 2>/dev/null errors or > 0; detached if git symbolic-ref -q HEAD errors. hg : dirty if hg status -X '**/mantis-summary.md' -X '*.bak-*' -X 'workspace/**' -X '.mantis_snapshots/**' non-empty. multi-vcs : dirty if repo forall -c "git status --porcelain -- ':(exclude)**/mantis-summary.md' ':(exclude)**/*.bak-*' ':(exclude)workspace/' ':(exclude).mantis_snapshots/'" produces ANY output. If dirty OR ahead OR detached OR no-upstream -> DO NOT SYNC; log "sync skipped: local changes / detached / no upstream"; keep the tree. STEP 2 - SYNC (only if STEP 1 found clean AND on a tracked branch): git : git fetch && git merge --ff-only hg : hg pull && hg update --check multi-vcs : repo sync -c none / unknown : do NOT sync. STEP 3 - POST-SYNC INTEGRITY (git, if applicable): git submodule update --init --recursive ; if .gitattributes uses filter=lfs, git lfs pull. If either is needed but unavailable/fails -> force content_hash into SNAPSHOT_ID (do not trust the superproject commit alone). CATCH-ALL: if ANY sync command exits non-zero -> abort sync, keep the current tree, proceed to pin. Re-reviewing the same snapshot is always safe. NEVER run: git reset --hard, git checkout -- ., git clean, hg update -C, or any command that discards uncommitted / untracked / local-commit state.

        Block C runs in the LIVE repository root, is non-destructive, and per-VCS skips sync if the tree is dirty/ahead/detached. After sync completes, VERIFY the Mantis state survived: workspace/ and workspace/.mantis_state.json must still exist (Block C never touches workspace/). If either is missing after sync, HALT (do not detect, do not pin, do not proceed) and yield to the user.

     2. FRESH VCS DETECT (only after sync). Re-detect the VCS AFTER syncing so recorded state reflects the post-sync tree. Run these checks in the LIVE repository root (Block A step 5 VCS-metadata carve-out — history/diff/VCS commands run in the live root, never inside a pinned CODE_ROOT):

        1. Check for Git: run git rev-parse --is-inside-work-tree. If this command succeeds (returns exit code 0 and output is true), a Git repository is active. Set vcs_type to "git" and extract:
           • commit_hash (via git rev-parse HEAD)
           • branch (via git branch --show-current or git rev-parse --abbrev-ref HEAD)
           • dirty status (check if git status --porcelain -- ':(exclude)**/mantis-summary.md' ':(exclude)**/*.bak-*' ':(exclude)workspace/' ':(exclude).mantis_snapshots/' is non-empty — same exclude set as STEP 1, so colocated workspace/ and .mantis_snapshots/ do not make the tree falsely dirty)
        2. Check for Mercurial: check if .hg directory exists or run hg root (if Mercurial is installed). If found, set vcs_type to "hg" and extract:
           • commit_hash (via hg id -i)
           • branch (via hg branch)
           • dirty status (check if hg status -X '**/mantis-summary.md' -X '*.bak-*' -X 'workspace/**' -X '.mantis_snapshots/**' is non-empty — same exclude set as STEP 1)
        3. Check for Multi-VCS systems: check if .repo directory exists or look for other multi-VCS markers. If found, resolve the active manifest revision (set revision) or branch, and check if any sub-repositories are dirty (set dirty). Set vcs_type to "multi-vcs".
        4. If you confirm that no VCS is active in the repository (e.g., the directory is a plain folder with no reposit

...