Mantis Reproduce

Reproducer (/mantis-reproduce)

System Goal

Integration Test Engineer. Designs crash reproducers or inputs and executes them inside isolated sandbox environments to empirically verify bugs.

Command Definition

• Command: /mantis-reproduce [--reattack] [--finding_id=<uuid>] [--force] [--target_root=<path>] [--state_root=<path>] [--snapshot_root=<path>] [--snapshot_id=<SNAPSHOT_ID>] [--snapshot_pinned=<true|false>]
• Description: Generates and runs crash reproducers to verify security flaws.
• Parameters:
• --reattack: When executing as part of patch verification to isolate re-attack outcomes.
• --finding_id: The specific finding UUID to reproduce. Must be provided and is required when --reattack is specified.
• --force: Override/bypass eligibility checks for targeted normal runs.
• --target_root: Path to the root of the target codebase under test (defaults to .). AUTHORITATIVE when supplied — overrides --snapshot_root (Block A step 1a); the sentinel check is skipped for this tree (e.g. a patched shadow during re-attack verification).
• --state_root: Path to the root of the Mantis state directory containing workspace/ (defaults to .).
• --snapshot_root: Root of the pinned immutable code snapshot for this pass. Consumed by Block A (Step 0) when --target_root is not supplied.
• --snapshot_id: The SNAPSHOT_ID string of the pinned snapshot, consumed by Block A (sentinel) and Block B (snapshot match check) in Step 0.
• --snapshot_pinned: When false (set by mantis-patch during re-attack on a patched shadow), the reproduce sub-agent MUST skip the snapshot sentinel/match check for this invocation — the --target_root tree is authoritative and sentinel-exempt (Block A step 1a).

Input/Output Contract

• Reads:
• state_root/workspace/findings/ (viable/conditional findings).
• target_root/ (Repository source files to analyze trigger paths).
• state_root/workspace/archive/.repro_attempts.json.
• state_root/workspace/.mantis_state.json (to track current loop pass).
• Writes:
• PoC reproduction files (e.g. poc_[uuid].py or crash_[uuid].payload inside state_root/workspace/reproducers/).
• If run normally: updates findings in-place under state_root/workspace/findings/ (sets "repro_status", "repro_file_path", "run_command", "repro_output", and appends history). Updates status to "VALID" if provisionally valid.
• If run with --reattack: updates findings in-place under state_root/workspace/findings/ (sets "reattack_status", "reattack_file_path", "reattack_run_command", "reattack_output", "reattack_variants", and appends history with stage "reattack"). Does not modify "repro_*" fields or "status". Exception: may atomically downgrade patch_status per INV-1 in Step 6 (never persist VERIFIED_SECURE alongside a non-failed_to_bypass reattack_status).
• Updates state_root/workspace/archive/.repro_attempts.json atomically.
• Stamps "repro_snapshot_id" / "reattack_snapshot_id" on updated findings and stores .repro_attempts.json values as {count,last_snapshot} objects (bare integers still read correctly).
• Preconditions:
• Findings must exist in state_root/workspace/findings/.
• Sandbox/container runtime environment must be available.
• Idempotency Guarantee:
• Updates findings in place. Uses state_root/workspace/archive/.repro_attempts.lock file locking and atomic temporary file swaps (os.replace on state_root/workspace/archive/.repro_attempts.json.tmp) to guarantee concurrency safety and retry stability.
• Snapshot-aware: regenerates the PoC when the finding's snapshot no longer matches; refuses to emit a negative verdict without reached-sink evidence. Re-attack verdicts on a snapshot mismatch are governed by the C5 unpatched-baseline re-run (Step 6), which supersedes the legacy blanket refusal — a failed_to_bypass verdict is only written after C5 has confirmed the unpatched baseline still triggers on the current snapshot.

Instructions

Step 0: Locator Resolution + Snapshot Match (run first)

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).

SNAPSHOT MATCH CHECK for finding F (decides MATCHED vs NOT_MATCHED):
1. If snapshot_pinned is false -> NOT_MATCHED. Stop.
2. Read F.discovery_commit:
   - missing OR empty OR the literal "MIXED" -> NOT_MATCHED.
   - not exactly equal to SNAPSHOT_ID          -> NOT_MATCHED.