@popovych.co/witness 0.8.0 → 0.10.0

package/README.md

@@ -117,6 +117,21 @@ witness commits the payload. It refuses the whole run if a payload path carries
 uncommitted change (`payload-dirty`) or if the CLI you are running is older than the
 payload already installed (`cli-behind-payload`).
 
+From **0.10.0** onward `init` installs into **every home of the repository** — the primary
+root and each live `.witness/worktrees/<plan-id>` — because a worktree is a branch
+checkout, so its payload is a different file on a different timeline. A worktree cut
+before an upgrade used to keep the old pin forever, and the old pin is what selects the
+CLI that runs there. Every home is preflighted before any is written, so a dirty payload
+in one refuses the whole run rather than leaving the set half-upgraded, and `witness check`
+now reports `payload-stale` per home and names the stale one.
+
+The same release makes the bound structural: every journal entry records the CLI that
+wrote it, and a CLI older than anything the repository's state has seen refuses every verb
+with `cli-behind-state` rather than answering from rules the repository has moved past.
+`witness floor --show` reports the bound. If you are deliberately rolling back — a bad
+release, say — lower it first with `witness floor --set <version> --note <why>`; the
+decision is journaled, and `floor` is the one verb that still runs under a bound it fails.
+
 ### Support tiers
 
 | Tier | Agents | What they get |

package/dist/cli.js

@@ -1,7 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync } from 'node:fs';
 import { configPath } from './config.js';
+import { stateFloor } from './floor.js';
 import { primaryRoot } from './gitio.js';
