@popovych.co/witness 0.19.3 → 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,9 +218,10 @@ 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 |
+| `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 |
 | `rename <old> <new>` | id rename across canon, refs, journal |
 | `clean` | reap stale worktrees |
@@ -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/abandon.js

@@ -58,12 +58,32 @@ const shaAt = (root, rev, rel) => {
 // D168 (review). Whether this effort's abandon left its write standing — kept, because a plan
 // stood on it or on a sibling slice, or the walk stopped at it. That content is canon of record:
 // no later walk goes past it, or an amendment on top of it took the keep with it.
-function stoodAtAbandon(root, effort, rel, sha) {
+export function stoodAtAbandon(root, effort, rel, sha) {
     const at = journalActs(root, effort, 'HEAD').find(({ entry }) => entry.t === 'human-decision' && entry.decision === 'abandon-effort');
     return at !== undefined && shaAt(root, at.commit, rel) === sha;
 }
 // This effort's newest write of an artifact (of this content, when `sha` is given).
 export const effortWrite = (root, effort, id, sha) => journalActs(root, effort, 'HEAD').filter(({ entry }) => isWrite(entry, id, sha)).at(-1);
+// D190 (review). The effort whose standing write a take-back stopped at, over some write of
+// `effort` that the take-back neither went past nor found already taken back — the write would
+// stay in canon with its effort abandoned. A write under content that stands for good (shipped by
+// a plan outside the set, or left standing by its own effort's abandon) has nothing left to take.
+export function leftUnder(root, canon, spec, effort, walk, abandonSet) {
+    const id = String(spec.meta.id);
+    const stop = walk.stop === undefined ? undefined : writeAct(root, id, walk.stop.sha, walk.stop.src);
+    const forGood = walk.stop !== undefined && (plansOn(canon, id, { exclude: abandonSet, pin: walk.stop.sha }).some((p) => String(p.meta.status) === 'done') ||
+        (stop !== undefined && effortAbandoned(readStream(root, stop.effort)) && stoodAtAbandon(root, stop.effort, spec.rel, walk.stop.sha)));
+    for (const { entry, commit } of journalActs(root, effort, 'HEAD')) {
+        if (!isWrite(entry, id) || walk.passed.includes(commit))
+            continue;
+        if (takenBackAlready(root, effort, id, spec.rel, String(entry.sha)))
+            continue;
+        if (forGood)
+            continue;
+        return stop?.effort ?? 'another write';
+    }
+    return undefined;
+}
 // D168 (review). Whether an earlier abandon already took this effort's newest write of a spec
 // back — `abandon <plan>` does, before the effort's own abandon: a status entry the abandon
 // journaled on the spec after that write, which is not a return, made where the spec stood at
@@ -95,8 +115,9 @@ export function abandonLines(items, kept) {
 }
 // D166 (review). The efforts whose writes the way back takes back besides this abandon's own
 // targets: every effort already abandoned — whose abandon skipped a spec a later re-slice had
-// departed — and the effort being abandoned now (`effort`, absent on the plan path).
-const goneEfforts = (root, effort) => effortStreams(root).filter((e) => e === effort || effortAbandoned(readStream(root, e)));
+// departed — and the efforts being abandoned now (`efforts`, absent on the plan path; D190:
+// several, when they are abandoned as one act).
+const goneEfforts = (root, efforts) => effortStreams(root).filter((e) => (efforts ?? []).includes(e) || effortAbandoned(readStream(root, e)));
 // Content whose act is a write of one of `efforts` never comes back into canon on its own —
 // unless a plan outside the abandon set stands on it (the keep rule, which never takes shipped
 // content back), or that effort's own abandon left it standing.
@@ -108,9 +129,10 @@ function takenBackBy(root, canon, abandonSet, efforts) {
         return act !== undefined && efforts.includes(act.effort) && !stoodAtAbandon(root, act.effort, rel, sha) ? act : undefined;
     };
 }
-// `act`: the write of `pin` this abandon takes back — the effort's own on the effort path, the
-// write the plan is paired with on the plan path. `effort`: the effort being abandoned, if any.
-export function specRevertFor(root, canon, spec, pin, abandonSet, act, effort) {
+// `act`: the write of `pin` this abandon takes back — on the effort path the write that is the
+// spec's content, by one of the efforts being abandoned (`efforts`); on the plan path the write
+// the plan is paired with.
+export function specRevertFor(root, canon, spec, pin, abandonSet, act, efforts) {
     const current = canonicalSha(spec.meta, spec.body);
     if (current !== pin) {
         return refuse([v('spec', 'stacked-amendment', `${String(spec.meta.id)} is at ${current.slice(0, 7)}, pin is ${pin.slice(0, 7)}`, 'abandon newest-first: a later amendment touched this spec')]);
@@ -131,7 +153,7 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, act, effort) {
     // this spec it made: a revise round re-writes, and taking back only the last write left the
     // effort's own first draft in canon. The walk goes back past those and past every abandoned
     // effort's write, and stops at content a plan stands on.
-    const gone = goneEfforts(root, effort);
+    const gone = goneEfforts(root, efforts);
     const walking = [...new Set([...gone, act.effort])];
     const back = takeBack(root, spec.rel, id, act, takenBackBy(root, canon, abandonSet, walking));
     if (back.end === 'lost') {
@@ -141,7 +163,7 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, act, effort) {
     // another plan still building stands on it, is a keep of that effort's content: the same keep
     // the first round alone would have been, and refused for the same reason — this abandon is the
     // last act that could take it back. Once a plan shipped it, it stands for good.
-    if (effort !== undefined && back.end === 'content') {
+    if (efforts !== undefined && back.end === 'content') {
         const sha = canonicalSha(back.doc.meta, back.doc.body);
         const on = plansOn(canon, id, { exclude: abandonSet, pin: sha });
         const owner = on.length > 0 ? writeAct(root, id, sha, back.src) : undefined;
@@ -163,12 +185,12 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, act, effort) {
     // good when a plan shipped it — and then so does this keep, since nothing can take the
     // sibling back. Every spec the walk passes through counts: each was a re-slice being taken back.
     // D188: on the plan path, also a slice whose own write departed nothing — another slice's
-    // write took the predecessor out. Its effort is still live, and its own abandon is the act that
-    // takes the split back together; deleting the slice now left the split half described. The
-    // effort path is that last act, and there a slice another effort cut cannot go back together
-    // with this one: holding it would leave two efforts' abandons each refusing for the other's.
+    // write took the predecessor out. Its effort is still live, and that effort's abandon is the act
+    // that takes the split back together. On the effort path a hold would tie this abandon to the
+    // other slices' efforts, and row 190's review found that no single act frees every such hold
+    // (an effort with shipped work cannot be abandoned; an adopted slice has no effort at all).
     const own = spec.meta.supersedes === undefined ? undefined : String(spec.meta.supersedes);
-    const slice = effort === undefined && back.end === 'create' && own !== undefined && canonExit(readStream(root, own))?.to === 'superseded' ? [own] : [];
+    const slice = efforts === undefined && back.end === 'create' && own !== undefined && canonExit(readStream(root, own))?.to === 'superseded' ? [own] : [];
     const cut = new Set([...returns.map((r) => r.entry.artifact), ...unwound.map((u) => u.artifact), ...slice]);
     const slices = canon.docs
         .filter((d) => d.meta.type === 'spec' && cut.has(String(d.meta.supersedes)) && String(d.meta.id) !== id)
@@ -176,7 +198,8 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, act, effort) {
         const id = String(d.meta.id);
         const leaving = abandonSet.has(id);
         const on = plansOn(canon, id, leaving ? { exclude: abandonSet, pin: canonicalSha(d.meta, d.body) } : { exclude: abandonSet });
-        return leaving && on.length === 0 ? [] : [{ id, shipped: on.some((p) => String(p.meta.status) === 'done') }];
+        // D190: a slice stamped live is shipped behavior whether or not a plan of it is on file.
+        return leaving && on.length === 0 ? [] : [{ id, shipped: String(d.meta.status) === 'live' || on.some((p) => String(p.meta.status) === 'done') }];
     });
     if (slices.length > 0) {
         return ok({ doc: spec, action: 'keep', standing: slices.map((s) => s.id), shipped: slices.some((s) => s.shipped) });
@@ -192,7 +215,7 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, act, effort) {
         // D166. The unwind departs the spec through the same door the re-slice uses, so
         // everything that leaves canon with a spec — its design included — leaves here too.
         return ok({
-            doc: spec, action: 'delete', returns, unwound,
+            doc: spec, action: 'delete', returns, unwound, walk: { passed: back.passed.map((w) => w.commit) },
             departure: prepareDeparture(root, canon.paths, spec, {
                 v: 1, t: 'status', artifact: id, from: String(spec.meta.status), to: 'removed', cause: 'abandon',
             }),
@@ -204,7 +227,9 @@ export function specRevertFor(root, canon, spec, pin, abandonSet, act, effort) {
     const designR = designRel(canon.paths, id);
     const priorDesign = gitBlob(root, back.src, designR);
     const design = priorDesign !== undefined || existsSync(join(root, designR)) ? { rel: designR, prior: priorDesign } : undefined;
-    return ok({ doc: spec, action: 'restore', content: back.blob.toString('utf8'), toStatus, design, returns, unwound });
+    const stopSha = back.end === 'content' ? canonicalSha(back.doc.meta, back.doc.body) : undefined;
+    const walk = { passed: back.passed.map((w) => w.commit), ...(stopSha === undefined ? {} : { stop: { src: back.src, sha: stopSha } }) };
+    return ok({ doc: spec, action: 'restore', content: back.blob.toString('utf8'), toStatus, design, returns, unwound, walk });
 }
 // D167. A return lands on the path its spec left from, and `rename` moves an id but leaves its
 // file, so another doc may hold that path — or another spec this abandon brings back may have
@@ -232,9 +257,18 @@ export function returnCollisions(root, canon, items) {
 // back only beside what it depends on: a dependency in canon that this abandon does not take
 // out, or one it brings back. `write` refuses a dangling `depends`, and an abandon landing one
 // left `check` red after it exited 0. Bringing the dependency back first is a human's call.
-export function landingEdges(root, canon, items) {
+export function landingEdges(root, canon, items, abandonSet = new Set()) {
     const leaving = new Set(items.flatMap((i) => (i.revert?.action === 'delete' ? [String(i.revert.doc.meta.id)] : [])));
     const coming = new Set(items.flatMap((i) => (i.revert?.returns ?? []).map((r) => r.entry.artifact)));
+    const restored = new Set(items.flatMap((i) => (i.revert?.action === 'restore' ? [String(i.revert.doc.meta.id)] : [])));
+    // D190 (review). A doc of the abandon set that this act leaves as it is — kept, or a write an
+    // earlier abandon already took back — stays in canon, so what it depends on may not leave:
+    // `waiting-dependents` reads only docs outside the set, and the act deleted the dependency.
+    const stays = canon.docs
+        .filter((d) => d.meta.type === 'spec' && abandonSet.has(String(d.meta.id)) && !leaving.has(String(d.meta.id)) && !restored.has(String(d.meta.id)))
+        .flatMap((d) => (d.meta.depends ?? []).map(String)
+        .filter((dep) => leaving.has(dep) && !coming.has(dep))
+        .map((dep) => v('spec', 'waiting-dependents', `${String(d.meta.id)} depends on ${dep}`, `${dep} kept while ${String(d.meta.id)} stays in canon — no doc this abandon leaves standing may depend on a spec it deletes`)));
     const lands = items.flatMap((i) => {
         if (!i.revert)
             return [];
@@ -251,7 +285,7 @@ export function landingEdges(root, canon, items) {
         const why = leaving.has(dep) ? 'it leaves with this abandon'
             : exit?.to === 'superseded' ? `it left superseded by ${exit.by ?? 'a successor'}` : 'it left canon';
         return humanCall(v('spec', 'dangling-depends', `${id} depends on ${dep}`, `${dep} in canon when ${id} comes back — ${why} · a human's call`));
