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 repository files or metadata), set `vcs_type` to `"none"`. 5. If detection commands fail due to errors, missing tool executables (e.g. `git` not found), or other unhandled exceptions during checks, set `vcs_type` to `"unknown"`. 3. **PIN IMMUTABLE SNAPSHOT (only after sync; `--sync` only).** Materialize an immutable per-pass copy and compute its identity: PIN SNAPSHOT (after SYNC, before any stage): 0. CRASH-RESUME (run FIRST, before any copy/detect): if `state.active_snapshot.pass == N` on entry, REUSE that dir (no re-copy/re-pin). This reuse check is SAME-PASS ONLY — it does NOT cover cross-pass staleness (where Stage 15 preserved `active_snapshot` while incrementing `pass_number`). Consumer stages must apply the current-pass check (`active_snapshot.pass == state.pass_number`) described in `mantis-pipeline-adapter` Scenario 2. If `snapshot_pinned` was true but the dir is now missing -> STOP and yield to the user (never re-pin to a possibly-drifted live tree). If reusing, skip steps 1–4 and go straight to step 5 (state write; the `snapshot_history` append inside Step 5 is itself idempotent — see Step 5). 1. Detect vcs_info (existing meta-agent detection). VCS_ID = commit_hash (git/hg) / manifest revision (multi-vcs) / "" (else). 2. FREE-SPACE PRECHECK: if a full copy is needed, compare `du -s` of the live tree to `df` free space at state_root. If it will not fit -> skip copy, go to step 5b (unpinned/HALT). Never crash mid-copy on ENOSPC. 3. Choose SNAPSHOT_ROOT and materialize (tiered): - Clean git -> `git worktree add --detach <SNAPSHOT_ROOT>`; clean hg