@popovych.co/witness 0.19.4 → 0.20.0

package/README.md

@@ -63,12 +63,30 @@ witness is two halves: **six skills**, distributed through the
 **engine + guard + dashboard**, which no skills installer can place — `witness init
 --agent <name>` writes those and commits them.
 
-**Claude Code** — one step, the native path:
+**Claude Code** — the native path:
 
 ```bash
 /plugin marketplace add popovych-co/witness    # skills, engine, guard and dashboard together
 ```
 
+**Claude Code, on either route** (the marketplace plugin above, or `init --agent claude-code`),
+also needs the `witness-context` plugin, installed once per machine — then start a new session:
+
+```bash
+claude plugin marketplace add popovych-co/witness && claude plugin install witness-context@witness
+```
+
+It puts the session's live context reading into every Bash command, which is what lets a
+session hand over at `session.contextLimit` (see Run economics below). The reading comes from
+a hooks module, and only a plugin can carry one. `init --agent claude-code` also declares the
+plugin in `.claude/settings.json`, the way a project names a plugin it needs, but the
+declaration alone does not load it in a headless session (`claude -p`, `witness drive`). A
+session loads the plugin when it starts, so one already running when you install it does not:
+start a new one. The install is a copy: after upgrading witness, `claude plugin update
+witness-context@witness` refreshes it, for the sessions started afterwards. Without the plugin
+witness still runs, on the step budget, and says so; `witness check`, run from a session, reports
+whether that session sees the reading.
+
 **Pi** (and any other agent the installer supports):
 
 ```bash
@@ -148,6 +166,8 @@ either.
 |---|---|
 | `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) |
+| `session.contextLimit` | the share of a session's context window, in percent, at which witness hands the work to a fresh session (integer 1–100, default 20). The harness measures the fill; the CLI decides where the journal carries the position — at a step close, after a revise, at a `witness ship` exit and at `next` — and never mid-red. A session whose fill cannot be read says so (`context: unmeasured (<reason>)`): an implement session then hands over by `implement.stepsPerDispatch`, and nothing else hands over (DESIGN.md row 191) |
+| `implement.stepsPerDispatch` | the step budget: steps an implement session closes before it hands over when its fill cannot be read (default 3) — the fallback for `session.contextLimit` |
 | `drive.sessionTimeoutMs` | milliseconds a `drive`-spawned session may run before SIGTERM (default 3600000) |
 | `drive.parallel` | sessions `witness drive` runs at once under autonomy, one per target (default 2) |
 | `drive.parallelSuites` | `true` lets test runs in two worktrees overlap (default false: they take turns, because suites that boot servers or browsers collide) |
@@ -198,7 +218,8 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 | `next` | the one next action across every effort |
 | `drive [--flow <plan-id>] [--max-spawns <n>] [--manual] [--detach] [--ask "<text>"]` | runs every session itself · under autonomy it needs no terminal and reports when nothing else can move. Up to `drive.parallel` targets at once, one session per target; usage limits are waited out; a target past a cap is parked. `--detach` (autonomy only) runs it in the background into `.witness/drive.log`; `--ask` queues an ask first; `--manual` runs serially and asks you at every stop. One drive per repo. A session drive spawned is refused — agents are what drive spawns, never what spawns drive |
 | `ship <plan-id> [--manual]` | lanes → ship gate → PR → CI watch → under autonomy: merge on green · `--manual` keeps that run's stop and merge for a human |
-| `test-evidence` / `verify-red` | journal red/green criteria evidence from a worktree |
+| `test-evidence <plan-id> --phase red\|green [--step <id>]` / `verify-red <plan-id> [--base <ref>] [--step <id>]` | journal red/green criteria evidence from a worktree; `--step` names the plan step the cycle closes — required before the plan's first implement gate (on a plan with a criteria step), left off for a fix round after it. A green that closes a step prints `context:`, `steps:` and `slice:` |
+| `step-close <plan-id> --step <id>` | close a scaffolding step, which has no red→green to witness; prints `context:`, `steps:` and `slice:` as a closing green does, and closing it again changes nothing |
 | `adopt <path>` | absolve a finished hand-edit into the journal |
 | `abandon <plan-id \| effort-slug…>` | wind a plan/effort down; reverts only specs that effort itself wrote — several efforts go as one act, so a split or an amendment they share goes back together |
 | `dispatch-report <plan-id> --steps-assigned <n> --steps-completed <n>` | journal a session slice's telemetry |
@@ -236,15 +257,41 @@ Releasing is `node scripts/release.mjs <major|minor|patch|x.y.z>` followed by tw
 
 ## Run economics (operator notes)
 
