@popovych.co/witness 0.6.0 → 0.9.0

package/README.md

@@ -81,12 +81,42 @@ npx @popovych.co/witness init --agent pi
 `<cwd>/.pi/skills` with no upward walk, and the implement stage runs with its cwd inside
 `.witness/worktrees/<plan-id>` — a directory the installer never touched. A
 project-scope install therefore loses every skill in the stage that does the most work.
-Global (`~/.pi/agent/skills`) is cwd-independent. `witness check` warns when the
-resolved harness cannot see all six skills.
+Global (`~/.pi/agent/skills`) is cwd-independent. `witness check` warns when six skills
+are installed where a worktree cannot see them, and states which harnesses have none.
 
 A tarball URL is version-pinned, so `skills update` cannot resolve forward: re-run `add`
 with the new version URL to upgrade.
 
+### Upgrading: skills first, then `init --agent`
+
+Every surface that invokes witness pins the CLI — the engine prompt and all six skills
+carry `npx -y @popovych.co/witness@<version>` — so a repo installed at an older release
+only ever runs that release, which compares its payload against itself and reports clean.
+The freeze is self-concealing, and a repo frozen at **0.6.0 or earlier cannot detect it**,
+because the detection ships in a CLI that repo never invokes. Unstick it from outside, in
+this order:
+
+```bash
+npx skills@latest add https://registry.npmjs.org/@popovych.co/witness/-/witness-<new-version>.tgz
+npx -y @popovych.co/witness@latest init --agent <name>   # restamps the engine, guard and dashboard
+```
+
+Skills first: their fresh pins are what invoke a CLI new enough to see the outdated
+payload. Claude Code users on the marketplace plugin get both halves from
+`/plugin marketplace add` and need no second step.
+
+From **0.7.0** onward the order stops mattering: `witness check` asks the registry what
+the published `latest` is and reports both halves of the skew — a CLI behind `latest`
+(`cli-behind`) and any visible skill pinning something older (`skills-behind`). The query
+is best-effort and silent on failure, so an offline machine reports nothing rather than a
+complaint about the network.
+
+`witness init --agent <name>` overwrites payload files it did not write and names what it
+replaced (`payload-overwritten`); the previous content is one `git revert` away, because
+witness commits the payload. It refuses the whole run if a payload path carries an
+uncommitted change (`payload-dirty`) or if the CLI you are running is older than the
+payload already installed (`cli-behind-payload`).
+
 ### Support tiers
 
 | Tier | Agents | What they get |
@@ -101,11 +131,11 @@ either.
 
 | Key | Meaning |
 |---|---|
