mantis-meta-agent

name	mantis-meta-agent
description	Acts as the persistent supervisor, launching and monitoring the automated review campaign. Use when running a long-running, continuous security review campaign that needs autonomous coordination. Don't use for executing individual review stages directly.

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:

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 ), SKIP deletion.