oh-my-opencode 5.1.54 → 5.1.56

package/packages/omo-codex/plugin/hooks/user-prompt-submit-loading-project-rules.json

@@ -7,7 +7,7 @@
 						"type": "command",
 						"command": "node \"${PLUGIN_ROOT}/components/rules/dist/cli.js\" hook user-prompt-submit",
 						"timeout": 10,
-						"statusMessage": "(OmO 5.1.54) Loading Project Rules",
+						"statusMessage": "(OmO 5.1.56) Loading Project Rules",
 						"commandWindows": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${PLUGIN_ROOT}\\components\\bootstrap\\scripts\\node-dispatch.ps1\" \"${PLUGIN_ROOT}\\components\\rules\\dist\\cli.js\" hook user-prompt-submit"
 					}
 				]

package/packages/omo-codex/plugin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "@sisyphuslabs/omo-codex-plugin",
-	"version": "5.1.54",
+	"version": "5.1.56",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@sisyphuslabs/omo-codex-plugin",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"workspaces": [
 				"components/comment-checker",
 				"components/git-bash",
@@ -100,7 +100,7 @@
 		},
 		"components/comment-checker": {
 			"name": "@code-yeongyu/codex-comment-checker",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"license": "MIT",
 			"bin": {
 				"omo-comment-checker": "dist/cli.js"
@@ -122,7 +122,7 @@
 		},
 		"components/git-bash": {
 			"name": "@sisyphuslabs/codex-git-bash-hook",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"bin": {
 				"omo-git-bash-hook": "dist/cli.js"
 			},
@@ -136,7 +136,7 @@
 		},
 		"components/lazycodex-executor-verify": {
 			"name": "@code-yeongyu/codex-lazycodex-executor-verify",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"license": "MIT",
 			"bin": {
 				"lazycodex-executor-verify": "dist/cli.js"
@@ -154,7 +154,7 @@
 		},
 		"components/lsp": {
 			"name": "@code-yeongyu/codex-lsp",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"license": "MIT",
 			"dependencies": {
 				"@code-yeongyu/lsp-daemon": "file:../../../../lsp-daemon",
@@ -176,7 +176,7 @@
 		},
 		"components/rules": {
 			"name": "@code-yeongyu/codex-rules",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"license": "MIT",
 			"dependencies": {
 				"picomatch": "^4.0.7"
@@ -199,7 +199,7 @@
 		},
 		"components/teammode": {
 			"name": "@sisyphuslabs/codex-teammode",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"devDependencies": {
 				"@types/node": "^26.6.2",
 				"@vitest/coverage-v8": "5.0.1",
@@ -213,7 +213,7 @@
 		},
 		"components/telemetry": {
 			"name": "@code-yeongyu/codex-telemetry",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"license": "MIT",
 			"bin": {
 				"omo-telemetry": "dist/cli.js"
@@ -232,7 +232,7 @@
 		},
 		"components/ultrawork": {
 			"name": "@code-yeongyu/codex-ultrawork",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"license": "MIT",
 			"bin": {
 				"omo-ultrawork": "dist/cli.js"
@@ -251,7 +251,7 @@
 		},
 		"components/ulw-execute-continuation": {
 			"name": "@code-yeongyu/codex-ulw-execute-continuation",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"license": "MIT",
 			"bin": {
 				"omo-ulw-execute-continuation": "dist/cli.js"
@@ -269,7 +269,7 @@
 		},
 		"components/ulw-loop": {
 			"name": "@code-yeongyu/codex-ulw-loop",
-			"version": "5.1.54",
+			"version": "5.1.56",
 			"license": "MIT",
 			"bin": {
 				"omo-ulw-loop": "dist/cli.js",

package/packages/omo-codex/plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sisyphuslabs/omo-codex-plugin",
-  "version": "5.1.54",
+  "version": "5.1.56",
   "description": "Aggregate Codex plugin root for OMO components.",
   "type": "module",
   "packageManager": "npm@11.12.1",

package/packages/omo-codex/plugin/skills/browser/runtime/omowright/manifest.json

@@ -5,5 +5,5 @@
     "index.js": "8b14c1775f397e36967a0d094c67e2a31f8ae1e92add172925548723ca339046",
     "page-bundle.js": "bfd51e8383cf47200d57387bbbed258bce5a3a3d00c38fc108034d2888e23f0c"
   },
-  "stagedAtUtc": "2026-10-31T15:59:33.751Z"
+  "stagedAtUtc": "2026-11-01T11:38:13.634Z"
 }

package/packages/omo-codex/plugin/skills/programming/SKILL.md

@@ -199,6 +199,8 @@ uv run scripts/python/check-no-excuse-rules.py <changed paths>
 bash scripts/rust/check-no-excuse-rules.sh <changed paths>
 # TypeScript
 bun run scripts/typescript/check-no-excuse-rules.ts <changed paths>
+# Any language, test files you touched: the junk classes a regex can see (candidates for "test your test")
+bun run scripts/typescript/check-test-junk.ts <changed test paths>
 ```
 
 ### Step 2 — interpret

package/packages/omo-codex/plugin/skills/programming/references/testing/README.md

@@ -56,12 +56,12 @@ When delegating test-writing, hand the child the behavior the test must distingu
 
 ## After writing: test your test
 
-A test earns its place by failing. Before the PR, for each new or reshaped test:
+A test earns its place by failing. Before the PR, run `bun run scripts/typescript/check-test-junk.ts <test files>` for the classes a regex can see (source grep, prose pin, fixed sleep, `.only`/`.skip`, self-comparison, lower bound), then for each new or reshaped test:
 
 1. **Break the owner** (flip the condition, drop the branch, return a constant, skip the write) and run the test. Confirm the mutated bytes are actually in the file before reading the result; a no-op edit "passes" identically to the original.
 2. **Red for the intended reason?** Read the failure message: a loose pattern can match the base's generic error by coincidence (a false red), and a fake that simulates the failure by a different mechanism than the guard reads fails with the fix present.
 3. **Still green?** Then one of: the test is vacuous (fix the assertion); the mutant is equivalent (a `try/catch`, fallback, or normalization maps it back to the same outcome: retarget the mutation at the observable claim); a second rule already produces the same outcome (make the input exercise only the rule under test and assert the recorded reason); or the mutated code is dead (delete the code, not the test's teeth).
-4. **Restore byte for byte.** Never commit a mutation.
+4. **Restore byte for byte.** Never commit a mutation. `bun run scripts/typescript/mutation-proof.ts --file <owner> --find <text> --replace <text> --test 'candidate=bun test <file>' --test 'keeper=bun test <file>'` does steps 1, 3 and 4 in one run and prints red/green per test.
 
 Assertion shapes that survive this step:
 

package/packages/omo-codex/plugin/skills/programming/scripts/typescript/check-test-junk-rules.ts

@@ -0,0 +1,140 @@
+import { extname } from "node:path"
+
+export type RuleId =
+  | "source-grep"
+  | "prose-pin"
+  | "fixed-sleep"
+  | "focused"
+  | "skipped"
+  | "self-compare"
+  | "lower-bound"
+
+export type Language = "typescript" | "python" | "rust" | "go"
+
+export type ReadKind = "prose" | "source"
+
+export type LineRule = {
+  readonly rule: RuleId
+  readonly languages: readonly Language[]
+  readonly pattern: RegExp
+  readonly message: string
+}
+
+export const RULE_IDS: readonly RuleId[] = [
+  "source-grep",
+  "prose-pin",
+  "fixed-sleep",
+  "focused",
+  "skipped",
+  "self-compare",
+  "lower-bound",
+]
+
+export function languageOf(file: string): Language | undefined {
+  switch (extname(file)) {
+    case ".ts":
+    case ".tsx":
+    case ".mts":
+    case ".cts":
+    case ".js":
+    case ".jsx":
+    case ".mjs":
+    case ".cjs":
+      return "typescript"
+    case ".py":
+      return "python"
+    case ".rs":
+      return "rust"
+    case ".go":
+      return "go"
+    default:
+      return undefined
+  }
+}
+
+const SLEEP_MESSAGE = "fixed sleep: wait on the event or state change, not on the clock"
+const SKIP_MESSAGE = "skipped test: fix the test or delete it with its proof; never park it"
+const LOWER_BOUND_MESSAGE = "lower bound on a cardinality: removing one item stays green; pin the exact set"
+
+export const LINE_RULES: readonly LineRule[] = [
+  {
+    rule: "fixed-sleep",
+    languages: ["typescript"],
+    pattern: /\bsetTimeout\s*\(\s*(resolve|res|r|done|cb)\s*,\s*[1-9]|\bawait\s+(Bun\.)?sleep\s*\(\s*[1-9]|new Promise\s*\(\s*\(?\s*\w*\s*\)?\s*=>\s*setTimeout\s*\(\s*\w+\s*,\s*[1-9]/,
+    message: SLEEP_MESSAGE,
+  },
+  { rule: "fixed-sleep", languages: ["python"], pattern: /\btime\.sleep\s*\(|\bawait\s+(asyncio|anyio|trio)\.sleep\s*\(\s*[0-9]/, message: SLEEP_MESSAGE },
+  { rule: "fixed-sleep", languages: ["rust"], pattern: /\bthread::sleep\s*\(|\btokio::time::sleep\s*\(/, message: SLEEP_MESSAGE },
+  { rule: "fixed-sleep", languages: ["go"], pattern: /\btime\.Sleep\s*\(/, message: SLEEP_MESSAGE },
+  {
+    rule: "focused",
+    languages: ["typescript"],
+    pattern: /\b(test|it|describe)\.only\s*\(/,
+    message: "focused test: the rest of the suite is skipped silently",
+  },
+  { rule: "skipped", languages: ["typescript"], pattern: /\b(test|it|describe)\.skip\s*\(|\b(xit|xdescribe|xtest)\s*\(/, message: SKIP_MESSAGE },
+  { rule: "skipped", languages: ["python"], pattern: /@pytest\.mark\.skip\b|\bpytest\.skip\s*\(|\bunittest\.skip\b/, message: SKIP_MESSAGE },
+  { rule: "skipped", languages: ["rust"], pattern: /#\[ignore\b/, message: SKIP_MESSAGE },
+  { rule: "skipped", languages: ["go"], pattern: /\bt\.Skip(f|Now)?\s*\(/, message: SKIP_MESSAGE },
+  {
+    rule: "lower-bound",
+    languages: ["typescript"],
+    pattern: /\.(length|size|count)\s*\)\s*\.(toBeGreaterThan\s*\(\s*[1-9]|toBeGreaterThanOrEqual\s*\(\s*([2-9]|\d{2,}))/,
+    message: LOWER_BOUND_MESSAGE,
+  },
+  {
+    rule: "lower-bound",
+    languages: ["python"],
+    pattern: /\bassert\s+len\s*\(.+\)\s*(>\s*[1-9]|>=\s*([2-9]|\d{2,}))/,
+    message: LOWER_BOUND_MESSAGE,
+  },
+]
+
+export const SELF_COMPARE: Readonly<Record<Language, RegExp>> = {
+  typescript: /\bexpect\s*\(\s*([^()]+?)\s*\)\s*\.(toBe|toEqual|toStrictEqual)\s*\(\s*\1\s*\)/,
+  python: /\bassert\s+([A-Za-z_][\w.]*)\s*==\s*\1\s*(#|$)/,
+  rust: /\bassert_eq!\s*\(\s*([^,()]+?)\s*,\s*\1\s*\)/,
+  go: /\b(Equal|Exactly)\s*\(\s*t\s*,\s*([^,()]+?)\s*,\s*\2\s*\)/,
+}
+
+const SOURCE_EXTENSIONS = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs|py|rs|go)$/
+const PROSE_EXTENSIONS = /\.(md|mdc|txt|prompt)$/
+const READ_ASSIGNMENT = /\b(?:const|let|var)\s+(\w+)\s*=\s*(?:await\s+)?(?:\w+\.)?(?:readFileSync|readFile|readTextSync|Bun\.file|open|read_text|read)\s*\(([^\n]*)$/
+const PYTHON_READ_ASSIGNMENT = /^\s*(\w+)\s*=\s*(?:\w+\.)?(?:open|Path|read_text)\s*\(([^\n]*)$/
+const STRING_LITERAL = /["'`]([^"'`]+)["'`]/g
+
+function readKindOf(callArguments: string): ReadKind | undefined {
+  for (const literal of callArguments.matchAll(STRING_LITERAL)) {
+    const value = literal[1] ?? ""
+    if (PROSE_EXTENSIONS.test(value)) return "prose"
+    if (SOURCE_EXTENSIONS.test(value)) return "source"
+  }
+  return undefined
+}
+
+export function collectReadVariables(lines: readonly string[], language: Language): ReadonlyMap<string, ReadKind> {
+  const variables = new Map<string, ReadKind>()
+  const pattern = language === "python" ? PYTHON_READ_ASSIGNMENT : READ_ASSIGNMENT
+  for (const line of lines) {
+    const match = pattern.exec(line)
+    if (match === null) continue
+    const kind = readKindOf(match[2] ?? "")
+    if (kind !== undefined && match[1] !== undefined) variables.set(match[1], kind)
+  }
+  return variables
+}
+
+export function greppedVariable(line: string, language: Language): string | undefined {
+  if (language === "python") {
+    return /\bassert\s+(?:not\s+)?["'][^"']*["']\s+(?:not\s+)?in\s+(\w+)/.exec(line)?.[1]
+  }
+  return (
+    /\bexpect\s*\(\s*(\w+)\s*\)\s*(?:\.not)?\.(?:toContain|toMatch|toMatchSnapshot|toMatchInlineSnapshot|toInclude|toStartWith|toEndWith)\s*\(/.exec(line)?.[1] ??
+    /\bexpect\s*\(\s*(\w+)\.(?:includes|match|indexOf|search)\s*\(/.exec(line)?.[1]
+  )
+}
+
+export const READ_RULE_MESSAGES: Readonly<Record<ReadKind, { readonly rule: RuleId; readonly message: string }>> = {
+  prose: { rule: "prose-pin", message: "wording of a prompt/skill/doc is pinned; assert a machine-consumed value or write no test" },
+  source: { rule: "source-grep", message: "a source file is grepped as text; drive the module and assert behavior" },
+}

package/packages/omo-codex/plugin/skills/programming/scripts/typescript/check-test-junk.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+/**
+ * Flag test files for the junk classes a regex can see (the rest need a reader):
+ *
+ *   source-grep    - a value read from a source file (.ts/.js/.py/.rs/.go/...) is grepped
+ *                    (toContain / toMatch / includes / `in`); byte equality between two reads is not flagged
+ *   prose-pin      - a value read from a prompt/skill/markdown file has its wording pinned
+ *                    (toContain / not.toContain / toMatch / toMatchSnapshot / `in`)
+ *   fixed-sleep    - setTimeout-as-wait, sleep(N), time.sleep, thread::sleep, time.Sleep
+ *   focused        - test.only / it.only / describe.only (a focused test silently skips the suite)
+ *   skipped        - .skip / xit / xdescribe / @pytest.mark.skip / #[ignore] / t.Skip
+ *   self-compare   - expect(x).toBe(x) / assert x == x / assert_eq!(x, x)
+ *   lower-bound    - toBeGreaterThan(N>=1) / toBeGreaterThanOrEqual(N>=2) on a length/size/count
+ *                    (removing one item stays green; a plain non-empty check is not flagged)
+ *
+ * Opt out per line with a trailing comment naming the rule and the reason:
+ *   // test-junk-ok: fixed-sleep debounce window is the behavior under test
+ *
+ * Usage:
+ *   bun run scripts/typescript/check-test-junk.ts [--json] <file-or-dir>...
+ *
+ * Exit codes: 0 no findings, 1 findings, 2 input error.
+ * Each class is explained in references/testing/junk-classes.md; a finding here is a candidate
+ * to prove with references/testing/README.md "test your test", not an automatic deletion.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { basename, extname, join } from "node:path"
+import process from "node:process"
+
+import {
+  collectReadVariables,
+  greppedVariable,
+  languageOf,
+  LINE_RULES,
+  READ_RULE_MESSAGES,
+  RULE_IDS,
+  SELF_COMPARE,
+  type RuleId,
+} from "./check-test-junk-rules"
+
+export type { RuleId } from "./check-test-junk-rules"
+
+export type Finding = {
+  readonly file: string
+  readonly line: number
+  readonly rule: RuleId
+  readonly message: string
+}
+
+const EXCLUDED_DIRS: ReadonlySet<string> = new Set([".git", "node_modules", "dist", "build", "target", "__pycache__", ".venv", "vendor"])
+
+const TEST_FILE_PATTERNS: readonly RegExp[] = [
+  /\.(test|spec)\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/,
+  /_test\.go$/,
+  /(^|\/)test_[^/]*\.py$/,
+  /(^|\/)[^/]*_test\.py$/,
+  /\.rs$/,
+]
+
+const OPT_OUT = /test-junk-ok:\s*([a-z-]+)/
+
+function isTestFile(file: string): boolean {
+  if (!TEST_FILE_PATTERNS.some((pattern) => pattern.test(file))) return false
+  // Rust unit tests live inside source files; only files declaring a test module count.
+  return extname(file) !== ".rs" || /#\[cfg\(test\)\]|#\[test\]/.test(readFileSync(file, "utf8"))
+}
+
+function* walk(root: string): Generator<string> {
+  if (statSync(root).isFile()) {
+    yield root
+    return
+  }
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!EXCLUDED_DIRS.has(entry.name)) yield* walk(join(root, entry.name))
+    } else if (entry.isFile()) {
+      yield join(root, entry.name)
+    }
+  }
+}
+
+function optedOut(line: string, rule: RuleId): boolean {
+  const match = OPT_OUT.exec(line)
+  return match !== null && match[1] === rule
+}
+
+function scanFile(file: string): readonly Finding[] {
+  const language = languageOf(file)
+  if (language === undefined) return []
+  const lines = readFileSync(file, "utf8").split("\n")
+  const readVariables = collectReadVariables(lines, language)
+  const findings: Finding[] = []
+  const report = (line: number, rule: RuleId, message: string): void => {
+    if (!optedOut(lines[line - 1] ?? "", rule)) findings.push({ file, line, rule, message })
+  }
+
+  lines.forEach((source, index) => {
+    const line = index + 1
+    for (const rule of LINE_RULES) {
+      if (rule.languages.includes(language) && rule.pattern.test(source)) report(line, rule.rule, rule.message)
+    }
+    if (SELF_COMPARE[language].test(source)) {
+      report(line, "self-compare", "the expected value is the value under test; derive it from the input")
+    }
+    const grepped = greppedVariable(source, language)
+    const kind = grepped === undefined ? undefined : readVariables.get(grepped)
+    if (kind !== undefined) report(line, READ_RULE_MESSAGES[kind].rule, READ_RULE_MESSAGES[kind].message)
+  })
+  return findings
+}
+
+function scan(paths: readonly string[]): readonly Finding[] {
+  const findings: Finding[] = []
+  for (const root of paths) {
+    for (const file of walk(root)) {
+      if (isTestFile(file)) findings.push(...scanFile(file))
+    }
+  }
+  return findings
+}
+
+function main(argv: readonly string[]): number {
+  const json = argv.includes("--json")
+  const paths = argv.filter((arg) => arg !== "--json")
+  if (paths.length === 0) {
+    console.error(`usage: ${basename(import.meta.path)} [--json] <file-or-dir>...`)
+    return 2
+  }
+  for (const path of paths) {
+    try {
+      statSync(path)
+    } catch {
+      console.error(`error: ${path} does not exist`)
+      return 2
+    }
+  }
+  const findings = scan(paths)
+  if (json) {
+    console.log(JSON.stringify({ findings, rules: RULE_IDS }, null, 2))
+  } else {
+    for (const finding of findings) console.log(`${finding.file}:${finding.line} ${finding.rule} ${finding.message}`)
+    console.log(findings.length === 0 ? "check-test-junk: no findings" : `check-test-junk: ${findings.length} finding(s)`)
+  }
+  return findings.length === 0 ? 0 : 1
+}
+
+if (import.meta.main) process.exit(main(process.argv.slice(2)))

package/packages/omo-codex/plugin/skills/programming/scripts/typescript/mutation-proof.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env bun
+/**
+ * Prove that a test can fail: apply one exact-match edit to a production file, run each test
+ * command against the mutated owner, then restore the original bytes and verify their hash.
+ *
+ * Usage:
+ *   bun run scripts/typescript/mutation-proof.ts --file <path> --find <text> --replace <text> \
+ *     --test '<label>=<argv...>' [--test ...] [--cwd <dir>] [--json]
+ *
+ *   --test takes "label=command words"; the command is split on spaces and quoting is not
+ *   supported, so select a test by a pattern without spaces or run the whole file.
+ *
+ * Verdicts per test: red (exit != 0, the test caught the mutation) or green (exit 0, it did not).
+ * The owner is restored on success, on a thrown error, and on SIGINT/SIGTERM.
+ * Exit codes: 0 ran and restored, 1 the find text is empty or did not match exactly once or the
+ * restore hash differed (the file was still restored), 2 usage, 130/143 interrupted and restored.
+ * Read references/testing/junk-classes.md "Proof rule" for how to read a candidate/keeper pair.
+ */
+
+import { createHash } from "node:crypto"
+import { readFileSync, writeFileSync } from "node:fs"
+import { resolve } from "node:path"
+import process from "node:process"
+import { parseArgs } from "node:util"
+
+export type MutationTest = { readonly label: string; readonly command: readonly string[] }
+
+export type MutationOutcome = {
+  readonly label: string
+  readonly command: readonly string[]
+  readonly exitCode: number
+  readonly verdict: "red" | "green"
+  readonly outputTail: string
+}
+
+export type MutationResult = {
+  readonly file: string
+  readonly find: string
+  readonly replace: string
+  readonly originalSha256: string
+  readonly restoredSha256: string
+  readonly outcomes: readonly MutationOutcome[]
+}
+
+export class MutationError extends Error {
+  constructor(
+    readonly kind: "FIND_EMPTY" | "FIND_NOT_UNIQUE" | "RESTORE_MISMATCH",
+    message: string,
+  ) {
+    super(message)
+    this.name = "MutationError"
+  }
+}
+
+const sha256 = (bytes: Uint8Array): string => createHash("sha256").update(bytes).digest("hex")
+
+async function runCaptured(command: readonly string[], cwd: string): Promise<{ readonly exitCode: number; readonly outputTail: string }> {
+  const child = Bun.spawn([...command], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" })
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  const lines = `${stdout}${stderr}`.trimEnd().split("\n")
+  return { exitCode, outputTail: lines.slice(-30).join("\n") }
+}
+
+export async function runMutation(options: {
+  readonly cwd: string
+  readonly file: string
+  readonly find: string
+  readonly replace: string
+  readonly tests: readonly MutationTest[]
+}): Promise<MutationResult> {
+  if (options.find.length === 0) throw new MutationError("FIND_EMPTY", `${options.file}: find text is empty`)
+  const full = resolve(options.cwd, options.file)
+  const original = readFileSync(full)
+  const text = original.toString("utf8")
+  const occurrences = text.split(options.find).length - 1
+  if (occurrences !== 1) {
+    throw new MutationError("FIND_NOT_UNIQUE", `${options.file}: find matched ${occurrences} times (need exactly 1)`)
+  }
+  const originalSha256 = sha256(original)
+  const outcomes: MutationOutcome[] = []
+  const restoreOnSignal = (signal: NodeJS.Signals): void => {
+    writeFileSync(full, original)
+    process.exit(signal === "SIGINT" ? 130 : 143)
+  }
+  process.on("SIGINT", restoreOnSignal)
+  process.on("SIGTERM", restoreOnSignal)
+  try {
+    writeFileSync(full, text.replace(options.find, () => options.replace))
+    for (const test of options.tests) {
+      const run = await runCaptured(test.command, options.cwd)
+      outcomes.push({
+        label: test.label,
+        command: test.command,
+        exitCode: run.exitCode,
+        verdict: run.exitCode === 0 ? "green" : "red",
+        outputTail: run.outputTail,
+      })
+    }
+  } finally {
+    writeFileSync(full, original)
+    process.off("SIGINT", restoreOnSignal)
+    process.off("SIGTERM", restoreOnSignal)
+  }
+  const restoredSha256 = sha256(readFileSync(full))
+  if (restoredSha256 !== originalSha256) {
+    throw new MutationError("RESTORE_MISMATCH", `${options.file} not restored byte for byte`)
+  }
+  return { file: options.file, find: options.find, replace: options.replace, originalSha256, restoredSha256, outcomes }
+}
+
+function parseTest(spec: string): MutationTest | undefined {
+  const separator = spec.indexOf("=")
+  if (separator <= 0) return undefined
+  const label = spec.slice(0, separator)
+  const command = spec
+    .slice(separator + 1)
+    .split(" ")
+    .filter((word) => word.length > 0)
+  return command.length === 0 ? undefined : { label, command }
+}
+
+function usage(): number {
+  console.error(
+    "usage: mutation-proof.ts --file <path> --find <text> --replace <text> --test '<label>=<argv...>' [--test ...] [--cwd <dir>] [--json]",
+  )
+  return 2
+}
+
+async function main(argv: readonly string[]): Promise<number> {
+  const { values } = parseArgs({
+    args: [...argv],
+    options: {
+      file: { type: "string" },
+      find: { type: "string" },
+      replace: { type: "string" },
+      test: { type: "string", multiple: true },
+      cwd: { type: "string", default: process.cwd() },
+      json: { type: "boolean", default: false },
+    },
+    strict: true,
+  })
+  if (values.file === undefined || values.find === undefined || values.replace === undefined || values.test === undefined) {
+    return usage()
+  }
+  const tests: MutationTest[] = []
+  for (const spec of values.test) {
+    const parsed = parseTest(spec)
+    if (parsed === undefined) return usage()
+    tests.push(parsed)
+  }
+  try {
+    const result = await runMutation({
+      cwd: values.cwd ?? process.cwd(),
+      file: values.file,
+      find: values.find,
+      replace: values.replace,
+      tests,
+    })
+    if (values.json) {
+      console.log(JSON.stringify(result, null, 2))
+    } else {
+      for (const outcome of result.outcomes) console.log(`${outcome.label}: ${outcome.verdict} (exit ${outcome.exitCode})`)
+      console.log(`restored ${result.file} (sha256 ${result.restoredSha256.slice(0, 12)})`)
+    }
+    return 0
+  } catch (error) {
+    if (error instanceof MutationError) {
+      console.error(`mutation-proof: ${error.kind}: ${error.message}`)
+      return 1
+    }
+    throw error
+  }
+}
+
+if (import.meta.main) process.exit(await main(process.argv.slice(2)))