@iceinvein/agent-skills 0.22.0 → 0.23.0

package/skills/magpie/evals/quality/replay-full.ts

@@ -4,7 +4,8 @@
 // the labelled ones, and scores them. Spends real money: the whole review runs
 // again, capped by --max-cost-usd.
 
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { detectMissingTests } from '../../scripts/tests-check.ts'
@@ -15,6 +16,14 @@ import {
   readFindings,
   resolveCorpusRoot,
 } from './corpus.ts'
+import {
+  DEFAULT_JUDGE_MODEL,
+  judgeRecall,
+  loadMisses,
+  type RecallScore,
+  type RecallVerdict,
+  scoreRecall,
+} from './recall.ts'
 import { claudeFailureMessage, worktreeRemoveCommand } from './replay-critic.ts'
 import {
   formatRatio,
@@ -29,6 +38,117 @@ const SKILL_DIR = new URL('../..', import.meta.url).pathname.replace(/\/$/, '')
 const MAGPIE_BIN = join(SKILL_DIR, 'bin', 'magpie.ts')
 const DEFAULT_MAX_COST_USD = 10
 
+export type ReplayDiagnostics = {
+  log: Array<Record<string, unknown>>
+  shardManifest: unknown | null
+  findingsFiles: string[]
+  dedupedCount: number | null
+  criticDropped: unknown | null
+  evidenceDropped: unknown | null
+  thresholdDropped: unknown | null
+}
+
+async function readJsonIfPresent(path: string): Promise<unknown | null> {
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch (err) {
+    throw new Error(`${path} is not valid JSON: ${err instanceof Error ? err.message : err}`)
+  }
+}
+
+/** What the scratch run dir says about the session, read before the dir is deleted:
+ *  without it a thin result cannot be told apart as missed shards or critic drops.
+ *  The model writes most log lines by hand, so a line that is not a JSON object is
+ *  kept raw in its place rather than failing a replay that has already been paid for. */
+export async function replayDiagnostics(runDir: string): Promise<ReplayDiagnostics> {
+  const log: Array<Record<string, unknown>> = []
+  for (const [i, line] of (await readFile(join(runDir, 'log.jsonl'), 'utf8')).split('\n').entries()) {
+    if (line.trim() === '') continue
+    let entry: unknown
+    try {
+      entry = JSON.parse(line)
+    } catch {
+      entry = null
+    }
+    if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+      log.push({ unparsed: line, line: i + 1 })
+    } else {
+      log.push(entry as Record<string, unknown>)
+    }
+  }
+
+  const dedupedPath = join(runDir, 'findings.deduped.json')
+  const deduped = await readJsonIfPresent(dedupedPath)
+  if (deduped !== null && !Array.isArray(deduped)) {
+    throw new Error(`${dedupedPath} is not a JSON array`)
+  }
+
+  return {
+    log,
+    shardManifest: await readJsonIfPresent(join(runDir, 'shards', 'manifest.json')),
+    findingsFiles: (await readdir(join(runDir, 'findings'))).sort(),
+    dedupedCount: deduped === null ? null : deduped.length,
+    criticDropped: await readJsonIfPresent(join(runDir, 'critic-dropped.json')),
+    evidenceDropped: await readJsonIfPresent(join(runDir, 'evidence-dropped.json')),
+    thresholdDropped: await readJsonIfPresent(join(runDir, 'threshold-dropped.json')),
+  }
+}
+
+/** Shards some specialist wrote a findings file for, out of the manifest's shards.
+ *  A single-shard run takes the unsharded path, so its files are `<focus>.json`;
+ *  `tests.json` is the deterministic setup finding and proves no specialist ran. */
+export function shardCoverageCount(
+  manifest: unknown | null,
+  findingsFiles: string[],
+): { reviewed: number; total: number } {
+  if (manifest === null) return { reviewed: 0, total: 0 }
+  const shards =
+    typeof manifest === 'object' && 'shards' in manifest ? manifest.shards : undefined
+  if (!Array.isArray(shards)) throw new Error('shard manifest has no shards array')
+  if (shards.length <= 1) {
+    const reviewed = findingsFiles.some((f) => /^[^.]+\.json$/.test(f) && f !== 'tests.json')
+    return { reviewed: reviewed && shards.length === 1 ? 1 : 0, total: shards.length }
+  }
+  const ids = new Set(
+    shards.map((s, i) => {
+      const id = typeof s === 'object' && s !== null && 'id' in s ? s.id : undefined
+      if (typeof id !== 'number') throw new Error(`shard manifest shards[${i}] has no numeric id`)
+      return id
+    }),
+  )
+  const reviewed = new Set<number>()
+  for (const f of findingsFiles) {
+    const m = /^[^.]+\.shard-(\d+)\.json$/.exec(f)
+    if (m && ids.has(Number(m[1]))) reviewed.add(Number(m[1]))
+  }
+  return { reviewed: reviewed.size, total: shards.length }
+}
+
+export function replaySummary(input: {
+  runId: string
+  kept: number
+  unlabelled: number
+  precision: number | null
+  recall: number | null
+  costUsd: number | null
+  missedRecall: { caught: number; misses: number } | null
+  coverage: { reviewed: number; total: number }
+  outPath: string
+}): string {
+  const missed =
+    input.missedRecall === null
+      ? ''
+      : `, missed-recall ${input.missedRecall.caught}/${input.missedRecall.misses}`
+  return (
+    `${input.runId}: kept ${input.kept} (${input.unlabelled} unlabelled), ` +
+    `precision ${formatRatio(input.precision)}, recall ${formatRatio(input.recall)}, ` +
+    `cost ${input.costUsd === null ? 'unreported' : `$${input.costUsd.toFixed(2)}`}${missed}, ` +
+    `shards ${input.coverage.reviewed}/${input.coverage.total}\n` +
+    `wrote ${input.outPath}\n`
+  )
+}
+
 async function exec(
   cmd: string[],
   options: { cwd?: string; stdinText?: string; claudeLabel?: string } = {},
@@ -72,13 +192,15 @@ This is an unattended evaluation run:
 }
 
 async function main(argv: string[]): Promise<number> {
-  const flags = parseFlags(argv, ['corpus', 'repo', 'out', 'max-cost-usd'])
+  const flags = parseFlags(argv, ['corpus', 'repo', 'out', 'max-cost-usd', 'judge-model'])
   if (!flags.corpus || !flags.repo) {
     throw new Error(
-      'usage: replay-full.ts --corpus <runId> --repo <path> [--max-cost-usd N] [--out <corpus-dir>]',
+      'usage: replay-full.ts --corpus <runId> --repo <path> [--max-cost-usd N] ' +
+        '[--judge-model M] [--out <corpus-dir>]',
     )
   }
   const maxCostUsd = positiveNumberFlag(flags, 'max-cost-usd') ?? DEFAULT_MAX_COST_USD
+  const judgeModel = flags['judge-model'] ?? DEFAULT_JUDGE_MODEL
   const corpusRoot = resolveCorpusRoot(flags)
   const run = await loadCorpusRun(join(corpusRoot, flags.corpus))
   const sha = headRefOid(run)
@@ -143,6 +265,9 @@ async function main(argv: string[]): Promise<number> {
       newKept,
     })
 
