Mantis Patch

Patcher (/mantis-patch)

System Goal

Security Patching Expert. Generates minimal, correct code fixes, applies them to source code files, and verifies them inside isolated sandboxes before appending logs to long-term memory.

Command Definition

• Command: /mantis-patch [--target_root=<path>] [--state_root=<path>] [--snapshot_root=<path>] [--snapshot_id=<id>] [--snapshot_pinned=<true|false>]
• Description: Generates minimal security fixes using transactional isolation (shadow directories or file backups), applies patches, and verifies them.
• Parameters (all optional; absent ⇒ today's behavior):
• --target_root: Root of the code snapshot to read (CODE_ROOT). When the orchestrator pins a snapshot it passes --snapshot_root; --target_root is reserved for a caller that hands you an already-prepared tree.
• --snapshot_root: Root of the pinned immutable snapshot for this pass.
• --snapshot_id: The SNAPSHOT_ID string of the pinned snapshot (used by the Snapshot Match Check).
• --snapshot_pinned: true when a pinned immutable snapshot exists this pass; false/absent ⇒ degraded/legacy (see Backward-compat).
• --state_root: Root of the Mantis state directory that contains workspace/ (defaults to the current directory). ALL workspace/... paths in this file are STATE-RELATIVE and resolve under <state_root>/workspace/....

Input/Output Contract

• Reads:
• workspace/findings/ (reproduced finding JSON files where patch_status is not "VERIFIED_SECURE" or "MITIGATION_PROPOSED").
• workspace/.mantis_state.json (to track current loop pass).
• workspace/.mantis_state.json active_snapshot (root, snapshot_id, snapshot_pinned) — resolved via Block A; supplies CODE_ROOT and the SNAPSHOT_ID used by the Snapshot Match Check when no --snapshot_* flag is passed.
• Target source code files.
• Reproducer script path (repro_file_path) and command (run_command) from findings.
• Pre-existing backup files matching finding ID (if Option B is used).
• Writes:
• Source code modifications (applied transactionally and rolled back).
• Updates finding JSON files in-place (sets "patch_status", "patch_diff", re-attack details including "reattack_status" and "reattack_variants", and history).
• Appends to workspace/learnings.jsonl.
• Reusable helper script workspace/helpers/append_patch.py.
• Preconditions:
• Findings must exist in workspace/findings/.
• Idempotency Guarantee:
• Snapshot-aware skip: Skips a finding whose patch_status is already "VERIFIED_SECURE" or "MITIGATION_PROPOSED" ONLY when its recorded patch_base_snapshot equals the current SNAPSHOT_ID (i.e. it was verified against THIS snapshot). If patch_base_snapshot is absent, empty, or different from the current SNAPSHOT_ID, the terminal status is stale — do NOT skip; re-open and re-verify the finding against the current snapshot. In legacy mode (no active_snapshot and no --snapshot_* flags) skip exactly as today (by patch_status alone).
• Transactional isolation: modifies code inside uniquely generated temporary directories or creates temporary file backups (target.c.bak-[id]), restoring baseline state upon completion (using try...finally rollback mechanisms).
• Reuses the existing append_patch.py script once created.

Instructions

Fix successfully reproduced security flaws without breaking standard code behavior.

Execute the patching and verification stage as follows:

1. Snapshot & Locator Resolution (run once, before touching any code):

0a. Resolve CODE_ROOT, SNAPSHOT_ID, snapshot_pinned, and state_root via Block A (Locator Resolution):

   LOCATOR RESOLUTION (before reading ANY target code or artifact):
   0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
      you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
      state for provenance/annotation; NEVER stop merely because a code root is unset.
   1. Determine CODE_ROOT, in this priority order:
      a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
         It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
         (used when a caller hands you a prepared tree, e.g. a patched shadow).
      b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
      c. Else read state_root/workspace/.mantis_state.json (state_root from
         --state_root if passed, else ./workspace/... relative to the current dir)
         -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
      d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
         treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
   2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
      verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
      or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
      deliberately mutated and is sentinel-EXEMPT.)
   3. PATH FIELDS:
      - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
        that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
        containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
        NOT of the form <existing-path>:<integer> is a non-source LOCATOR
        (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
        line-range and line-existence logic.
      - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
        kb_references, repro_file_path, reattack_file_path, helper scripts, report
        files, and all state/findings JSON.
   4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
      compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
      (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
      cd into CODE_ROOT.
   5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
      run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
      (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
      lacks .git/.hg/.repo.
   6. Every shell command uses ABSOLUTE paths and sets its own working directory on
      that call. Do NOT assume the working directory persists between calls.

[!NOTE] CURRENT-PASS CHECK (defensive; the binding guarantee is on the harness per `mantis-pipeline-adapter` Scenario 2): if active_snapshot is present AND active_snapshot.pass != state.pass_number, treat the snapshot as STALE for this pass — STOP "stale active_snapshot: pass mismatch" or degrade as HALT (snapshot_pinned effectively false: no authoritative verdicts, Block B NOT_MATCHED, reproduce not_attempted). This catches a custom harness that preserved active_snapshot across the Stage 15 pass increment without re-pinning. The reference meta-agent re-pins every pass, so this check never fires there. Block B itself cannot detect this (it is snapshot_id-only, not pass-aware).

For this stage: mantis-patch READS target code (it is NOT a findings-only stage), so it runs Block A steps 1–6 in full. CODE_ROOT is the immutable pinned snapshot; you MUST NOT write, compile, or run reproducers under it (Block A step 4) — do all mutation in a private shadow (step 2 below).

0b. Determine PATCH_MODE (mechanical, using the resolved values):

• active_snapshot absent AND no --snapshot_root/--snapshot_id/ --target_root passed ⇒ LEGACY mode (today's behavior; the new ceilings in step 3 do NOT fire).