-Non-load-bearing knobs for the machine that hosts long implement runs — the design
-depends on none of them (DESIGN.md row 79):
+A witness session ends at a configured share of its context window:
+`session.contextLimit`, 20% by default (DESIGN.md row 191). The harness measures the
+fill — the `witness-context` plugin on Claude Code and the witness extension on Pi put the
+live reading into every shell command's environment — and witness counts no tokens of its
+own. The CLI decides only where the journal already carries the position: at a step
+close (`slice: end`), after a revise, at a `witness ship` exit and at `next`, by
+printing a `relay:` line. A session never hands over mid-red. Once per session, at the
+limit, one line follows a command's result, so a long step learns it is over:
+
+```
+witness: context 21% of 1M has reached the 20% limit — finish what you are in (implement: the red→green), then hand over
+```
+
+Where nothing supplies the reading, witness says so —
+`context: unmeasured (no adapter) — step budget 3` — and an implement session hands over
+after `implement.stepsPerDispatch` steps instead; nothing else hands over.
+
+Operator notes, non-load-bearing — the design depends on none of them:
 
+- **Mind the window.** The limit is a share, so one warm-up weighs differently by model:
+  51k tokens is 5% of a 1M window and 25% of a 200k one. A session that opens over the
+  limit is warned (`warn: this session opens at …`) and works one step per slice; on a
+  small window, raise `session.contextLimit` or accept a warm-up per step. `witness drive`'s
+  defaults were set when a slice was three steps: `drive.sessionTimeoutMs` (1 h) and
+  `drive.caps.spawns` (24). A measured slice on a large window can run past an hour, and on a
+  200k window every slice is one step, so a plan takes more sessions; raise either if drive
+  times out or caps a plan that is still moving.
 - **Keep the host awake.** A suspend longer than an hour mid-run expires the prompt
   cache; on wake the full agent context is re-written at cache-write price. On macOS:
   `witness drive` holds `caffeinate -ims` for its own lifetime (a closed lid on battery
   still sleeps); for a chat session, `caffeinate -dims`, or plug in and disable sleep.
 - **`CLAUDE_CODE_AUTO_COMPACT_WINDOW`** (set at CLI launch) lowers the harness's
-  auto-compaction threshold as belt-and-suspenders under the dispatch budget. It is
-  documented for main sessions only — whether subagents honor it is unverified.
-- The designed mechanisms are the dispatch budget (`implement.stepsPerDispatch`),
-  the loop-width protocol, and `dispatch-report` telemetry — see DESIGN.md rows 79–81.
+  auto-compaction threshold, as belt-and-suspenders under the fill relay. Compaction
+  stays the harness's continuity mechanism, never witness's; the variable is documented
+  for main sessions only — whether subagents honor it is unverified.
+- The designed mechanisms are the fill relay (`session.contextLimit`, with
+  `implement.stepsPerDispatch` for sessions it cannot measure), the loop-width protocol,
+  and `dispatch-report` telemetry — see DESIGN.md rows 79–81 and 191.

package/dist/cli.js

@@ -1,7 +1,9 @@
 import { existsSync } from 'node:fs';
 import { configPath } from './config.js';
+import { journalStamp } from './context.js';
 import { stateFloor } from './floor.js';
 import { primaryRoot } from './gitio.js';
+import { withJournalCtx } from './journal.js';
 import { renderRefusal, v } from './refusal.js';
 import { NPX_LATEST, compareTriple, version } from './version.js';
 export const EXIT = { OK: 0, FINDINGS: 1, REFUSED: 2, BLOCKED: 3 };
@@ -24,6 +26,8 @@ const VERBS = {
     'test-evidence': () => import('./verbs/evidence.js'),
     'verify-red': () => import('./verbs/evidence.js').then((m) => ({ run: m.runVerifyRed })),
     'dispatch-report': () => import('./verbs/dispatch.js'),
+    // Row 191 §4.3. The close of a scaffolding step, the one plan step with no evidence to witness.
+    'step-close': () => import('./verbs/step-close.js'),
     adopt: () => import('./verbs/adopt.js'),
     gate: () => import('./verbs/gate.js'),
     decide: () => import('./verbs/decide.js'),
@@ -77,10 +81,11 @@ const VERB_USAGE = {
     ship: 'witness ship <plan-id> [--manual]',
     start: 'witness start <plan-id>',
     status: 'witness status — flows · blocked docs · reconcile rows · pending gates (bare `witness` is the same screen)',
+    'step-close': 'witness step-close <plan-id> --step <id>',
     sync: 'witness sync',
     trust: 'witness trust <artifact-id> [--yes]',
-    'test-evidence': 'witness test-evidence <plan-id> --phase red|green',
-    'verify-red': 'witness verify-red <plan-id> [--base <ref>]',
+    'test-evidence': 'witness test-evidence <plan-id> --phase red|green [--step <id>]',
+    'verify-red': 'witness verify-red <plan-id> [--base <ref>] [--step <id>]',
 };
 // Row 116 moved the body to version.ts, which journal.ts can import without closing a
 // cycle. Re-exported here because eleven call sites already ask the CLI shell for it and
@@ -132,11 +137,15 @@ export async function main(ctx, argv) {
             }
         }
     }