+    const diagnostics = await replayDiagnostics(scratch)
+    const shardCoverage = shardCoverageCount(diagnostics.shardManifest, diagnostics.findingsFiles)
+
     const resultsDir = join(corpusRoot, 'results')
     await mkdir(resultsDir, { recursive: true })
     const outPath = join(resultsDir, `${resultTimestamp(new Date())}-full-${run.runId}.json`)
@@ -156,12 +281,49 @@ async function main(argv: string[]): Promise<number> {
       matches: Object.fromEntries(matches),
       newKept,
       score,
+      recall: null as RecallScore | null,
+      recallVerdicts: null as RecallVerdict[] | null,
+      judgeModel: null as string | null,
+      judgeCostUsd: null as number | null,
+      ...diagnostics,
+      shardCoverage,
     }
+    // Written before the judge runs so a judge failure cannot lose a paid replay.
     await writeFile(outPath, `${JSON.stringify(result, null, 2)}\n`)
+
+    try {
+      const misses = await loadMisses(join(corpusRoot, 'misses', `${run.runId}.json`))
+      if (misses !== null) {
+        const judged = await judgeRecall({
+          misses,
+          findings: newKept,
+          model: judgeModel,
+          cwd: scratch,
+        })
+        result.recall = scoreRecall(misses, judged.verdicts)
+        result.recallVerdicts = judged.verdicts
+        result.judgeModel = judgeModel
+        result.judgeCostUsd = judged.costUsd
+        await writeFile(outPath, `${JSON.stringify(result, null, 2)}\n`)
+      }
+    } catch (err) {
+      throw new Error(
+        `${err instanceof Error ? err.message : err} (replay result already written to ${outPath})`,
+      )
+    }
+
     process.stdout.write(
-      `${run.runId}: kept ${score.kept} (${unlabelled} unlabelled), ` +
-        `precision ${formatRatio(score.precision)}, recall ${formatRatio(score.recall)}, ` +
-        `cost ${costUsd === null ? 'unreported' : `$${costUsd.toFixed(2)}`}\nwrote ${outPath}\n`,
+      replaySummary({
+        runId: run.runId,
+        kept: score.kept,
+        unlabelled,
+        precision: score.precision,
+        recall: score.recall,
+        costUsd,
+        missedRecall: result.recall,
+        coverage: shardCoverage,
+        outPath,
+      }),
     )
     return 0
   } finally {

package/skills/magpie/evals/rules.json

@@ -147,7 +147,15 @@
       "states": "SKILL.md: 10. Cleanup",
       "origin": "commit:e49534b",
       "cases": [],
-      "unpinned": "No case runs cleanup, and the fakes have no cleanup subcommand."
+      "unpinned": "Only local-mode-hands-back runs cleanup, and local cleanup prints no view-later line by design; no PR case reaches stage 10, and the PR fakes have no cleanup subcommand."
+    },
+    {
+      "id": "local-mode-hands-back-via-handoff",
+      "states": "SKILL.md: Local mode",
+      "origin": "commit:9353023",
+      "cases": [
+        "local-mode-hands-back"
+      ]
     },
     {
       "id": "resumable-means-log-not-server-info",

package/skills/magpie/references/checks.md

@@ -0,0 +1,78 @@
+# Checks prompt
+
+Stage 3 of the walkthrough dispatches one subagent from this file, alongside the scout,
+once per run and never per shard. Build its prompt from two parts, in this order, and
+send it as the agent's entire task:
+
+1. The fenced `magpie-checks` block below, with `<<RUN_DIR>>`, `<<WORKTREE>>` and
+   `<<TARGET>>` replaced by the real values, as `references/scout.md` describes them.
+2. The `## Output Contract` section of `references/specialists.md`, verbatim, with every
+   `<RUN_DIR>` replaced. Its `<focus>` is `checks`, which the block tells the agent, so
+   the findings land in `<RUN_DIR>/findings/checks.json`.
+
+The subagent has no shell variables from your session, so an unexpanded path means it
+writes its findings where nothing will read them.
+
+```magpie-checks
+You are a senior engineer reviewing the checks in <<TARGET>>: the tests, scenario
+and golden-file harnesses, runner scripts that score or gate results, baselines and blessed
+fixtures, positive and negative controls, guards in test helpers, and CI steps that the
+diff adds or changes. Your focus id is `checks`.
+
+Working directory: <<WORKTREE>>
+Diff: <<RUN_DIR>>/diff.patch
+
+The specialists reviewing this PR read the product code. You read the checks, and ask of
+each one: what is it for, and could it pass without proving that?
+
+## How to work
+
+For each check the diff adds or changes, and for each runner or helper the diff changes
+that existing checks rely on:
+
+1. Work out what behaviour it exists to prove, from the code and from any test name,
+   comment, doc or plan in the repo that says so. Cite the file:line you learned it from.
+2. Find what it depends on that it does not control: the real clock under a frozen or
+   faked one, the user's real data directory or database, process-wide state shared with
+   tests that run in parallel, network, timing on a loaded machine, another check's output.
+3. Find how it could pass while proving nothing:
+   - an assertion that cannot fail;
+   - an expected value produced by running the code under test;
+   - a test double that ignores the input the check is about (a query filter, an id);
+   - a guard missing for the very case the check was added for;
+   - an empty, skipped or timed-out run that scores as a pass;
+   - a control that cannot tell "worked" from "did not run";
+   - a baseline re-blessed with no stated cause;
+   - a suite that CI never runs, or that skips itself silently when its environment is absent.
+4. Confirm each condition by reading the code before you report it. A condition you
+   could not confirm is not a finding.
+
+Report a check only when it is weaker than its purpose in a way that would let a real
+regression through, or when it can fail for a reason unrelated to its purpose (the clock,
+shared state, load), which teaches people to ignore it. A check that is merely thin, or
+tests a constant, is not a finding unless something depends on it catching more.
+
+## Findings
+
+Each finding names the check, what it is for, and the concrete way it passes without
+proving it.
+- `Observation:` the condition, with the file:line that shows it.
+- `Why it matters:` the regression it would let through.
+- `Suggested direction:` the smallest change that makes the check able to fail.
+
+Anchor a finding on the line of the assertion, guard, double or runner branch at fault,
+with its `evidence`. Use `line: null` only when the defect is an absence, such as a
+missing guard entry or a suite CI never runs, and name the file where it belongs.
+
+Risk guide (`risk.impact`):
+- high: a check the PR relies on to prove a fix or a security property cannot fail
+- medium: a check that passes on a realistic broken path, or depends on uncontrolled state
+- low: a weak check whose purpose is covered elsewhere
+
+Boundary: report the check's weakness. A defect in the product code the check should have
+caught belongs to the specialists; mention it only as what the weak check lets through.
+
+Report at most 8 findings, the ones whose false pass would mislead the most.
+
+Use the JSON schema defined in the `## Output Contract` section that follows; do not invent fields.
+```

package/skills/magpie/references/peer-review.md

@@ -27,6 +27,13 @@ Replace each `<<NAME>>` placeholder in the block below:
   `severity` is left out on purpose: it is derived from `risk.impact`, so a reviewer who wants to change how bad a finding is changes `risk`.
 - `<<DIFF_EXCERPT>>` — the diff hunks containing the kept findings. For small PRs, the full `diff.patch` is fine. For larger PRs, narrow to the files referenced by `findings.kept.json`.
 
+**Local runs.** A local run has no `pr.json`. Take these four from `local.json` instead; the rest are unchanged:
+
+- `<<PR_TITLE>>`: `Local branch <branch>`, with `<branch>` from `jq -r .branch < $RUN_DIR/local.json`, or `Local detached HEAD` when that is null
+- `<<PR_AUTHOR>>`: `jq -r .author < $RUN_DIR/local.json`
+- `<<PR_HEAD_BRANCH>>`: `jq -r '.branch // "detached HEAD"' < $RUN_DIR/local.json`
+- `<<PR_BASE_BRANCH>>`: `jq -r .baseRef < $RUN_DIR/local.json`
+
 ````magpie-peer-review
 You are the second-opinion reviewer for a PR review. <<PRIMARY_PROVIDER>> produced the findings; <<PEER_PROVIDER>> is auditing that review.
 

package/skills/magpie/references/scout.md

@@ -2,16 +2,23 @@
 
 Stage 3 of the walkthrough dispatches one subagent from this file, before the five
 specialists. Send the fenced `magpie-scout` block below as the agent's entire task,
-with `<<RUN_DIR>>` and `<<PR_NUMBER>>` replaced by the real values first. The
-subagent has no shell variables from your session, so an unexpanded path means it
-writes the brief where nothing will read it.
+with `<<RUN_DIR>>`, `<<WORKTREE>>` and `<<TARGET>>` replaced by the real values first:
+`<<WORKTREE>>` is what `magpie target "$RUN_DIR"` prints, and `<<TARGET>>` is `PR #<n>`
+or, on a local run, `local branch <branch> against <baseRef>` (`detached HEAD
+against <baseRef>` when HEAD has no branch). The subagent has no shell variables from
+your session, so an unexpanded path means it writes the brief where nothing will read it.
+
+On a local run there is no `pr.json`, so drop the `PR metadata:` line from the block.
+The intent evidence is `<<RUN_DIR>>/local.json` instead: its `commits[].headline` and
+`commits[].body`, plus the file named by its `intentFile` when that is not null. Tell
+the scout to read those in place of `title`, `body` and the linked issues.
 
 ```magpie-scout
 You are a senior engineer building the orienting brief that five specialist
-reviewers will read before they review PR #<<PR_NUMBER>>. You are not reviewing the
+reviewers will read before they review <<TARGET>>. You are not reviewing the
 code. You are answering "what is this PR for, and what does it actually do".
 
-Working directory: <<RUN_DIR>>/worktree
+Working directory: <<WORKTREE>>
 PR metadata: <<RUN_DIR>>/pr.json
 Diff: <<RUN_DIR>>/diff.patch
 

package/skills/magpie/references/specialists.md

@@ -9,16 +9,16 @@ them is instruction to you, not text for the specialist.
 2. The run header, with the placeholders filled in. Unsharded:
 
 ```
-You are reviewing PR #<PR_NUMBER>.
-Working directory: <RUN_DIR>/worktree
+You are reviewing <TARGET>.
+Working directory: <WORKTREE>
 Diff: <RUN_DIR>/diff.patch
 ```
 
 When stage 4 is fanning this focus across shards, use instead:
 
 ```
-You are reviewing PR #<PR_NUMBER>.
-Working directory: <RUN_DIR>/worktree
+You are reviewing <TARGET>.
+Working directory: <WORKTREE>
 Shard: <n> of <N>
 Diff: <RUN_DIR>/shards/shard-<n>.patch
 
@@ -68,10 +68,12 @@ review rule is a convention the maintainers wrote down: a change that breaks one
 finding in your domain when the rule bears on it, citing the rule's source.
 ```
 
-Replace every `<RUN_DIR>` and `<PR_NUMBER>` with the real values before sending: the
-subagent has no shell variables from your session, so an unexpanded path means it
-writes its findings where nothing will read them. Leave `<focus>` as written; the
-contract tells the subagent to substitute it.
+Replace every `<RUN_DIR>`, `<WORKTREE>` and `<TARGET>` with the real values before
+sending. `<WORKTREE>` is what `magpie target "$RUN_DIR"` prints. `<TARGET>` is `PR #<n>`,
+or on a local run `local branch <branch> against <baseRef>` (`detached HEAD
+against <baseRef>` when HEAD has no branch). The subagent has no shell variables from
+your session, so an unexpanded path means it writes its findings where nothing will
+read them. Leave `<focus>` as written; the contract tells the subagent to substitute it.
 
 Parts 1, 2, and 3 go every time. The contract is what makes the output parseable by
 `magpie dedupe`, and the focus blocks are what keep the five reviews from collapsing

package/skills/magpie/scripts/__tests__/cleanup-cmd.test.ts

@@ -3,6 +3,9 @@ import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os'
 import { basename, dirname, join } from 'node:path'
 import { killServer, runCleanup } from '../cleanup-cmd.ts'
+import { runSetup } from '../setup-cmd.ts'
+
+const FAKE_GH = new URL('../../fixtures/fake-gh.sh', import.meta.url).pathname
 
 let repo: string
 let runDir: string
@@ -13,6 +16,14 @@ async function sh(cwd: string, ...cmd: string[]): Promise<void> {
   if (exit !== 0) throw new Error(`${cmd.join(' ')} exit ${exit}`)
 }
 
+async function gitOut(cwd: string, ...args: string[]): Promise<string> {
+  const proc = Bun.spawn(['git', ...args], { cwd, stdout: 'pipe', stderr: 'pipe' })
+  const out = await new Response(proc.stdout).text()
+  const exit = await proc.exited
+  if (exit !== 0) throw new Error(`git ${args.join(' ')} exit ${exit}`)
+  return out
+}
+
 beforeEach(async () => {
   repo = await mkdtemp(join(tmpdir(), 'magpie-cleanup-repo-'))
   runDir = await mkdtemp(join(tmpdir(), 'magpie-cleanup-run-'))
@@ -26,6 +37,8 @@ beforeEach(async () => {
   await sh(repo, 'git', 'commit', '-q', '-m', 'init')
   await sh(repo, 'git', 'worktree', 'add', '--detach', join(runDir, 'worktree'), 'HEAD')
   await mkdir(join(runDir, 'state'), { recursive: true })
+  // setup writes log.jsonl first in every real run.
+  await writeFile(join(runDir, 'log.jsonl'), '')
 })
 
 afterEach(async () => {
@@ -62,6 +75,35 @@ test('cleanup prints a view-later hint line with the archived id', async () => {
   expect(text).toMatch(/magpie open \S+\.archived-\d+/)
 })
 
+test('cleanup of a local run prints the archive path but no view-later hint', async () => {
+  await sh(repo, 'git', 'worktree', 'remove', '--force', join(runDir, 'worktree'))
+  await writeFile(join(runDir, 'target.json'), JSON.stringify({ mode: 'local', root: repo }))
+  const out: string[] = []
+  const origWrite = process.stdout.write.bind(process.stdout)
+  process.stdout.write = ((s: string) => {
+    out.push(s)
+    return true
+  }) as typeof process.stdout.write
+  try {
+    await runCleanup({ runDir, repoPath: repo, gitBin: 'git' })
+  } finally {
+    process.stdout.write = origWrite
+  }
+  const text = out.join('')
+  expect(text).toContain('archived to ')
+  expect(text).not.toContain('view later')
+})
+
+test('cleanup with a malformed target.json rejects before archiving or writing labels', async () => {
+  await writeFile(join(runDir, 'log.jsonl'), '')
+  await writeFile(join(runDir, 'findings.final.json'), '[]')
+  await writeFile(join(runDir, 'target.json'), '{not json')
+  await expect(runCleanup({ runDir, repoPath: repo, gitBin: 'git' })).rejects.toThrow('target.json')
+  const entries = await readdir(dirname(runDir))
+  expect(entries.some((e) => e.startsWith(`${basename(runDir)}.archived-`))).toBe(false)
+  expect(await Bun.file(join(runDir, 'labels.json')).exists()).toBe(false)
+})
+
 test('killServer reports no-server-info when state/server-info missing', async () => {
   const result = await killServer(runDir, 100)
   expect(result.outcome).toBe('no-server-info')
@@ -151,3 +193,55 @@ test('runCleanup logs kill outcome to log.jsonl', async () => {
   expect(log).toContain('"stage":"cleanup"')
   expect(log).toContain('"outcome":"no-server-info"')
 })
+
+test('cleanup after a local setup archives the run and leaves the repo as it was', async () => {
+  // The shared fixture adds a worktree; a local run has none, so it gets its own repo and run dir.
+  const localRepo = await mkdtemp(join(tmpdir(), 'magpie-cleanup-local-repo-'))
+  const localRun = await mkdtemp(join(tmpdir(), 'magpie-cleanup-local-run-'))
+  try {
+    await sh(localRepo, 'git', 'init', '-q', '-b', 'main')
+    await sh(localRepo, 'git', 'config', 'user.email', 't@t.t')
+    await sh(localRepo, 'git', 'config', 'user.name', 't')
+    await sh(localRepo, 'git', 'config', 'commit.gpgsign', 'false')
+    await writeFile(join(localRepo, 'a.txt'), 'a\n')
+    await sh(localRepo, 'git', 'add', '.')
+    await sh(localRepo, 'git', 'commit', '-q', '-m', 'init')
+    await sh(localRepo, 'git', 'checkout', '-q', '-b', 'feature-x')
+    await writeFile(join(localRepo, 'b.txt'), 'b\n')
+    await sh(localRepo, 'git', 'add', 'b.txt')
+    await sh(localRepo, 'git', 'commit', '-q', '-m', 'add b')
+    await writeFile(join(localRepo, 'a.txt'), 'a\nedited\n')
+    await writeFile(join(localRepo, 'new.txt'), 'untracked\n')
+
+    const setupExit = await runSetup({
+      mode: 'local',
+      runDir: localRun,
+      repoPath: localRepo,
+      baseRef: 'main',
+      deps: { bun: 'bun', gh: FAKE_GH, codex: 'echo', git: 'git' },
+    })
+    expect(setupExit).toBe(0)
+
+    const exit = await runCleanup({ runDir: localRun, repoPath: localRepo, gitBin: 'git' })
+    expect(exit).toBe(0)
+
+    const parent = dirname(localRun)
+    const archived = (await readdir(parent)).find((e) =>
+      e.startsWith(`${basename(localRun)}.archived-`),
+    )
+    if (!archived) throw new Error('expected an archived run dir')
+    const target = JSON.parse(await readFile(join(parent, archived, 'target.json'), 'utf8'))
+    await rm(join(parent, archived), { recursive: true, force: true })
+    expect(target).toEqual({ mode: 'local', root: localRepo })
+
+    expect(await readFile(join(localRepo, 'a.txt'), 'utf8')).toBe('a\nedited\n')
+    expect(await readFile(join(localRepo, 'new.txt'), 'utf8')).toBe('untracked\n')
+    const status = await gitOut(localRepo, 'status', '--porcelain')
+    expect(status).toBe(' M a.txt\n?? new.txt\n')
+    const worktrees = await gitOut(localRepo, 'worktree', 'list')
+    expect(worktrees.trim().split('\n')).toHaveLength(1)
+  } finally {
+    await rm(localRepo, { recursive: true, force: true })
+    await rm(localRun, { recursive: true, force: true })
+  }
+})

package/skills/magpie/scripts/__tests__/critic-cmd.test.ts

@@ -12,6 +12,8 @@ let stderr: string
 
 beforeEach(async () => {
   runDir = await mkdtemp(join(tmpdir(), 'magpie-critic-'))
+  // setup's first write; without it the dir does not read as a run.
+  await writeFile(join(runDir, 'log.jsonl'), '')
   stdout = ''
   stderr = ''
   spyOn(process.stdout, 'write').mockImplementation((chunk: string | Uint8Array) => {
@@ -88,6 +90,22 @@ test('critic-prompt writes the prompt file from the magpie-critic block and prin
   expect(prompt).toContain(`Write to: ${outputPath}`)
 })
 
+test('critic-prompt points <<WORKTREE>> at the review root named in target.json', async () => {
+  const templatePath = join(runDir, 'critic.md')
+  await writeFile(templatePath, TEMPLATE_DOC)
+  await writeDeduped([finding('a', 'bugs')])
+  await writeFile(
+    join(runDir, 'target.json'),
+    `${JSON.stringify({ mode: 'local', root: '/repos/caller' }, null, 2)}\n`,
+  )
+
+  const exit = await runCriticPrompt(runDir, { templatePath })
+
+  expect(exit).toBe(0)
+  const prompt = await readFile(join(runDir, 'critic-prompt.md'), 'utf8')
+  expect(prompt).toContain('Worktree: /repos/caller\n')
+})
+
 test('critic-prompt writes one numbered prompt per batch', async () => {
   const templatePath = join(runDir, 'critic.md')
   await writeFile(templatePath, TEMPLATE_DOC)

package/skills/magpie/scripts/__tests__/dedupe-cmd.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
 import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
@@ -10,6 +10,8 @@ let runDir: string
 beforeEach(async () => {
   runDir = await mkdtemp(join(tmpdir(), 'magpie-dedupe-'))
   await mkdir(join(runDir, 'findings'), { recursive: true })
+  // setup's first write; without it the dir does not read as a run.
+  await writeFile(join(runDir, 'log.jsonl'), '')
 })
 
 afterEach(async () => {
@@ -385,6 +387,36 @@ test('a malformed shards/manifest.json is treated as no manifest', async () => {
   expect(done?.coverage).toBeUndefined()
 })
 
+test('a checks.json written once per run reaches the deduped findings', async () => {
+  await writeWorktreeSource()
+  await writeFile(
+    join(runDir, 'findings', 'checks.json'),
+    JSON.stringify([
+      {
+        ...f('checks-1', 'a.ts', 0, 'runner scores an empty report as a passing control', 'checks'),
+        line: null,
+      },
+    ]),
+  )
+  expect(await runDedupe(runDir, { threshold: 0 })).toBe(0)
+  const out = JSON.parse(await readFile(join(runDir, 'findings.deduped.json'), 'utf8'))
+  expect(out.map((x: ReviewFinding) => [x.id, x.domain])).toEqual([['checks-1', 'checks']])
+})
+
+test('a sharded run never expects a checks file per shard', async () => {
+  await writeManifest(2)
+  for (const focus of LLM_FOCUSES) {
+    for (const shard of [1, 2]) {
+      await writeFile(join(runDir, 'findings', `${focus}.shard-${shard}.json`), JSON.stringify([]))
+    }
+  }
+  await writeFile(join(runDir, 'findings', 'checks.json'), JSON.stringify([]))
+  const { exit } = await dedupeCapturingStdout()
+  expect(exit).toBe(0)
+  const done = await dedupeLogEntry('done')
+  expect(done?.coverage).toEqual({ expected: 10, missing: [] })
+})
+
 test('runDedupe still skips files it cannot map to a focus', async () => {
   await writeFile(join(runDir, 'findings', 'nonsense.json'), JSON.stringify([]))
   await writeFile(join(runDir, 'findings', 'security.shard-x.json'), JSON.stringify([]))
@@ -398,3 +430,50 @@ test('runDedupe still skips files it cannot map to a focus', async () => {
     .filter((e) => e.status === 'skip' && e.reason === 'unknown-focus')
   expect(skips.map((s) => s.file).sort()).toEqual(['nonsense.json', 'security.shard-x.json'])
 })
+
+describe('with target.json naming a review root outside the run dir', () => {
+  let root: string
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'magpie-dedupe-root-'))
+    await writeFile(
+      join(runDir, 'target.json'),
+      `${JSON.stringify({ mode: 'local', root }, null, 2)}\n`,
+    )
+    await writeFile(
+      join(runDir, 'findings', 'bugs.json'),
+      JSON.stringify([
+        {
+          ...f('bugs-1', 'a.ts', 2, 'secret read without a fallback', 'bugs'),
+          evidence: 'const secret = process.env.KEY',
+        },
+      ]),
+    )
+  })
+
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true })
+  })
+
+  test('keeps a finding whose file and evidence are in that root', async () => {
+    await writeFile(join(root, 'a.ts'), '// line 1\nconst secret = process.env.KEY\n')
+    expect(await runDedupe(runDir, { threshold: 0 })).toBe(0)
+    const kept = JSON.parse(await readFile(join(runDir, 'findings.deduped.json'), 'utf8'))
+    expect(kept.map((x: ReviewFinding) => x.id)).toEqual(['bugs-1'])
+  })
+
+  test('fails without writing findings when a local root does not exist', async () => {
+    await rm(root, { recursive: true, force: true })
+    const exit = await runDedupe(runDir, { threshold: 0 })
+    expect(exit).not.toBe(0)
+    expect(await Bun.file(join(runDir, 'findings.deduped.json')).exists()).toBe(false)
+  })
+
+  test('drops the finding as hallucinated-file when that root lacks the file', async () => {
+    expect(await runDedupe(runDir, { threshold: 0 })).toBe(0)
+    const evidence = JSON.parse(await readFile(join(runDir, 'evidence-dropped.json'), 'utf8'))
+    expect(evidence.dropped).toEqual([
+      { id: 'bugs-1', reason: 'hallucinated-file', file: 'a.ts', line: 2 },
+    ])
+  })
+})