-| `harness: claude-code \| pi` | fallback used only when detection cannot answer. Order: `PI_CODING_AGENT` → `CLAUDECODE` → `harness:` → `claude-code` |
+| `harness: claude-code \| pi` | **the judge** — which harness runs this repo's gate reviewers, is measured by `calibrate`, and is probed by `check`. Judgment resolves `harness:` → `PI_CODING_AGENT` → `CLAUDECODE` → `claude-code`; session lines (`next`'s handoff, `dispatch`'s relay, `init --agent auto`) resolve detection first, because those name the CLI you are about to type at. Committed, so it binds every teammate's gates; `witness init --agent` writes it once and never re-points it. Undeclared repos are judged by whichever agent's session is open — `witness check` and `witness status` say so |
 | `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
+There is no `provider:` key. `witness gate` spawns the DECLARED harness's headless
+mode for every reviewer (Decisions 88, 105): 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 —

package/dist/cli.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { configPath } from './config.js';
 import { primaryRoot } from './gitio.js';
+import { renderRefusal, v } from './refusal.js';
 export const EXIT = { OK: 0, FINDINGS: 1, REFUSED: 2, BLOCKED: 3 };
 const VERBS = {
     recover: () => import('./verbs/recover.js'),
@@ -41,7 +42,7 @@ 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]',
     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>]',
@@ -99,5 +100,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/drift.js

@@ -8,7 +8,7 @@ import { acquireLock } from './lock.js';
 import { appendEntry, entryLine, journalRel, readStream } from './journal.js';
 import { primaryRoot, stateCommit } from './gitio.js';
 import { renderRefusal, v, ok } from './refusal.js';
-import { resolveHarness } from './harness.js';
+import { resolveJudge } from './harness.js';
 import { invokeReviewer, parseVerdictText, resolvePrompt } from './reviewer.js';
 import { runFullSuite, runnerConfig } from './runner.js';
 import { findById, loadCanon } from './scan.js';
@@ -120,7 +120,7 @@ export async function deepDrift(root, ctx, canon, specId) {
     // like every other. A silent claude fallback here would swap the reviewer identity
     // for pure-pi users on the one check that judges live specs.
     const cfgR = loadConfig(root);
-    const hxR = resolveHarness(ctx.env, cfgR.ok ? cfgR.value.raw : {});
+    const hxR = resolveJudge(ctx.env, cfgR.ok ? cfgR.value.raw : {});
     if (!hxR.ok) {
         renderRefusal(hxR.violations).forEach(ctx.err);
         return EXIT.REFUSED;

package/dist/gate.js

@@ -8,13 +8,14 @@ import { appendEntry, entryLine, journalRel, policyPins, readStream } from './jo
 import { primaryRoot, stateCommit } from './gitio.js';
 import { loadCanon, findById } from './scan.js';
 import { newRunId } from './drift.js';
-import { resolveHarness } from './harness.js';
+import { resolveJudge } from './harness.js';
 import { ok, refuse, renderRefusal, v } from './refusal.js';
 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, gateRuns, lastGateRun, roundsSinceApprove, } 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);
@@ -170,7 +169,7 @@ export async function runGate(ctx, gateName, target, flags) {
             lens.docs = docs;
         lenses.push(lens);
     }
-    const hxR = resolveHarness(ctx.env, cfgR.value.raw);
+    const hxR = resolveJudge(ctx.env, cfgR.value.raw);
     if (!hxR.ok) {
         renderRefusal(hxR.violations).forEach((l) => ctx.err(l));
         return EXIT.REFUSED;
@@ -195,9 +194,14 @@ export async function runGate(ctx, gateName, target, flags) {
     // (D98a). Only the caller's own pin being below the floor is news at run time.
     if (warning && warningKind === 'below-floor')
         ctx.err(`warning: ${warning}`);
+    // Row 106: the key is built BEFORE invoking, so the only model knowable here is the one
+    // being asked for. Naming it `pin` is what stops the entry's `model` — what actually
+    // answered — from being compared against it by accident, which is how the streak brake
+    // below spent three releases never firing.
+    const pin = chain[0];
     const key = {
         reviewed_sha: input.reviewedSha, gate: spec.gate,
-        prompts_sha: promptsSha(lenses, pinsText === '' ? undefined : pinsText), model: chain[0], witness: version(),
+        prompts_sha: promptsSha(lenses, pinsText === '' ? undefined : pinsText), pin, witness: version(),
         harness: harness.name,
     };
     // D99: `gateSettled` reads only the last run, so any new run un-settles the gate.
@@ -211,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.
@@ -220,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;
     }
@@ -238,11 +259,30 @@ export async function runGate(ctx, gateName, target, flags) {
         return EXIT.BLOCKED;
     }
     if (!flags.fresh) {
-        // malformed rounds don't spend the bound (rounds.ts) — this brake is what
-        // stops an unreliable battery from re-running for free forever instead
-        const tail = gateRuns(entries, spec.gate).slice(-2);
-        const sameSetup = (r) => r.outcome === 'malformed' && r.model === key.model && r.prompts_sha === key.prompts_sha &&
-            (r.harness ?? 'claude-code') === key.harness;
+        // Both brakes guard the SAME window as the round budget (rounds.ts): exempt rounds
+        // could otherwise repeat for free, and a run on the far side of an approve was
+        // disposed of and can trip nothing.
+        const tail = runsSinceReset(entries, spec.gate).slice(-2);
+        const samePin = (r) => (r.pin ?? r.model) === key.pin && (r.harness ?? 'claude-code') === key.harness;
+        // Row 107. A fallen-back round does not spend the budget, and an exempt round that
+        // repeats forever is D67's livelock — the exemption and this trigger are one change.
+        // `prompts_sha` is deliberately NOT compared: a lens edit has nothing to do with
+        // whether a model answers, and comparing it would let an unrelated edit reset a brake
+        // on a dead pin. Checked first because when both hold, "the pinned model is not
+        // answering" is the true remedy and "your battery emits invalid verdicts" is not.
+        // No --fresh in the want: --fresh bypasses the brake and would spend a battery
+        // re-invoking the same dead pin. Fixing the pin moves key.pin, samePin goes false,
+        // and the battery runs — which is only reachable BECAUSE these rounds were exempt.
+        if (tail.length === 2 && tail.every((r) => fellBack(r) && samePin(r))) {
+            renderRefusal([v(`gates.${spec.gate}.model`, 'fallback-streak', `${tail.length} consecutive rounds fell back from ${key.pin}`, 'a reachable gates.<gate>.model — the pinned model is not answering')])
+                .forEach((l) => ctx.err(l));
+            return EXIT.REFUSED;
+        }
+        // malformed rounds don't spend the bound either — this brake is what stops an
+        // unreliable battery from re-running for free forever instead. Row 106: "same setup"
+        // always meant the same PIN, and comparing the answering rung meant two malformed
+        // fallen-back rounds never matched, which is the one thing this exists to stop.
+        const sameSetup = (r) => r.outcome === 'malformed' && samePin(r) && r.prompts_sha === key.prompts_sha;
         if (tail.length === 2 && tail.every(sameSetup)) {
             renderRefusal([v('reviewers', 'malformed-streak', `${tail.length} consecutive malformed rounds on ${tail[1].model}`, `a changed gates.${spec.gate}.model pin or updated prompts — the battery is emitting invalid verdicts (or force with --fresh)`)]).forEach((l) => ctx.err(l));
             return EXIT.REFUSED;
@@ -258,7 +298,7 @@ export async function runGate(ctx, gateName, target, flags) {
     const fallback = [];
     const rerolled = [];
     let rung = 0;
-    let model = chain[0];
+    let model = pin;
     let cached = false;
     if (kind.kind === 'cached') {
         verdicts = kind.from.verdicts ?? [];
@@ -309,14 +349,22 @@ export async function runGate(ctx, gateName, target, flags) {
             }
         }
     }
-    if (fallback.length > 0 && chain[0] !== SESSION_DEFAULT && fallback.includes(chain[0])) {
-        ctx.err(`warning: head model ${chain[0]} failed to invoke — reviewers ran on ${model}; check gates.${spec.gate}.model`);
-    }
     const blocking = verdicts.flatMap((x) => x.findings).filter((f) => f.blocking).length;
     const pinConflicts = verdicts.flatMap((x) => x.findings).filter((f) => f.contradicts_pin !== undefined).length;
     const standing = [
         input.standingStop,
         pinConflicts > 0 ? 'contradicts-pin — a finding disputes a settled policy pin; the human decides which one dies' : undefined,
+        // Row 98c, specified by row 107. Composed HERE, after the battery, because whether a
+        // fallback happened is not knowable at resolve() time. Dismissed by a plain
+        // --approve: --override is reserved for the bound and this is a first-round event.
+        // The remedy is deliberately absent — on round one the honest statement is that a
+        // human decides whether the verdict counts; the remedy becomes true only once the pin
+        // proves persistently dead, which is what fallback-streak above prints. It REPLACES
+        // the stderr warning that fired on this same condition: unjournaled and non-blocking,
+        // it let a substituted verdict pass behind a line that scrolls by.
+        model !== pin
+            ? `fallback — reviewers ran on ${model}, not the pinned ${pin}; the human decides whether that verdict counts`
+            : undefined,
     ].filter((s) => s !== undefined).join(' · ') || undefined;
     const checksGreen = input.checks.every((c) => c.ok);
     const outcome = malformed.length > 0 ? 'malformed'
@@ -349,7 +397,7 @@ export async function runGate(ctx, gateName, target, flags) {
             v: 1, t: 'gate-run', gate: spec.gate, artifact: target,
             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),
+            witness: key.witness, model, pin, harness: harness.name, calibration: calibrationOf(model),
             ...(localR.value.reviewerExtensions.length ? { reviewer_extensions: localR.value.reviewerExtensions } : {}),
             ...(cached ? { cached: true } : {}),
             ...(flags.manual ? { manual: true } : {}),
@@ -396,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/harness.js

@@ -1,7 +1,8 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CLAUDE_THINKING_BUDGET, parsePin } from './pin.js';
 import { ok, refuse, v } from './refusal.js';
+import { pinIn } from './version.js';
 export const HARNESSES = ['claude-code', 'pi'];
 export const DEFAULT_HARNESS = 'claude-code';
 // The six shipped stage skills, by directory name. `check`'s visibility probe asks
@@ -150,33 +151,59 @@ export function loadHarness(name) {
     }
     return ok(harness);
 }
-// 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
-// CLAUDECODE=1 nor PI_CODING_AGENT=true is a documented value contract.
-//
-// 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) {
-    if (env.PI_CODING_AGENT !== undefined) {
-        const r = loadHarness('pi');
-        return r.ok ? ok({ harness: r.value, source: 'detected' }) : refuse(r.violations);
-    }
-    if (env.CLAUDECODE !== undefined) {
-        const r = loadHarness('claude-code');
-        return r.ok ? ok({ harness: r.value, source: 'detected' }) : refuse(r.violations);
-    }
+// Detection tests PRESENCE: neither CLAUDECODE=1 nor PI_CODING_AGENT=true is a documented
+// value contract.
+function detectedRung(env) {
+    if (env.PI_CODING_AGENT !== undefined)
+        return { source: 'detected', name: 'pi' };
+    if (env.CLAUDECODE !== undefined)
+        return { source: 'detected', name: 'claude-code' };
+    return undefined;
+}
+function declaredRung(raw) {
     const configured = raw.harness;
-    if (configured !== undefined) {
-        const r = loadHarness(String(configured));
-        return r.ok ? ok({ harness: r.value, source: 'config' }) : refuse(r.violations);
+    return configured === undefined ? undefined : { source: 'config', name: String(configured) };
+}
+function walk(ladder) {
+    const rung = ladder.find((r) => r !== undefined)
+        ?? { source: 'default', name: DEFAULT_HARNESS };
+    const r = loadHarness(rung.name);
+    return r.ok ? ok({ harness: r.value, source: rung.source }) : refuse(r.violations);
+}
+// THE JUDGE — which harness runs this repo's gate reviewers, reads its calibration matrix
+// and is probed for runnability. A committed declaration wins, because reviewer identity
+// is a property of the repo's evidence trail and must be comparable across machines; row
+// 88 already said an identity chosen by ambient environment is the opposite of a pin.
+export function resolveJudge(env, raw) {
+    return walk([declaredRung(raw), detectedRung(env)]);
+}
+// THE DRIVER — which CLI is about to be typed at. Detection wins, because a launch or
+// relay line is a fact about the session that will run it, and 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.
+export function resolveDriver(env, raw) {
+    return walk([detectedRung(env), declaredRung(raw)]);
+}
+// One renderer for both orientation surfaces, on modelFloorLines' precedent: the judge
+// must read identically on `check` and `status`, or the two screens disagree about which
+// binary judges the same repo. Provenance is RENDERED here, never stored — HarnessSource
+// stays a resolution fact and the wording stays a presentation one.
+//
+// It prints in every state, including `declared`: that line read from a foreign session
+// is exactly what row 105 exists to surface, and a line that appeared only in the bad
+// state would teach people to read its absence as "nothing to know" — the confident
+// silence row 104 spent a release killing. The nudge is not decoration: an UNDECLARED
+// repo's judge still flips with the terminal, and declaring is the only thing that ends it.
+export function judgeLine(r) {
+    if (!r.ok) {
+        // A diagnostic surface must not brick on a broken key — `check` reports it as a
+        // finding and the floor falls back — so say what was fallen back TO, and to what.
+        return `${DEFAULT_HARNESS} (default — harness: ${r.violations[0]?.got ?? '?'} is unreadable; witness check reports it)`;
     }
-    const r = loadHarness(DEFAULT_HARNESS);
-    return r.ok ? ok({ harness: r.value, source: 'default' }) : refuse(r.violations);
+    const nudge = 'undeclared; set harness: in witness.config.yaml to pin it';
+    if (r.value.source === 'config')
+        return `${r.value.harness.name} (declared in witness.config.yaml)`;
+    return `${r.value.harness.name} (${r.value.source} — ${nudge})`;
 }
 // Decision 9: the model flag is a renderer, not a string. Pi's default provider is
 // `google`, so a bare `--model claude-opus-5` in a Pi handoff resolves wrong or not at
@@ -222,14 +249,35 @@ export function relayLine(harness) {
 // upward walk, and implement runs with cwd inside .witness/worktrees/<plan-id> — an
 // untracked directory the installer never touched. A project-scope install therefore
 // loses every skill in the stage that does the most work.
-export function skillsVisibility(env, root, harness) {
+//
+// Row 103 needs the DIRECTORY, not just the verdict: with `latest` in hand, one pass
+// reports both halves of the skew, and the skills half has to read the files it found.
+export function resolveSkills(env, root, harness) {
     const home = env.HOME ?? env.USERPROFILE ?? '';
     const has = (dir) => STAGE_SKILLS.every((s) => existsSync(join(dir, s, 'SKILL.md')));
-    if (home !== '' && has(join(home, harness.skills.global)))
-        return 'global';
-    if (has(join(root, harness.skills.project)))
-        return 'project-only';
-    return 'absent';
+    const global = home === '' ? undefined : join(home, harness.skills.global);
+    if (global !== undefined && has(global))
+        return { scope: 'global', dir: global };
+    const project = join(root, harness.skills.project);
+    if (has(project))
+        return { scope: 'project-only', dir: project };
+    return { scope: 'absent' };
+}
+export function skillsVisibility(env, root, harness) {
+    return resolveSkills(env, root, harness).scope;
+}
+// What pin does each installed skill carry? Nothing more — whether a pin is a PROBLEM
+// takes the published `latest`, which is check's question and check's alone. A skill
+// whose SKILL.md carries no pin is simply absent from the result: the pin is what makes
+// a skill invoke a particular CLI, so one without it says nothing about skew.
+export function skillPins(dir) {
+    return STAGE_SKILLS.flatMap((skill) => {
+        const p = join(dir, skill, 'SKILL.md');
+        if (!existsSync(p))
+            return [];
+        const pin = pinIn(readFileSync(p, 'utf8'));
+        return pin === undefined ? [] : [{ skill, pin }];
+    });
 }
 // Harness-compat rung of pin validation. Grammar and alias checks live in stagePin
 // (model.ts); THIS check needs the harness, which stagePin deliberately never resolves.