probatio 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# Probatio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Probatio (Latin: a testing, a proof) is a free, open-source testing toolkit built for AI agents
+(Claude, Grok, ChatGPT, others), working alone or as swarms. Every claim it makes is checkable;
+it remembers what was fixed so agents with small context do not redo or undo work; and it finds
+the bugs a test suite would miss instead of asking anyone to read more tests.
+
+Status (2026-10-05): `mutate run` discovers the project suite and scores it. Python, JavaScript, and TypeScript narrow each mutant with a line map collected on the baseline. C does the same when the binary was built with LLVM coverage. A suite with no line map, a baseline of 5 seconds or more, and more than 30 mutants stops before the first mutant. `verify-change` mutates the changed lines and uses that same map. `mutate tally` reads a finished run, names tests that killed nothing, and does not delete a test. The MCP server speaks one JSON object per line and returns the same JSON as the CLI.
+
+Read in this order:
+
+1. `HANDOFF.md` — why, the evidence from Auspex, the design, and the lessons that cost time.
+2. `FOR-GROK.md` — the builder brief: build order with acceptance tests, the agent contract,
+   memory for agents, anti-gaming, swarm protocol, traps.
+3. `seed/` — code copied from the Auspex experiment to start from (Auspex paths inside).
+
+Roles: Grok builds most of it; Claude refines and finishes. Grok keeps `NOTES-FOR-CLAUDE.md` here
+(decisions, guesses, shortcuts with file:line, acceptance output actually run).
+
+## mutate
+
+One JSON object on stdout. `schemaVersion`, `ok`, `summary`, `next`, `nextCall`. Exit 0 only when `ok` is true. Human text is `--human`. A run checks the suite out in a throwaway worktree, so the checkout you are in stays as it is.
+
+```bash
+npx probatio mutate generate --package . --out .probatio/generate
+npx probatio mutate run --package . --patches .probatio/generate/mutants --out .probatio/runs
+npx probatio mutate tally --out .probatio/runs
+```
+
+`generate` writes operator mutants (conditions, `&&`/`||`, `===`/`!==`, boundaries, booleans, a dropped `!`). The same class is written for COBOL (`.cob`, `.cbl`), Rust, C, C++, Java, Go, Python, JavaScript, and C#. Strings and comments are not mutated. A COBOL `*>` comment and a fixed-format line whose column 7 is `*` or `/` are comments. Each patch is forward: apply it to introduce the bug, and the file says so. When mutants were written, `next` states the count, the suite command if one was discovered, and whether the first run collects a line map.
+
+`run` discovers the suite: `run_tests.sh`, Cargo, Go, Swift, Maven, dotnet, pytest, unittest, node:test, Mocha, then `make test` when COBOL tests sit under that Makefile. An unknown layout stops and asks for `--suite-command`. It does not compile one file and call that the suite. `make test` that would curl or wget a missing file stops, and nothing is fetched. A worktree that has no `node_modules` uses the main checkout's. Omitting `--build` runs no build. Pass `--build` with a command when the suite needs one first.
+
+Python, JavaScript, and TypeScript collect a line map on the baseline. C collects one when LLVM coverage was instrumented. Go and Maven/Java collect file, line, and the test names that hit that line. A later mutant runs only those tests (`go test -run`, Maven `-Dtest`). A line no test executed is `no coverage`, and the suite is not started. Rust and C# can take a test name and do not collect a line. A baseline of 5 seconds or more, with no line map and more than 30 mutants still pending, stops before the first mutant. `next` names that baseline and tells you to narrow `--src` or pass a smaller patch directory. A one-file C, C++, Java, COBOL, or assembly launcher is not a suite discovery returns.
+
+The mutant timeout is the baseline duration times 5, and at least 20 seconds, capped by `--suite-timeout-ms`. A timeout is not a kill. `--budget-ms` stops mutant work after the baseline. The first mutant still runs, except for that no-line-map stop. A kill is the test that failed, or a compiler token when the mutant did not build. Confirm is on by default and reruns the failing names. Pytest names that `-k` cannot express are passed as node ids. A usage error, including pytest exit 4, is not a kill. `verify-change` does not confirm a second time. Add `--affected` to limit the file list to tests that can see the change. The default, once a line map exists, runs the tests on the changed line.
+
+`tally` reads that run directory. The summary leads with the no-coverage count, then the survivors. It names tests that killed a mutant and tests that killed nothing. A gap is a survivor. An unseen line is not a gap and not a pass. A timeout is neither a kill nor a gap. `deletedTests` is 0. It does not delete a file.
+
+## ledger
+
+```bash
+npx probatio ledger build --package . --commit HEAD --out .probatio/ledger
+```
+
+A fix commit has a `Fixes-bug:` trailer, or it changes both `src` and a test. `ledger build` reverts that commit's src diff onto the tree you name. A diff that applies is written as a forward patch (`source=history`): apply it to put the bug back. A diff that does not apply is reported, and left for a hand-made patch in the same directory (`source=hand`, `fix=<commit>`). A rebuild keeps those hand-made files. Nothing is fuzzy-applied. A src diff over `--max-lines` (default 300) is skipped. `--max-commits N` reads only the newest N non-merge commits and says when older history was not scanned. The default reads the whole history. A tree is checked out only when a fix inside that cap has to be applied.
+
+## matrix
+
+```bash
+npx probatio matrix report --scores round2-union-scores.tsv --direct round2-direct-scores.txt --patches mutants/holdout --patches mutants/train --out .probatio/matrix
+```
+
+Reads those recorded tables. It does not rerun the mutants. The headline is the gap list: `file:line`, the top 10, how many are left, and the path to the full JSON. A test that killed nothing can be named. The file is not deleted.
+
+## golden
+
+```bash
+npx probatio golden check --recorded table.json --actual now.json --update wording
+```
+
+`next` and `nextLead` are wording. `ok`, `reason`, `status`, `hostChanged`, and `nextCall` are the contract. `--update wording` re-records a changed `next` or `nextLead` and leaves the contract fields alone. A file whose case names are the top-level keys is written back in that shape. A changed `ok` or `reason` also needs `Golden-Change: <row>: <why>` in `--message`. A home path, or `ok` without a reason, fails and nothing is written.
+
+## status
+
+```bash
+npx probatio status --state .probatio --page PROBATIO.md
+```
+
+Rewrites `PROBATIO.md` from the same JSON: open gaps, recent fixes and their guards, protected guards, decisions. A sealed id is left out of the page, the JSON, and `queue seed`. If visible kills rise and sealed kills do not, the summary is `these tests fit the yardstick, not the code.`
+
+## verify-change
+
+```bash
+npx probatio verify-change --package . --base HEAD~1 --out .probatio/verify
+```
+
+Lists the tests that can see the diff, runs mutants on the changed lines, and reports caught, missed, mutants that were not run, lines with no coverage, and any golden contract change. The mutants are the same operator class `mutate generate` would write, including a non-TypeScript diff. A string or a comment is not a mutant. `ran` is still the direct-importer list. The tests that execute are chosen by the line map, the same way `mutate run` chooses them, including when that importer list is empty. No discovered suite leaves those mutants in `notRun` and does not start a run. The suite timeout is 10 minutes. `--max-tests` only shortens the reported importer list. `--max-mutants` (default 4) caps how many changed lines are run.
+
+## queue
+
+An item is `.probatio/queue/<id>.json`. `queue claim` renames it to `claimed/<agent>-<id>.json` with a lease. `queue reap` moves an expired lease back. `check-kill <id>` runs the tests that directly import the mutated file and confirms the killing test again. It is done only when that mutant dies and that suite is still green. `verify-change` is the edit-sized run: it uses the line map and does not confirm a second time.
+
+The MCP server speaks stdio JSON-RPC. Its one tool runs the CLI and returns that command's JSON.