+import { renderRefusal, v } from './refusal.js';
+import { NPX_LATEST, compareTriple, version } from './version.js';
 export const EXIT = { OK: 0, FINDINGS: 1, REFUSED: 2, BLOCKED: 3 };
 const VERBS = {
     recover: () => import('./verbs/recover.js'),
@@ -32,6 +34,9 @@ const VERBS = {
     rename: () => import('./verbs/rename.js'),
     sync: () => import('./verbs/sync.js'),
     calibrate: () => import('./verbs/calibrate.js'),
+    // Row 116's valve. Exempt from the floor gate in `main`, because a repository that
+    // refuses every verb must still be able to run the one that unrefuses it.
+    floor: () => import('./verbs/floor.js'),
 };
 // answered centrally so no verb can crash on --help (several parse argv
 // strictly); each line mirrors the verb's own usage refusal where one exists
@@ -41,7 +46,8 @@ const VERB_USAGE = {
     calibrate: 'witness calibrate <exact-model-id> [--suite all|reviewers|skills] [--only <name>] [--samples <n>] [--publish]',
     check: 'witness check',
     clean: 'witness clean',
-    decide: 'witness decide <gate> <target> --approve|--revise|--stop [--override] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]',
+    decide: 'witness decide <gate> <target> --approve|--revise|--stop [--override] [--repair] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]',
+    floor: 'witness floor --show | --set <triple> --note <why>',
     design: 'witness design <spec-id> --file <html> | --reconfirm | --open',
     diff: 'witness diff <spec-id>',
     'dispatch-report': 'witness dispatch-report <plan-id> --steps-assigned <n> --steps-completed <n> [--tokens <n>] [--tool-uses <n>] [--duration-ms <n>]',
@@ -61,10 +67,10 @@ const VERB_USAGE = {
     'test-evidence': 'witness test-evidence <plan-id> --phase red|green',
     'verify-red': 'witness verify-red <plan-id> [--base <ref>]',
 };
-export function version() {
-    const pkg = JSON.parse(readFileSync(join(new URL('.', import.meta.url).pathname, '..', 'package.json'), 'utf8'));
-    return pkg.version;
-}
+// Row 116 moved the body to version.ts, which journal.ts can import without closing a
+// cycle. Re-exported here because eleven call sites already ask the CLI shell for it and
+// the question they are asking has not changed.
+export { version };
 export function usage() {
     return [
         'witness — spec-led pipeline: specs are state, plans are motion',
@@ -79,6 +85,38 @@ export async function main(ctx, argv) {
         ctx.out(version());
         return EXIT.OK;
     }
+    // Row 116. Above the verb table on purpose — including above the bare-`witness`
+    // dashboard route, which reads the same state every verb does. The invariant is "one
+    // repository, one witness version", and a per-verb opt-in is a list some future verb
+    // forgets to join.
+    //
+    // This is the guard row 102's `cli-behind-payload` structurally could not be. That one
+    // fires inside the home it protects, so a home frozen at an old pin runs an old CLI that
+    // never learned to check — which is how two sessions a lifecycle apart each computed a
+    // different next stage, each redirected to the other's home, and each honestly ended its
+    // turn. The state is the one thing every home shares, so the state is where the bound
+    // belongs.
+    //
+    // Forward-only, and the text must never imply otherwise: a CLI published before this row
+    // cannot run this code. Homes already frozen are found by `check` and repaired by `init`.
+    //
+    // Two exemptions, both load-bearing. `floor` is how a bad publish is recovered from — a
+    // repository that refuses every verb must still be able to run the one that unrefuses it.
+    // An explicit help request is information, and refusing to print a usage line teaches
+    // the human nothing they can act on.
+    const helpRequested = verb === 'help' || verb === '--help'
+        || rest.includes('--help') || rest.includes('-h');
+    if (!helpRequested && verb !== 'floor') {
+        const gateRoot = primaryRoot(ctx.cwd);
+        if (gateRoot.ok) {
+            const floor = stateFloor(gateRoot.value);
+            if (floor !== undefined && (compareTriple(version(), floor.pin) ?? 0) < 0) {
+                renderRefusal([v('witness', 'cli-behind-state', `this CLI is ${version()}, this repository's state was written by ${floor.pin}`, `a CLI at or ahead of ${floor.pin} — run ${NPX_LATEST} init --agent <name>; if you are `
+                        + `deliberately rolling back, lower the bound first with witness floor --set ${version()} --note <why>`)]).forEach((l) => ctx.err(l));
+                return EXIT.REFUSED;
+            }
+        }
+    }
     if (!verb || verb === 'help' || verb === '--help') {
         if (!verb) {
             const rootRes = primaryRoot(ctx.cwd);
@@ -99,5 +137,21 @@ export async function main(ctx, argv) {
         ctx.err(usage());
         return EXIT.REFUSED;
     }
-    return (await load()).run(ctx, rest);
+    try {
+        return await (await load()).run(ctx, rest);
+    }
+    catch (e) {
+        // Row 113. Eight verbs parse argv with node's strict `parseArgs`, which THROWS on a
+        // stray positional or a mistyped flag. bin.ts's crash net then rendered a typo as
+        // `unexpected-error … a bug — re-run with the same arguments and report this line`:
+        // the tool asked to be reported for a mistake it could answer with its own usage. This
+        // is the one throw class that is a user statement rather than a witness fault, and the
+        // usage line lives right here. Anything else still reaches bin.ts unchanged.
+        const code = e.code;
+        if (typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS')) {
+            renderRefusal([v(verb, 'bad-arguments', String(e.message).split('.')[0].slice(0, 160), VERB_USAGE[verb] ?? `witness ${verb} --help`)]).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        throw e;
+    }
 }

package/dist/floor.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { journalRel } from './journal.js';
+import { compareTriple } from './version.js';
+// Row 116. The state's own answer to "what is the oldest CLI allowed to touch this
+// repository", derived from the `w` stamps entryLine writes and stored nowhere. Derived
+// because a stored floor is a second source of truth that drifts from the entries it
+// summarises — the shape rows 93, 95 and 96 all name — and because a derived one cannot
+// be lowered by editing a file, only by a journaled decision (verbs/floor.ts).
+//
+// MAXIMUM, not most-recent: a downgraded CLI writing a lower stamp after a higher one is
+// exactly the event this guards against, and a floor that fell to the last writer would
+// ratify the regression it exists to refuse.
+//
+// `undefined` means the state carries no readable stamp at all — every repository written
+// before this row shipped. It is silence, not zero: a floor of 0.0.0 would be a claim the
+// state never made, and it would refuse nothing anyway.
+export function stateFloor(root) {
+    const dir = join(root, '.witness', 'journal');
+    if (!existsSync(dir))
+        return undefined;
+    // An explicit decision outranks the derived maximum — including downward, which is the
+    // only reason the verb exists. Latest wins, so a second rollback supersedes the first:
+    // the last decision is the state, the same doctrine D94 applies to gate decisions.
+    const pinned = entries(root, FLOOR_STREAM)
+        .filter((e) => e.t === 'policy-pin' && e.key === FLOOR_KEY && typeof e.pin === 'string')
+        .at(-1);
+    if (pinned !== undefined)
+        return { pin: pinned.pin, stream: 'a human decision' };
+    let best;
+    for (const file of readdirSync(dir).filter((f) => f.endsWith('.jsonl')).sort()) {
+        const stream = file.slice(0, -'.jsonl'.length);
+        for (const e of entries(root, stream)) {
+            if (typeof e.w !== 'string')
+                continue;
+            const pin = e.w;
+            // `compareTriple(pin, pin)` is the parse check: undefined means CANNOT COMPARE, the
+            // same contract install.ts's two guards read it under. A stamp we cannot read must
+            // never raise a bound — that would refuse a legal CLI over a typo.
+            if (compareTriple(pin, pin) === undefined)
+                continue;
+            if (best === undefined || (compareTriple(pin, best.pin) ?? 0) > 0)
+                best = { pin, stream };
+        }
+    }
+    return best;
+}
+// The journal stream a floor decision lives in. Its first entry is a policy-pin, never a
+// recap, so `effortStreams` does not mistake it for an effort.
+export const FLOOR_STREAM = 'floor';
+export const FLOOR_KEY = 'floor';
+// Deliberately NOT journal.ts's readStream, whose bare JSON.parse throws. This runs on
+// EVERY verb now, so one unreadable line would brick the whole CLI — including `floor`
+// itself, the one verb that could unstick it. readStream's strict parse stays right for
+// callers that need the entry; a bound derived from stamps needs only the lines it can
+// actually read, and skipping the rest is the honest reading of a damaged file.
+function entries(root, stream) {
+    const path = join(root, journalRel(stream));
+    if (!existsSync(path))
+        return [];
+    const out = [];
+    for (const raw of readFileSync(path, 'utf8').split('\n')) {
+        if (raw === '')
+            continue;
+        try {
+            out.push(JSON.parse(raw));
+        }
+        catch {
+            // a line we cannot parse carries no decision and no stamp we can trust — the same
+            // answer as a line that never had one
+        }
+    }
+    return out;
+}

package/dist/gate.js

@@ -14,7 +14,8 @@ import { kv, rows } from './toon.js';
 import { loadMatrix, resolveModel, SESSION_DEFAULT } from './model.js';
 import { docKeysFor, docsBlock, invokeReviewer, loadLensDocs, parseVerdictText, pinsBlock, promptsSha, resolvePrompt } from './reviewer.js';
 import { anchorMenu, parseVerdict, verdictViolations } from './verdict.js';
-import { ROUND_BOUND, appendKind, boundReached, fellBack, lastGateRun, roundsSinceApprove, runsSinceReset, } from './rounds.js';
+import { ROUND_BOUND, appendKind, boundReached, fellBack, lastGateRun, liveExits, roundBudget, roundsSinceApprove, runsSinceReset, } from './rounds.js';
+export { liveExits } from './rounds.js';
 import { gateSettled } from './verbs/next.js';
 import { prepareStamp, writeStamp } from './stamp.js';
 const GATES = new Map();
@@ -40,27 +41,16 @@ export function batteryFor(cfg, gate, cls) {
     }
     return ok(picked);
 }
-// Which decisions are legal RIGHT NOW is a pure function of journal state, so it belongs
-// where the state is. Skills used to recite a fixed triple, which is wrong at the bound
-// (D67's endgame set) — and now wrong in three more states.
-export function liveExits(gate, target, entries, stale) {
-    // The bound outranks staleness: at the bound the gate short-circuits and will not run
-    // again (:227), so "re-gate" is the D67 lie whatever the sha says. Stale content only
-    // removes APPROVE from the endgame — a human cannot honestly stamp bytes no battery
-    // read — which is the same set decide's stale-verdict refusal names.
-    if (boundReached(entries, gate)) {
-        return stale
-            ? `witness decide ${gate} ${target} --revise --upstream <id> | --stop`
-            : `witness decide ${gate} ${target} --approve --override | --revise --upstream <id> | --stop`;
-    }
-    if (stale)
-        return `witness gate ${gate} ${target}`;
-    return `witness decide ${gate} ${target} --approve | --revise --note "<why>" | --revise --upstream <id> | --stop`;
-}
-export function renderGateRun(ctx, entry, mode) {
+// `entries` is the stream AS OF AFTER this entry: without it the renderer cannot tell the
+// round that spends the budget from any other, and rows 109/110 are both about that round.
+// `help: false` is for callers that render their own `exits:` line (`decide --show`).
+export function renderGateRun(ctx, entry, mode, opts = {}) {
+    const entries = opts.entries ?? [];
+    const budget = opts.entries ? roundBudget(entries, entry.gate) : ROUND_BOUND;
+    const atBound = opts.entries !== undefined && boundReached(entries, entry.gate);
     ctx.out(kv('gate', entry.gate));
     ctx.out(kv('target', entry.artifact));
-    ctx.out(kv('round', `${entry.round} of ${ROUND_BOUND}${mode === 'resume' ? ' (resume — content unchanged)' : ''}`));
+    ctx.out(kv('round', `${entry.round} of ${budget}${mode === 'resume' ? ' (resume — content unchanged)' : ''}`));
     ctx.out(kv('reviewed', entry.reviewed_sha.slice(0, 7)));
     ctx.out(kv('model', `${entry.model} · calibration: ${entry.calibration}${entry.cached ? ' · cached' : ''}`));
     if (entry.skipped?.length)
@@ -84,11 +74,20 @@ export function renderGateRun(ctx, entry, mode) {
         ctx.out(kv('standing-stop', entry.standing));
     ctx.out(kv('outcome', entry.outcome));
     if (entry.outcome !== 'passed') {
-        // `[]` keeps this a pure formatter over the entry it was handed — callers that know
-        // the stream (`--show`) render their own `exits:` line from the real entries. The
-        // non-bound triple is correct for runGate's own post-run render: a run that reached
-        // the bound short-circuits before rendering.
-        ctx.out(`help: ${liveExits(entry.gate, entry.artifact, [], false)}`);
+        // Row 110. The round that SPENDS the budget is the one that has to say so. It rendered
+        // like any other, so the natural next act — fix the finding, re-gate — was advertised
+        // by the help line below and then refused twice: the gate short-circuits, and the edit
+        // that answered the finding forfeits `--approve` under D75. Nothing warned, and the
+        // finding is itself an instruction to edit. Printed above the `help:` suppression, not
+        // inside it: `decide --show` renders its own exits and is the surface a human reads
+        // while deciding — the one place this warning is most owed.
+        if (atBound) {
+            ctx.out(kv('last-round', 'the round budget is spent — the gate will not run again, and an edit from here forfeits --approve (the verdict would describe an older tree)'));
+        }
+        // Without `entries` this stays a pure formatter over the entry it was handed, and the
+        // off-bound triple is the right answer; with them it tells the truth at the bound too.
+        if (opts.help !== false)
+            ctx.out(`help: ${liveExits(entry.gate, entry.artifact, entries, false)}`);
     }
 }
 // Row 79: the human approving a plan sees the run's shape before it starts.
@@ -139,9 +138,9 @@ export async function runGate(ctx, gateName, target, flags) {
         renderRefusal(batteryR.violations).forEach((l) => ctx.err(l));
         return EXIT.REFUSED;
     }
-    const skip = new Set(input.skipLenses ?? []);
+    const skip = new Map((input.skipLenses ?? []).map((s) => [s.lens, s.why]));
     const active = batteryR.value.filter((n) => !skip.has(n));
-    const dropped = batteryR.value.filter((n) => skip.has(n));
+    const dropped = batteryR.value.filter((n) => skip.has(n)).map((n) => `${n} — ${skip.get(n)}`);
     const entries = readStream(root, target);
     const pins = policyPins(entries);
     const pinsText = pinsBlock(pins);
@@ -216,7 +215,24 @@ export async function runGate(ctx, gateName, target, flags) {
             .forEach((l) => ctx.err(l));
         return EXIT.REFUSED;
     }
-    const kind = flags.fresh ? { kind: 'fresh' } : appendKind(entries, spec.gate, key);
+    let kind = flags.fresh ? { kind: 'fresh' } : appendKind(entries, spec.gate, key);
+    // Row 112. The cache key is the REVIEWED content digest, but the deterministic checks
+    // read inputs it cannot see — decompose's `goal-coverage`/`spec-coverage` read journaled
+    // `covers`, `amendment-ack` reads a sibling plan's pin, `graph` reads the whole canon. So
+    // correcting a goal mapping left the doc bytes untouched, the key unmoved, and `resume`
+    // served a blocking finding describing a state that no longer existed; `--fresh` was the
+    // only escape, and an operator who did not think of it spent a human decision on it.
+    // `resolve` has already recomputed the checks by this point — the fresh answer was in
+    // hand and thrown away. A flip is a new judgment, so it appends a real round rather than
+    // silently re-rendering; the verdicts are REPLAYED (`cached`), so no battery is spent.
+    // Compared on `ok` alone: a detail carries run output on some gates (timings, paths), and
+    // keying on it would append a round for every re-run of an unchanged tree.
+    const checkOk = (cs) => cs.map((c) => `${c.name}:${c.ok}`).sort().join('|');
+    if ((kind.kind === 'resume' || kind.kind === 'changed-nothing') &&
+        checkOk(kind.entry.checks) !== checkOk(input.checks) &&
+        kind.entry.outcome !== 'malformed' && (kind.entry.verdicts?.length ?? 0) > 0) {
+        kind = { kind: 'cached', from: kind.entry };
+    }
     // A key that moved for a NON-content reason — edited prompt, re-pinned model, new
     // witness version — un-settles just as quietly as --fresh did. Content moving explains
     // itself; this does not.
@@ -225,7 +241,7 @@ export async function runGate(ctx, gateName, target, flags) {
         ctx.err(`warning: reviewer setup changed — this run discards the settled approve on ${spec.gate} ${target}`);
     }
     if (kind.kind === 'resume') {
-        renderGateRun(ctx, kind.entry, 'resume');
+        renderGateRun(ctx, kind.entry, 'resume', { entries });
         printDispatchArithmetic(ctx, root, spec.gate, target);
         return kind.entry.outcome === 'passed' ? EXIT.OK : EXIT.FINDINGS;
     }
@@ -428,7 +444,7 @@ export async function runGate(ctx, gateName, target, flags) {
             renderRefusal(txn.violations).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
-        renderGateRun(ctx, entry, 'ran');
+        renderGateRun(ctx, entry, 'ran', { entries: [...entriesNow, entry] });
         printDispatchArithmetic(ctx, root, spec.gate, target);
         if (input.repin)
             ctx.out(kv('re-pinned', `derives-from → ${input.repin.sha.slice(0, 7)} (witnessed by the drift lane)`));

package/dist/gates/implement.js

@@ -104,7 +104,7 @@ registerGate({
         }
         else {
             // not UI-work: drop the lens if a battery names it (stages shrink, never skip)
-            skipLenses.push('design-reviewer');
+            skipLenses.push({ lens: 'design-reviewer', why: 'no design-from pin: not UI work' });
         }
         const checks = [];
         checks.push({ name: 'diff', ok: files.length > 0,

package/dist/install.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { version } from './cli.js';
@@ -114,6 +114,45 @@ export function installPayload(root, harness) {
     }
     return ok(out);
 }
+// Row 117. "Upgrade the repository" has always meant "upgrade one checkout of it":
+// installPayload had exactly one call site and it targeted the primary root, so nothing
+// ever refreshed a live worktree. A worktree is a branch checkout, so its payload is a
+// different file on a different timeline — the same property row 87 relies on to get the
+// payload to the agent at all, read the other way round.
+//
+// Root first, then worktrees in sorted order: the root is the home the human is standing
+// in, and if a later home fails they need the report to read top-down.
+export function payloadHomes(root) {
+    const dir = join(root, '.witness', 'worktrees');
+    if (!existsSync(dir))
+        return [root];
+    return [root, ...readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => join(dir, e.name))
+            .sort()];
+}
+// Preflight EVERY home before writing ANY. install.ts's standing doctrine is that a
+// refusal leaves nothing half-installed; across homes that matters more, not less — a
+// half-upgraded set of homes IS the skew row 116 refuses and this row prevents.
+export function installAllHomes(root, harness) {
+    const homes = payloadHomes(root);
+    const failures = homes.flatMap((home) => {
+        const pre = preflightPayload(home, harness);
+        // Name the home in the field, or a `payload-dirty` row over `.claude/commands/witness.md`
+        // is ambiguous across four checkouts of the same repository.
+        return pre.ok ? [] : pre.violations.map((x) => ({ ...x, field: home === root ? x.field : `${home}: ${x.field}` }));
+    });
+    if (failures.length > 0)
+        return refuse(failures);
+    const out = [];
+    for (const home of homes) {
+        const synced = installPayload(home, harness);
+        if (!synced.ok)
+            return refuse(synced.violations);
+        out.push({ home, synced: synced.value });
+    }
+    return ok(out);
+}
 function hasCommand(entries, command) {
     return (entries ?? []).some((e) => (e.hooks ?? []).some((h) => h.command === command));
 }

package/dist/journal.js

@@ -1,11 +1,18 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { version } from './version.js';
 const dir = (root) => join(root, '.witness', 'journal');
 export const journalRel = (id) => `.witness/journal/${id}.jsonl`;
 export function streamExists(root, id) {
     return existsSync(join(root, journalRel(id)));
 }
-export const entryLine = (entry) => JSON.stringify({ v: 1, ...entry });
+// Row 116. `w` is the CLI that wrote this line. Stamped HERE because entryLine is the
+// single funnel every state write passes through, so one edit covers fourteen entry types
+// and every verb without a widened signature to disagree over. It is what lets the state
+// name its own floor (floor.ts) instead of a stored number that drifts from the entries it
+// summarises — and it is why a repo can refuse a CLI older than its own history without
+// consulting any payload file, which is the guard row 102 structurally could not be.
+export const entryLine = (entry) => JSON.stringify({ v: 1, w: version(), ...entry });
 export function appendEntry(root, id, entry) {
     mkdirSync(dir(root), { recursive: true });
     const line = entryLine(entry);

package/dist/rounds.js

@@ -66,8 +66,51 @@ export function roundsSinceApprove(entries, gate) {
     return runsSinceReset(entries, gate)
         .filter((r) => r.outcome !== 'malformed' && !fellBack(r)).length;
 }
+// Row 109. The final round's blocking findings can only be VERIFIED by another round, so
+// fixing one at the bound forfeits `--approve` (D75 puts staleness at consumption) and the
+// only exits left are a full upstream re-cycle or a stop. A repair grant buys exactly one
+// more round. It is read from the journal window rather than counted anywhere: the window
+// closes on every reset `lastResetIndex` already knows about, so an approve, a
+// revise-upstream or a passed run refreshes the grant for the next game and nothing else
+// does. A second grant inside one window is therefore a no-op by construction, not by a
+// rule someone has to remember to write.
+export function repairGranted(entries, gate) {
+    return entries.slice(lastResetIndex(entries, gate) + 1).some((e) => isDecision(e, gate) && e.repair === true);
+}
+export function roundBudget(entries, gate) {
+    return ROUND_BOUND + (repairGranted(entries, gate) ? 1 : 0);
+}
 export function boundReached(entries, gate) {
-    return roundsSinceApprove(entries, gate) >= ROUND_BOUND;
+    return roundsSinceApprove(entries, gate) >= roundBudget(entries, gate);
+}
+// Which decisions are legal RIGHT NOW is a pure function of journal state, so it lives
+// where the state is — it was in `gate.ts`, which `next.ts` cannot import back (gate.ts
+// already imports next.ts), and that one-way edge is precisely why `next` grew three
+// hand-copied bound triples that then went stale twice over: they miss the repair grant
+// (109), and a fixed set is what this function was written to abolish. Skills used to
+// recite the same triple, which is wrong at the bound (D67's endgame set) and now wrong
+// in three more states.
+// `upstream` is the id the caller already resolved (next knows the owning effort; the gate
+// and decide surfaces do not) — the placeholder is a fallback, never a downgrade of a line
+// that used to name the real target.
+export function liveExits(gate, target, entries, stale, upstream = '<id>') {
+    // The bound outranks staleness: at the bound the gate short-circuits and will not run
+    // again (gate.ts), so "re-gate" is the D67 lie whatever the sha says. Stale content only
+    // removes APPROVE from the endgame — a human cannot honestly stamp bytes no battery
+    // read — which is the same set decide's stale-verdict refusal names.
+    if (boundReached(entries, gate)) {
+        // Row 109: the repair grant is an exit exactly while it is unspent, and it is the one
+        // the human standing at the bound with a fixed finding actually wants — naming it
+        // beside `--upstream` is what stops "fix it and re-gate" from being a move the tool
+        // advertises nowhere and refuses twice.
+        const repair = repairGranted(entries, gate) ? '' : ' | --revise --repair';
+        return stale
+            ? `witness decide ${gate} ${target} --revise --upstream ${upstream}${repair} | --stop`
+            : `witness decide ${gate} ${target} --approve --override | --revise --upstream ${upstream}${repair} | --stop`;
+    }
+    if (stale)
+        return `witness gate ${gate} ${target}`;
+    return `witness decide ${gate} ${target} --approve | --revise --note "<why>" | --revise --upstream ${upstream} | --stop`;
 }
 export function pendingDecision(entries, gate) {
     for (let i = entries.length - 1; i >= 0; i--) {

package/dist/verbs/check.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { adoptedCommits } from '../adopt.js';
 import { EXIT, version } from '../cli.js';
 import { DEFAULT_HARNESS, HARNESSES, judgeLine, loadHarness, resolveJudge, resolveSkills, skillPins } from '../harness.js';
-import { packageRoot } from '../install.js';
+import { packageRoot, payloadHomes } from '../install.js';
 import { latestPublished } from '../registry.js';
 import { NPX_LATEST, compareTriple } from '../version.js';
 import { probe } from '../probe.js';
@@ -254,14 +254,24 @@ export async function run(ctx, argv = []) {
             // whole suite stays green, because vitest reads from the repo root. installPayload
             // is where that condition refuses (`source-missing`); a diagnostic verb must not
             // crash on it, and must not report the repo as stale for it either.
-            const stale = installed.filter((p) => {
+            //
+            // Row 118: per HOME, not per repository. A worktree is a branch checkout, so its
+            // payload is a different file that can be a different age — and that is exactly the
+            // state row 116's floor cannot see, because the floor binds only CLIs at or after
+            // the version that introduced it while the frozen homes were cut before it. The
+            // root keeps its bare relative path; a worktree is named, or four checkouts of one
+            // repository all report `.claude/commands/witness.md` and the human cannot tell
+            // which of them is the rotten one.
+            const stale = payloadHomes(root).flatMap((home) => installed
+                .filter((p) => {
                 const src = join(packageRoot(), p.from);
-                if (!existsSync(src))
+                if (!existsSync(src) || !existsSync(join(home, p.to)))
                     return false;
-                return readFileSync(join(root, p.to), 'utf8') !== readFileSync(src, 'utf8');
-            });
+                return readFileSync(join(home, p.to), 'utf8') !== readFileSync(src, 'utf8');
+            })
+                .map((p) => (home === root ? p.to : `${home}: ${p.to}`)));
             if (stale.length > 0) {
-                findings.push(f('warn', 'harness', `${name}: payload`, 'payload-stale', `${stale.map((p) => p.to).join(' · ')} differ from what ${version()} ships — run ${NPX_LATEST} init --agent ${name}`));
+                findings.push(f('warn', 'harness', `${name}: payload`, 'payload-stale', `${stale.join(' · ')} differ from what ${version()} ships — run ${NPX_LATEST} init --agent ${name}`));
             }
         }
         const skills = resolveSkills(ctx.env, root, harness);

package/dist/verbs/decide.js

@@ -15,7 +15,7 @@ import { newRunId } from '../drift.js';
 import { renderRefusal, v } from '../refusal.js';
 import { short } from '../sha.js';
 import { kv, rows } from '../toon.js';
-import { boundReached, lastGateRun, openReopen, pendingDecision, roundsSinceApprove, } from '../rounds.js';
+import { ROUND_BOUND, boundReached, lastGateRun, openReopen, pendingDecision, repairGranted, roundsSinceApprove, } from '../rounds.js';
 import { prepareStamp, writeStamp } from '../stamp.js';
 const asEntry = (e) => e;
 function flagValue(argv, flag) {
@@ -47,7 +47,7 @@ export async function run(ctx, argv) {
     const [gate, target] = positional;
     const spec = gate ? gateSpec(gate) : undefined;
     if (!gate || !target || !spec) {
-        ctx.err('usage: witness decide <gate> <target> --approve|--revise|--stop [--override] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]');
+        ctx.err('usage: witness decide <gate> <target> --approve|--revise|--stop [--override] [--repair] [--note <t>] [--upstream <artifact|effort>] [--pin <policy>]… [--show]');
         return EXIT.REFUSED;
     }
     const rootR = primaryRoot(ctx.cwd);
@@ -113,7 +113,7 @@ export async function run(ctx, argv) {
             return EXIT.OK;
         }
         // pending (no disposition) or revise (the author's input): the verdict is actionable
-        renderGateRun(ctx, last, 'ran');
+        renderGateRun(ctx, last, 'ran', { entries, help: false });
         const shownPins = policyPins(entries);
         if (shownPins.length > 0)
             ctx.out(rows('pins', ['ordinal', 'text'], shownPins).join('\n'));
@@ -134,6 +134,7 @@ export async function run(ctx, argv) {
     const decision = picked[0].slice(2);
     const note = flagValue(argv, '--note');
     const override = argv.includes('--override');
+    const repair = argv.includes('--repair');
     const upstream = flagValue(argv, '--upstream');
     const pinTexts = flagValues(argv, '--pin');
     if (pinTexts.length > 0 && gate !== 'implement') {
@@ -146,11 +147,30 @@ export async function run(ctx, argv) {
         return EXIT.REFUSED;
     }
     const atBound = boundReached(entries, gate);
+    // Row 109. The grant is a REVISE — the human is sending the artifact back, they are just
+    // paying for the round that verifies the fix. Refusing the other spellings is not
+    // pedantry: `--approve --repair` reads as "approve and let it re-run", which is not a
+    // state this machine has, and silently ignoring the flag would journal an approve the
+    // human believed was something else.
+    if (repair && decision !== 'revise') {
+        renderRefusal([v('repair', 'repair-scope', `--${decision}`, 'witness decide … --revise --repair — a repair grant sends the artifact back for one verified round')])
+            .forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    if (repair && !atBound) {
+        renderRefusal([v('repair', 'repair-not-at-bound', `${roundsSinceApprove(entries, gate)} of ${ROUND_BOUND} rounds spent`, `the round bound — below it a plain revise already re-gates: witness decide ${gate} ${target} --revise --note "<why>"`)])
+            .forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    if (repair && repairGranted(entries, gate)) {
+        renderRefusal([v('repair', 'repair-spent', 'one repair round was already granted in this budget window', liveExits(gate, target, entries, false))]).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
     // at the bound the gate refuses to run again, so no fresh pending decision can
     // ever exist — the endgame decisions must stay reachable anchored to the last
     // run, or the target livelocks (incident c2692b93)
     const boundEndgame = atBound && (decision === 'stop' || (decision === 'approve' && override) ||
-        (decision === 'revise' && upstream !== undefined));
+        (decision === 'revise' && (upstream !== undefined || repair)));
     // D94: a revise is the author's INPUT, not a disposition — it leaves the run
     // undisposed, and with the content unchanged `gate` answers `changed-nothing` and
     // appends nothing, so a pending decision can never reappear. Every exit the human is
@@ -186,44 +206,50 @@ export async function run(ctx, argv) {
     const blockedCode = guardTxn(ctx, root);
     if (blockedCode !== undefined)
         return blockedCode;
-    if (decision === 'revise' && atBound && upstream === undefined) {
-        return renderBound(ctx, gate, target, entries, last !== undefined && nowSha !== undefined && nowSha !== last.reviewed_sha, 'upstream reopens the parent and resets the budget');
-    }
-    if (decision === 'approve' && atBound && !override) {
-        renderRefusal([v('decision', 'override-required', 'approve at the round bound', 'witness decide … --approve --override')]).forEach((l) => ctx.err(l));
-        return EXIT.REFUSED;
+    if (decision === 'revise' && atBound && upstream === undefined && !repair) {
+        return renderBound(ctx, gate, target, entries, last !== undefined && nowSha !== undefined && nowSha !== last.reviewed_sha, 'upstream reopens the parent and resets the budget; --repair buys one more round here');
     }
-    // A standing stop is only human judgment if the human was shown the thing. The gate
-    // refuses the same way, but the gate does not run at the round bound (gate.ts:176) —
-    // and approve is the act that stamps, so the line has to hold here too. Sha-keyed:
-    // re-authoring invalidates prior sight, as re-capturing invalidates a witnessed
-    // screenshot (D71). Only approve — revise and stop need no sight to be honest.
-    if (gate === 'design' && decision === 'approve') {
-        const unseen = designUnseen(root, cfgR.value.paths, target);
-        if (unseen !== undefined) {
-            renderRefusal([v('design', 'design-unseen', `no sight witnessed for ${short(unseen)}`, `a human shown this artifact — run: witness design ${target} --open`)]).forEach((l) => ctx.err(l));
-            return EXIT.REFUSED;
-        }
-    }
-    // A `human-decision` entry is a RECORD — honest about the sha it judged whatever the
-    // tree does afterward, which is why D76 declined a write-time staleness check. A stamp
-    // is an ASSERTION about current content (`status: approved`, `design: {sha}`), and D75
-    // puts staleness checks at consumption. approveMeta reads the artifact from disk and
-    // never consults the run, so approving after a re-author blessed unreviewed bytes.
-    // `currentSha` is undefined when it cannot be computed (no worktree, missing parent):
-    // approve then proceeds, and the entry still honestly records what it judged — this
-    // check must never convert an unrelated condition into a misleading refusal.
+    // Row 111. Every reason an approve cannot happen, in ONE refusal. These used to fire
+    // sequentially: `--approve` reported `override-required`, and only the re-run carrying
+    // `--override` reported the `stale-verdict` that was the actual blocker — the operator
+    // learned the real state one refusal later than the tool knew it, and at the bound that
+    // costs a round of thinking on an exit that was never available.
     if (decision === 'approve') {
+        const blockers = [];
+        if (atBound && !override) {
+            blockers.push(v('decision', 'override-required', 'approve at the round bound', 'witness decide … --approve --override'));
+        }
+        // A standing stop is only human judgment if the human was shown the thing. The gate
+        // refuses the same way, but the gate does not run at the round bound (gate.ts:176) —
+        // and approve is the act that stamps, so the line has to hold here too. Sha-keyed:
+        // re-authoring invalidates prior sight, as re-capturing invalidates a witnessed
+        // screenshot (D71). Only approve — revise and stop need no sight to be honest.
+        if (gate === 'design') {
+            const unseen = designUnseen(root, cfgR.value.paths, target);
+            if (unseen !== undefined) {
+                blockers.push(v('design', 'design-unseen', `no sight witnessed for ${short(unseen)}`, `a human shown this artifact — run: witness design ${target} --open`));
+            }
+        }
+        // A `human-decision` entry is a RECORD — honest about the sha it judged whatever the
+        // tree does afterward, which is why D76 declined a write-time staleness check. A stamp
+        // is an ASSERTION about current content (`status: approved`, `design: {sha}`), and D75
+        // puts staleness checks at consumption. approveMeta reads the artifact from disk and
+        // never consults the run, so approving after a re-author blessed unreviewed bytes.
+        // `currentSha` is undefined when it cannot be computed (no worktree, missing parent):
+        // approve then proceeds, and the entry still honestly records what it judged — this
+        // check must never convert an unrelated condition into a misleading refusal.
         const now = spec.currentSha?.(root, canon, cfgR.value, target);
         if (now !== undefined && now !== anchor.reviewed_sha) {
             // At the bound the gate will not re-run (gate.ts:176), so "go re-gate" would be
-            // the lie D67 was written about. Name the exits that actually work: approve is
-            // genuinely unavailable here — a human cannot honestly stamp bytes no gate read —
-            // but --stop and --revise --upstream both remain, so nothing livelocks.
-            renderRefusal([v('gate', 'stale-verdict', `verdict @${short(anchor.reviewed_sha)}, content @${short(now)}`, atBound
-                    ? `witness decide ${gate} ${target} --revise --upstream <id> | --stop (bound reached — the gate will not re-run)`
-                    : `a verdict describing current content — run: witness gate ${gate} ${target}`)])
-                .forEach((l) => ctx.err(l));
+            // the lie D67 was written about. `liveExits` names the ones that actually work —
+            // including the repair grant while it is unspent, which is the exit an operator who
+            // just fixed the finding is looking for.
+            blockers.push(v('gate', 'stale-verdict', `verdict @${short(anchor.reviewed_sha)}, content @${short(now)}`, atBound
+                ? `${liveExits(gate, target, entries, true)} (bound reached — the gate will not re-run as it stands)`
+                : `a verdict describing current content — run: witness gate ${gate} ${target}`));
+        }
+        if (blockers.length > 0) {
+            renderRefusal(blockers).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
         }
     }
@@ -231,6 +257,7 @@ export async function run(ctx, argv) {
         v: 1, t: 'human-decision', gate, artifact: target, round: anchor.round,
         decision: decision === 'revise' && upstream ? 'revise-upstream' : decision,
         ...(override ? { override: true } : {}),
+        ...(repair ? { repair: true } : {}),
         ...(note ? { note } : {}),
     };
     const priorPins = entries.filter((e) => e.t === 'policy-pin').length;
@@ -364,9 +391,15 @@ export async function run(ctx, argv) {
     ctx.out(kv('decided', `${gate} ${target} → ${entry.decision}${override ? ' (override)' : ''}`));
     for (const p of pinEntries)
         ctx.out(kv('pinned', `#${p.ordinal} ${p.text}`));
+    if (repair) {
+        // What was bought, and that it does not come again — a grant the human forgets is
+        // spent is a second walk into the same wall.
+        ctx.out(kv('repair', `one extra round granted — round ${ROUND_BOUND + 1} of ${ROUND_BOUND + 1} is the last, and the grant does not refresh until an approve, a revise-upstream or a passed run`));
+        ctx.out(`help: fix the finding, then re-run: witness gate ${gate} ${target}`);
+    }
     if (entry.decision === 'revise' || entry.decision === 'revise-upstream') {
         ctx.out('revise-context: (reconstructed from the journal — survives session death)');
-        renderGateRun(ctx, anchor, 'ran');
+        renderGateRun(ctx, anchor, 'ran', { entries, help: false });
         const pins = policyPins(readStream(root, target));
         if (pins.length > 0)
             ctx.out(rows('pins', ['ordinal', 'text'], pins).join('\n'));

package/dist/verbs/floor.js

@@ -0,0 +1,49 @@
+import { parseArgs } from 'node:util';
+import { EXIT } from '../cli.js';
+import { FLOOR_KEY, FLOOR_STREAM, stateFloor } from '../floor.js';
+import { primaryRoot } from '../gitio.js';
+import { appendEntry } from '../journal.js';
+import { renderRefusal, v } from '../refusal.js';
+import { kv } from '../toon.js';
+import { compareTriple, version } from '../version.js';
+// Row 116's safety valve. The floor is derived from what the state has seen, which is
+// correct until a published version turns out to be broken: then every repository that ran
+// it once carries a bound no fixed CLI can satisfy, and the tool has locked its users out
+// over its own defect. Lowering it is a human act with a reason, so it is journaled as a
+// policy-pin — the entry type row 83 added for exactly this shape — and never a flag on
+// another verb or a file someone can edit without leaving a trace.
+export async function run(ctx, argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: { show: { type: 'boolean' }, set: { type: 'string' }, note: { type: 'string' } },
+    });
+    const rootRes = primaryRoot(ctx.cwd);
+    if (!rootRes.ok) {
+        renderRefusal(rootRes.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const root = rootRes.value;
+    if (values.set !== undefined) {
+        // Both faults in one refusal, the way row 111 collects an approve's: a human who fixes
+        // one and learns about the other on the re-run has spent a turn witness could have saved.
+        const violations = [];
+        if (compareTriple(values.set, values.set) === undefined) {
+            violations.push(v('--set', 'bad-pin', values.set, 'a numeric triple such as 0.9.0 — prerelease ordering is out of scope (row 102)'));
+        }
+        if (values.note === undefined || values.note.trim() === '') {
+            violations.push(v('--note', 'note-required', 'absent', 'a reason — lowering the bound is a decision the journal has to be able to explain later'));
+        }
+        if (violations.length > 0) {
+            renderRefusal(violations).forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        appendEntry(root, FLOOR_STREAM, { t: 'policy-pin', key: FLOOR_KEY, pin: values.set, note: values.note });
+        ctx.out(kv('floor', `${values.set} — set by hand: ${values.note}`));
+        return EXIT.OK;
+    }
+    const floor = stateFloor(root);
+    ctx.out(floor === undefined
+        ? kv('floor', 'none — this state predates the writer stamp, so it claims no bound')
+        : kv('floor', `${floor.pin} · from ${floor.stream} · this CLI is ${version()}`));
+    return EXIT.OK;
+}

package/dist/verbs/init.js

@@ -6,7 +6,7 @@ import { configPath } from '../config.js';
 import { writeDoc } from '../fm.js';
 import { commitWithTrailer, primaryRoot, tryGit } from '../gitio.js';
 import { loadHarness, resolveDriver } from '../harness.js';
-import { installPayload, mergeSettings, preflightPayload, readIfExists, recordHarness, writeSettings, } from '../install.js';
+import { installAllHomes, mergeSettings, preflightPayload, readIfExists, recordHarness, writeSettings, } from '../install.js';
 import { probe } from '../probe.js';
 import { acquireLock } from '../lock.js';
 import { renderRefusal, v } from '../refusal.js';
@@ -119,13 +119,30 @@ export async function run(ctx, argv = []) {
         }
         let synced;
         if (harness !== undefined) {
-            const payload = installPayload(root, harness);
+            const payload = installAllHomes(root, harness);
             if (!payload.ok) {
                 renderRefusal(payload.violations).forEach(ctx.err);
                 return EXIT.REFUSED;
             }
-            synced = payload.value;
+            synced = payload.value.find((p) => p.home === root)?.synced ?? { written: [], overwritten: [] };
             files.push(...synced.written, ...synced.overwritten);
+            // Row 117. Each worktree is a separate checkout on a separate branch, so its payload
+            // can only be committed there — the root's commit below cannot reach it.
+            // commitWithTrailer, not a hand-rolled `commit --only`: `--only` resolves its
+            // pathspec against the index, so a freshly written payload the worktree has never
+            // tracked is "did not match any file(s) known to git" until the add it already does.
+            // It also carries the state-commit trailer and treats a no-op as silent success.
+            for (const { home, synced: s } of payload.value.filter((p) => p.home !== root)) {
+                const touched = [...s.written, ...s.overwritten];
+                if (touched.length === 0)
+                    continue;
+                const committed = commitWithTrailer(home, touched, `init(${harness.name}): agent payloads`);
+                if (!committed.ok) {
+                    renderRefusal(committed.violations).forEach(ctx.err);
+                    return EXIT.REFUSED;
+                }
+                ctx.out(kv('payload-synced', `${home} — ${touched.join(' · ')}`));
+            }
             if (harness.settings !== undefined) {
                 const merged = mergeSettings(readIfExists(root, harness.settings));
                 if (merged.changed) {

package/dist/verbs/next.js

@@ -15,7 +15,7 @@ import { worktreeFlow, worktreePath } from '../worktree.js';
 import { lazyStamp } from '../stamp.js';
 import { ok, refuse, renderRefusal, v } from '../refusal.js';
 import { kv, rows } from '../toon.js';
-import { ROUND_BOUND, boundReached, lastGateRun, openReopen, pendingDecision } from '../rounds.js';
+import { ROUND_BOUND, boundReached, lastGateRun, liveExits, openReopen, pendingDecision } from '../rounds.js';
 // A gate is settled only if the verdict that settled it still describes the CURRENT
 // content. `reviewed_sha` is the tree we actually judged; when the caller can compute
 // what that sha is now and the two differ, the approval has lapsed and the gate re-arms.
@@ -341,7 +341,7 @@ export function computeNext(root, ctx, canon, cfg) {
     for (const e of efforts) {
         if (boundReached(e.entries, 'decompose') && !gateSettled(e.entries, 'decompose')) {
             return {
-                line: `witness decide decompose ${e.slug} --approve --override | --revise --upstream ${e.slug} | --stop`,
+                line: liveExits('decompose', e.slug, e.entries, false, e.slug),
                 target: e.slug, note: 'round bound reached — human decision required',
             };
         }
@@ -353,7 +353,7 @@ export function computeNext(root, ctx, canon, cfg) {
             if (boundReached(entries, gate) && !gateSettled(entries, gate)) {
                 const up = gate === 'plan' ? String(plan.meta.parent) : id;
                 return {
-                    line: `witness decide ${gate} ${id} --approve --override | --revise --upstream ${up} | --stop`,
+                    line: liveExits(gate, id, entries, false, up),
                     target: id, note: 'round bound reached — human decision required',
                 };
             }
@@ -365,7 +365,7 @@ export function computeNext(root, ctx, canon, cfg) {
         if (boundReached(entries, 'design') && !gateSettled(entries, 'design')) {
             const eff = effortOf(root, id);
             return {
-                line: `witness decide design ${id} --approve --override | --revise --upstream ${eff ?? '<effort>'} | --stop`,
+                line: liveExits('design', id, entries, false, eff ?? '<effort>'),
                 target: id, note: 'round bound reached — human decision required',
             };
         }

package/dist/verbs/recap.js

@@ -5,7 +5,7 @@ import { EXIT } from '../cli.js';
 import { loadConfig } from '../config.js';
 import { ID_RE } from '../dsl.js';
 import { primaryRoot, stateCommit } from '../gitio.js';
-import { appendEntry, effortAbandoned, journalRel, readStream, streamExists } from '../journal.js';
+import { appendEntry, effortAbandoned, entryLine, journalRel, readStream, streamExists } from '../journal.js';
 import { acquireLock } from '../lock.js';
 import { renderRefusal, v } from '../refusal.js';
 import { kv } from '../toon.js';
@@ -120,7 +120,9 @@ export async function run(ctx, argv) {
             t: 'recap', effort: recap.effort, class: recap.class,
             goals: recap.goals, non_goals: recap.non_goals, constraints: recap.constraints, slices: recap.slices,
         };
-        const line = JSON.stringify({ v: 1, ...entry });
+        // entryLine, never a second inline JSON.stringify — completeTxn re-appends when this
+        // marker line differs from what appendEntry wrote, so the two must be one derivation.
+        const line = entryLine(entry);
         const stream = journalRel(recap.effort);
         const res = withTxn(root, { op: `recap(${recap.effort})`, files: [stream], journal: { stream: recap.effort, line } }, () => {
             appendEntry(root, recap.effort, entry);

package/dist/verbs/sync.js

@@ -14,6 +14,22 @@ export async function run(ctx, _argv) {
     const blocked = guardTxn(ctx, root);
     if (blocked !== undefined)
         return blocked;
+    // Row 114. `git pull --rebase` refuses on ANY unstaged TRACKED change, and every
+    // non-conflict failure below rendered as `rebase conflict — resolve manually`, which
+    // names neither the real condition nor a single file. A field report read that line as a
+    // structural deadlock ("ship owns the sole code commit, so the work is always unstaged")
+    // — sync runs in the primary root and never in a worktree, and the actual cause was one
+    // hand-edited tracked file. Untracked paths are deliberately not counted: git rebases
+    // around them, so refusing on them would invent a block that does not exist.
+    const dirty = tryGit(root, 'status', '--porcelain');
+    const tracked = dirty.ok
+        ? dirty.out.split('\n').filter((l) => l.trim() !== '' && !l.startsWith('??'))
+        : [];
+    if (tracked.length > 0) {
+        renderRefusal([v('worktree', 'worktree-dirty', tracked.map((l) => l.slice(3)).join(' · ').slice(0, 200), 'a clean tree — commit or stash the tracked edits, then witness sync (a rebase cannot run over them)')])
+            .forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
     const lockR = acquireLock(root);
     if (!lockR.ok) {
         renderRefusal(lockR.violations).forEach((l) => ctx.err(l));

package/dist/verbs/write.js

@@ -193,7 +193,12 @@ export async function run(ctx, argv) {
             ...(existing === undefined ? { created: true } : {}),
             ...(supersedes !== undefined ? { supersedes } : {}),
         };
-        const line = JSON.stringify({ v: 1, ...entry });
+        // entryLine, never a second inline JSON.stringify: completeTxn decides whether to
+        // re-append by comparing this marker line against the last journal line, so any field
+        // entryLine adds and this does not makes the two differ and the recovery duplicate the
+        // entry. Row 116's `w` stamp is what caught it; the shape is the one rows 93, 95 and
+        // 96 all name, and every other txn writer already calls entryLine.
+        const line = entryLine(entry);
         const supersededDesignRel = reslice ? designRel(cfg.value.paths, reslice.entry.artifact) : undefined;
         const files = [rel, stream,
             ...(reslice ? [reslice.doc.rel, journalRel(reslice.entry.artifact)] : []),
@@ -238,7 +243,7 @@ function journalRefusal(ctx, root, effort, artifact, violations) {
         t: 'write-refused', effort, artifact,
         rules: violations.map(({ field, rule }) => ({ field, rule })),
     };
-    const line = JSON.stringify({ v: 1, ...entry });
+    const line = entryLine(entry);
     const stream = journalRel(effort);
     const res = withTxn(root, { op: `write-refused(${artifact})`, files: [stream], journal: { stream: effort, line } }, () => {
         appendEntry(root, effort, entry);

package/dist/version.js

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 // The one home for "which version of witness is which". install.ts parsed the pin to
 // decide whether a payload was only a pin apart (row 102 killed that rule) and check.ts
 // re-declared the same regex inline — one question answered in two places, which is the
@@ -36,3 +38,13 @@ export function compareTriple(a, b) {
 // through a frozen /witness is `npx …@0.5.1 init`, which restamps 0.5.1 onto 0.5.1 — a
 // no-op that reads as compliance. Remedies name the version.
 export const NPX_LATEST = 'npx -y @popovych.co/witness@latest';
+// Row 116. Moved here from cli.ts. `journal.ts` stamps every entry with it and cannot
+// import the CLI shell without closing a cycle (cli → verbs/* → journal). This module
+// already claimed to be the one home for "which version of witness is which" while the
+// reader itself lived in the shell — the same split rows 93, 95 and 96 keep naming. The
+// single readFileSync is the exception to this file's no-I/O rule and the only one it
+// may ever have.
+export function version() {
+    const pkg = JSON.parse(readFileSync(join(new URL('.', import.meta.url).pathname, '..', 'package.json'), 'utf8'));
+    return pkg.version;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Evidence-gated spec-driven development pipeline for AI coding agents: brainstorm to PR in six stages, where specs are state, plans are motion, and no transition passes without evidence. Drives from Claude Code or Pi.",
   "keywords": [
     "spec-driven-development",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "witness",
   "description": "Spec-driven development with evidence gates: brainstorm → PR through six stages and five gates. Skills author, the pinned witness CLI writes state and witnesses evidence; gates stop where judgment is owed.",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "author": {
     "name": "Kostiantyn Popovych"
   },

package/plugin/commands/witness.md

@@ -10,7 +10,7 @@ The CLI decides, you act. If `$ARGUMENTS` contains `--manual`, append `--manual`
 Resolve the CLI once:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.10.0}"
 ```
 
 If the repo has no `witness.config.yaml`, run `$WITNESS init` first (one bootstrap commit), then proceed. If init or any verb refuses on a dirty tree, the human commits or cleans it — **never `git commit` yourself, anywhere, at any stage**: the CLI makes its own state commits, and the ship phase makes the sole code commit.

package/plugin/hooks/session-dashboard.sh

@@ -3,4 +3,4 @@
 # context). Silent everywhere that isn't a witness repo; failures swallowed:
 # session start must never hang or die on this.
 [ -f witness.config.yaml ] || exit 0
-${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.10.0} 2>/dev/null || true

package/plugin/skills/witness-brainstorm/SKILL.md

@@ -15,7 +15,7 @@ witness: ends in a confirmed scope recap, writes no document. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.10.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

package/plugin/skills/witness-decompose/SKILL.md

@@ -10,7 +10,7 @@ description: Slice a witness effort's confirmed recap into vertical spec slices,
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.10.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

package/plugin/skills/witness-design/SKILL.md

@@ -16,7 +16,7 @@ No text copied verbatim; the design-critic lens is new material. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.10.0}"
 ```
 
 - **Never edit `specs/**`, `plans/**`, or `designs/**`** — the CLI is the sole writer of state. Author HTML in `$(mktemp -d)` and hand it to `witness design`. (The canon guard blocks direct edits; the trailer audit catches end-runs.)

package/plugin/skills/witness-implement/SKILL.md

@@ -15,7 +15,7 @@ tests carry the parent spec's tag in their NAME. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.10.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

package/plugin/skills/witness-plan/SKILL.md

@@ -15,7 +15,7 @@ parent's criteria. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.10.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)

package/plugin/skills/witness-ship/SKILL.md

@@ -15,7 +15,7 @@ model can. See NOTICE.md. -->
 Resolve the CLI once per session:
 
 ```bash
-WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.8.0}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.10.0}"
 ```
 
 - **Never edit `specs/**` or `plans/**`** (the canon dirs — `paths:` in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under `$(mktemp -d)` and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)