-    }));
+    })).concat(stays);
 }
 // D188 (review). A spec kept for good stays in canon with what it depends on: a dependency this
 // abandon would delete is kept beside it, and for good with it. `waiting-dependents` reads only
@@ -276,7 +310,7 @@ export function keepDependencies(items, kept) {
     }
     return { items: walked, kept: held };
 }
-export function executeAbandon(root, ctx, items, effortEntry, subject) {
+export function executeAbandon(root, ctx, items, efforts, subject) {
     const files = new Set();
     const journalMulti = [];
     const stamps = [];
@@ -319,16 +353,17 @@ export function executeAbandon(root, ctx, items, effortEntry, subject) {
             returnEntries.push(...lines);
         }
     }
-    let effortLine;
-    if (effortEntry) {
+    // D190. Each effort the act abandons ends in the same transaction: one terminal entry each.
+    const effortLines = efforts.map((effort) => {
         const entry = {
-            v: 1, t: 'human-decision', gate: 'effort', artifact: effortEntry.effort,
+            v: 1, t: 'human-decision', gate: 'effort', artifact: effort,
             round: 0, decision: 'abandon-effort',
         };
-        effortLine = { stream: effortEntry.effort, line: entryLine(entry) };
-        files.add(journalRel(effortEntry.effort));
-        journalMulti.push(effortLine);
-    }
+        const line = { stream: effort, line: entryLine(entry) };
+        files.add(journalRel(effort));
+        journalMulti.push(line);
+        return line;
+    });
     const lockR = acquireLock(root);
     if (!lockR.ok)
         return lockR;
@@ -360,9 +395,8 @@ export function executeAbandon(root, ctx, items, effortEntry, subject) {
                 appendEntry(root, se.stream, se.entry);
             for (const re of returnEntries)
                 appendEntry(root, re.stream, re.entry);
-            if (effortLine) {
-                appendEntry(root, effortLine.stream, JSON.parse(effortLine.line));
-            }
+            for (const l of effortLines)
+                appendEntry(root, l.stream, JSON.parse(l.line));
             crashPoint(ctx.env, 'abandon-commit');
             const r = stateCommit(root, [...files], subject);
             // D141. `abandon` runs from wherever the human typed it, which may be the very

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'),
@@ -51,7 +55,7 @@ const VERBS = {
 // answered centrally so no verb can crash on --help (several parse argv
 // strictly); each line mirrors the verb's own usage refusal where one exists
 const VERB_USAGE = {
-    abandon: 'witness abandon <plan-id | effort-slug>',
+    abandon: 'witness abandon <plan-id | effort-slug…>',
     adopt: 'witness adopt <specs/... | plans/...>.md',
     ask: 'witness ask <text> | --withdraw <id> [--note <why>]',
     calibrate: 'witness calibrate <exact-model-id> [--suite all|reviewers|skills] [--only <name>] [--samples <n>] [--publish]',
@@ -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/departure.js

@@ -137,12 +137,18 @@ function returnsThrough(root, paths, commit, chain, takenBack, seen) {
         const reached = walkBack(root, rel, id, { src, blob, doc: parsed.value }, takenBack, seen);
         // A write the walk cannot go past leaves the return where it stood before that write.
         const walked = reached.end === 'lost' ? { ...reached, ...reached.at, end: 'content' } : reached;
+        // D190 (review). Every amendment the walk took back on the way brings back what it folded
+        // in (an amendment with `supersedes`): row 168 left that out, and a shipped spec folded into
+        // a predecessor that a later re-slice departed never came back.
+        const amended = walked.passed.filter((w) => walked.end !== 'create' || w !== walked.act);
+        const folds = amended.map((w) => returnsThrough(root, paths, w.commit, [id], takenBack, seen));
+        const folded = { returns: folds.flatMap((f) => f.returns), unwound: folds.flatMap((f) => f.unwound) };
         if (walked.end === 'create') {
             // That write created it: it stays out — journaled so whether or not anything lies under
             // the create — and what it had departed comes back instead.
             const gone = { v: 1, t: 'status', artifact: id, from: 'superseded', to: 'removed', cause: 'abandon' };
             const under = returnsThrough(root, paths, walked.act.commit, [...chain, id], takenBack, seen);
-            return { returns: under.returns, unwound: [gone, ...under.unwound] };
+            return { returns: [...under.returns, ...folded.returns], unwound: [gone, ...under.unwound, ...folded.unwound] };
         }
         const status = walked.passed.length > 0 ? String(walked.doc.meta.status) : exit.from;
         const design = designRel(paths, id);
@@ -165,8 +171,8 @@ function returnsThrough(root, paths, commit, chain, takenBack, seen) {
                     rel,
                     by: successor,
                     depends: (walked.doc.meta.depends ?? []).map(String),
-                }],
-            unwound: [],
+                }, ...folded.returns],
+            unwound: folded.unwound,
         };
     });
     return { returns: ways.flatMap((w) => w.returns), unwound: ways.flatMap((w) => w.unwound) };

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