package/dist/cli.js

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { SCHEMA_VERSION, render } from "./contract.js";
+import { bool, int, parseArgs, requireText, text, texts } from "./flags.js";
+import { asTable, checkGolden, goldenShape, readGolden, writeGolden } from "./golden/check.js";
+import { buildLedger } from "./ledger/build.js";
+import { readKills, reportMatrix } from "./matrix/report.js";
+import { appendFinding, chooseSealed, fixGap, guardAllows, lineHash, loadState, parseGuard, readSourceLine, revertGap, saveState, sealIds, statusEnvelope, } from "./memory/state.js";
+import { git } from "./mutate/patch.js";
+import { generateMutants } from "./mutate/generate.js";
+import { runMutants } from "./mutate/run.js";
+import { generateNext } from "./mutate/suite-decision.js";
+import { discoverSuite } from "./mutate/suites.js";
+import { tallyRun } from "./mutate/tally.js";
+import { checkKill } from "./swarm/check-kill.js";
+import { claimItem, reapClaims, seedQueue } from "./swarm/queue.js";
+import { verifyChange } from "./verify/change.js";
+const parsed = parseArgs(process.argv.slice(2));
+const [group, action] = parsed.command;
+try {
+    if (group === "mutate" && action === "generate")
+        finish(await generateCommand(parsed.flags), parsed.human);
+    if (group === "mutate" && action === "run")
+        finish(await runCommand(parsed.flags), parsed.human);
+    if (group === "mutate" && action === "tally")
+        finish(tallyCommand(parsed.flags), parsed.human);
+    if (group === "ledger" && action === "build")
+        finish(await ledgerCommand(parsed.flags), parsed.human);
+    if (group === "matrix" && action === "report")
+        finish(matrixCommand(parsed.flags), parsed.human);
+    if (group === "golden" && action === "check")
+        finish(goldenCommand(parsed.flags), parsed.human);
+    if (group === "gap" && action === "fix")
+        finish(gapFixCommand(parsed.flags), parsed.human);
+    if (group === "gap" && action === "revert")
+        finish(gapRevertCommand(parsed.flags), parsed.human);
+    if (group === "guard" && action === "check")
+        finish(guardCommand(parsed.flags), parsed.human);
+    if (group === "findings" && action === "add")
+        finish(findingsCommand(parsed.flags), parsed.human);
+    if (group === "status")
+        finish(statusCommand(parsed.flags), parsed.human);
+    if (group === "seal")
+        finish(sealCommand(parsed.flags), parsed.human);
+    if (group === "queue" && action === "seed")
+        finish(queueSeedCommand(parsed.flags), parsed.human);
+    if (group === "queue" && action === "claim")
+        finish(queueClaimCommand(parsed.flags), parsed.human);
+    if (group === "queue" && action === "reap")
+        finish(queueReapCommand(parsed.flags), parsed.human);
+    if (group === "check-kill")
+        finish(await checkKillCommand(parsed.flags, action), parsed.human);
+    if (group === "verify-change")
+        finish(await verifyCommand(parsed.flags), parsed.human);
+    finish(usage(false, "Use mutate, ledger, matrix, golden, gap, guard, findings, status, queue, check-kill, or verify-change."), parsed.human);
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    finish({
+        schemaVersion: SCHEMA_VERSION,
+        ok: false,
+        command: `${group ?? "mutate"}.${action ?? "help"}`,
+        summary: message,
+        next: "Fix the command and run it again.",
+        nextCall: null,
+    }, parsed.human);
+}
+function usage(ok, summary) {
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok,
+        command: "mutate.help",
+        summary,
+        next: "probatio mutate generate writes operator mutants. probatio mutate run confirms each kill twice. probatio mutate tally reads a finished run and does not delete a test. probatio ledger build reverts fix commits. probatio matrix report reads a recorded score table.",
+        nextCall: null,
+    };
+}
+async function generateCommand(flags) {
+    const packageDir = path.resolve(requireText(flags, "package"));
+    const outDir = path.resolve(requireText(flags, "out"));
+    const perFile = int(flags, "per-file");
+    const result = generateMutants({
+        packageDir,
+        srcDir: text(flags, "src") ?? "src",
+        outDir,
+        perFile: perFile === undefined ? null : perFile,
+        skip: int(flags, "skip") ?? 0,
+        seed: int(flags, "seed") ?? 20261003,
+        maxMutants: int(flags, "max-mutants") ?? null,
+        maxMinutes: int(flags, "max-minutes") ?? null,
+        skipFiles: texts(flags, "skip-file"),
+    });
+    if (result.violations.length > 0) {
+        const first = result.violations[0];
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            ok: false,
+            command: "mutate.generate",
+            summary: `Refusing to write mutants: ${first.file}:${first.line} sits inside a string or a comment.`,
+            next: "That is a generator bug. Do not use the batch.",
+            nextCall: null,
+            stringLiteralMutants: result.violations.length,
+        };
+    }
+    const shown = result.mutants.slice(0, 10).map(({ id, file, line, op }) => ({ id, file, line, op }));
+    const patches = path.join(outDir, "mutants");
+    const stopped = result.budgetHit;
+    const suite = discoverSuite(packageDir, text(flags, "tests-dir") ?? "tests");
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: true,
+        command: "mutate.generate",
+        summary: stopped
+            ? `Stopped by the time budget after ${result.filesVisited} files. ${result.mutants.length} mutants written.`
+            : `${result.mutants.length} mutants in ${result.filesVisited} files. No string-literal mutant.`,
+        next: stopped
+            ? "Narrow --src or raise --max-minutes, then run the same command."
+            : generateNext(result.mutants.length, suite ? { kind: suite.kind, command: suite.command } : null),
+        nextCall: result.mutants.length === 0
+            ? null
+            : { argv: ["mutate", "run", "--package", packageDir, "--patches", patches, "--out", path.join(outDir, "runs")] },
+        mutantCount: result.mutants.length,
+        stringLiteralMutants: 0,
+        filesVisited: result.filesVisited,
+        budgetHit: result.budgetHit,
+        mutants: shown,
+        rest: Math.max(result.mutants.length - shown.length, 0),
+        full: path.join(patches, "mutants.json"),
+    };
+}
+async function runCommand(flags) {
+    const packageDir = path.resolve(requireText(flags, "package"));
+    const patchDirs = texts(flags, "patches").map((dir) => path.resolve(dir));
+    if (patchDirs.length === 0)
+        throw new Error("--patches is required");
+    const outDir = path.resolve(requireText(flags, "out"));
+    const repoDir = path.resolve(text(flags, "repo") ?? gitRoot(packageDir));
+    const workers = int(flags, "workers") ?? 1;
+    if (workers < 1)
+        throw new Error("--workers must be at least 1");
+    const direction = text(flags, "direction") ?? "auto";
+    if (direction !== "auto" && direction !== "forward" && direction !== "reverse") {
+        throw new Error("--direction must be auto, forward, or reverse");
+    }
+    const build = buildCommand(flags);
+    const report = await runMutants({
+        packageDir,
+        repoDir,
+        commit: text(flags, "commit") ?? "HEAD",
+        patchDirs,
+        outDir,
+        direction,
+        workers,
+        concurrency: int(flags, "concurrency") ?? 3,
+        maxMinutes: int(flags, "max-minutes") ?? null,
+        maxMutants: int(flags, "max-mutants") ?? null,
+        build,
+        testsDir: text(flags, "tests-dir") ?? "tests",
+        unset: texts(flags, "unset"),
+        suiteTimeoutMs: int(flags, "suite-timeout-ms") ?? 600_000,
+        testTimeoutMs: int(flags, "test-timeout-ms") ?? 60_000,
+        confirm: bool(flags, "confirm", true),
+        affected: bool(flags, "affected", false),
+        agent: text(flags, "agent") ?? null,
+        suiteCommand: text(flags, "suite-command") ?? null,
+        historyPath: text(flags, "history") ? path.resolve(text(flags, "history")) : null,
+        timeoutMultiple: int(flags, "timeout-multiple") ?? 5,
+        timeoutFloorMs: int(flags, "timeout-floor-ms") ?? 20_000,
+        budgetMs: int(flags, "budget-ms") ?? null,
+        onProgress: (line) => process.stderr.write(`${line}\n`),
+    });
+    const resume = report.budgetHit
+        ? { argv: ["mutate", "run", "--package", packageDir, "--repo", repoDir, "--out", outDir, ...patchDirs.flatMap((dir) => ["--patches", dir])] }
+        : null;
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: report.ok,
+        command: "mutate.run",
+        summary: report.summary,
+        next: report.next,
+        nextCall: report.ok ? resume : null,
+        killed: report.killed,
+        survived: report.survived,
+        flaky: report.flaky,
+        timeouts: report.timeouts,
+        errors: report.errors,
+        noCoverage: report.noCoverage,
+        notStarted: report.notStarted,
+        suiteCommand: report.suiteCommand,
+        baselineMs: report.baselineMs,
+        commands: report.commands,
+        gaps: report.gaps,
+        rest: report.rest,
+        flakyIds: report.flakyIds,
+        budgetHit: report.budgetHit,
+        commit: report.commit,
+        runId: report.runId,
+        kills: report.kills,
+        full: report.full,
+    };
+}
+function tallyCommand(flags) {
+    return tallyRun(path.resolve(requireText(flags, "out")));
+}
+async function ledgerCommand(flags) {
+    const packageDir = path.resolve(requireText(flags, "package"));
+    const outDir = path.resolve(requireText(flags, "out"));
+    const repoDir = path.resolve(text(flags, "repo") ?? gitRoot(packageDir));
+    const report = buildLedger({
+        packageDir,
+        repoDir,
+        commit: text(flags, "commit") ?? "HEAD",
+        outDir,
+        srcDir: text(flags, "src") ?? "src",
+        testsDir: text(flags, "tests-dir") ?? "tests",
+        maxLines: int(flags, "max-lines") ?? 300,
+        maxCommits: int(flags, "max-commits") ?? null,
+    });
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: report.ok,
+        command: "ledger.build",
+        summary: report.summary,
+        next: report.next,
+        nextCall: report.ok ? report.nextCall : null,
+        clean: report.clean,
+        hand: report.hand,
+        handmade: report.handmade,
+        skipped: report.skipped,
+        handNeeded: report.handNeeded,
+        rest: report.rest,
+        commit: report.commit,
+        full: report.full,
+        historyBudgetHit: report.historyBudgetHit,
+        commitsScanned: report.commitsScanned,
+    };
+}
+function matrixCommand(flags) {
+    const scoresPath = requireText(flags, "scores");
+    const directPath = requireText(flags, "direct");
+    const outDir = path.resolve(requireText(flags, "out"));
+    const killsPath = text(flags, "kills");
+    return reportMatrix({
+        scores: readFileSync(scoresPath, "utf8"),
+        direct: readFileSync(directPath, "utf8"),
+        patchDirs: texts(flags, "patches").map((dir) => path.resolve(dir)),
+        outDir,
+        kills: killsPath ? readKills(killsPath) : new Map(),
+    });
+}
+function goldenCommand(flags) {
+    const recordedPath = requireText(flags, "recorded");
+    const recordedText = readFileSync(recordedPath, "utf8");
+    const updateRaw = text(flags, "update");
+    if (updateRaw && updateRaw !== "wording" && updateRaw !== "all")
+        throw new Error("--update must be wording or all");
+    const result = checkGolden({
+        recorded: asTable(recordedText),
+        actual: readGolden(requireText(flags, "actual")),
+        update: updateRaw === "wording" || updateRaw === "all" ? updateRaw : null,
+        message: text(flags, "message") ?? "",
+        roots: texts(flags, "root").map((dir) => path.resolve(dir)),
+    });
+    if (result.write)
+        writeGolden(recordedPath, result.table, goldenShape(recordedText));
+    return result.envelope;
+}
+function gapFixCommand(flags) {
+    const dir = path.resolve(requireText(flags, "state"));
+    const line = int(flags, "line");
+    if (line === undefined || line < 1)
+        throw new Error("--line must be a positive integer");
+    const state = fixGap(loadState(dir), {
+        id: requireText(flags, "id"),
+        file: requireText(flags, "file"),
+        line,
+        guard: requireText(flags, "guard"),
+        commit: requireText(flags, "commit"),
+        root: path.resolve(text(flags, "root") ?? dir),
+    });
+    saveState(dir, state);
+    const gap = state.gaps.find((item) => item.id === requireText(flags, "id"));
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: true,
+        command: "gap.fix",
+        summary: `${gap?.id} is fixed, guarded by ${gap?.guard}.`,
+        next: "Run status.",
+        nextCall: { argv: ["status", "--state", dir] },
+    };
+}
+function gapRevertCommand(flags) {
+    const dir = path.resolve(requireText(flags, "state"));
+    const reverted = revertGap(loadState(dir), requireText(flags, "id"));
+    saveState(dir, reverted.state);
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: true,
+        command: "gap.revert",
+        summary: reverted.text,
+        next: reverted.text,
+        nextCall: null,
+    };
+}
+function guardCommand(flags) {
+    const dir = path.resolve(requireText(flags, "state"));
+    const guard = requireText(flags, "guard");
+    parseGuard(guard);
+    const result = guardAllows(loadState(dir), guard, text(flags, "message") ?? "", path.resolve(text(flags, "root") ?? dir));
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: result.ok,
+        command: "guard.check",
+        summary: result.summary,
+        next: result.ok ? "The guard check passed." : "Add a Guard-Change trailer naming the guard, or restore it.",
+        nextCall: null,
+    };
+}
+function findingsCommand(flags) {
+    const dir = path.resolve(requireText(flags, "state"));
+    const status = text(flags, "status");
+    if (status !== "open" && status !== "fixed" && status !== "equivalent" && status !== "wont-fix") {
+        throw new Error("--status must be open, fixed, equivalent, or wont-fix");
+    }
+    const id = requireText(flags, "id");
+    const reason = requireText(flags, "reason");
+    const finding = {
+        id,
+        status,
+        reason,
+    };
+    const agent = text(flags, "agent");
+    if (agent)
+        finding.agent = agent;
+    const file = text(flags, "file");
+    const line = int(flags, "line");
+    if (file && line !== undefined) {
+        const source = readSourceLine(path.resolve(text(flags, "root") ?? dir, file), line);
+        if (source === null)
+            throw new Error("decision line does not exist");
+        finding.file = file;
+        finding.line = line;
+        finding.hash = lineHash(source);
+        const state = loadState(dir);
+        const decisions = state.decisions.filter((item) => item.id !== id);
+        decisions.push({ id, file, line, hash: finding.hash, status, reason });
+        saveState(dir, { ...state, decisions });
+    }
+    appendFinding(dir, finding);
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: true,
+        command: "findings.add",
+        summary: `Recorded ${id} as ${status}.`,
+        next: "Run status.",
+        nextCall: null,
+    };
+}
+function statusCommand(flags) {
+    const dir = path.resolve(requireText(flags, "state"));
+    const root = path.resolve(text(flags, "root") ?? dir);
+    const pagePath = path.resolve(text(flags, "page") ?? "PROBATIO.md");
+    const scoresPath = text(flags, "scores");
+    const score = scoresPath ? JSON.parse(readFileSync(scoresPath, "utf8")) : null;
+    const view = statusEnvelope(dir, root, score, text(flags, "agent") ?? null);
+    mkdirSync(path.dirname(pagePath), { recursive: true });
+    writeFileSync(pagePath, view.page);
+    return view.envelope;
+}
+function sealCommand(flags) {
+    const dir = path.resolve(requireText(flags, "state"));
+    const from = text(flags, "from");
+    let ids = texts(flags, "id");
+    if (from) {
+        const parsed = JSON.parse(readFileSync(from, "utf8"));
+        const list = Array.isArray(parsed) ? parsed : parsed.ids ?? [];
+        const fraction = Number(text(flags, "fraction") ?? "0.2");
+        if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1)
+            throw new Error("--fraction must be between 0 and 1");
+        ids = chooseSealed(list, fraction, int(flags, "seed") ?? 20261004);
+    }
+    sealIds(dir, ids);
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: true,
+        command: "seal",
+        summary: `Sealed ${ids.length} ids.`,
+        next: "status, PROBATIO.md, and the queue omit them.",
+        nextCall: null,
+        sealedCount: ids.length,
+    };
+}
+function queueSeedCommand(flags) {
+    const dir = path.resolve(requireText(flags, "state"));
+    const written = seedQueue(dir, texts(flags, "id"));
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: true,
+        command: "queue.seed",
+        summary: `Seeded ${written.length} queue items.`,
+        next: "Claim one.",
+        nextCall: null,
+        seeded: written,
+    };
+}
+function queueClaimCommand(flags) {
+    const dir = path.resolve(requireText(flags, "state"));
+    const now = int(flags, "now") ?? Date.now();
+    const lease = int(flags, "lease-ms") ?? 600_000;
+    const result = claimItem(dir, requireText(flags, "id"), requireText(flags, "agent"), now, lease);
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: result.ok,
+        command: "queue.claim",
+        summary: result.summary,
+        next: result.ok ? "Work the claim, then check-kill it." : "Pick another item.",
+        nextCall: null,
+    };
+}
+function queueReapCommand(flags) {
+    const dir = path.resolve(requireText(flags, "state"));
+    const now = int(flags, "now") ?? Date.now();
+    const returned = reapClaims(dir, now);
+    return {
+        schemaVersion: SCHEMA_VERSION,
+        ok: true,
+        command: "queue.reap",
+        summary: `Returned ${returned.length} expired claims.`,
+        next: returned.length === 0 ? "Nothing expired." : "The expired claims are back in the queue.",
+        nextCall: null,
+        returned,
+    };
+}
+async function checkKillCommand(flags, id) {
+    if (!id)
+        throw new Error("check-kill needs a mutant id");
+    const packageDir = path.resolve(requireText(flags, "package"));
+    const patchDirs = texts(flags, "patches").map((dir) => path.resolve(dir));
+    if (patchDirs.length === 0)
+        throw new Error("--patches is required");
+    const build = buildCommand(flags);
+    return checkKill(id, {
+        packageDir,
+        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
+        commit: text(flags, "commit") ?? "HEAD",
+        patchDirs,
+        outDir: path.resolve(requireText(flags, "out")),
+        direction: "forward",
+        workers: 1,
+        concurrency: 1,
+        maxMinutes: int(flags, "max-minutes") ?? 3,
+        maxMutants: null,
+        build,
+        testsDir: text(flags, "tests-dir") ?? "tests",
+        unset: ["SOLARI_API_KEY", "AUSPEX_LIVE"],
+        suiteTimeoutMs: int(flags, "suite-timeout-ms") ?? 60_000,
+        testTimeoutMs: int(flags, "test-timeout-ms") ?? 30_000,
+        confirm: bool(flags, "confirm", true),
+        affected: false,
+        agent: text(flags, "agent") ?? null,
+        onProgress: (line) => process.stderr.write(`${line}\n`),
+    });
+}
+async function verifyCommand(flags) {
+    const packageDir = path.resolve(requireText(flags, "package"));
+    return verifyChange({
+        packageDir,
+        repoDir: path.resolve(text(flags, "repo") ?? gitRoot(packageDir)),
+        outDir: path.resolve(requireText(flags, "out")),
+        base: text(flags, "base") ?? "HEAD",
+        commit: text(flags, "commit") ?? "HEAD",
+        maxMutants: int(flags, "max-mutants") ?? 4,
+        maxMinutes: int(flags, "max-minutes") ?? 3,
+        maxTests: int(flags, "max-tests") ?? null,
+        onProgress: (line) => process.stderr.write(`${line}\n`),
+    });
+}
+function gitRoot(cwd) {
+    const result = git(cwd, ["rev-parse", "--show-toplevel"]);
+    if (result.status !== 0)
+        throw new Error("package is not inside a git repository. Pass --repo.");
+    return result.stdout.trim();
+}
+function finish(envelope, human) {
+    process.stdout.write(render(envelope, human));
+    process.exit(envelope.ok ? 0 : 1);
+}
+/** Omitted `--build` and `--no-build` both mean no build. `--build <cmd>` opts in. */
+function buildCommand(flags) {
+    const values = flags.get("build");
+    if (!values || values.length === 0)
+        return null;
+    const last = values[values.length - 1];
+    if (typeof last !== "string")
+        return null;
+    const parts = last.split(" ").filter(Boolean);
+    return parts.length > 0 ? parts : null;
+}

package/dist/contract.js

@@ -0,0 +1,29 @@
+import { homedir } from "node:os";
+export const SCHEMA_VERSION = 1;
+/** Replace the home directory so a result never carries a user's name or home path. */
+export function scrub(value, home = homedir()) {
+    if (typeof value === "string") {
+        if (!home || !value.includes(home))
+            return value;
+        return value.split(home).join("~");
+    }
+    if (Array.isArray(value))
+        return value.map((item) => scrub(item, home));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value))
+            out[key] = scrub(item, home);
+        return out;
+    }
+    return value;
+}
+export function render(envelope, human, home = homedir()) {
+    const clean = scrub(envelope, home);
+    if (!human)
+        return `${JSON.stringify(clean, null, 2)}\n`;
+    const lines = [clean.summary, clean.next];
+    const call = clean.nextCall;
+    if (call && Array.isArray(call.argv))
+        lines.push(`next call: probatio ${call.argv.join(" ")}`);
+    return `${lines.filter((line) => line.length > 0).join("\n")}\n`;
+}