@popovych.co/witness 0.4.1 → 0.5.1

package/README.md

@@ -101,13 +101,26 @@ either.
 
 | Key | Meaning |
 |---|---|
-| `harness: claude-code \| pi` | fallback used only when detection cannot answer. Order: `WITNESS_HARNESS` → `PI_CODING_AGENT` → `CLAUDECODE` → `harness:` → `claude-code` |
+| `harness: claude-code \| pi` | fallback used only when detection cannot answer. Order: `PI_CODING_AGENT` → `CLAUDECODE` → `harness:` → `claude-code` |
+| `gates.reviewerTimeoutMs` | milliseconds per reviewer invocation (default 600000) |
+
+There is no `provider:` key. `witness gate` spawns the RESOLVED harness's headless
+mode for every reviewer (Decision 88): claude-code renders bare Anthropic ids, pi
+renders `provider/model[:thinking]` with the provider witness knows it needs. The pi
+reviewer runs hermetic (`--no-extensions --no-skills --no-context-files`); machine
+extensions it must keep — e.g. an OAuth adapter that supplies your Anthropic auth —
+are declared in machine config, not env:
+
+```yaml
+# .witness/config.local.yaml — machine facts, gitignored, never committed
+reviewerExtensions:
+  - /Users/you/.pi/agent/npm/node_modules/pi-claude-oauth-adapter
+opener: xdg-open   # optional; nonstandard desktops only
+```
 
-There is no `provider:` key. Harnesses whose `--model` flag is `provider/id` (Pi) are
-rendered with the provider witness knows they need. That is not a preference: `witness
-gate` spawns the Claude CLI for every reviewer on every harness, and `gates.<stage>.model`
-drives **both** those reviewers and the implement session's own model — so the pin must be
-an Anthropic id, and a Pi implement session on a non-Anthropic model is not expressible.
+Repo facts live in `witness.config.yaml` (committed); machine facts live in
+`.witness/config.local.yaml` (gitignored). Every key has exactly one home — a key in
+the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 
 ## Verbs
 

package/dist/calibrate.js

@@ -114,14 +114,14 @@ export function distribute(samples, buckets) {
 }
 export const threshold = (samples) => Math.ceil(0.9 * samples);
 export const injectSamples = (samples) => Math.max(2, Math.ceil(samples / 5));