+    // Row 191 §4.8. Every line this command journals carries the session it runs in, read once
+    // from this invocation's own env: an in-process `main` (drive's decisions, a test's CLI) is
+    // an invocation of its own, with its own env and so its own stamp.
+    const stamp = journalStamp(ctx.env);
     if (!verb || verb === 'help' || verb === '--help') {
         if (!verb) {
             const rootRes = primaryRoot(ctx.cwd);
             if (rootRes.ok && existsSync(configPath(rootRes.value))) {
-                return (await import('./verbs/dashboard.js')).run(ctx, []);
+                return withJournalCtx(stamp, async () => (await import('./verbs/dashboard.js')).run(ctx, []));
             }
         }
         ctx.out(usage());
@@ -153,7 +162,7 @@ export async function main(ctx, argv) {
         return EXIT.REFUSED;
     }
     try {
-        return await (await load()).run(ctx, rest);
+        return await withJournalCtx(stamp, async () => (await load()).run(ctx, rest));
     }
     catch (e) {
         // Row 113. Eight verbs parse argv with node's strict `parseArgs`, which THROWS on a

package/dist/config.js

@@ -99,6 +99,25 @@ export function resolveImplement(raw) {
     }
     return ok({ stepsPerDispatch: val });
 }
+// Row 191 §4.2. The default 20 is the row's premise (§1): once a session's context is more
+// than about 20% full, its output gets worse. A repo decision, so its one home is
+// witness.config.yaml, never config.local.yaml (row 90).
+export const DEFAULT_CONTEXT_LIMIT = 20;
+export function resolveSession(raw) {
+    const conf = raw.session;
+    if (conf === undefined)
+        return ok({ contextLimit: DEFAULT_CONTEXT_LIMIT });
+    if (typeof conf !== 'object' || conf === null || Array.isArray(conf)) {
+        return refuse([v('session', 'invalid', String(conf), 'a map of session settings')]);
+    }
+    const val = conf.contextLimit;
+    if (val === undefined)
+        return ok({ contextLimit: DEFAULT_CONTEXT_LIMIT });
+    if (typeof val !== 'number' || !Number.isInteger(val) || val < 1 || val > 100) {
+        return refuse([v('session.contextLimit', 'invalid', String(val), 'an integer from 1 to 100 — % of the session\'s context window at which witness hands over to a fresh session')]);
+    }
+    return ok({ contextLimit: val });
+}
 // D145. One hour. An implement slice is ~25 minutes at the default budget of 3 steps,
 // and the cost of the two errors is not symmetric: a generous ceiling wastes an hour
 // once, a starved one kills a working e2e run and hands the human a false `spawn-timeout`
@@ -356,6 +375,9 @@ export function loadConfig(root) {
     const implement = resolveImplement(obj);
     if (!implement.ok)
         return refuse(implement.violations);
+    const session = resolveSession(obj);
+    if (!session.ok)
+        return refuse(session.violations);
     const gates = resolveGates(obj);
     if (!gates.ok)
         return refuse(gates.violations);
@@ -375,6 +397,7 @@ export function loadConfig(root) {
         paths: paths.value,
         docs: docs.value,
         implement: implement.value,
+        session: session.value,
         gates: gates.value,
         drive: drive.value,
         autonomy: autonomy.value && !uncommitted,

package/dist/context.js

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { HARNESSES, loadHarness, resolveDriver } from './harness.js';
+// Row 191 §4.1. Before every shell command the harness adapter puts the session's live fill
+// here, as the harness itself measures it:
+//   {"session":"<harness session id>","tokens":31627,"window":1000000,"percent":3}
+// The CLI counts nothing and keeps no table of windows (§2: a second ledger would drift from
+// what the harness shows), and it ignores `percent`, so the two harnesses cannot round apart.
+export const CONTEXT_ENV = 'WITNESS_CONTEXT';
+// The session is a fact about the process running this command, not about the repo, so it
+// comes from the driver ladder without the config rung: detection, else the default harness.
+// The variable is the registry's `session` facet, never spelled here.
+export function sessionIdOf(env) {
+    const driver = resolveDriver(env, {});
+    if (!driver.ok)
+        return undefined;
+    const id = env[driver.value.harness.session];
+    return id === undefined || id === '' ? undefined : id;
+}
+// Row 191 §4.8: the journal is committed, so it carries this hash and never the id itself.
+export function sessionHash(id) {
+    return createHash('sha256').update(id).digest('hex').slice(0, 12);
+}
+const unmeasured = (reason) => ({ measured: false, reason });
+const isInt = (x) => typeof x === 'number' && Number.isInteger(x);
+// Row 191 §4.1. Trusted only when it parses, carries integer counts with tokens ≤ window, and
+// names the session the harness names. That last check is what makes an inherited value
+// harmless: a drive launched from a chat session's shell carries the chat's reading, and its
+// child runs as a session of its own. The order is the reasons' precedence: a broken value is
+// malformed whoever wrote it, and only this session's own value can say it has no reading yet.
+export function readFill(env) {
+    const raw = env[CONTEXT_ENV];
+    if (raw === undefined || raw === '')
+        return unmeasured('no adapter');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return unmeasured('malformed');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return unmeasured('malformed');
+    const { session, tokens, window } = parsed;
+    if (typeof session !== 'string' || session === '')
+        return unmeasured('malformed');
+    if (!isInt(window) || window < 1)
+        return unmeasured('malformed');
+    if (tokens !== undefined && tokens !== null && (!isInt(tokens) || tokens < 0 || tokens > window)) {
+        return unmeasured('malformed');
+    }
+    if (session !== sessionIdOf(env))
+        return unmeasured('stale');
+    // P7: Claude Code sends no `tokens` before the session's first response, Pi sends 0 then,
+    // and Pi sends null right after a compaction. Each is a reading not taken yet.
+    if (!isInt(tokens) || tokens === 0)
+        return unmeasured('no reading yet');
+    return { measured: true, reading: { session, tokens, window } };
+}
+// Row 191 §4.8: what this invocation's journal lines carry. The session whenever the harness
+// names one, even unmeasured, because the step-budget fallback counts a session's steps by
+// it; the reading only when it is trusted. Outside a harness session, nothing.
+export function journalStamp(env) {
+    const id = sessionIdOf(env);
+    if (id === undefined)
+        return undefined;
+    const session = sessionHash(id);
+    const fill = readFill(env);
+    return fill.measured ? { session, tokens: fill.reading.tokens, window: fill.reading.window } : { session };
+}
+// Row 191 §4.9. Drive is a scheduler, not a session. Started from a chat session's shell, it
+// inherits that session's reading and the harness's session variable, and neither is a fact
+// about drive or about the sessions it spawns: each harness names its own session on its own
+// commands (P1, and pi's bash tool). Every harness's variable goes, whichever drive spawns,
+// read from the registry so none is spelled here.
+export function withoutSession(env) {
+    const out = { ...env };
+    delete out[CONTEXT_ENV];
+    for (const name of HARNESSES) {
+        const harness = loadHarness(name);
+        if (harness.ok)
+            delete out[harness.value.session];
+    }
+    return out;
+}
+// Row 191 §4.5. The decision is `reached`, in integer tokens; the display is floored, so the
+// two agree: a printed 19% never hands over and a printed 20% always does. Rounding would
+// print 20% beside a session that carries on.
+//
+// pctOf and windowLabel have a twin in plugin/hooks/context-core.mjs, for the adapters' warning:
+// the CLI must not import plugin/ at runtime, so tests/context-core.test.ts holds the two equal.
+export function pctOf(tokens, window) {
+    return Math.floor(tokens * 100 / window);
+}
+export function reached(tokens, window, limit) {
+    return tokens * 100 >= limit * window;
+}
+// The window a fill is a share of, the way people say it: 1M, 200k. Display only: a window that
+// is not round reads approximately (1048576 is 1M), and the percentage still uses the exact one.
+// Thousands are rounded first, so a window that rounds up to a thousand of them reads 1M, never
+// 1000k.
+export function windowLabel(window) {
+    if (window < 1_000)
+        return String(window);
+    const thousands = Math.round(window / 1_000);
+    if (thousands < 1_000)
+        return `${thousands}k`;
+    return `${Math.round(window / 100_000) / 10}M`;
+}

package/dist/drive.js

@@ -4,7 +4,8 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { EXIT, main } from './cli.js';
 import { loadConfig, loadLocalConfig } from './config.js';
-import { resolveJudge } from './harness.js';
+import { withoutSession } from './context.js';
+import { detectionVariables, resolveJudge } from './harness.js';
 import { ok, refuse, renderRefusal, v } from './refusal.js';
 import { findById, loadCanon } from './scan.js';
 import { resolveSpawn } from './spawn.js';
@@ -16,6 +17,7 @@ import { unmetNeeds } from './needs.js';
 import { capHit, parkAtCap } from './caps.js';
 import { effortStreams, readStream } from './journal.js';
 import { effortOf } from './reviewed.js';
+import { vacuousEvidence } from './steps.js';
 import { pendingTxn } from './txn.js';
 import { duration, limitIn, realClock, sessionLimit, SINGLE_WAIT_MAX_MS, TOTAL_WAIT_MAX_MS, waitFor, } from './usage.js';
 import { keepAwake } from './awake.js';
@@ -145,12 +147,26 @@ export async function spawnSession(step, cfg, ctx, spawnN, opts = {}) {
     // a scripted fake that performs real CLI acts. Never documented for users — a spawn
     // binary chosen by ambient env is exactly the identity confusion row 90 removed.
     const bin = ctx.env.WITNESS_DRIVE_AGENT_BIN ?? cmd;
-    // Row 164: on Windows the agent CLI may be a `.cmd` shim, which only cmd.exe can start.
     // Row 180: the marker is the child's target and its recursion guard in one.
-    const run = resolveSpawn(bin, args, {
-        ...ctx.env, ...env, WITNESS_BIN: localBin(ctx), [DRIVE_ENV]: step.target ?? TARGETLESS,
+    //
+    // Row 191 §4.9: a drive started from a chat session's shell inherits that session's reading
+    // and session variable, and the child is a session of its own that its harness names itself.
+    // The session check already makes a stale reading harmless; leaving both out is the second
+    // guard. The verb drops them on entry too; this holds for any other caller.
+    //
+    // Every harness's detection variable goes too, from the child alone (final review minor 5): its
+    // harness sets its own, and an inherited one named the chat's harness to a child of another — a
+    // claude child of a drive typed in a Pi chat detected Pi, read its own reading as stale and
+    // relayed with /new. Drive keeps them: the judge above, whose worker this is, may be detection's.
+    const inherited = withoutSession(ctx.env);
+    for (const variable of detectionVariables())
+        delete inherited[variable];
+    const childEnv = {
+        ...inherited, ...env, WITNESS_BIN: localBin(ctx), [DRIVE_ENV]: step.target ?? TARGETLESS,
         [DRIVE_DEADLINE_ENV]: String(t0 + cfg.drive.sessionTimeoutMs),
-    });
+    };
+    // Row 164: on Windows the agent CLI may be a `.cmd` shim, which only cmd.exe can start.
+    const run = resolveSpawn(bin, args, childEnv);
     if (!run.ok) {
         renderRefusal(run.violations).forEach((l) => ctx.err(l));
         return end('spawn-failed');
@@ -259,8 +275,10 @@ const STREAM_PREFIX = /^\[\d+ [^\]]*\] /;
 // What `mergeOwnPr` prints when it leaves the merge to a human (ship.ts), and nothing else.
 const MERGE_LINE = /^ship: "?merge PR #(\d+) on GitHub when ready/;
 const streamLines = (root, id) => readStream(root, id).length;
-// A refused write is the CLI saying no: it moves nothing (F5).
-const moved = (e) => e.t !== 'write-refused';
+// A refused write is the CLI saying no: it moves nothing (F5). Nor does a vacuous red (row 191,
+// final review I3): a session that only re-runs one has done nothing, and counted, it read as
+// progress, so the target was respawned until its spawn cap.
+const moved = (e) => e.t !== 'write-refused' && !vacuousEvidence(e);
 // Row 181. Did anything happen for THIS target? A whole-journal count is satisfied by any
 // other lane's progress, so a stalled flow beside a busy one would spawn until the ceiling.
 // A target's key is its line, its stream, and the entries in its owning effort's stream that

package/dist/evidence.js

@@ -86,6 +86,8 @@ export async function runSpecTests(runRoot, ctx, parentId, trustRoot, opts = {})
     }
     return ok({ runner: 'full-suite', tests, allOk: tests.every((t) => t.ok) });
 }
+// Row 191 §4.3. `step` is the plan step this cycle closes; absent on a cycle that is no plan
+// step's (a fix round after a gate).
 export function journalEvidence(stateRoot, planId, phase, run, extra = {}) {
     const entry = { t: 'test-evidence', artifact: planId, phase, runner: run.runner, tests: run.tests, ...extra };
     const marker = {
@@ -169,7 +171,10 @@ export function changedFiles(runRoot, base) {
     return [...new Set([...tracked, ...untracked])].sort();
 }
 const inCommit = (runRoot, ref, rel) => tryGit(runRoot, 'cat-file', '-e', `${ref}:${rel}`).ok;
-export async function verifyRed(runRoot, stateRoot, ctx, planId, parentId, base) {
+export async function verifyRed(runRoot, stateRoot, ctx, planId, parentId, base, step) {
+    // Row 191 §4.3: a reconstructed cycle closes a plan step as a witnessed one does, so both of
+    // its entries name the step.
+    const extra = { reconstructed: true, ...(step !== undefined ? { step } : {}) };
     const files = changedFiles(runRoot, base);
     if (!files.some(isTestPath)) {
         return refuse([v('diff', 'no-test-changes', `${files.length} changed files, none are tests`, 'a diff that adds or modifies tagged tests')]);
@@ -210,7 +215,7 @@ export async function verifyRed(runRoot, stateRoot, ctx, planId, parentId, base)
             else if (existsSync(join(runRoot, rel)))
                 rmSync(join(runRoot, rel));
         }
-        red = await recordEvidence(runRoot, stateRoot, ctx, planId, parentId, 'red', { reconstructed: true });
+        red = await recordEvidence(runRoot, stateRoot, ctx, planId, parentId, 'red', extra);
     }
     finally {
         for (const rel of trackedNonTest) {
@@ -232,7 +237,14 @@ export async function verifyRed(runRoot, stateRoot, ctx, planId, parentId, base)
     }
     if (!red.ok)
         return red;
-    const green = await recordEvidence(runRoot, stateRoot, ctx, planId, parentId, 'green', { reconstructed: true });
+    // Final review I3. A vacuous red is a finding, not a cycle: the green still runs, since it is
+    // what confirms the restore, but journals nothing. Journaled, it read as an act of the session
+    // and as drive's progress, so a session that opened over the limit and only re-ran this handed
+    // over forever, and drive respawned it to its cap. A step an earlier genuine red opened is
+    // closed by the green `next` routes for that open red, never by this reconstruction.
+    const green = red.value.allOk
+        ? await runSpecTests(runRoot, ctx, parentId, stateRoot)
+        : await recordEvidence(runRoot, stateRoot, ctx, planId, parentId, 'green', extra);
     if (!green.ok)
         return green;
     return ok({ redOk: !red.value.allOk, greenOk: green.value.allOk, vacuous: red.value.allOk });

package/dist/gate.js

@@ -24,6 +24,7 @@ import { gateSettled, owedRun } from './verbs/next.js';
 import { prepareStamp, writeStamp } from './stamp.js';
 import { recommend, renderDecision } from './recommend.js';
 import { autonomyLines } from './autonomy.js';
+import { reportHandover, slicesLine } from './slice.js';
 const GATES = new Map();
 export function registerGate(spec) { GATES.set(spec.gate, spec); }
 export function gateSpec(name) { return GATES.get(name); }
@@ -114,7 +115,7 @@ export function renderGateRun(ctx, entry, mode, opts = {}) {
 // nothing-pending and the exits line's single re-gate act is the whole live set (D131).
 function renderChoices(ctx, gate, target, entries, upstream, stale = false) {
     // D154. Resolved here rather than threaded through four call sites, on this file's own
-    // precedent (`printDispatchArithmetic` loads canon itself so the entry-renderers stay
+    // precedent (`printSliceShape` loads canon itself so the entry-renderers stay
     // pure formatters). Best-effort: a root that will not resolve costs the trust variants,
     // never the block.
     const rootR = primaryRoot(ctx.cwd);
@@ -127,10 +128,11 @@ function renderChoices(ctx, gate, target, entries, upstream, stale = false) {
     else
         ctx.out(cmd('help', liveExits(gate, target, entries, stale, upstream)));
 }
-// Row 79: the human approving a plan sees the run's shape before it starts.
-// Display only — no lens, no threshold; loads config/canon itself so the
+// Row 79: the human approving a plan sees the run's shape before it starts. Row 191 §4.10:
+// under a measured harness that shape is the rule that will cut the run into slices, not a
+// count of them. Display only — no lens, no threshold; loads config/canon itself so the
 // entry-renderers stay pure formatters.
-export function printDispatchArithmetic(ctx, root, gateName, target) {
+export function printSliceShape(ctx, root, gateName, target) {
     if (gateName !== 'plan')
         return;
     const cfg = loadConfig(root);
@@ -139,9 +141,7 @@ export function printDispatchArithmetic(ctx, root, gateName, target) {
     const doc = findById(loadCanon(root), target);
     if (!doc || doc.meta.type !== 'plan')
         return;
-    const budget = cfg.value.implement.stepsPerDispatch;
-    const steps = (doc.meta.steps ?? []).length;
-    ctx.out(kv('dispatches', `${steps} step(s) ≈ ${Math.ceil(steps / budget)} dispatch(es) at budget ${budget}`));
+    ctx.out(kv('slices', slicesLine(cfg.value)));
 }
 // Row 173. The gate, then — under `autonomy: on` and not a `--manual` run — the settling of
 // the stop it produced or re-showed, in the same invocation, so a chat session and drive
@@ -161,7 +161,14 @@ export async function runGate(ctx, gateName, target, flags) {
     // A dynamic import: settle.ts reaches decide.ts, whose gates/index.js import would close a
     // static cycle through this module — each gate's registerGate would run before GATES exists.
     const { settleStop, settledCode } = await import('./settle.js');
-    return settledCode(code, await settleStop(ctx, rootR.value, cfgR.value, gateName, target));
+    const settled = await settleStop(ctx, rootR.value, cfgR.value, gateName, target);
+    // Row 191 §4.4. A revise settled here is handed to the session that ran the gate, so this is
+    // where a session at its limit hands it to a fresh one. Ship passes `handover: false`: its run
+    // hands over once, at its own exit (Plan's call 7).
+    const revised = settled.kind === 'decided' && (settled.decision === 'revise' || settled.decision === 'revise-upstream');
+    if (revised && flags.handover !== false)
+        reportHandover(ctx, rootR.value, cfgR.value, { guard: false });
+    return settledCode(code, settled);
 }
 async function judge(ctx, gateName, target, flags) {
     const rootR = primaryRoot(ctx.cwd);
@@ -340,7 +347,7 @@ async function judge(ctx, gateName, target, flags) {
             entries, upstream: upstreamId,
             ...(kind.entry.outcome === 'stopped' && leftToTail(entries) ? { help: false } : {}),
         });
-        printDispatchArithmetic(ctx, root, spec.gate, target);
+        printSliceShape(ctx, root, spec.gate, target);
         return kind.entry.outcome === 'passed' ? EXIT.OK : EXIT.FINDINGS;
     }
     if (kind.kind === 'changed-nothing') {
@@ -565,7 +572,7 @@ async function judge(ctx, gateName, target, flags) {
             entries: after, upstream: upstreamId,
             ...(entry.outcome === 'stopped' && leftToTail(after) ? { help: false } : {}),
         });
-        printDispatchArithmetic(ctx, root, spec.gate, target);
+        printSliceShape(ctx, root, spec.gate, target);
         for (const d of discharged)
             ctx.out(kv('discharged', `${d.id} — no longer reported by this round`));
         if (input.repin)

package/dist/gates/implement.js

@@ -53,7 +53,9 @@ function resolveDesignCaptures(stateRoot, wt, planId) {
         out.push({ name: c.name, path });
     }
     if (out.length === 0) {
-        return refuse([v('screens', 'screens-matched-nothing', `0 verified captures for the latest green cycle of ${planId}`, 'a UI plan (design-from pinned) must witness ≥1 screenshot — name captures in the browser test, then re-run: witness test-evidence <plan> --phase green')]);
+        // Row 191: refusing journals no gate run, so on a plan's first gate the re-run it names is
+        // still a step's cycle, and `test-evidence` requires the step there.
+        return refuse([v('screens', 'screens-matched-nothing', `0 verified captures for the latest green cycle of ${planId}`, 'a UI plan (design-from pinned) must witness ≥1 screenshot — name captures in the browser test, then re-run: witness test-evidence <plan> --phase green --step <id>')]);
     }
     return ok(out);
 }

package/dist/harness.js

@@ -74,6 +74,7 @@ const REGISTRY = {
         name: 'claude-code',
         launch: 'claude',
         relay: '/clear',
+        session: 'CLAUDE_CODE_SESSION_ID',
         settings: '.claude/settings.json',
         bundled: true,
         payload: [
@@ -114,13 +115,15 @@ const REGISTRY = {
         launch: 'pi',
         defaultProvider: 'anthropic',
         relay: '/new',
+        session: 'PI_SESSION_ID',
         bundled: false,
         payload: [
             { from: 'plugin/commands/witness.md', to: '.pi/prompts/witness.md' },
             { from: 'plugin/hooks/canon-guard.mjs', to: '.pi/extensions/canon-guard.mjs' },
-            // Source-tree sibling of canon-guard.mjs, exactly as it is in .pi/extensions/:
-            // the adapter imports the core with ONE static relative specifier, and a
-            // specifier that only resolves after install is a trap no unit test can hold.
+            { from: 'plugin/hooks/context-core.mjs', to: '.pi/extensions/context-core.mjs' },
+            // Source-tree sibling of both cores, exactly as it is in .pi/extensions/: the
+            // adapter imports each with ONE static relative specifier, and a specifier that
+            // only resolves after install is a trap no unit test can hold.
             { from: 'plugin/hooks/witness-pi.ts', to: '.pi/extensions/witness.ts' },
             { from: 'plugin/hooks/session-dashboard.sh', to: '.pi/extensions/session-dashboard.sh' },
         ],
@@ -166,13 +169,20 @@ export function loadHarness(name) {
     return ok(harness);
 }
 // Detection tests PRESENCE: neither CLAUDECODE=1 nor PI_CODING_AGENT=true is a documented
-// value contract.
+// value contract. Each harness sets its variable on the commands it runs; read in this order.
+const DETECTION = [
+    { variable: 'PI_CODING_AGENT', name: 'pi' },
+    { variable: 'CLAUDECODE', name: 'claude-code' },
+];
 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;
+    const hit = DETECTION.find((d) => env[d.variable] !== undefined);
+    return hit === undefined ? undefined : { source: 'detected', name: hit.name };
+}
+// Row 191 §4.9 (final review minor 5). Every harness's detection variable: what a session drive
+// spawns must not inherit, since its own harness sets its own on the commands it runs, and one
+// inherited from the chat drive was typed in would name that chat's harness to a child of another.
+export function detectionVariables() {
+    return DETECTION.map((d) => d.variable);
 }
 function declaredRung(raw) {
     const configured = raw.harness;

package/dist/install.js

@@ -156,6 +156,28 @@ export function installAllHomes(root, harness) {
 function hasCommand(entries, command) {
     return (entries ?? []).some((e) => (e.hooks ?? []).some((h) => h.command === command));
 }
+// Row 191 §4.11. The context reading comes from a hooks module, and only a plugin carries one:
+// witness-context, listed in witness's own GitHub marketplace beside the full plugin, which does
+// not carry it (two copies would each latch and warn). P9 (2026-10-22): a headless session
+// skipped a plugin the project's settings declared while its marketplace was not registered on
+// the machine, and loaded one installed at user scope from the registered marketplace, at the
+// root and in a worktree. So every machine installs it once: CONTEXT_INSTALL, which init and
+// check print.
+const WITNESS_REPO = 'popovych-co/witness';
+export const WITNESS_MARKETPLACE = 'witness';
+export const CONTEXT_PLUGIN = `witness-context@${WITNESS_MARKETPLACE}`;
+// No comma: check prints it through toon's kv, which quotes a value holding one.
+export const CONTEXT_INSTALL = `claude plugin marketplace add ${WITNESS_REPO} && claude plugin install ${CONTEXT_PLUGIN}`;
+// The settings map `current` with `name` added, or undefined when it needs nothing: an entry of
+// that name is the human's, and so is a value that is not a map at all — theirs to fix, never
+// ours to replace.
+function withEntry(current, name, value) {
+    if (current === undefined)
+        return { [name]: value };
+    if (typeof current !== 'object' || current === null || Array.isArray(current))
+        return undefined;
+    return Object.hasOwn(current, name) ? undefined : { ...current, [name]: value };
+}
 // Merge, never replace: .claude/settings.json is the human's file and may already carry
 // their own hooks, model pin and permissions. We append only what is missing, matched
 // by command string, and preserve every other key byte for byte.
@@ -199,10 +221,25 @@ export function mergeSettings(existing) {
             changed = true;
         }
     }
+    // Row 191 §4.11. The repo declares the plugin its sessions read the fill from, the way Claude
+    // Code lets a project name a plugin it needs: its marketplace, and the plugin enabled. Headless
+    // the entry is skipped, harmlessly, until the machine has registered the marketplace (P9);
+    // whether a session's trust prompt offers the install from it is unprobed, owed with §6's
+    // chat-mode check. Append-what's-missing, as above: an entry the human has under either name
+    // is theirs — an explicit `false` turns the plugin off on purpose, and their `witness`
+    // marketplace may point at a local checkout.
+    const marketplaces = withEntry(doc.extraKnownMarketplaces, WITNESS_MARKETPLACE, { source: { source: 'github', repo: WITNESS_REPO } });
+    const plugins = withEntry(doc.enabledPlugins, CONTEXT_PLUGIN, true);
+    if (marketplaces !== undefined || plugins !== undefined)
+        changed = true;
     if (!changed)
         return { text: existing ?? '', changed: false };
     doc.hooks = { ...hooks, PreToolUse: pre, SessionStart: start };
     doc.permissions = { ...perms, allow };
+    if (marketplaces !== undefined)
+        doc.extraKnownMarketplaces = marketplaces;
+    if (plugins !== undefined)
+        doc.enabledPlugins = plugins;
     return { text: `${JSON.stringify(doc, null, 2)}\n`, changed: true };
 }
 // The config rung of Decision 5's ladder, and rung ONE of Decision 105's judgment ladder.