@popovych.co/witness 0.16.0 → 0.18.0

package/README.md

@@ -149,6 +149,12 @@ 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) |
 | `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) |
+| `drive.caps.rounds` | gate rounds one target may run across budget resets (default 16) — the run parks a target that reaches it |
+| `drive.caps.upstream` | upstream resets one target may take (default 6) — the run parks a target that reaches it |
+| `drive.caps.spawns` | sessions one target may take in one drive run (default 24) — the run parks a target that reaches it |
+| `drive.caps.wallClockMs` | milliseconds of session time one target may take in one drive run (default 57600000 · 16 h) — the run parks a target that reaches it |
 | `autonomy: on \| off` | whether the CLI settles its own stops — through its recommendation or the arbiter it launches — and merges its own PRs once CI is green (default off). A committed repo fact: it counts only once HEAD says it, and the merge also needs the ship branch on origin to say it. `--manual` on a gate run keeps that run's stop for a human, and three stops always reach one: the look of a new screen, an unmet plan need and a trust grant |
 | `ship.merge: merge \| squash \| rebase` | how `witness ship` merges its own PR under `autonomy: on` (default merge) — only once the ship gate is approved and CI is green, and never when the approval lapsed or GitHub refuses |
 | `ship.ciSettleMs` | milliseconds a green check set must hold still before `witness ship` merges under autonomy (default 60000, at most 1800000) — gh's watch ends the moment nothing is pending, so a check that registers late would otherwise be missed. Green means at least one check passed and none failed, was cancelled or is pending |
@@ -165,6 +171,7 @@ are declared in machine config, not env:
 reviewerExtensions:
   - /Users/you/.pi/agent/npm/node_modules/pi-claude-oauth-adapter
 opener: xdg-open   # optional; nonstandard desktops only
+notify: /usr/local/bin/ping-me   # optional; the run summary is its one argument · default: the platform notifier
 ```
 
 Repo facts live in `witness.config.yaml` (committed); machine facts live in
@@ -182,14 +189,14 @@ the wrong file refuses. There are no `WITNESS_*` env vars for configuration.
 | `read <id> [--design] [--outline] [--lines <a>-<b>]` | print a spec/plan/design from the primary root — the read route, since a worktree carries no canon copy; `--outline` names each anchor's line range for fat artifacts |
 | `check` | schema, graph, invariants, needs, trailer audit, probes |
 | `index` | id · summary · status · depends across the canon, then each spec's plans |
-| `satisfy <id> --need <text\|n>` | flip a manual need via the write path |
+| `satisfy <id> --need <id\|n\|text>` | journal a manual need as met — the spec is never rewritten |
 | `log <id>` | render a journal stream |
 | `gate <decompose\|plan\|implement\|ship\|design> <id>` | run the reviewer gate; journals the round, stamps on pass |
 | `decide <gate> <id> --approve\|--revise [--pin <policy>]` | record the human decision on a stopped gate; `--pin` adds a standing content policy |
 | `design <spec-id> --file <html>\|--open\|--reconfirm` | register/show a `ui` spec's approved look |
 | `start <plan-id>` | create/re-attach the plan's worktree (`.witness/worktrees/<id>`) — code only: the canon dirs are excluded from it, so a plan cannot go stale in there |
 | `next` | the one next action across every effort |
-| `drive [--flow <plan-id>] [--max-spawns <n>]` | schedule green-path work through headless sessions; you appear only at judgment stops. TTY-only — agents are what drive spawns, never what spawns drive |
+| `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 |
 | `adopt <path>` | absolve a finished hand-edit into the journal |
@@ -234,7 +241,8 @@ depends on none of them (DESIGN.md row 79):
 
 - **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:
-  `caffeinate -dims` for the session, or plug in and disable sleep.
+  `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.