-export function runSample(ctx, harness, model, lens, suite, overlay) {
+export function runSample(ctx, harness, model, lens, suite, overlay, extras) {
     const { dir, files } = materialize(suite, overlay);
     const { reviewed, context } = composeReviewed(suite, dir, files);
     // same anchor-menu injection as the gate path — calibration must measure the
     // prompt condition production reviewers actually see
     const menu = anchorMenu(reviewed);
     const prompt = `${lens}\n\n${menu ? `${menu}\n\n` : ''}${renderReviewed(reviewed, context)}\n`;
-    const invoked = invokeReviewer(ctx, harness, { cwd: dir, prompt, model });
+    const invoked = invokeReviewer(ctx, harness, { cwd: dir, prompt, model, ...extras });
     if (!invoked.ok)
         return invoked; // invocation-layer failure aborts the run
     const raw = parseVerdictText(invoked.value.text);
@@ -139,7 +139,7 @@ export function runSample(ctx, harness, model, lens, suite, overlay) {
 function side() {
     return { ok: 0, total: 0 };
 }
-export async function runReviewerSuite(ctx, harness, model, reviewer, samples) {
+export async function runReviewerSuite(ctx, harness, model, reviewer, samples, extras) {
     const suiteR = loadReviewerSuite(reviewer);
     if (!suiteR.ok)
         return suiteR;
@@ -156,7 +156,7 @@ export async function runReviewerSuite(ctx, harness, model, reviewer, samples) {
     const perSeed = distribute(samples, suite.seeds.length);
     for (const [i, seed] of suite.seeds.entries()) {
         for (let n = 0; n < perSeed[i]; n += 1) {
-            const s = runSample(ctx, harness, model, lens, suite, seed.overlay);
+            const s = runSample(ctx, harness, model, lens, suite, seed.overlay, extras);
             if (!s.ok)
                 return s;
             catches.total += 1;
@@ -166,7 +166,7 @@ export async function runReviewerSuite(ctx, harness, model, reviewer, samples) {
     }
     for (const seed of suite.injects) {
         for (let n = 0; n < injectSamples(samples); n += 1) {
-            const s = runSample(ctx, harness, model, lens, suite, seed.overlay);
+            const s = runSample(ctx, harness, model, lens, suite, seed.overlay, extras);
             if (!s.ok)
                 return s;
             inject.total += 1;
@@ -175,7 +175,7 @@ export async function runReviewerSuite(ctx, harness, model, reviewer, samples) {
         }
     }
     for (let n = 0; n < samples; n += 1) {
-        const s = runSample(ctx, harness, model, lens, suite);
+        const s = runSample(ctx, harness, model, lens, suite, undefined, extras);
         if (!s.ok)
             return s;
         clean.total += 1;
@@ -185,13 +185,13 @@ export async function runReviewerSuite(ctx, harness, model, reviewer, samples) {
     const pass = catches.ok >= threshold(catches.total) && clean.ok >= threshold(clean.total) && inject.ok === inject.total;
     return ok({ reviewer, catches, clean, inject, pass });
 }
-export async function runReviewerSuites(ctx, harness, model, samples, only) {
+export async function runReviewerSuites(ctx, harness, model, samples, only, extras) {
     const names = [...PROMPT_NAMES].sort().filter((n) => only === undefined || n === only);
     if (names.length === 0)
         return refuse([v('--only', 'unknown-reviewer', only ?? '', PROMPT_NAMES.join(' '))]);
     const scores = [];
     for (const name of names) {
-        const r = await runReviewerSuite(ctx, harness, model, name, samples);
+        const r = await runReviewerSuite(ctx, harness, model, name, samples, extras);
         if (!r.ok)
             return r;
         scores.push(r.value);
@@ -324,7 +324,7 @@ function firstCriterionTag(meta) {
     const withTest = criteria.find((c) => typeof c.test === 'string');
     return withTest ? String(withTest.test).replace(/^@spec:/, '') : '';
 }
-export async function runDecomposeSeed(ctx, harness, model, seed) {
+export async function runDecomposeSeed(ctx, harness, model, seed, extras) {
     const { root } = seedScratchRepo(`decompose-${seed.id}`);
     const canonDir = join(seed.dir, 'canon');
     if (existsSync(canonDir)) {
@@ -348,7 +348,7 @@ export async function runDecomposeSeed(ctx, harness, model, seed) {
         `### witness index\n\n${indexH.out()}`,
         NONINTERACTIVE_OVERRIDE,
     ].join('\n\n');
-    const invoked = invokeReviewer(ctx, harness, { cwd: root, prompt, model });
+    const invoked = invokeReviewer(ctx, harness, { cwd: root, prompt, model, ...extras });
     if (!invoked.ok)
         return invoked;
     const raw = parseVerdictText(invoked.value.text);
@@ -413,7 +413,7 @@ export async function runDecomposeSeed(ctx, harness, model, seed) {
         return ok({ ok: false, why: `goals uncovered: ${uncovered.join(',')}` });
     return ok({ ok: true, why: 'first-try valid' });
 }
-export async function runPlanSeed(ctx, harness, model, seed) {
+export async function runPlanSeed(ctx, harness, model, seed, extras) {
     const { root } = seedScratchRepo(`plan-${seed.id}`);
     const recapText = readFileSync(join(seed.dir, 'recap.json'), 'utf8');
     const recap = JSON.parse(recapText);
@@ -446,7 +446,7 @@ export async function runPlanSeed(ctx, harness, model, seed) {
         `### witness diff ${parentId}\n\n${diffH.out()}`,
         NONINTERACTIVE_OVERRIDE,
     ].join('\n\n');
-    const invoked = invokeReviewer(ctx, harness, { cwd: root, prompt, model });
+    const invoked = invokeReviewer(ctx, harness, { cwd: root, prompt, model, ...extras });
     if (!invoked.ok)
         return invoked;
     const raw = parseVerdictText(invoked.value.text);
@@ -560,7 +560,7 @@ export async function runSkillSuites(ctx, harness, model, samples, opts = {}) {
         let total = 0;
         for (const [i, seed] of seeds.entries()) {
             for (let n = 0; n < perSeed[i]; n += 1) {
-                const r = await runDecomposeSeed(ctx, harness, model, seed);
+                const r = await runDecomposeSeed(ctx, harness, model, seed, opts.extras);
                 if (!r.ok)
                     return r;
                 total += 1;
@@ -577,7 +577,7 @@ export async function runSkillSuites(ctx, harness, model, samples, opts = {}) {
         let total = 0;
         for (const [i, seed] of seeds.entries()) {
             for (let n = 0; n < perSeed[i]; n += 1) {
-                const r = await runPlanSeed(ctx, harness, model, seed);
+                const r = await runPlanSeed(ctx, harness, model, seed, opts.extras);
                 if (!r.ok)
                     return r;
                 total += 1;

package/dist/config.js

@@ -98,6 +98,71 @@ export function resolveImplement(raw) {
     }
     return ok({ stepsPerDispatch: val });
 }
+export const DEFAULT_REVIEWER_TIMEOUT_MS = 600_000;
+// gates.* is otherwise read loosely at its consumers (stagePin); the timeout is
+// resolved here, typed, because a typo'd key silently defaulting to ten minutes is
+// exactly the ambient-value class row 90 removed from env.
+export function resolveGates(raw) {
+    const conf = raw.gates;
+    if (conf === undefined)
+        return ok({ reviewerTimeoutMs: DEFAULT_REVIEWER_TIMEOUT_MS });
+    if (typeof conf !== 'object' || conf === null || Array.isArray(conf)) {
+        return refuse([v('gates', 'invalid', String(conf), 'a map of gate settings')]);
+    }
+    const val = conf.reviewerTimeoutMs;
+    if (val === undefined)
+        return ok({ reviewerTimeoutMs: DEFAULT_REVIEWER_TIMEOUT_MS });
+    if (typeof val !== 'number' || !Number.isInteger(val) || val < 1) {
+        return refuse([v('gates.reviewerTimeoutMs', 'invalid', String(val), 'an integer >= 1 — milliseconds each reviewer invocation may take')]);
+    }
+    return ok({ reviewerTimeoutMs: val });
+}
+const LOCAL_KEYS = ['reviewerExtensions', 'opener'];
+export const localConfigPath = (root) => join(root, '.witness', 'config.local.yaml');
+export function loadLocalConfig(root) {
+    const p = localConfigPath(root);
+    if (!existsSync(p))
+        return ok({ reviewerExtensions: [] });
+    let raw;
+    try {
+        raw = parseYaml(readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        return refuse([v('.witness/config.local.yaml', 'yaml-parse', String(e.message).slice(0, 120), 'valid YAML')]);
+    }
+    const obj = (raw ?? {});
+    if (typeof obj !== 'object' || Array.isArray(obj)) {
+        return refuse([v('.witness/config.local.yaml', 'invalid', String(obj), 'a map of machine-local keys')]);
+    }
+    const violations = [];
+    for (const key of Object.keys(obj)) {
+        if (!LOCAL_KEYS.includes(key)) {
+            violations.push(v(key, 'unknown-local-key', key, `a machine-local key (${LOCAL_KEYS.join(' | ')}) — repo facts belong in witness.config.yaml`));
+        }
+    }
+    let reviewerExtensions = [];
+    const ext = obj.reviewerExtensions;
+    if (ext !== undefined) {
+        if (!Array.isArray(ext) || !ext.every((x) => typeof x === 'string' && x !== '')) {
+            violations.push(v('reviewerExtensions', 'invalid', JSON.stringify(ext), 'a list of extension paths handed to the harness reviewer spawn'));
+        }
+        else {
+            reviewerExtensions = ext;
+        }
+    }
+    let opener;
+    if (obj.opener !== undefined) {
+        if (typeof obj.opener !== 'string' || obj.opener === '') {
+            violations.push(v('opener', 'invalid', String(obj.opener), 'a command name or path'));
+        }
+        else {
+            opener = obj.opener;
+        }
+    }
+    if (violations.length)
+        return refuse(violations);
+    return ok({ reviewerExtensions, ...(opener !== undefined ? { opener } : {}) });
+}
 // Lenient path resolution for callers without a loaded Config (canon scan, git
 // state scoping): a missing or broken config falls back to the defaults — the
 // verbs own the refusal messaging via loadConfig, which validates paths strictly.
@@ -144,12 +209,16 @@ export function loadConfig(root) {
     const implement = resolveImplement(obj);
     if (!implement.ok)
         return refuse(implement.violations);
+    const gates = resolveGates(obj);
+    if (!gates.ok)
+        return refuse(gates.violations);
     return ok({
         schema,
         raw: obj,
         paths: paths.value,
         docs: docs.value,
         implement: implement.value,
+        gates: gates.value,
         warning: schema < SCHEMA_VERSION ? `schema ${schema} < ${SCHEMA_VERSION} — run witness migrate (reserved)` : undefined,
     });
 }

package/dist/drift.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { join } from 'node:path';
 import { EXIT } from './cli.js';
-import { loadConfig } from './config.js';
+import { loadConfig, loadLocalConfig } from './config.js';
 import { runCriteria } from './criteria.js';
 import { serializeDoc, writeDoc } from './fm.js';
 import { acquireLock } from './lock.js';
@@ -125,8 +125,20 @@ export async function deepDrift(root, ctx, canon, specId) {
         renderRefusal(hxR.violations).forEach(ctx.err);
         return EXIT.REFUSED;
     }
+    // Repo config may be broken here by design — the timeout falls to the default. A
+    // broken LOCAL file refuses instead: silently dropping declared extensions
+    // reproduces the exact misdiagnosed 400 this release exists to kill.
+    const localR = loadLocalConfig(root);
+    if (!localR.ok) {
+        renderRefusal(localR.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
     const prompt = `${lensR.value.contents}\n\n## Reviewed content\n\n### Spec: ${specId}\n${serializeDoc({ meta: doc.meta, body: doc.body })}\n\n(Deterministic lane: ${lane.ok ? lane.value.criteria.map((c) => `${c.id}:${c.ok ? 'ok' : 'fail'}`).join(' · ') : 'unrunnable'})\n`;
-    const invoked = invokeReviewer(ctx, hxR.value.harness, { cwd: root, prompt });
+    const invoked = invokeReviewer(ctx, hxR.value.harness, {
+        cwd: root, prompt,
+        timeoutMs: cfgR.ok ? cfgR.value.gates.reviewerTimeoutMs : undefined,
+        extensions: localR.value.reviewerExtensions,
+    });
     if (!invoked.ok) {
         renderRefusal(invoked.violations).forEach(ctx.err);
         return EXIT.REFUSED;

package/dist/gate.js

@@ -1,6 +1,6 @@
 import { join } from 'node:path';
 import { EXIT, version } from './cli.js';
-import { loadConfig } from './config.js';
+import { loadConfig, loadLocalConfig } from './config.js';
 import { writeDoc } from './fm.js';
 import { crashPoint, guardTxn, withTxn } from './txn.js';
 import { acquireLock } from './lock.js';
@@ -169,6 +169,15 @@ export async function runGate(ctx, gateName, target, flags) {
         return EXIT.REFUSED;
     }
     const harness = hxR.value.harness;
+    const localR = loadLocalConfig(root);
+    if (!localR.ok) {
+        renderRefusal(localR.violations).forEach((l) => ctx.err(l));
+        return EXIT.REFUSED;
+    }
+    const extras = {
+        timeoutMs: cfgR.value.gates.reviewerTimeoutMs,
+        extensions: localR.value.reviewerExtensions,
+    };
     const modelR = resolveModel(cfgR.value, loadMatrix(root, harness.name), spec.gate);
     if (!modelR.ok) {
         renderRefusal(modelR.violations).forEach((l) => ctx.err(l));
@@ -240,7 +249,7 @@ export async function runGate(ctx, gateName, target, flags) {
                 let answered;
                 for (;;) {
                     const id = chain[rung];
-                    const r = invokeReviewer(ctx, harness, { cwd: root, prompt, model: id === SESSION_DEFAULT ? undefined : id });
+                    const r = invokeReviewer(ctx, harness, { cwd: root, prompt, model: id === SESSION_DEFAULT ? undefined : id, ...extras });
                     if (r.ok) {
                         answered = r.value.text;
                         model = id;
@@ -314,6 +323,7 @@ export async function runGate(ctx, gateName, target, flags) {
             round: roundsSinceApprove(entriesNow, spec.gate) + 1, run_id: newRunId(),
             reviewed_sha: input.reviewedSha, prompts_sha: key.prompts_sha,
             witness: key.witness, model, harness: harness.name, calibration: calibrationOf(model),
+            ...(localR.value.reviewerExtensions.length ? { reviewer_extensions: localR.value.reviewerExtensions } : {}),
             ...(cached ? { cached: true } : {}),
             ...(flags.manual ? { manual: true } : {}),
             ...(fallback.length ? { fallback } : {}),

package/dist/gates/ship.js

@@ -11,6 +11,7 @@ import { effortOf, worktreeTreeSha } from '../reviewed.js';
 import { worktreePath } from '../worktree.js';
 import { codePromptBody } from './implement.js';
 import { registerGate } from '../gate.js';
+import { gateSettled } from '../verbs/next.js';
 import { lastGateRun } from '../rounds.js';
 import { serializeDoc } from '../fm.js';
 async function commandLane(wt, root, ctx, name, cmd) {
@@ -46,16 +47,19 @@ registerGate({
         const checks = [];
         const entries = readStream(root, planId);
         const lastImplement = lastGateRun(entries, 'implement');
-        const implementSettled = (() => {
-            if (!lastImplement)
-                return false;
-            if (lastImplement.outcome === 'passed')
-                return true;
-            const after = entries.slice(entries.lastIndexOf(lastImplement) + 1);
-            return after.some((e) => e.t === 'human-decision' &&
-                e.gate === 'implement' &&
-                e.decision === 'approve');
-        })();
+        // One settle predicate, not two. This block used to inline its own copy of
+        // gateSettled, which meant `ship` and `next` could answer "is implement settled?"
+        // differently for the same journal — the split-brain that reads as a deadlock when
+        // two sessions compare notes.
+        //
+        // The missing sha argument is DELIBERATE and load-bearing, not an oversight. D75's
+        // `worktreeTreeSha` covers the whole worktree, so ship's own `pr #N` stamp — pulled
+        // into the worktree by the watch-phase rebase — moves the tree and would lapse the
+        // very gate ship is checking: approve → pr → lapse → gate, the livelock D75/D77
+        // record. `next` re-arms on tree movement because authoring is what it routes to;
+        // ship asks only whether implement was ever settled. Passing a sha here re-opens
+        // that livelock — do not "fix" this by adding one.
+        const implementSettled = gateSettled(entries, 'implement');
         checks.push({ name: 'implement-gate', ok: implementSettled,
             detail: lastImplement
                 ? `last implement round ${lastImplement.round}: ${lastImplement.outcome}`

package/dist/gitio.js

@@ -44,6 +44,12 @@ const LOCAL_STATE_FILES = new Set([
     '.witness/txn.json',
     '.witness/allow.json',
     '.witness/calibration.local.yaml',
+    // Row 90's machine-config file is this tier too, and the exemption is load-bearing
+    // rather than belt-and-braces: init only gitignores it for repos scaffolded at
+    // >=0.5.0, so on every pre-0.5.0 repo the file is untracked-but-visible under a
+    // state dir — and an unrelated-dirty refusal there would brick the very gate the
+    // declared extensions exist to unblock.
+    '.witness/config.local.yaml',
 ]);
 export function dirtyStatePaths(root) {
     const res = tryGit(root, 'status', '--porcelain', '--untracked-files=all', '--', ...stateDirs(root));
@@ -57,13 +63,35 @@ export function dirtyStatePaths(root) {
         .filter((p) => !LOCAL_STATE_FILES.has(p));
 }
 export const TRAILER = 'Witness-State: 1';
+// Row 87's rule: nothing to COMMIT is the same legal silent success as nothing to write.
+// It lives here, at the one choke point every state commit passes through, because git
+// rejects BOTH empty cases fatally and a caller cannot tell them apart in advance:
+//   • no paths at all → `commit --only ... --` dies "No paths with --include/--only"
+//     (a drift sweep with no live specs journals nothing and stamps nothing);
+//   • paths with no diff → `commit --only` exits non-zero (a restamp that restores a
+//     file to exactly its HEAD content, or a pathspec the repo gitignores).
+// Either way there is no state to record, so HEAD is already the answer. Implementing
+// this at init.ts's call site alone left every other caller throwing out of gitio and
+// surfacing through bin.ts as `unexpected-error` — "report a bug" on a healthy repo.
+function headSha(root) {
+    const head = tryGit(root, 'rev-parse', 'HEAD');
+    return head.ok ? head.out : ''; // unborn HEAD: no commit exists to name
+}
 export function commitWithTrailer(root, files, subject) {
+    if (files.length === 0)
+        return ok({ sha: headSha(root) });
     // tryGit, not git: a path already fully processed by a prior `git mv` (both sides
     // of a rename staged atomically) is absent from working tree AND index, so `add`
     // reports it unmatched — even though the rename itself is already staged. `commit
     // --only` resolves its pathspecs against the index-vs-HEAD diff, where the rename
     // is visible, so it still succeeds and is the real validation here.
     tryGit(root, 'add', '--', ...files);
+    // Ask git what actually changed rather than assuming every file we touched is dirty.
+    // Runs AFTER the add, so a freshly staged untracked path reads as `A ` and commits;
+    // a staged rename reads as `R ` on whichever side the pathspec names.
+    if (tryGit(root, 'status', '--porcelain', '--', ...files).out === '') {
+        return ok({ sha: headSha(root) });
+    }
     // --no-verify: state commits are machine-authored and scope-restricted to non-source
     // paths (isStatePath), so a host lint/test hook has nothing to validate here — while
     // its stash/restore step can destroy the human's unrelated dirty work, and a

package/dist/harness.js

@@ -39,7 +39,15 @@ function parsePiEnvelope(stdout) {
     }
     const assistant = end?.messages?.filter((m) => m.role === 'assistant').at(-1);
     if (assistant?.stopReason === 'error') {
-        return refuse([v('pi', 'reviewer-invocation', (assistant.errorMessage ?? 'provider error').slice(0, 200), 'a provider the pinned model can reach — check auth and billing for that provider')]);
+        const msg = (assistant.errorMessage ?? 'provider error').slice(0, 200);
+        // Anthropic's extra-usage 400 against subscription OAuth is the hermetic spawn
+        // disabling an auth-supplying extension, NOT an auth/billing problem — the old
+        // want text cost a real user rounds of re-login (row 89 overturned row 88's
+        // billing-asymmetry residual on this evidence).
+        if (/Third-party apps|extra usage/i.test(msg)) {
+            return refuse([v('pi', 'reviewer-invocation', msg, 'a credential headless pi can use — the reviewer runs hermetic (--no-extensions); if your provider auth is supplied by a pi extension, declare its path in .witness/config.local.yaml reviewerExtensions')]);
+        }
+        return refuse([v('pi', 'reviewer-invocation', msg, 'a provider the pinned model can reach — check auth and billing for that provider')]);
     }
     const text = (assistant?.content ?? []).filter((c) => c.type === 'text').map((c) => c.text ?? '').join('\n');
     if (text === '') {
@@ -68,7 +76,7 @@ const REGISTRY = {
         ],
         skills: { project: '.claude/skills', global: '.claude/skills' },
         reviewer: {
-            spawn(pin) {
+            spawn(pin, _extensions) {
                 const args = ['-p', '--output-format', 'json'];
                 const env = {};
                 if (pin !== undefined) {
@@ -105,10 +113,20 @@ const REGISTRY = {
         // Hermetic (Decision 88): every omitted flag here is a machine-local variable that
         // would silently change reviewer behavior — this machine's `defaultThinkingLevel:
         // xhigh` was the probable true cause of row 87's "stalls on long prompts".
+        //
+        // Declared reviewerExtensions (machine config) are the ONE sanctioned readmission —
+        // auth transport, journaled per gate-run, never part of the verdict-cache key. The
+        // worker below keeps full discovery on purpose: skills and context files are what
+        // the implement seed measures; auth extensions ride along with everything else there.
         reviewer: {
-            spawn(pin) {
-                const args = ['-p', '--mode', 'json', '--no-session', '--no-extensions',
-                    '--no-skills', '--no-context-files', '--thinking', pin?.thinking ?? 'off'];
+            spawn(pin, extensions) {
+                const args = ['-p', '--mode', 'json', '--no-session', '--no-extensions'];
+                // Declared machine extensions ride INSIDE the hermetic set (row 89): pi's
+                // --no-extensions disables discovery but explicit -e paths still load, so
+                // auth-supplying adapters work without readmitting ambient machine state.
+                for (const e of extensions ?? [])
+                    args.push('-e', e);
+                args.push('--no-skills', '--no-context-files', '--thinking', pin?.thinking ?? 'off');
                 if (pin !== undefined)
                     args.push('--model', `${pin.provider ?? 'anthropic'}/${pin.model}`);
                 return { cmd: 'pi', args, env: {} };
@@ -132,7 +150,6 @@ export function loadHarness(name) {
     }
     return ok(harness);
 }
-const relabel = (violations, field) => violations.map((x) => ({ ...x, field }));
 // Decision 5. Detection is the authority; config is the fallback. A config-authority
 // default in a fresh repo emits a runnable-LOOKING, unrunnable handoff behind a warning
 // that gets scrolled past — bug B2's exact shape. Detection tests PRESENCE: neither
@@ -141,12 +158,10 @@ const relabel = (violations, field) => violations.map((x) => ({ ...x, field }));
 // Deliberately NOT wired into loadConfig: every verb calls that, so an invalid
 // `harness:` there would brick `witness check` on a key nothing read. Verbs that need
 // a harness ask for one; `check` reports a malformed config value as a finding.
+//
+// Row 90 removed the WITNESS_HARNESS env rung: configuration has one home, and tests
+// simulate harnesses by setting the detection vars production actually reads.
 export function resolveHarness(env, raw) {
-    const override = env.WITNESS_HARNESS;
-    if (override !== undefined && override !== '') {
-        const r = loadHarness(override);
-        return r.ok ? ok({ harness: r.value, source: 'env' }) : refuse(relabel(r.violations, 'WITNESS_HARNESS'));
-    }
     if (env.PI_CODING_AGENT !== undefined) {
         const r = loadHarness('pi');
         return r.ok ? ok({ harness: r.value, source: 'detected' }) : refuse(r.violations);

package/dist/opener.js

@@ -16,12 +16,13 @@ function resolves(cmd) {
     return probe.status === 0;
 }
 // Show a file to the human. Returns the resolved command alongside the outcome so the
-// caller can journal WHAT was run — a degenerate opener (`WITNESS_OPENER=/usr/bin/true`)
-// then reads as a degenerate opener in the record instead of as a human looking at a
-// screen. `WITNESS_OPENER` overrides the binary: test seam, and the real escape hatch
-// for nonstandard desktops, so it accepts a bare name off PATH as well as a path.
-export function openArtifact(env, absPath) {
-    const argv = env.WITNESS_OPENER ? [env.WITNESS_OPENER] : platformOpener();
+// caller can journal WHAT was run — a degenerate opener (`opener: /usr/bin/true` in
+// .witness/config.local.yaml) then reads as a degenerate opener in the record instead
+// of as a human looking at a screen. `opener` is the machine-config value (row 90 —
+// nonstandard desktops declare it there; tests inject it as a parameter), a bare name
+// off PATH or a path.
+export function openArtifact(opener, absPath) {
+    const argv = opener !== undefined && opener !== '' ? [opener] : platformOpener();
     const [cmd, ...pre] = argv;
     // Probe before spawning: a detached spawn reports ENOENT asynchronously, and the
     // caller needs the outcome synchronously to journal it in the same transaction.

package/dist/reviewer.js

@@ -94,8 +94,8 @@ export function invokeReviewer(ctx, harness, opts) {
             return refuse(pinR.violations);
         pin = pinR.value;
     }
-    const { cmd, args, env } = harness.reviewer.spawn(pin);
-    const timeout = Number(ctx.env.WITNESS_REVIEWER_TIMEOUT_MS) || REVIEWER_TIMEOUT_MS;
+    const { cmd, args, env } = harness.reviewer.spawn(pin, opts.extensions);
+    const timeout = opts.timeoutMs ?? REVIEWER_TIMEOUT_MS;
     for (let attempt = 0;; attempt += 1) {
         const r = spawnSync(cmd, args, {
             cwd: opts.cwd,
@@ -111,7 +111,7 @@ export function invokeReviewer(ctx, harness, opts) {
             if (r.error.code === 'ETIMEDOUT') {
                 if (attempt < TIMEOUT_RETRIES)
                     continue;
-                return refuse([v(cmd, 'reviewer-timeout', `no response in ${timeout}ms after ${attempt + 1} attempts`, 'a reviewer that answers within the timeout — raise WITNESS_REVIEWER_TIMEOUT_MS if the model is simply slow')]);
+                return refuse([v(cmd, 'reviewer-timeout', `no response in ${timeout}ms after ${attempt + 1} attempts`, 'a reviewer that answers within the timeout — raise gates.reviewerTimeoutMs in witness.config.yaml if the model is simply slow')]);
             }
             return refuse([v(cmd, 'reviewer-invocation', String(r.error.message), `a runnable ${cmd} binary on PATH — gates invoke reviewers headlessly; witness check probes this`)]);
         }

package/dist/verbs/calibrate.js

@@ -1,7 +1,7 @@
 import { EXIT } from '../cli.js';
 import { kv, rows } from '../toon.js';
 import { renderRefusal, v } from '../refusal.js';
-import { loadConfig } from '../config.js';
+import { loadConfig, loadLocalConfig } from '../config.js';
 import { resolveHarness } from '../harness.js';
 import { MODEL_ALIASES } from '../model.js';
 import { primaryRoot } from '../gitio.js';
@@ -78,13 +78,26 @@ export async function run(ctx, argv) {
         return EXIT.REFUSED;
     }
     const harness = hxR.value.harness;
-    const reviewers = runReviewers ? await runReviewerSuites(ctx, harness, model, flags.samples, reviewerOnly) : undefined;
+    // Row 89: calibration measures through the SAME spawn as the gate battery, declared
+    // extensions included — a reviewer scored without its auth adapter is not the
+    // reviewer production runs.
+    const localR = loadLocalConfig(rootR.value);
+    if (!localR.ok) {
+        for (const line of renderRefusal(localR.violations))
+            ctx.err(line);
+        return EXIT.REFUSED;
+    }
+    const extras = {
+        timeoutMs: cfgR.ok ? cfgR.value.gates.reviewerTimeoutMs : undefined,
+        extensions: localR.value.reviewerExtensions,
+    };
+    const reviewers = runReviewers ? await runReviewerSuites(ctx, harness, model, flags.samples, reviewerOnly, extras) : undefined;
     if (reviewers && !reviewers.ok) {
         for (const line of renderRefusal(reviewers.violations))
             ctx.err(line);
         return EXIT.REFUSED;
     }
-    const skills = runSkills ? await runSkillSuites(ctx, harness, model, flags.samples, { only: skillOnly }) : undefined;
+    const skills = runSkills ? await runSkillSuites(ctx, harness, model, flags.samples, { only: skillOnly, extras }) : undefined;
     if (skills && !skills.ok) {
         for (const line of renderRefusal(skills.violations))
             ctx.err(line);

package/dist/verbs/check.js

@@ -4,10 +4,10 @@ import { adoptedCommits } from '../adopt.js';
 import { EXIT, version } from '../cli.js';
 import { HARNESSES, resolveHarness, skillsVisibility } from '../harness.js';
 import { probe } from '../probe.js';
-import { loadConfig } from '../config.js';
+import { loadConfig, loadLocalConfig, localConfigPath } from '../config.js';
 import { designPending } from '../design.js';
 import { runDrift } from '../drift.js';
-import { auditStateCommits, dirtyStatePaths, primaryRoot } from '../gitio.js';
+import { auditStateCommits, dirtyStatePaths, primaryRoot, tryGit } from '../gitio.js';
 import { contentAtSha } from '../history.js';
 import { effortStreams, readStream } from '../journal.js';
 import { sourceTags } from '../matcher.js';
@@ -37,6 +37,24 @@ export async function run(ctx, argv = []) {
         cfg.violations.forEach((x) => findings.push(f('error', 'config', x.field, x.rule, x.got)));
     else if (cfg.value.warning)
         findings.push(f('warn', 'config', 'schema', 'older-schema', cfg.value.warning));
+    // Machine config is read here as FINDINGS, never a refusal — same doctrine that
+    // keeps harness resolution out of loadConfig (row 87): check must be able to
+    // report a broken machine file rather than brick on it.
+    const local = loadLocalConfig(root);
+    if (!local.ok) {
+        local.violations.forEach((x) => findings.push(f('error', 'local-config', x.field, x.rule, x.got)));
+    }
+    else {
+        for (const p of local.value.reviewerExtensions) {
+            if (!existsSync(p))
+                findings.push(f('warn', 'local-config', 'reviewerExtensions', 'extension-path-missing', p));
+        }
+    }
+    // init's gitignore write is scaffold-once, so pre-0.5.0 repos never receive the new
+    // ignore line — this finding is their honest path to it.
+    if (existsSync(localConfigPath(root)) && !tryGit(root, 'check-ignore', '-q', '--', '.witness/config.local.yaml').ok) {
+        findings.push(f('warn', 'local-config', '.witness/config.local.yaml', 'local-config-unignored', 'machine-local file — add it to .gitignore'));
+    }
     const canon0 = loadCanon(root);
     const lazy = lazyStamp(root, ctx, canon0);
     const canon = lazy.stamped.length > 0 ? loadCanon(root) : canon0;

package/dist/verbs/design.js

@@ -3,7 +3,7 @@ import { hostname, userInfo } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { EXIT } from '../cli.js';
-import { loadConfig } from '../config.js';
+import { loadConfig, loadLocalConfig } from '../config.js';
 import { designPending, designRel, designStamp, htmlSha, validateDesignArtifact } from '../design.js';
 import { writeDoc } from '../fm.js';
 import { dirtyStatePaths, primaryRoot, stateCommit } from '../gitio.js';
@@ -85,9 +85,14 @@ function openOnly(ctx, root, rel, id) {
         return EXIT.REFUSED;
     }
     const sha = htmlSha(readFileSync(abs, 'utf8'));
-    const { outcome, command } = openArtifact(ctx.env, abs);
+    const localR = loadLocalConfig(root);
+    if (!localR.ok) {
+        renderRefusal(localR.violations).forEach(ctx.err);
+        return EXIT.REFUSED;
+    }
+    const { outcome, command } = openArtifact(localR.value.opener, abs);
     if (outcome === 'failed') {
-        renderRefusal([v('design', 'opener-failed', `${command} did not resolve`, `a working platform opener, or WITNESS_OPENER — meanwhile open it yourself: file://${abs}`)]).forEach(ctx.err);
+        renderRefusal([v('design', 'opener-failed', `${command} did not resolve`, `a working platform opener, or opener: in .witness/config.local.yaml — meanwhile open it yourself: file://${abs}`)]).forEach(ctx.err);
         return EXIT.REFUSED;
     }
     // `by` is the account and machine the spawn happened on — not a claim about who looked.

package/dist/verbs/init.js

@@ -5,7 +5,7 @@ import { EXIT } from '../cli.js';
 import { configPath } from '../config.js';
 import { writeDoc } from '../fm.js';
 import { commitWithTrailer, primaryRoot, tryGit } from '../gitio.js';
-import { resolveHarness } from '../harness.js';
+import { loadHarness, resolveHarness } from '../harness.js';
 import { installPayload, mergeSettings, preflightPayload, readIfExists, recordHarness, writeSettings, } from '../install.js';
 import { probe } from '../probe.js';
 import { acquireLock } from '../lock.js';
@@ -18,6 +18,7 @@ schema: 1
 #   conventions: [docs/code/architecture.md]   # → injected into code-reviewer at implement + ship (cache-keyed)
 gates:
   model: claude-fable-5      # reviewer model pin — exact id, aliases refused
+  # reviewerTimeoutMs: 600000  # ms per reviewer invocation (machine auth/extension knobs live in .witness/config.local.yaml)
   # any gate block may pin its own model (wins over the global pin), e.g.
   # decompose: { reviewers: [slicing-critic], model: claude-opus-4-8 }
   decompose: { reviewers: [slicing-critic] }
@@ -37,6 +38,7 @@ const GITIGNORE_BLOCK = `# witness local (never committed)
 .witness/txn.json
 .witness/allow.json
 .witness/calibration.local.yaml
+.witness/config.local.yaml
 .witness/screens/
 `;
 const PRINCIPLES_BODY = `# Principles
@@ -73,15 +75,14 @@ export async function run(ctx, argv = []) {
     let harness;
     if (agent !== undefined) {
         // `auto` is the one value that consults the detection rungs; a named agent is a
-        // claim and refuses when false, listing the harnesses that exist.
-        const hxR = agent === 'auto'
-            ? resolveHarness(ctx.env, {})
-            : resolveHarness({ WITNESS_HARNESS: agent }, {});
+        // claim and refuses when false, listing the harnesses that exist (row 90: no env
+        // impersonation — a name resolves through the registry directly).
+        const hxR = agent === 'auto' ? resolveHarness(ctx.env, {}) : loadHarness(agent);
         if (!hxR.ok) {
             renderRefusal(hxR.violations.map((x) => ({ ...x, field: '--agent' }))).forEach(ctx.err);
             return EXIT.REFUSED;
         }
-        harness = hxR.value.harness;
+        harness = 'harness' in hxR.value ? hxR.value.harness : hxR.value;
         // Revision 6: pre-flight before the lock and before any scaffold write, so a
         // refusal here leaves the repo exactly as it was.
         const pre = preflightPayload(root, harness);

package/dist/verbs/next.js

@@ -14,7 +14,7 @@ import { handoffLine, relayLine, resolveHarness } from '../harness.js';
 import { worktreeFlow, worktreePath } from '../worktree.js';
 import { lazyStamp } from '../stamp.js';
 import { ok, refuse, renderRefusal, v } from '../refusal.js';
-import { kv } from '../toon.js';
+import { kv, rows } from '../toon.js';
 import { boundReached, lastGateRun, 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
@@ -60,6 +60,21 @@ function authoringOwed(entries, gate, currentSha) {
         e.gate === gate &&
         ['revise', 'revise-upstream'].includes(e.decision));
 }
+// D75 re-arms a gate whose reviewed sha has moved, and `worktreeTreeSha` covers the
+// WHOLE worktree — so any state commit reaching it lapses the gate. That is correct, but
+// the row it produces is a bare `gate implement`, indistinguishable from a CLI stuck on
+// a stale answer. A human who just watched that gate pass reads it as the latter, and
+// with a second session in the worktree answering `ship` the pair looks like a deadlock
+// with no error anywhere. The lapse is a fact the CLI already knows; say it.
+function lapseNote(entries, gate, currentSha) {
+    const last = lastGateRun(entries, gate);
+    if (!last || currentSha === undefined || last.reviewed_sha === currentSha)
+        return undefined;
+    // sha-free: asks "was it ever settled", which is the only thing that can lapse
+    if (!gateSettled(entries, gate))
+        return undefined;
+    return `${gate} approval lapsed — judged @${last.reviewed_sha.slice(0, 7)}, worktree now @${currentSha.slice(0, 7)} — re-gate to judge the current tree`;
+}
 // The action for ONE flow. A flow is a plan with status `in-progress`: it begins at
 // `witness start` and ends at the merge stamp. Anything else returns undefined and is
 // not a flow. Exported because `--flow` and the dashboard must answer with the SAME
@@ -87,8 +102,13 @@ export function flowAction(root, cfg, plan) {
     const satisfied = files.length > 0 && baseR.ok && evidenceForDiff(wt, root, plan, baseR.value).satisfied;
     if (!satisfied)
         return { line: `witness test-evidence ${id} --phase red|green`, stage: 'implement', target: id, ...inWorktree };
-    if (!gateSettled(entries, 'implement', worktreeTreeSha(wt)))
-        return { line: `witness gate implement ${id}`, target: id, ...inWorktree };
+    const treeSha = worktreeTreeSha(wt);
+    if (!gateSettled(entries, 'implement', treeSha)) {
+        return {
+            line: `witness gate implement ${id}`, target: id, ...inWorktree,
+            ...noteOf(lapseNote(entries, 'implement', treeSha)),
+        };
+    }
     return { line: `witness ship ${id}`, stage: 'ship', target: id, ...atRoot };
 }
 // How far along a flow is — the drain order when several are actionable. Most-advanced
@@ -198,8 +218,13 @@ export function computeNext(root, ctx, canon, cfg) {
         .sort((a, b) => flowRank(b) - flowRank(a) || String(a.target).localeCompare(String(b.target)));
     if (flows.length > 0) {
         const waiting = pendingDecisionsAll(root, efforts, specs, plans);
+        // noteOf, not an overwrite: a lapse note explains WHY this row is the gate rather
+        // than the ship it was a moment ago, and must not be evicted by the waiting list.
         return waiting.length > 0
-            ? { ...flows[0], note: `${waiting.length} waiting: ${waiting.map((w) => `${w.gate} ${w.target}`).join(' · ')}` }
+            ? {
+                ...flows[0],
+                ...noteOf(flows[0].note, `${waiting.length} waiting: ${waiting.map((w) => `${w.gate} ${w.target}`).join(' · ')}`),
+            }
             : flows[0];
     }
     // TIER 2 — human-owed decisions and bound endgames. Unchanged from today's rungs; they
@@ -398,6 +423,14 @@ export async function run(ctx, argv) {
     const lazy = lazyStamp(root, ctx, canon);
     if (lazy.stamped.length > 0)
         canon = loadCanon(root);
+    // `dashboard` renders these; `next` computed them and dropped them. A merge stamp that
+    // cannot proceed (commit refused, PR closed unmerged, lock held) leaves the flow parked
+    // at ship forever, and `next` — the one verb the driving loop calls every turn — said
+    // nothing at all. Printed BEFORE the routing block so it cannot split the contiguous
+    // next:/stage:/target:/note:/home:/run:/relay: unit the stage skills read verbatim.
+    if (lazy.stale.length > 0) {
+        rows('stale', ['plan', 'why'], lazy.stale).forEach(ctx.out);
+    }
     const { values } = parseArgs({ args: argv, options: { flow: { type: 'string' } }, allowPositionals: true });
     // Precedence: an explicit --flow is a CLAIM about a flow and refuses when false.
     // A worktree cwd is AMBIENT context — it may scope a read-only question, never select

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popovych.co/witness",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "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.4.1",
+  "version": "0.5.1",
   "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.4.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 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.4.1} 2>/dev/null || true
+${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1} 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.4.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **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.4.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **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.4.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **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.)
@@ -69,7 +69,7 @@ $WITNESS design <spec-id> --open   # opens the artifact for the human — requir
 ```
 
 - **Register, then show.** `witness gate design` refuses `design-unseen` until the human has been shown the artifact's current bytes, so `--open` is part of the flow, not a nicety. Re-authoring re-arms it: new bytes, new showing. `witness next` names this step by itself — follow it.
-- The opener failing (`opener-failed`) prints a `file://` path. Give the human that path verbatim and stop; do not work around it by pointing `WITNESS_OPENER` at something that does not show anything.
+- The opener failing (`opener-failed`) prints a `file://` path. Give the human that path verbatim and stop; do not work around it by pointing `opener:` in `.witness/config.local.yaml` at something that does not show anything.
 
 ## Gate
 

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.4.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **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.4.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **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.4.1}"
+WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.5.1}"
 ```
 
 - **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.)