@popovych.co/witness 0.6.0 → 0.8.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/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,13 @@ 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, roundsSinceApprove, runsSinceReset, } from './rounds.js';
 import { gateSettled } from './verbs/next.js';
 import { prepareStamp, writeStamp } from './stamp.js';
 const GATES = new Map();
@@ -170,7 +170,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 +195,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.
@@ -238,11 +243,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 +282,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 +333,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 +381,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 } : {}),

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.

package/dist/install.js

@@ -1,8 +1,10 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { version } from './cli.js';
 import { tryGit } from './gitio.js';
 import { ok, refuse, v } from './refusal.js';
+import { NPX_LATEST, compareTriple, pinIn } from './version.js';
 // dist/install.js and src/install.ts both sit one level under the package root, so the
 // same '..' works built and under vitest — the pattern model.ts:14 already uses. This is
 // the only place that still needs it: locating the shipped `plugin/` tree, which is a
@@ -15,42 +17,83 @@ export function packageRoot() {
 // hook commands (verified against 2.1.220).
 const GUARD_CMD = 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-state.mjs"';
 const DASHBOARD_CMD = 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/session-dashboard.sh"';
-const PIN = /@popovych\.co\/witness@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/g;
-// Revision 6. Committing the payload is load-bearing: the implement stage runs with cwd
-// inside .witness/worktrees/<plan-id>, which is a checkout of the branch, so only
-// committed files reach it. A gitignored target therefore has exactly one honest answer
-// — refuse. `git add -f` would override a rule the human wrote down; writing without
-// committing would leave the payload in the primary root and the worktree with no guard,
-// while every `check` reads clean. Called BEFORE the lock and before any scaffold write,
-// so a refusal leaves nothing half-installed.
+// The engine file is the one payload entry every harness carries, and its pin is what
+// decides which CLI the whole pipeline runs — so it is also the only file whose pin can
+// answer "which version installed what is here".
+const ENGINE_SOURCE = 'plugin/commands/witness.md';
+// Revision 6, extended by row 102. Committing the payload is load-bearing: the implement
+// stage runs with cwd inside .witness/worktrees/<plan-id>, which is a checkout of the
+// branch, so only committed files reach it. A gitignored target therefore has exactly one
+// honest answer — refuse. `git add -f` would override a rule the human wrote down; writing
+// without committing would leave the payload in the primary root and the worktree with no
+// guard, while every `check` reads clean.
+//
+// Row 102 adds two more preconditions, because the rule that spared an edited file is
+// gone and the write now clobbers:
+//
+//   payload-dirty      — a clobbered edit is recoverable only from git, so an uncommitted
+//                        payload change must refuse rather than be overwritten into
+//                        nothing. --untracked-files=all, so a present-but-untracked
+//                        payload counts.
+//   cli-behind-payload — an older CLI running in a repo a newer one installed would
+//                        REVERT the payload, re-freezing the repo one version further
+//                        back. Equal triples write (the witness-developer case);
+//                        prerelease ordering is out of scope.
+//
+// All three refuse the WHOLE run, called BEFORE the lock and before any scaffold write,
+// so a refusal leaves nothing half-installed — and a half-upgraded payload set (guard at
+// one version, engine at another) is precisely the skew row 102 exists to close.
+//
+// harness.settings is deliberately outside the dirty guard: mergeSettings appends and
+// never clobbers, so a dirty settings file is not at risk.
 export function preflightPayload(root, harness) {
-    const ignored = [...harness.payload.map((p) => p.to), ...(harness.settings ? [harness.settings] : [])]
+    const targets = harness.payload.map((p) => p.to);
+    const ignored = [...targets, ...(harness.settings ? [harness.settings] : [])]
         .filter((rel) => tryGit(root, 'check-ignore', '-q', '--', rel).ok);
-    if (ignored.length === 0)
-        return ok(undefined);
-    return refuse(ignored.map((rel) => v(rel, 'payload-ignored', 'matched by .gitignore', 'a committable path — worktrees are branch checkouts, so only committed payloads reach ' +
-        '.witness/worktrees/<plan-id>; un-ignore it, or install a different agent here')));
-}
-// A shipped file and an installed file that differ ONLY by version pin are the same
-// file, one upgrade apart. Substituting the installed pin into the shipped text and
-// comparing is exact — no heuristics, no diffing.
-function pinOnlyDifference(shipped, installed) {
-    const installedPin = installed.match(PIN)?.[0];
-    if (installedPin === undefined)
-        return false;
-    return shipped.replace(PIN, installedPin) === installed;
+    if (ignored.length > 0) {
+        return refuse(ignored.map((rel) => v(rel, 'payload-ignored', 'matched by .gitignore', 'a committable path — worktrees are branch checkouts, so only committed payloads reach ' +
+            '.witness/worktrees/<plan-id>; un-ignore it, or install a different agent here')));
+    }
+    // A failed status call is not evidence of dirt: primaryRoot already proved this is a
+    // repo, and inventing a refusal out of a git error would block the upgrade this row
+    // exists to deliver.
+    const status = tryGit(root, 'status', '--porcelain', '--untracked-files=all', '--', ...targets);
+    const dirty = status.ok
+        ? status.out.split('\n').filter((l) => l !== '').map((l) => l.slice(3).trim())
+        : [];
+    // The remedy has to cover both authors of the dirt. `init` writes the payload and
+    // commits it under a lock but NOT a transaction (verbs/init.ts), so a crash between
+    // the two leaves a dirty payload the human never wrote — and telling them to commit it
+    // would be telling them to commit bytes they did not author. Name both cases.
+    if (dirty.length > 0) {
+        return refuse(dirty.map((rel) => v(rel, 'payload-dirty', 'uncommitted change on a payload path', 'a committed payload tree — init overwrites payload files now, and a clobbered edit is ' +
+            'recoverable only from git; commit it if the change is yours, or revert it — a payload ' +
+            'left dirty by a crashed init should be reverted, never committed')));
+    }
+    const engine = harness.payload.find((p) => p.from === ENGINE_SOURCE);
+    const installedPin = engine !== undefined && existsSync(join(root, engine.to))
+        ? pinIn(readFileSync(join(root, engine.to), 'utf8'))
+        : undefined;
+    // `?? 0` is the "cannot compare, so do not refuse" rule: an unparseable pin must never
+    // block an upgrade, exactly as compareTriple's undefined contract states.
+    if (engine !== undefined && installedPin !== undefined && (compareTriple(version(), installedPin) ?? 0) < 0) {
+        return refuse([v(engine.to, 'cli-behind-payload', `payload pins ${installedPin}, this CLI is ${version()}`, `a CLI at or ahead of the installed payload — run ${NPX_LATEST} init --agent ${harness.name}`)]);
+    }
+    return ok(undefined);
 }
-// Revision 1: SYNC, not install-once. These files are witness's artifacts that happen
-// to live in the user's repo, and the engine file's pin is the single point deciding
-// which CLI version the entire pipeline runs — so an install-once rule pinned every repo
-// to whatever version first touched it, forever, with `payload: already installed`
-// printed on every attempt to fix it. A file the human actually edited is still theirs:
-// report it, never clobber it.
+// Revision 1: SYNC, not install-once. Row 102: three-way, not four. The payload files
+// are witness's artifacts that happen to live in the user's repo — the engine file's pin
+// is the single point deciding which CLI the entire pipeline runs, and there is no
+// sanctioned way to customise any of them (the human's config home is
+// witness.config.yaml, repo prose reaches reviewers through row 68's docs: registry).
+// The rule that spared an edited file was defending an unsupported hack while the file
+// it defended froze the repo forever, so it is gone: differing content is overwritten
+// and NAMED, one `git revert` away because row 87 already commits the payload.
 export function installPayload(root, harness) {
     const pre = preflightPayload(root, harness);
     if (!pre.ok)
         return refuse(pre.violations);
-    const out = { written: [], restamped: [], modified: [] };
+    const out = { written: [], overwritten: [] };
     for (const { from, to } of harness.payload) {
         const src = join(packageRoot(), from);
         if (!existsSync(src)) {
@@ -64,15 +107,10 @@ export function installPayload(root, harness) {
             out.written.push(to);
             continue;
         }
-        const installed = readFileSync(dst, 'utf8');
-        if (installed === shipped)
+        if (readFileSync(dst, 'utf8') === shipped)
             continue;
-        if (pinOnlyDifference(shipped, installed)) {
-            writeFileSync(dst, shipped);
-            out.restamped.push(to);
-            continue;
-        }
-        out.modified.push(to);
+        writeFileSync(dst, shipped);
+        out.overwritten.push(to);
     }
     return ok(out);
 }
@@ -113,14 +151,25 @@ export function mergeSettings(existing) {
     doc.hooks = { ...hooks, PreToolUse: pre, SessionStart: start };
     return { text: `${JSON.stringify(doc, null, 2)}\n`, changed: true };
 }
-// The config rung of Decision 5's ladder. Recorded once, on the run that installs the
-// first payload set; a later `--agent` for a second harness leaves it alone, because
-// detection outranks it anyway and rewriting config is not what that run was asked for.
+// The config rung of Decision 5's ladder, and rung ONE of Decision 105's judgment ladder.
+// Recorded once, on the run that installs the first payload set; a later `--agent` for a
+// second harness leaves it alone, because installing a payload set is not being asked to
+// re-point every subsequent verdict. `declared` is what lets the caller SAY so when the
+// two disagree — `{changed: false}` alone cannot tell "already says this" from "says
+// something else", which is why the mismatch was silent.
+//
+// The anchor matters: a commented `# harness: pi` in the scaffold must NOT read as a
+// declaration. Relaxing this to /harness:/ would turn documentation into a permanent,
+// write-once declaration on every repo that ran `witness init`.
 export function recordHarness(configText, name) {
-    if (/^harness:/m.test(configText))
-        return { text: configText, changed: false };
+    const found = /^harness:\s*(\S+)/m.exec(configText);
+    if (found)
+        return { text: configText, changed: false, declared: found[1] };
     const suffix = configText.endsWith('\n') ? '' : '\n';
-    return { text: `${configText}${suffix}harness: ${name}   # detection wins; this is the fallback\n`, changed: true };
+    return {
+        text: `${configText}${suffix}harness: ${name}   # the judge — which harness runs this repo's gate reviewers; declared wins\n`,
+        changed: true,
+    };
 }
 export function writeSettings(root, rel, text) {
     const p = join(root, rel);

package/dist/registry.js

@@ -0,0 +1,39 @@
+// Row 103. The freeze is self-concealing: version() reports the RUNNING CLI, and all
+// seven invocation surfaces (the engine prompt plus six skills) pin the CLI — so a
+// frozen repo only ever runs the frozen CLI, which compares the payload against itself
+// and reports clean. The one fact living outside that loop is what the registry
+// publishes, which is why this is the single network call in the codebase.
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+// The scope's slash must be percent-encoded; the `@` must not be. Same shape pacote uses.
+const PACKAGE = '@popovych.co%2Fwitness';
+// Short on purpose: this rides inside `check`, and a validator that hangs on a bad
+// network is worse than one that stays quiet about it.
+const TIMEOUT_MS = 2000;
+// Best-effort and SILENT on every failure — offline, air-gapped, proxied, rate-limited,
+// HTML interstitial, garbage JSON. `undefined` means "we do not know", which is never a
+// finding: an air-gapped machine must report nothing about the network rather than a
+// complaint about it, and nothing here may touch check's exit code (row 101).
+//
+// WITNESS_REGISTRY is a TEST SEAM, not a configuration key — it overrides the base URL
+// and the literal `off` skips the query, which is what keeps the suite off the network.
+// It is deliberately undocumented, on the precedent of crashPoint's WITNESS_CRASH_AFTER
+// (txn.ts:26): row 90 killed WITNESS_HARNESS to establish that configuration has exactly
+// one home, and the README says so outright. If suppressing this call ever becomes a
+// real user need, it belongs in .witness/config.local.yaml with the other machine facts.
+export async function latestPublished(env) {
+    const base = env.WITNESS_REGISTRY ?? DEFAULT_REGISTRY;
+    if (base === 'off')
+        return undefined;
+    try {
+        const res = await fetch(`${base}/-/package/${PACKAGE}/dist-tags`, {
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return undefined;
+        const tags = (await res.json());
+        return typeof tags.latest === 'string' ? tags.latest : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}