package/dist/allowlist.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { heldCriteria } from './needs.js';
 const allowPath = (root) => join(root, '.witness', 'allow.json');
 function load(root) {
     if (!existsSync(allowPath(root)))
@@ -35,11 +36,15 @@ export function grantCommands(root, cmds) {
 // artifact is the SPEC that owns the criteria: a plan gate judges a plan, but criteria live
 // on the spec it derives from, and a block that listed nothing there would hide the very
 // commands its approve is about to leave blocked.
+//
+// Row 179: a criterion an unmet need holds is not run, so it needs no trust until the need is
+// met. `witness trust <id>` still lists every command, so a human may trust one ahead of time.
 export function untrustedCmdsFor(root, doc) {
     if (!doc)
         return [];
+    const held = heldCriteria(doc);
     const list = Array.isArray(doc.meta.criteria) ? doc.meta.criteria : [];
-    const cmds = list.map((c) => c.cmd).filter((c) => typeof c === 'string');
+    const cmds = list.filter((c) => !held.has(String(c.id))).map((c) => c.cmd).filter((c) => typeof c === 'string');
     const trusted = new Set(load(root));
     return [...new Set(cmds.filter((c) => !trusted.has(c)))];
 }

package/dist/arbiter.js

@@ -1,3 +1,4 @@
+import { askOf, askText } from './ask.js';
 import { decidedBy } from './autonomy.js';
 import { loadLocalConfig } from './config.js';
 import { openDeferrals } from './deferral.js';
@@ -13,7 +14,7 @@ import { anchorRecurrence, gateRuns, roundBudget } from './rounds.js';
 import { findById } from './scan.js';
 import { canonicalJson } from './sha.js';
 // How a later mode (plan A2's recap check) adds its own prompt without a second invoker.
-export const PROMPT_OF = { decision: 'arbiter' };
+export const PROMPT_OF = { decision: 'arbiter', recap: 'arbiter-recap' };
 const TEXT_MAX = 600;
 function renderOptions(menu) {
     return menu.flatMap((o, i) => [
@@ -87,7 +88,7 @@ export async function arbitrate(ctx, root, cfg, req) {
         }
         const ruling = readRuling(text, req.menu.length);
         if (ruling.ok) {
-            return ok({ ...ruling.value, model: chain[rung], prompts_sha: promptsSha([{ name: 'arbiter', contents: lens.contents }]) });
+            return ok({ ...ruling.value, model: chain[rung], prompts_sha: promptsSha([{ name: PROMPT_OF[req.mode], contents: lens.contents }]) });
         }
         if (attempt === 0) {
             // One self-repair reroll on the same rung, in the shape runBattery gives a lens.
@@ -184,6 +185,11 @@ export function decisionEvidence(root, canon, stop) {
             }
         }
         sections.push({ title: 'Scope', body: scope.join('\n\n') });
+        // Row 177. A decompose stop is judged against the ask as well as the recap: both of its
+        // arbiter routes (the feature-scope stop and amendment-ack) re-scope what the human asked.
+        const ask = gate === 'decompose' ? askOf(root, target) : undefined;
+        if (ask !== undefined)
+            sections.push({ title: 'The ask', body: `${ask.id} — ${askText(ask.text)}` });
     }
     return sections;
 }

package/dist/ask.js

@@ -0,0 +1,182 @@
+import { FLOOR_STREAM } from './floor.js';
+import { stateCommit } from './gitio.js';
+import { appendEntry, effortStreams, entryLine, journalRel, readStream } from './journal.js';
+import { acquireLock } from './lock.js';
+import { ok, refuse, v } from './refusal.js';
+import { ROUND_BOUND } from './rounds.js';
+import { crashPoint, pendingTxn, withTxn } from './txn.js';
+// Row 176. The human's ask is journaled state, on a stream witness owns the way it owns
+// `floor`. This module is its one home: the entries, the queue derived from them, and the
+// one write path the verb, `/witness <text>` and `drive --ask` share — so a crashed session
+// loses nothing, because the brainstorm that answers an ask reads it from here, never from
+// its prompt.
+export const ASK_STREAM = 'asks';
+// The house bound on review rounds: a recap sent back three times waits for a human.
+export const RECAP_CHECK_BOUND = ROUND_BOUND;
+export function recapChecks(root, id) {
+    return readStream(root, ASK_STREAM)
+        .filter((e) => e.t === 'human-decision' && e.gate === 'recap' && e.artifact === id);
+}
+// The one rendering of why a check sent a recap back, shared by `recap`'s output, `next`'s
+// rung and the arbiter's own prior-checks section — so it lives here, and this module never
+// imports recap-check.ts.
+export function checkReason(e) {
+    return e.rule === 'recap-class'
+        ? `class — the recap says ${e.class} and the check decided ${e.decided ?? '?'} · ${e.reason}`
+        : e.reason;
+}
+// Display only: the stored text is the human's, trimmed and otherwise as given.
+export function askText(text) {
+    return oneLine(text);
+}
+// Text a human or a model wrote, made safe to print where a reader parses lines: the
+// skills read `next`'s unit line by line, and a prompt section must never open a heading of
+// its own. Whitespace runs collapse to one space; the words stay as written.
+export function oneLine(text) {
+    return text.trim().replace(/\s+/g, ' ');
+}
+export function askQueue(root) {
+    const out = [];
+    for (const e of readStream(root, ASK_STREAM)) {
+        if (e.t === 'ask')
+            out.push({ id: String(e.id), text: String(e.text), state: 'unanswered', checks: 0 });
+        else if (e.t === 'ask-withdrawn') {
+            const a = out.find((x) => x.id === e.ask);
+            if (a)
+                a.state = 'withdrawn';
+        }
+    }
+    for (const a of out) {
+        const checks = recapChecks(root, a.id);
+        const last = checks.at(-1);
+        a.checks = checks.length;
+        if (last?.decision === 'revise') {
+            a.reason = oneLine(checkReason({ rule: String(last.rule), class: last.class, decided: last.decided, reason: String(last.reason ?? '') }));
+            if (last.note !== undefined)
+                a.note = oneLine(last.note);
+        }
+        if (a.state !== 'unanswered' || last === undefined)
+            continue;
+        if (last.decision === 'stop')
+            a.parked = 'malformed';
+        else if (last.decision === 'revise' && checks.length >= RECAP_CHECK_BOUND)
+            a.parked = 'bound';
+        if (a.parked !== undefined)
+            a.state = 'parked';
+    }
+    // An ask is answered once any recap names it, even one an abandon later ended: re-asking is
+    // the human's act, so an abandoned effort never puts its ask back in the queue.
+    const answeredBy = new Map();
+    for (const effort of effortStreams(root)) {
+        for (const e of readStream(root, effort)) {
+            if (e.t === 'recap' && typeof e.ask === 'string' && !answeredBy.has(e.ask))
+                answeredBy.set(e.ask, effort);
+        }
+    }
+    for (const a of out) {
+        const effort = answeredBy.get(a.id);
+        if (effort !== undefined) {
+            a.state = 'answered';
+            a.effort = effort;
+            delete a.parked;
+        }
+    }
+    return out;
+}
+// The one list of stream ids witness owns. A stream id is an artifact's whole history, so an
+// effort, spec, plan or rename that took one of these would merge two histories into one.
+export function reservedId(id) {
+    if (id === ASK_STREAM)
+        return "witness's own ask queue";
+    if (id === FLOOR_STREAM)
+        return "witness's own floor stream";
+    return undefined;
+}
+const TEXT_REQUIRED = v('text', 'required', 'absent', 'what to build in words — witness ask <text>');
+export function queueAsk(ctx, root, text) {
+    if (askText(text) === '')
+        return refuse([TEXT_REQUIRED]);
+    const lock = acquireLock(root);
+    if (!lock.ok)
+        return lock;
+    try {
+        // Under the lock: a writer that crashed before this one took it left its marker here.
+        const pending = pendingTxn(root);
+        if (pending)
+            return refuse([v('.witness/txn.json', 'pending-txn', pending.op, 'witness recover --complete | --rollback')]);
+        // Final review F7: a stream an older witness wrote under this name is another artifact's
+        // history, and asks appended to it would be read as part of that artifact.
+        const first = readStream(root, ASK_STREAM)[0];
+        if (first !== undefined && first.t !== 'ask') {
+            return refuse([v(ASK_STREAM, 'stream-taken', `the stream starts with ${first.t}`, 'a stream for asks alone — witness check names the artifact that holds it')]);
+        }
+        // Final review F10: the same words while that ask is still open are the same ask — a
+        // crashed `/witness <words>` run again must not queue, and build, the work twice.
+        const queue = askQueue(root);
+        const unanswered = () => askQueue(root).filter((a) => a.state === 'unanswered').length;
+        const open = queue.find((a) => (a.state === 'unanswered' || a.state === 'parked') && askText(a.text) === askText(text));
+        if (open !== undefined)
+            return ok({ id: open.id, unanswered: unanswered(), already: true });
+        // numbered under the lock: two queuers racing must not both take the next id
+        const id = `a${queue.length + 1}`;
+        const entry = { t: 'ask', id, text: text.trim() };
+        const stream = journalRel(ASK_STREAM);
+        const res = withTxn(root, { op: `ask(${id})`, files: [stream], journal: { stream: ASK_STREAM, line: entryLine(entry) } }, () => {
+            appendEntry(root, ASK_STREAM, entry);
+            crashPoint(ctx.env, 'journal-append');
+            return stateCommit(root, [stream], `ask(${id}): ${askText(text).slice(0, 60)}`);
+        });
+        if (!res.ok)
+            return res;
+        return ok({ id, unanswered: unanswered(), already: false });
+    }
+    finally {
+        lock.value();
+    }
+}
+export function withdrawAsk(ctx, root, id, note) {
+    const lock = acquireLock(root);
+    if (!lock.ok)
+        return lock;
+    try {
+        const pending = pendingTxn(root);
+        if (pending)
+            return refuse([v('.witness/txn.json', 'pending-txn', pending.op, 'witness recover --complete | --rollback')]);
+        const ask = askQueue(root).find((a) => a.id === id);
+        if (!ask)
+            return refuse([v('--withdraw', 'unknown-ask', id, 'an ask id — witness status lists the queue')]);
+        if (ask.state === 'withdrawn')
+            return ok({ already: true });
+        if (ask.state === 'answered') {
+            return refuse([v('--withdraw', 'ask-answered', `${id} is answered by ${ask.effort}`, `an unanswered ask — ${ask.effort} answers it now · witness abandon ${ask.effort} ends that effort`)]);
+        }
+        const entry = { t: 'ask-withdrawn', ask: id, ...(note !== undefined ? { note } : {}) };
+        const stream = journalRel(ASK_STREAM);
+        const res = withTxn(root, { op: `ask(${id})`, files: [stream], journal: { stream: ASK_STREAM, line: entryLine(entry) } }, () => {
+            appendEntry(root, ASK_STREAM, entry);
+            crashPoint(ctx.env, 'journal-append');
+            return stateCommit(root, [stream], `ask(${id}): withdrawn`);
+        });
+        if (!res.ok)
+            return res;
+        return ok({ already: false });
+    }
+    finally {
+        lock.value();
+    }
+}
+// The one derivation of which ask is routed next: the oldest still open. A parked ask waits
+// for a human, so it is routable whenever a human interviews and skipped under autonomy,
+// where re-offering it would repeat a command `recap` refuses.
+export function nextAsk(root, autonomous) {
+    return askQueue(root).find((a) => a.state === 'unanswered' || (a.state === 'parked' && !autonomous));
+}
+// The ask an effort answers: what the decompose arbiter judges a slicing against beside the
+// recap itself (row 177). Named by the recap that birthed the effort — an amend carries no
+// ask, and it is exactly a re-scoped slicing that must still be judged against the ask.
+export function askOf(root, effort) {
+    const id = readStream(root, effort).find((e) => e.t === 'recap' && typeof e.ask === 'string')?.ask;
+    if (id === undefined)
+        return undefined;
+    return readStream(root, ASK_STREAM).find((e) => e.t === 'ask' && e.id === id);
+}

package/dist/awake.js

@@ -0,0 +1,16 @@
+import { spawn } from 'node:child_process';
+export function keepAwake(env, platform, pid) {
+    // Test seam, on WITNESS_DRIVE_AGENT_BIN's precedent: never documented.
+    const bin = env.WITNESS_KEEP_AWAKE_BIN ?? (platform === 'darwin' ? 'caffeinate' : undefined);
+    if (bin === undefined)
+        return { stop: () => { } };
+    const args = ['-ims', '-w', String(pid)];
+    const child = spawn(bin, args, { stdio: 'ignore' });
+    child.on('error', () => { }); // a missing binary costs the guard, never the run
+    child.unref();
+    return {
+        command: [bin, ...args].join(' '),
+        stop: () => { if (child.exitCode === null && child.signalCode === null)
+            child.kill('SIGTERM'); },
+    };
+}

package/dist/caps.js

@@ -0,0 +1,74 @@
+import { EXIT } from './cli.js';
+import { fellBack, gateRuns, lastGateRun } from './rounds.js';
+import { duration } from './usage.js';
+import { gateSettled } from './verbs/next.js';
+const isCapPark = (e) => {
+    if (e.t !== 'human-decision')
+        return false;
+    const d = e;
+    return d.selected === 'policy' && typeof d.rule === 'string' && d.rule.startsWith('cap-');
+};
+// The gates still open on a target — run, and neither settled nor approved — most recent
+// last. A cap parks only on one of these (F7): a flow whose gates converged is moving, and a
+// stop journaled on a settled gate would hide it behind a reopen that refuses.
+function openGates(entries) {
+    const order = entries.filter((e) => e.t === 'gate-run').map((e) => String(e.gate));
+    return [...new Set(order.reverse())].reverse().filter((g) => !gateSettled(entries, g));
+}
+// First hit wins, in this order: rounds · upstream · spawns · wall clock.
+export function capHit(entries, use, caps) {
+    let lastPark = -1;
+    entries.forEach((e, i) => { if (isCapPark(e))
+        lastPark = i; });
+    const since = entries.slice(lastPark + 1);
+    // Every budget reset is ignored: this counts the rounds a gate ran, not its window. The
+    // exemptions are `roundsSinceApprove`'s — a malformed or fallen-back round spends nothing.
+    const gates = [...new Set(since.filter((e) => e.t === 'gate-run').map((e) => String(e.gate)))];
+    for (const gate of gates) {
+        const n = gateRuns(since, gate).filter((r) => r.outcome !== 'malformed' && !fellBack(r)).length;
+        // a gate that converged at the cap is not capped
+        if (n >= caps.rounds && !gateSettled(entries, gate)) {
+            return { cap: 'rounds', gate, note: `drive cap: ${gate} ran ${n} rounds across budget resets · drive.caps.rounds ${caps.rounds}` };
+        }
+    }
+    const upstream = since.filter((e) => e.t === 'human-decision' &&
+        e.decision === 'revise-upstream').length;
+    if (upstream >= caps.upstream && openGates(entries).length > 0) {
+        return { cap: 'upstream', note: `drive cap: ${upstream} upstream resets · drive.caps.upstream ${caps.upstream}` };
+    }
+    if (use.spawns >= caps.spawns) {
+        return { cap: 'spawns', note: `drive cap: ${use.spawns} session(s) this run · drive.caps.spawns ${caps.spawns}` };
+    }
+    if (use.ms >= caps.wallClockMs) {
+        return {
+            cap: 'wall-clock',
+            note: `drive cap: ${duration(use.ms)} of sessions this run · drive.caps.wallClockMs ${duration(caps.wallClockMs)}`,
+        };
+    }
+    return undefined;
+}
+// The park goes through A1's one door with `selected: 'policy'` and the cap as its rule.
+// `park` anchors it on the gate's last run even after the author moved the tree. A target
+// with no open gate has nothing to park on; a refusal from the door is named, not guessed.
+export async function parkAtCap(ctx, root, target, hit) {
+    const { readStream } = await import('./journal.js');
+    const entries = readStream(root, target);
+    if (!entries.some((e) => e.t === 'gate-run'))
+        return { parked: false, why: 'no gate run to park it on' };
+    const open = openGates(entries);
+    const gate = hit.gate !== undefined && open.includes(hit.gate) ? hit.gate : open.at(-1);
+    const last = gate !== undefined ? lastGateRun(entries, gate) : undefined;
+    if (gate === undefined || last === undefined)
+        return { parked: false, why: 'no open gate to park it on' };
+    // Loaded on A1's precedent for settle.ts: decide.ts reaches the gate registry.
+    const { applyDecision } = await import('./verbs/decide.js');
+    const errs = [];
+    const code = await applyDecision({ ...ctx, cwd: root, err: (l) => { errs.push(l); ctx.err(l); } }, {
+        gate, target, decision: 'stop', note: hit.note, selected: 'policy', rule: `cap-${hit.cap}`, park: true, runId: last.run_id,
+    });
+    if (code === EXIT.OK)
+        return { parked: true };
+    // the refusal's rows are indented under its header; the rule is each row's second field
+    const rule = errs.map((l) => /^\s+[^,]+,([a-z-]+),/.exec(l)?.[1]).find((r) => r !== undefined);
+    return { parked: false, why: `the policy could not park it (${rule ?? `exit ${code}`})` };
+}

package/dist/cli.js

@@ -9,6 +9,8 @@ const VERBS = {
     recover: () => import('./verbs/recover.js'),
     init: () => import('./verbs/init.js'),
     recap: () => import('./verbs/recap.js'),
+    // Row 176. The human's ask, queued as state so `next` routes it and no session can lose it.
+    ask: () => import('./verbs/ask.js'),
     write: () => import('./verbs/write.js'),
     // Row 132's read route. Canon lives at the primary root and nowhere else, so reading it
     // is a verb rather than a path — which is also what lets a worktree carry no copy.
@@ -51,6 +53,7 @@ const VERBS = {
 const VERB_USAGE = {
     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]',
     check: 'witness check',
     clean: 'witness clean',
@@ -58,7 +61,7 @@ const VERB_USAGE = {
     floor: 'witness floor --show | --set <triple> --note <why>',
     design: 'witness design <spec-id> --file <html> | --reconfirm | --open',
     diff: 'witness diff <spec-id>',
-    drive: 'witness drive [--flow <plan-id>] [--max-spawns <n>] — schedule green-path work through headless sessions; you appear at judgment stops',
+    drive: 'witness 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',
     'dispatch-report': 'witness dispatch-report <plan-id> --steps-assigned <n> --steps-completed <n> [--tokens <n>] [--tool-uses <n>] [--duration-ms <n>]',
     gate: 'witness gate <decompose|plan|implement|ship|design> <target> [--fresh] [--manual]',
     index: 'witness index',
@@ -66,10 +69,10 @@ const VERB_USAGE = {
     log: 'witness log <stream> [--all] [--lineage]',
     next: 'witness next',
     read: 'witness read <id> [--design] [--outline] [--lines <a>-<b>]',
-    recap: 'witness recap --file <recap.json> [--amend]',
+    recap: 'witness recap --file <recap.json> [--ask <id>] [--amend] [--manual]',
     recover: 'witness recover [--complete | --rollback]',
     rename: 'witness rename <old-id> <new-id>',
-    satisfy: 'witness satisfy <doc-id> --need <text | index>',
+    satisfy: 'witness satisfy <doc-id> --need <id | index | text>',
     dismiss: 'witness dismiss <artifact> --deferral <id|index> --cause <superseded|lens-retired|judged-wrong> --note "<why>"',
     ship: 'witness ship <plan-id> [--manual]',
     start: 'witness start <plan-id>',

package/dist/config.js

@@ -104,20 +104,87 @@ export function resolveImplement(raw) {
 // once, a starved one kills a working e2e run and hands the human a false `spawn-timeout`
 // to debug. The ceiling exists to break a hung child, not to pace a healthy one.
 export const DEFAULT_SESSION_TIMEOUT_MS = 3_600_000;
+// Rows 181 and 183. Drive runs up to `parallel` sessions at once, one per target (design
+// §11 call 5). The caps park a target that will not converge; their defaults are fewhats's
+// 2026-10-19 calibration (B5): rounds = the largest normal merged plan's 13 implement rounds
+// plus one budget window · upstream = where the human abandoned thread-mirror-plan-1 ·
+// spawns = half again over the busiest normal merged plan's 16 sessions · wall clock = 16 h,
+// over the slowest normal merged plan's ~14 h in worktree sessions.
+export const DEFAULT_PARALLEL = 2;
+export const DEFAULT_CAPS = { rounds: 16, upstream: 6, spawns: 24, wallClockMs: 57_600_000 };
+const DRIVE_WANTS = {
+    sessionTimeoutMs: 'an integer >= 1 — milliseconds each spawned session may take before SIGTERM',
+    parallel: 'an integer >= 1 — sessions drive runs at once · one per target',
+};
+const CAP_WANTS = {
+    rounds: 'an integer >= 1 — gate rounds one target may run across budget resets before drive parks it',
+    upstream: 'an integer >= 1 — upstream resets one target may take before drive parks it',
+    spawns: 'an integer >= 1 — sessions one target may take in one drive run',
+    wallClockMs: 'an integer >= 1 — milliseconds of session time one target may take in one drive run',
+};
+const DRIVE_KEYS = ['sessionTimeoutMs', 'parallel', 'parallelSuites', 'caps'];
+const isCount = (val) => typeof val === 'number' && Number.isInteger(val) && val >= 1;
+const isMap = (val) => typeof val === 'object' && val !== null && !Array.isArray(val);
+// Strict: no consumer sets `drive:` today, so a typo'd key refusing costs nobody, while a
+// typo'd cap silently defaulting would let a flow run past the bound its author meant.
 export function resolveDrive(raw) {
     const conf = raw.drive;
+    const defaults = {
+        sessionTimeoutMs: DEFAULT_SESSION_TIMEOUT_MS, parallel: DEFAULT_PARALLEL, parallelSuites: false, caps: { ...DEFAULT_CAPS },
+    };
     if (conf === undefined)
-        return ok({ sessionTimeoutMs: DEFAULT_SESSION_TIMEOUT_MS });
-    if (typeof conf !== 'object' || conf === null || Array.isArray(conf)) {
+        return ok(defaults);
+    if (!isMap(conf))
         return refuse([v('drive', 'invalid', String(conf), 'a map of drive settings')]);
+    const violations = [];
+    for (const key of Object.keys(conf)) {
+        if (!DRIVE_KEYS.includes(key)) {
+            violations.push(v(`drive.${key}`, 'unknown-drive-key', key, `a drive setting (${DRIVE_KEYS.join(' | ')})`));
+        }
     }
-    const val = conf.sessionTimeoutMs;
-    if (val === undefined)
-        return ok({ sessionTimeoutMs: DEFAULT_SESSION_TIMEOUT_MS });
-    if (typeof val !== 'number' || !Number.isInteger(val) || val < 1) {
-        return refuse([v('drive.sessionTimeoutMs', 'invalid', String(val), 'an integer >= 1 — milliseconds each spawned session may take before SIGTERM')]);
+    const out = defaults;
+    for (const key of ['sessionTimeoutMs', 'parallel']) {
+        const val = conf[key];
+        if (val === undefined)
+            continue;
+        if (!isCount(val))
+            violations.push(v(`drive.${key}`, 'invalid', String(val), DRIVE_WANTS[key]));
+        else
+            out[key] = val;
+    }
+    if (conf.parallelSuites !== undefined) {
+        if (typeof conf.parallelSuites !== 'boolean') {
+            violations.push(v('drive.parallelSuites', 'invalid', String(conf.parallelSuites), 'true | false — whether test runs in two worktrees may overlap'));
+        }
+        else {
+            out.parallelSuites = conf.parallelSuites;
+        }
     }
-    return ok({ sessionTimeoutMs: val });
+    const caps = conf.caps;
+    if (caps !== undefined) {
+        if (!isMap(caps)) {
+            violations.push(v('drive.caps', 'invalid', String(caps), 'a map of cap settings'));
+        }
+        else {
+            for (const key of Object.keys(caps)) {
+                if (!(key in CAP_WANTS)) {
+                    violations.push(v(`drive.caps.${key}`, 'unknown-drive-key', key, `a cap (${Object.keys(CAP_WANTS).join(' | ')})`));
+                }
+            }
+            for (const key of Object.keys(CAP_WANTS)) {
+                const val = caps[key];
+                if (val === undefined)
+                    continue;
+                if (!isCount(val))
+                    violations.push(v(`drive.caps.${key}`, 'invalid', String(val), CAP_WANTS[key]));
+                else
+                    out.caps[key] = val;
+            }
+        }
+    }
+    if (violations.length)
+        return refuse(violations);
+    return ok(out);
 }
 export const DEFAULT_REVIEWER_TIMEOUT_MS = 600_000;
 // gates.* is otherwise read loosely at its consumers (stagePin); the timeout is
@@ -188,7 +255,7 @@ export function autonomyAt(root, rev) {
     }
 }
 const committedAutonomy = (root) => autonomyAt(root, 'HEAD');
-const LOCAL_KEYS = ['reviewerExtensions', 'opener'];
+const LOCAL_KEYS = ['reviewerExtensions', 'opener', 'notify'];
 export const localConfigPath = (root) => join(root, '.witness', 'config.local.yaml');
 export function loadLocalConfig(root) {
     const p = localConfigPath(root);
@@ -230,9 +297,18 @@ export function loadLocalConfig(root) {
             opener = obj.opener;
         }
     }
+    let notify;
+    if (obj.notify !== undefined) {
+        if (typeof obj.notify !== 'string' || obj.notify === '') {
+            violations.push(v('notify', 'invalid', String(obj.notify), 'a command name or path — it receives the run summary as its one argument'));
+        }
+        else {
+            notify = obj.notify;
+        }
+    }
     if (violations.length)
         return refuse(violations);
-    return ok({ reviewerExtensions, ...(opener !== undefined ? { opener } : {}) });
+    return ok({ reviewerExtensions, ...(opener !== undefined ? { opener } : {}), ...(notify !== undefined ? { notify } : {}) });
 }
 // Lenient path resolution for callers without a loaded Config (canon scan, git
 // state scoping): a missing or broken config falls back to the defaults — the

package/dist/criteria.js

@@ -1,9 +1,15 @@
 import { ensureTrusted } from './allowlist.js';
 import { loadConfig } from './config.js';
 import { matchesTag, sourceTags } from './matcher.js';
+import { heldCriteria, satisfyCommand } from './needs.js';
 import { ok } from './refusal.js';
 import { criteriaExcludes, execCommand, runFiltered, runFullSuite, runnerConfig, untrustedOf } from './runner.js';
 import { canonicalSha } from './sha.js';
+export function criterionMark(c) {
+    if (c.held !== undefined)
+        return `held by ${c.held.join(' · ')}`;
+    return c.ok ? 'ok' : 'fail';
+}
 export async function runCriteria(runRoot, ctx, doc, opts = {}) {
     const trustRoot = opts.trustRoot ?? runRoot;
     // D154 root unification. The trust list and the runner config are two halves of one
@@ -34,9 +40,18 @@ export async function runCriteria(runRoot, ctx, doc, opts = {}) {
     const src = rc.mode === 'filtered'
         ? sourceTags(runRoot, criteriaExcludes(cfg.value))
         : undefined;
+    const held = heldCriteria(doc);
     const criteria = [];
     for (const c of list) {
         const cid = String(c.id);
+        // A hold names a `cmd:` record, never just an id: a hand-edited doc can give a test
+        // criterion the same id, and holding it would skip the spec's tests.
+        const holders = typeof c.cmd === 'string' ? held.get(cid) : undefined;
+        if (holders !== undefined) {
+            criteria.push({ id: cid, kind: 'cmd', ok: false, held: holders,
+                detail: `held by ${holders.join(' · ')} — ${satisfyCommand(id, holders[0])}` });
+            continue;
+        }
         if (typeof c.test === 'string') {
             if (rc.mode === 'full-suite') {
                 if (!suite) {
@@ -94,7 +109,9 @@ export async function runCriteria(runRoot, ctx, doc, opts = {}) {
     return ok({
         spec: id,
         sha: canonicalSha(doc.meta, doc.body),
-        ok: criteria.length > 0 && criteria.every((c) => c.ok),
+        // A lane passes only when something actually passed and nothing failed: a held criterion
+        // is not a failure, and it is never a pass either.
+        ok: criteria.some((c) => c.ok) && criteria.every((c) => c.ok || c.held !== undefined),
         mode: rc.mode,
         tagCount,
         criteria,
@@ -107,12 +124,18 @@ export function laneCheck(lane) {
     const untrusted = lane.ok
         ? [...new Set(lane.value.criteria.flatMap((c) => (c.untrusted !== undefined ? [c.untrusted] : [])))]
         : [];
+    // Row 179: a lane that passed with held criteria says so in its own record, so no reader
+    // of the gate-run can take the green for a verification of what was not run.
+    const held = lane.ok
+        ? lane.value.criteria.flatMap((c) => (c.held ?? []).map((need) => ({ criterion: c.id, need, satisfy: satisfyCommand(lane.value.spec, need) })))
+        : [];
     return {
         name: 'drift-lane',
         ok: lane.ok && lane.value.ok,
         detail: lane.ok
-            ? lane.value.criteria.map((c) => `${c.id}:${c.ok ? 'ok' : 'fail'}`).join(' · ')
+            ? lane.value.criteria.map((c) => `${c.id}:${criterionMark(c)}`).join(' · ')
             : lane.violations.map((x) => `${x.field}:${x.rule}`).join(' · '),
         ...(untrusted.length > 0 ? { untrusted } : {}),
+        ...(held.length > 0 ? { held } : {}),
     };
 }

package/dist/departure.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readdirSync, unlinkSync, writeFileSync } from 'n
 import { dirname, join } from 'node:path';
 import { deferralMoves } from './deferral.js';
 import { designRel } from './design.js';
-import { FLOOR_STREAM } from './floor.js';
+import { reservedId } from './ask.js';
 import { splitDoc } from './fm.js';
 import { adoptedCommits, lastWitnessed } from './adopt.js';
 import { gitBlob, tryGit } from './gitio.js';
@@ -130,13 +130,14 @@ function returnsThrough(root, paths, commit, chain, unwound, takenBack, seen) {
 // Whether a NEW artifact may take this id. An id names one artifact for the life of the repo,
 // because its stream IS that artifact's history. Three streams already belong to something
 // else: a superseded spec's (a successor owns its content, and its finished plans resolve their
-// parent there), an effort's, and witness's own floor pins. The one re-use is the same artifact
+// parent there), an effort's, and witness's own (`reservedId`: the floor pins and the ask queue). The one re-use is the same artifact
 // again: a spec its own abandon unwound may be written again as a spec. A stream that records
 // none of these — a stray, or a doc canon cannot parse — does not hold its id; the findings
 // that already name it (`orphan-journal`, the parse error) are its remedy.
 export function idRetired(root, id, type) {
-    if (id === FLOOR_STREAM)
-        return v('id', 'id-taken', id, `a new id — ${id} is witness's own floor stream`);
+    const reserved = reservedId(id);
+    if (reserved !== undefined)
+        return v('id', 'id-taken', id, `a new id — ${id} is ${reserved}`);
     const entries = readStream(root, id);
     if (entries[0]?.t === 'recap')
         return v('id', 'id-taken', id, `a new id — ${id} is an effort's slug`);