tickmarkr 1.84.0 → 1.86.0

package/dist/drivers/herdr.js

@@ -1,6 +1,11 @@
-import { declaredInputBoxForWorkerName, matchesEmptyInputBox, matchesInputBox, shq } from "../adapters/types.js";
-import { PANE_IDENTITY_ENV, paneIdentityLine } from "../brand.js";
+import { randomUUID } from "node:crypto";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { declaredInputBoxForWorkerName, matchesEmptyInputBox, matchesInputBox, matchesOccupiedInputBox, missingInputStateDeclarations, shq } from "../adapters/types.js";
+import { consumePaneLaunchIntent, PANE_IDENTITY_ENV, paneIdentityLine } from "../brand.js";
 import { createWorktree, sh } from "../run/git.js";
+import { Journal } from "../run/journal.js";
 import { herdrSealShellPrefix } from "./subprocess.js";
 import { canonicalizeLegacyName, formatOwnedName, panesToClose, parseOwnedName } from "./types.js";
 // VIS-09 P43-03: adopted safety floor from 43-MEASUREMENT.md (narrowest safe 53 → floor 108).
@@ -14,6 +19,15 @@ const DELIVERY_READ_LINES = 80;
 const DELIVERY_SETTLE_READ_ATTEMPTS = 6;
 const DELIVERY_SETTLE_POLL_MS = 100;
 const DELIVERY_READINESS_TIMEOUT_MS = 1_000;
+// OBS-140/253: a shell or bootstrap dispatch is acknowledged by a START nonce the delivered line
+// PRINTS as its first statement. The printf splits the nonce across two arguments, so the joined
+// marker exists only after the shell actually ran the line — a pane that merely echoed the text it
+// was given never produces it. The marker is written to a private file as well as the pane, because
+// a pane snapshot is not a channel: a full-screen TUI or a noisy launch can scroll a printed nonce
+// out of any bounded read, and a successful dispatch read as corrupt is dispatched TWICE.
+export const DISPATCH_START_PREFIX = "TICKMARKR_START_";
+const DISPATCH_ACK_TIMEOUT_MS = 15_000;
+const DISPATCH_ACK_POLL_MS = 100;
 const SYSTEM_TIME = {
     now: () => Date.now(),
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
@@ -32,16 +46,53 @@ export class DeliveryReadinessError extends Error {
         this.name = "DeliveryReadinessError";
     }
 }
+// OBS-253: the dispatch-corruption class, typed so the driver's own one-shot recovery can recognise
+// it and the daemon can keep classifying an unrecovered one as `kind: dispatch`. A dispatch that
+// never registered produced no output to trust, so a fresh-pane retry risks nothing a first dispatch
+// does not already risk — the second consecutive one is what parks the task.
+export class DeliveryCorruptedError extends Error {
+    pane;
+    transcript;
+    phase = "DISPATCH";
+    constructor(pane, reason, transcript) {
+        super(`herdr delivery corrupted on pane ${pane} — ${reason} (OBS-140/253); pane transcript:\n${transcript}`);
+        this.pane = pane;
+        this.transcript = transcript;
+        this.name = "DeliveryCorruptedError";
+    }
+}
 /** First-generation join direction from measured trailer-safe floor (43-MEASUREMENT.md). */
 export function workerSplitDirection(paneCols, safeFloor = TRAILER_SAFE_FLOOR_COLS, margin = TRAILER_WIDTH_MARGIN) {
     if (paneCols == null || paneCols <= 0)
         return "down";
     return paneCols / 2 >= safeFloor + margin ? "right" : "down";
 }
+/** The tab a slot belongs to: its TASK — worker, judge, review and consult panes for one task share it.
+ *  Returns undefined for everything else, which keeps those on the dedicated-tab path.
+ *
+ *  The ROLE gate is load-bearing and was added after it bit: `canonicalizeLegacyName` returns
+ *  `role:"other", taskId:"<the whole name>"` for any unrecognised string, so keying on taskId alone
+ *  makes EVERY one-off pane its own "task" and gives it a group tab. `watch` is excluded for the same
+ *  reason in the other direction — its taskId is the literal "run", which is a board, not a task. */
+const TASK_TAB_ROLES = new Set(["worker", "judge", "review", "consult"]);
+export function taskGroupOf(name) {
+    const { role, taskId } = canonicalizeLegacyName(name, "");
+    if (!TASK_TAB_ROLES.has(role))
+        return undefined;
+    return taskId && taskId.trim() ? taskId : undefined;
+}
+/** Gate panes ride with the task they belong to and never consume the tab cap; everything else does.
+ *  Scoped to the three GATE roles deliberately — an earlier cut of this said "not a worker", which let
+ *  role:"other" members (any unrecognised name) bypass the cap and silently disabled overflow for
+ *  explicit stage groups. The cap still governs every member it governed before. */
+const GATE_ROLES = new Set(["judge", "review", "consult"]);
+const ridesWithTask = (name) => GATE_ROLES.has(canonicalizeLegacyName(name, "").role);
+const cappedMembers = (g) => g.members.filter((m) => !ridesWithTask(m.name)).length;
 export class HerdrDriver {
     bin;
     workersPerTab;
     time;
+    journal;
     id = "herdr";
     interactive = true;
     groups = new Map();
@@ -54,16 +105,44 @@ export class HerdrDriver {
     dispatchLeases = new WeakMap();
     deliveredPanes = new WeakMap();
     inputBoxes = new WeakMap();
+    // OBS-253: the adapter-declared bootstrap this slot has already delivered. A fresh pane is a bare
+    // shell, so it is the only thing that can put a TUI back under a typed turn that has to move.
+    bootstraps = new WeakMap();
+    // runDaemon gives the driver the authoritative repo root at its worktree seam before it allocates
+    // that task's slot. Keep the binding by cwd so a dispatch retry opens THAT run's Journal even when
+    // the caller launched tickmarkr elsewhere (process.cwd is not run identity). The repo itself is
+    // also bound for judge/review/consult slots whose cwd is the root rather than a task worktree.
+    journalRoots = new Map();
     // VIS-10: the run's workspace id, captured once at construction (the daemon inherits it from the
     // operator's env before the driver is built). Required at slot() time, never in the constructor —
     // pickDriver and its unit test construct HerdrDriver without env, so slot() is the trust gate.
     ws = process.env.HERDR_WORKSPACE_ID;
     callerPane = process.env.HERDR_PANE_ID;
     watches = new Map();
-    constructor(bin = "herdr", workersPerTab = 3, time = SYSTEM_TIME) {
+    constructor(bin = "herdr", workersPerTab = 3, time = SYSTEM_TIME, journal) {
         this.bin = bin;
         this.workersPerTab = workersPerTab;
         this.time = time;
+        this.journal = journal;
+    }
+    // The dispatch-retry record is mandatory: it is the only durable fact left by a recovered pane
+    // swap. Tests may inject a sink, while production resolves the daemon's real Journal from the
+    // worktree binding plus the canonical slot name. Every resolution/open/append failure propagates;
+    // an unjournaled recovery is never performed and its audit failure is never hidden by the original
+    // corruption error.
+    appendDispatchRetry(slot, data) {
+        if (this.journal) {
+            this.journal("dispatch-retry", slot.name, data);
+            return;
+        }
+        const owned = parseOwnedName(slot.name);
+        if (!owned)
+            throw new Error(`cannot journal dispatch-retry: slot ${slot.name} carries no run identity`);
+        const repoRoot = this.journalRoots.get(slot.cwd);
+        if (!repoRoot) {
+            throw new Error(`cannot journal dispatch-retry: slot ${slot.name} has no daemon repo binding for ${slot.cwd}`);
+        }
+        Journal.open(repoRoot, owned.runId).append("dispatch-retry", owned.taskId, data);
     }
     serial(fn) {
         const p = this.groupSerial.then(fn, fn);
@@ -124,62 +203,18 @@ export class HerdrDriver {
         const needle = norm(cmd);
         return needle.length > 0 && hay.includes(needle);
     }
-    shellExecutionEchoed(transcript, cmd) {
-        const norm = (s) => s.replace(/\u001B\[[0-9;?]*[ -/]*[@-~]/g, "").replace(/\s+/g, " ").trim();
-        const needle = norm(cmd);
-        if (!needle)
+    // v1.85 T5: submission is acknowledged CAUSALLY or not at all. The adapter's declared OCCUPIED
+    // state means the prompt is still sitting in the box — never submitted; its declared EMPTY state
+    // means the box consumed it. Nothing else counts: the positional-transcript fallback this used to
+    // end with (prompt found, bytes exist after it ⇒ "delivered") answered yes for panes that had
+    // processed nothing (OBS-181), and it is DELETED. A box that is off-screen or unrecognisable is an
+    // absence of evidence, which fails closed — the same posture every gate takes. The launch-stage
+    // shell-echo reader is gone with it: a bootstrap line is now delivered atomically and acknowledged
+    // by its own START nonce, so there is no echo left to read (OBS-144 closed by construction).
+    submissionRegistered(transcript, inputBox) {
+        if (matchesOccupiedInputBox(transcript, inputBox))
             return false;
-        return transcript.split("\n").some((rawLine) => {
-            const line = norm(rawLine);
-            if (line === needle || !line.endsWith(needle))
-                return false;
-            const prefix = line.slice(0, -needle.length).trimEnd();
-            if (/[│┃╭╰┌└]/.test(prefix))
-                return false;
-            return /^(?:[$%#>]|[➜❯❱›»λ])(?:\s|$)/.test(prefix)
-                || /[$%#>✗❯❱›»λ]$/.test(prefix);
-        });
-    }
-    // Submission requires positive post-Enter evidence. A prompt echoed above a fresh input target
-    // proves registration; a declared box that is visibly empty after the verified paste also proves
-    // it consumed the prompt. At the launch stage, a structurally prompt-prefixed shell execution echo
-    // is stronger evidence than waiting for first paint from the launched interface (OBS-144).
-    // Prompt absence alone is never success (OBS-142).
-    submissionRegistered(transcript, cmd, inputBox) {
-        const norm = (s) => s.replace(/\s+/g, "");
-        const hay = norm(transcript);
-        const needle = norm(cmd);
-        const promptAt = hay.lastIndexOf(needle);
-        if (needle.length === 0)
-            return false;
-        if (inputBox?.launchCommand?.(cmd) === true && this.shellExecutionEchoed(transcript, cmd))
-            return true;
-        if (promptAt < 0)
-            return inputBox !== undefined && matchesEmptyInputBox(transcript, inputBox);
-        if (inputBox) {
-            // OBS-181: an EMPTY declared input box is positive evidence of submission even while the
-            // prompt is still visible above as the echoed user turn — which is exactly how every TUI
-            // renders the moment after Enter lands. Test it FIRST: `match` means "the box is painted" and
-            // is deliberately true for an empty box, so asking `match` first cannot decide submission.
-            if (matchesEmptyInputBox(transcript, inputBox))
-                return true;
-            // The box is painted and is NOT empty: the prompt is still sitting in it. Only a fingerprint
-            // appearing AFTER the prompt — a fresh input line below the submitted text — counts.
-            //
-            // This is the branch a wedged kimi pane belongs in, and could not reach: its occupied editor
-            // renders a blank continuation row, the matcher demanded the bottom border immediately below
-            // the prompt, so NEITHER matcher fired and the positional fallback below answered "delivered"
-            // for a pane that had processed nothing. The matcher fix (adapters/kimi.ts) is what routes it
-            // here; keeping the fallback unreachable for a painted box is what stops the next one.
-            if (matchesInputBox(transcript, inputBox)) {
-                return hay.lastIndexOf(norm(inputBox.fingerprint)) > promptAt;
-            }
-        }
-        // No declared box, or the box is not on screen at all (it may have scrolled out of the read
-        // window). Positional evidence only — weaker, and unsound for any surface that paints chrome
-        // below its prompt, which is why a declared box must be able to recognise its own OCCUPIED
-        // state. Every adapter declaring an inputBox needs a captured occupied frame in its tests.
-        return promptAt + needle.length < hay.length;
+        return matchesEmptyInputBox(transcript, inputBox);
     }
     static available() {
         return process.env.HERDR_ENV === "1";
@@ -236,8 +271,22 @@ export class HerdrDriver {
         // reconcile.ts and this driver's own renameGroupTab/glyphFor decode role/taskId/attempt from
         // those shapes without a call-site migration; T2 retires this branch by always passing `owned`.
         const resolved = opts?.owned ? formatOwnedName(opts.owned) : name;
-        const allocate = opts?.group
-            ? () => this.serial(() => this.groupSlot(cwd, resolved, opts.group))
+        // ONE TAB PER TASK. The group defaults to the task id, derived from the same parser that already
+        // decodes role/taskId for tab labels — so a worker and every gate pane it earns (judge, review,
+        // consult) land in that task's tab instead of scattering. Deriving it HERE rather than at each
+        // call site is the point: the defect this replaces was three call sites of which exactly one
+        // passed a group, so judge/review/consult each opened a tab of their own. A caller may still pass
+        // `group` explicitly to override, and a name with no task id (or an explicit `label`) keeps the
+        // dedicated-tab path unchanged.
+        // PRECEDENCE: a task-bearing name ALWAYS groups by its task; an explicit `group` applies only to
+        // names with no task identity. That direction is deliberate — the invariant is "a task's panes are
+        // never scattered", and a caller passing a stage group (the daemon still passes "workers", which now
+        // serves as the fallback for task-less names) must not be able to override it by omission or habit.
+        // An explicit `label` still wins outright: that is the dedicated-role-tab path, chosen on purpose.
+        const derivedGroup = opts?.label ? undefined : taskGroupOf(resolved);
+        const group = derivedGroup ?? opts?.group;
+        const allocate = group
+            ? () => this.serial(() => this.groupSlot(cwd, resolved, group))
             : () => this.tabSlot(cwd, resolved, opts?.label);
         // Production dispatch names are canonical even when the gate call site supplies the already-
         // formatted name rather than SlotOpts.owned. Hold one lease across slot() → run(); legacy/manual
@@ -285,8 +334,6 @@ export class HerdrDriver {
             throw new Error(`herdr tab create returned no tab_id (refusing untargeted placement): ${t.stdout}`);
         if (typeof id !== "string" || !id)
             throw new Error(`herdr tab create returned no root pane id (refusing untargeted placement): ${t.stdout}`);
-        // T5: the banner's pane identity line, derived from the T1 owned name (legacy names pass through).
-        const identity = shq(paneIdentityLine(canonicalizeLegacyName(name, "")));
         // durable identity: label the PANE (resolution + reconcile read it back via `pane list`); fail closed
         // and reap the tab we just made if the rename fails (no orphan tab).
         const rn = await this.herdr(`pane rename ${shq(id)} ${shq(name)}`);
@@ -303,7 +350,7 @@ export class HerdrDriver {
         // not a rule it must remember (P40-02 probe leak). Fail closed: a failed seed rejects.
         // v1.22 T3 / OBS-17: also strip HERDR_ENV + socket path so the worker cannot open/mutate panes in
         // the operator's session. Daemon-side this.herdr() calls keep process.env (unsealed).
-        const seed = await this.herdr(`pane run ${shq(id)} ${shq(`export HERDR_WORKSPACE_ID=${shq(this.ws)}; export ${PANE_IDENTITY_ENV}=${identity}; ${herdrSealShellPrefix()}`)}`);
+        const seed = await this.herdr(`pane run ${shq(id)} ${shq(`export HERDR_WORKSPACE_ID=${shq(this.ws)}; export ${PANE_IDENTITY_ENV}=${shq(paneIdentityLine(canonicalizeLegacyName(name, "")))}; ${herdrSealShellPrefix()}`)}`);
         if (seed.code !== 0)
             throw new Error(`herdr workspace-id seed failed (refusing untargeted pane): ${seed.stderr || seed.stdout}`);
         return { id, name, cwd, tabId };
@@ -346,7 +393,10 @@ export class HerdrDriver {
             return this.tabSlot(cwd, name); // D-09: degrade, NOT a shared-tab member
         if (state) {
             const latest = state.generations[state.generations.length - 1];
-            if (latest && latest.members.length < this.workersPerTab) {
+            // A task tab's judge/review/consult panes belong with their worker and must never overflow into a
+            // `cleanup` tab — that would re-scatter exactly what the per-task grouping exists to gather. They
+            // therefore join freely and do not consume `workersPerTab`; every other member still does.
+            if (latest && (ridesWithTask(name) || cappedMembers(latest) < this.workersPerTab)) {
                 const joined = await this.joinGroup(cwd, name, group, latest);
                 if (joined)
                     return joined;
@@ -381,7 +431,11 @@ export class HerdrDriver {
         const newest = [...entry.members].reverse().find((m) => canonicalizeLegacyName(m.name, "").role === "worker");
         const token = newest ? canonicalizeLegacyName(newest.name, "").taskId : undefined;
         const glyph = newest ? await this.glyphFor(newest) : "";
-        const label = token ? `${entry.label} · ${token}${glyph}` : entry.label;
+        // A per-task tab is already labelled with its task id; appending the same token again reads as a
+        // duplicate rather than as state, so the glyph rides the existing label instead.
+        const label = !token ? entry.label
+            : entry.label === token ? `${token}${glyph}`
+                : `${entry.label} · ${token}${glyph}`;
         const cmd = `tab rename ${shq(entry.tabId)} ${shq(label)}`;
         const ok = async () => (await this.herdr(cmd)).code === 0;
         if (await ok() || await ok())
@@ -450,22 +504,22 @@ export class HerdrDriver {
         await this.renameGroupTab(entry);
         return { id: pane, name, cwd, tabId: entry.tabId, group };
     }
-    // OBS-85 verified delivery: a pane paste can interleave a long dispatch line with itself (codex
-    // `$(git rev-parse…)` mashed into its trailing printf — v1.58 T2 attempts 2-4, v1.61 T10). Never
-    // the atomic `pane run` (text+Enter in one request, uninspectable between the two): type WITHOUT
-    // enter, read the pane back — `wait output --match` checks the same unwrapped transcript pane
-    // read exposes, event-driven so wrap and render timing can't race the check — and press Enter
-    // only when that read-back contains the typed command. A corrupted paste is captured (pane read),
-    // cleared (C-u), and retyped, bounded; persistent corruption fails closed WITH the captured
-    // transcript — the dispatch-time pincer the ledger asks for, not post-hoc `git:` archaeology.
+    // v1.85 T5 (OBS-140/253): every dispatch is routed by what the target actually IS. A shell or
+    // bootstrap line goes out atomically through `pane run` and is acknowledged by its own START
+    // nonce; only a real TUI turn — an adapter-declared input box, and not that adapter's own launch
+    // command — earns the typed pincer. One dispatch corruption is then retried in-process against a
+    // FRESH pane before anything is reported as a failure.
     async run(slot, cmd) {
+        // paneLaunchCommand is a linear same-call handoff: consume before the first await so concurrent
+        // task dispatches cannot exchange intent. The command remains an ordinary string for every
+        // ExecutorDriver implementation; classification never reads its bytes when the builder spoke.
+        const recordedLaunch = consumePaneLaunchIntent();
         const lease = this.dispatchLeases.get(slot);
         if (lease) {
             this.dispatchLeases.delete(slot);
             try {
                 const paneId = await this.verifyPaneIdentityBinding(slot);
-                await this.deliver(slot, cmd, paneId);
-                this.deliveredPanes.set(slot, paneId);
+                await this.dispatchWithRetry(slot, cmd, paneId, recordedLaunch);
             }
             finally {
                 lease.release();
@@ -473,13 +527,200 @@ export class HerdrDriver {
             return;
         }
         return this.deliveryQueue(async () => {
-            const paneId = await this.paneId(slot);
-            await this.deliver(slot, cmd, paneId);
-            this.deliveredPanes.set(slot, paneId);
+            await this.dispatchWithRetry(slot, cmd, await this.paneId(slot), recordedLaunch);
         });
     }
-    async deliver(slot, cmd, pane, verifySubmission = true) {
-        const readiness = await this.awaitDeliveryReadiness(slot, cmd, pane);
+    // OBS-253: dispatch corruption is self-clearing — all ten recorded occurrences cleared on a fresh
+    // pane and a fresh submit, and every one of them cost an operator `resume --retry-failed`. Retry
+    // ONCE here against a pane that has never seen this delivery; the wedged pane is closed, never
+    // re-pressed. A second consecutive corruption propagates, and the daemon parks the task on it.
+    async dispatchWithRetry(slot, cmd, pane, recordedLaunch = false) {
+        try {
+            await this.dispatch(slot, cmd, pane, recordedLaunch);
+            this.deliveredPanes.set(slot, pane);
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof DeliveryCorruptedError))
+                throw error;
+            // A fresh pane is a bare shell. A shell dispatch is simply re-run on it; a typed turn first
+            // needs its interface back, which is possible only where the adapter declared the bootstrap
+            // this slot already delivered. Retyping a turn into a bare shell would guarantee the second
+            // failure rather than recover from the first, so without a replayable bootstrap the
+            // corruption propagates untouched.
+            const typedTurn = this.isTuiTurn(slot, cmd, recordedLaunch);
+            const relaunch = typedTurn ? this.bootstraps.get(slot) : undefined;
+            if (typedTurn && relaunch === undefined)
+                throw error;
+            // Record BEFORE acting: a retry that cannot be written to the run's ledger is not taken at all,
+            // because an unrecorded pane swap is exactly the silence OBS-253 cost ten times. The journal
+            // failure itself propagates visibly; the original corruption then remains terminal rather than
+            // triggering an off-record recovery.
+            this.appendDispatchRetry(slot, { wedgedPane: pane, reason: error.message });
+            const fresh = await this.freshPane(slot, pane);
+            if (fresh === null)
+                throw error;
+            if (relaunch !== undefined)
+                await this.deliverAtomic(slot, relaunch, fresh);
+            await this.dispatch(slot, cmd, fresh, recordedLaunch);
+            this.deliveredPanes.set(slot, fresh);
+        }
+    }
+    // Is this delivery a turn TYPED into a running interface, rather than a line a shell runs? The
+    // The builder's recorded fact decides first, regardless of command bytes. For direct driver users,
+    // an adapter may declare the fresh-slot lifecycle rather than a prefix list. Legacy declarations
+    // still decide where neither stronger fact exists. With NO declaration the only evidence is history — a
+    // pane that already accepted a delivery is running whatever that delivery started, so a second
+    // delivery is a turn into it. Answering "shell" there is what would run an adapter's seed prompt
+    // as a shell command; answering "turn" routes it to deliverTyped, which refuses it by name
+    // because the adapter declared no input box (fail closed, never a guess).
+    isTuiTurn(slot, cmd, recordedLaunch = false) {
+        if (recordedLaunch)
+            return false;
+        const inputBox = this.inputBoxes.get(slot);
+        if (inputBox?.firstDeliveryIsLaunch && !this.deliveredPanes.has(slot))
+            return false;
+        return inputBox ? inputBox.launchCommand?.(cmd) !== true : this.deliveredPanes.has(slot);
+    }
+    dispatch(slot, cmd, pane, recordedLaunch = false) {
+        if (this.isTuiTurn(slot, cmd, recordedLaunch))
+            return this.deliverTyped(slot, cmd, pane);
+        // A classified bootstrap is the one command that can restore this slot's interface on a fresh
+        // pane, so remember the fact's command without asking its bytes to prove the classification again.
+        if (this.inputBoxes.has(slot))
+            this.bootstraps.set(slot, cmd);
+        return this.deliverAtomic(slot, cmd, pane);
+    }
+    // The OBS-140 class dies here. `pane run` puts text and Enter in ONE herdr request, so there is no
+    // seam in which a swallowed Enter can leave a verified-but-unsubmitted prompt, and nothing about
+    // the delivery is inferred from typed-text read-back. The line's first two statements print a
+    // per-dispatch START nonce assembled from two printf arguments — once to a file whose name only
+    // this process knows, then once to the pane for the operator. The joined marker cannot exist
+    // unless the shell RAN our line, so the acknowledgment is causal; and because the file is written
+    // before the agent the line launches produces a byte, no amount of later output can hide it. Both
+    // statements are shell builtins: the ack cannot fail for want of a binary on the pane's PATH.
+    //
+    // v1.85 T5 review: the durable half GATES the launch, and goes FIRST. A dispatch whose ack the
+    // pane could not write is indistinguishable, from here, from a line that never ran — so if the
+    // command ran anyway, the miss buys a fresh pane and a SECOND live agent for the same task. The
+    // `|| exit 1` makes that impossible: no ack, no command. Ordering carries the same weight in the
+    // other direction — a pane-visible marker printed before a failed ack write would satisfy the
+    // event watch and report a launch that never happened.
+    async deliverAtomic(slot, cmd, pane) {
+        const suffix = randomUUID(); // unguessable: nothing the delivered command runs can forge the ack
+        const nonce = `${DISPATCH_START_PREFIX}${suffix}`;
+        const ackPath = join(tmpdir(), `tickmarkr-dispatch-${suffix}.ack`);
+        // Open the channel before spending a pane on it: an ack path this process cannot write is a
+        // broken host, not a wedged pane, and the fresh-pane retry would fail there for the same reason.
+        // Throwing something other than DeliveryCorruptedError is what keeps that retry unspent.
+        try {
+            writeFileSync(ackPath, ""); // empty: only the delivered line may ever put the nonce here
+        }
+        catch (error) {
+            throw new Error(`dispatch acknowledgment channel unavailable (${ackPath}): ${error.message}`);
+        }
+        const marker = `printf '%s%s\\n' ${shq(DISPATCH_START_PREFIX)} ${shq(suffix)}`;
+        const line = `${marker} > ${shq(ackPath)} || exit 1; ${marker}; ${cmd}`;
+        const deadline = this.time.now() + DISPATCH_ACK_TIMEOUT_MS;
+        try {
+            const sent = await this.herdr(`pane run ${shq(pane)} ${shq(line)}`, slot.cwd);
+            if (sent.code !== 0) {
+                throw new DeliveryCorruptedError(pane, `pane run failed: ${sent.stderr || sent.stdout}`, "");
+            }
+            // Fast path: herdr's own event-driven watch on the pane's output. A match is causal — the pane
+            // cannot emit the joined marker without having RUN the line. A MISS is not evidence of
+            // anything: this watch subscribes after the request, and a full-screen repaint can swallow the
+            // very line it is watching for, which is how a successful launch got dispatched twice. So a
+            // miss falls through to the channel the line wrote for itself, which nothing can repaint.
+            const seen = await this.herdr(`pane wait-output ${shq(pane)} --match ${shq(nonce)} --timeout ${DISPATCH_ACK_TIMEOUT_MS}`, slot.cwd, DISPATCH_ACK_TIMEOUT_MS + 15_000);
+            if (this.waitOk(seen.code, seen.stdout))
+                return;
+            if (await this.awaitDispatchAck(ackPath, nonce, deadline))
+                return;
+            // Only now, and only as evidence for the operator: the transcript explains the failure, it
+            // never decides one. A pane that looks like it ran the line but never wrote the ack did not.
+            const transcript = (await this.herdr(`pane read ${shq(pane)} --source recent-unwrapped --lines ${DELIVERY_READ_LINES}`, slot.cwd)).stdout;
+            throw new DeliveryCorruptedError(pane, `START nonce ${nonce} never appeared — the line never ran`, transcript);
+        }
+        finally {
+            try {
+                unlinkSync(ackPath);
+            }
+            catch { /* never written, or already reaped — nothing to clean */ }
+        }
+    }
+    // The durable half of the acknowledgment: the file the delivered line wrote before it launched
+    // anything. Checked at least once even when the shared dispatch deadline has already passed, so a
+    // watch that spent the whole window missing the line still gets the truth from the line itself.
+    async awaitDispatchAck(ackPath, nonce, deadline) {
+        for (;;) {
+            try {
+                if (readFileSync(ackPath, "utf8").includes(nonce))
+                    return true;
+            }
+            catch {
+                /* the line has not reached the marker yet — or never will, which the deadline decides */
+            }
+            if (this.time.now() >= deadline)
+                return false;
+            await this.time.sleep(DISPATCH_ACK_POLL_MS);
+        }
+    }
+    // OBS-253: a fresh pane is a SIBLING inside this slot's own tab. Split first so the tab can never
+    // empty, then close the wedged pane and take its durable label — every other driver call addresses
+    // this slot through that label or the delivered-pane pin, so no caller observes the swap.
+    async freshPane(slot, wedged) {
+        if (!this.ws)
+            return null;
+        const sp = await this.herdr(`pane split ${shq(wedged)} --direction down --no-focus --cwd ${shq(slot.cwd)}`);
+        if (sp.code !== 0)
+            return null;
+        let pane;
+        try {
+            pane = JSON.parse(sp.stdout).result?.pane?.pane_id ?? undefined;
+        }
+        catch {
+            return null;
+        }
+        if (typeof pane !== "string" || !pane)
+            return null;
+        // The wedged pane is never re-pressed, only reaped — and the reap is a POSTCONDITION, not a
+        // best-effort. It still carries this slot's durable label, so a close that fails (or succeeds
+        // and frees nothing) leaves two panes answering to one name and `pane list` resolving it by
+        // whichever comes first. Verify the name is free BEFORE the replacement is renamed, seeded or
+        // dispatched: a fresh pane that is only PROBABLY the slot is not a fresh pane (v1.85 T5 review).
+        const closed = await this.herdr(`pane close ${shq(wedged)}`);
+        if (closed.code !== 0 || (await this.staleLabelPanes(slot.name, pane)).length > 0) {
+            await this.herdr(`pane close ${shq(pane)}`);
+            return null;
+        }
+        const rn = await this.herdr(`pane rename ${shq(pane)} ${shq(slot.name)}`);
+        if (rn.code !== 0 || (await this.namedPaneId(slot.name)) !== pane) {
+            await this.herdr(`pane close ${shq(pane)}`);
+            return null;
+        }
+        // VIS-10 hole 3: a split pane is a bare shell with FRESH env, so it is untargeted until seeded.
+        const seed = await this.herdr(`pane run ${shq(pane)} ${shq(`export HERDR_WORKSPACE_ID=${shq(this.ws)}; export ${PANE_IDENTITY_ENV}=${shq(paneIdentityLine(canonicalizeLegacyName(slot.name, "")))}; ${herdrSealShellPrefix()}`)}`, slot.cwd);
+        if (seed.code !== 0) {
+            await this.herdr(`pane close ${shq(pane)}`);
+            return null;
+        }
+        return pane;
+    }
+    // OBS-85 typed delivery, now reserved for real TUI turns: type WITHOUT enter, read the pane back
+    // — `wait output --match` checks the same unwrapped transcript pane read exposes, event-driven so
+    // wrap and render timing can't race the check — and press Enter only when that read-back contains
+    // the typed command. A corrupted paste is captured (pane read), cleared (C-u), and retyped,
+    // bounded; persistent corruption fails closed WITH the captured transcript.
+    async deliverTyped(slot, cmd, pane) {
+        const inputBox = this.inputBoxes.get(slot);
+        const missing = missingInputStateDeclarations(inputBox);
+        if (missing.length > 0) {
+            throw new Error(`herdr refuses typed delivery to ${slot.name}: the adapter has not declared its input states `
+                + `(missing: ${missing.join(", ")}) — only a declared box can acknowledge a submission, and `
+                + `nothing else may stand in for it (OBS-140)`);
+        }
+        const readiness = await this.awaitDeliveryReadiness(slot, cmd, pane, inputBox);
         let transcript = "";
         for (let attempt = 0; attempt < DELIVERY_ATTEMPTS; attempt++) {
             if (attempt > 0) {
@@ -487,7 +728,7 @@ export class HerdrDriver {
                 // line only after two consecutive pane reads agree; an already-stable frame returns on the
                 // first fresh read without a timer. A changing pane is bounded and preserves OBS-85's
                 // fail-closed error instead of guessing from an adapter fingerprint.
-                const settled = await this.settleDeliveryLine(pane, slot.cwd, transcript, this.inputBoxes.get(slot));
+                const settled = await this.settleDeliveryLine(pane, slot.cwd, transcript, inputBox);
                 transcript = settled.transcript;
                 if (!settled.ok) {
                     throw new Error(`herdr delivery clear failed — refusing to retype onto a corrupted line (OBS-85); pane transcript:\n${transcript}`);
@@ -506,24 +747,14 @@ export class HerdrDriver {
                 throw new Error(`herdr pane send-text failed: ${typed.stderr || typed.stdout}`);
             const back = await this.herdr(`pane wait-output ${shq(pane)} --match ${shq(cmd)} --timeout ${DELIVERY_VERIFY_TIMEOUT_MS}`, slot.cwd, DELIVERY_VERIFY_TIMEOUT_MS + 15_000);
             if (this.waitOk(back.code, back.stdout) || await this.deliveryReadMatches(pane, cmd, slot.cwd)) {
-                if (verifySubmission) {
-                    await this.submitVerifiedDelivery(slot, cmd, pane, readiness);
-                }
-                else {
-                    const enter = await this.herdr(`pane send-keys ${shq(pane)} Enter`, slot.cwd);
-                    if (enter.code !== 0)
-                        throw new Error(`herdr pane send-keys Enter failed: ${enter.stderr || enter.stdout}`);
-                }
+                await this.submitVerifiedDelivery(slot, pane, inputBox, readiness);
                 return;
             }
             // capture the corrupted delivery BEFORE clearing it — the OBS-85 byte-level evidence
             transcript = (await this.herdr(`pane read ${shq(pane)} --source recent-unwrapped --lines ${DELIVERY_READ_LINES}`, slot.cwd)).stdout;
         }
-        throw new Error(`herdr delivery corrupted after ${DELIVERY_ATTEMPTS} attempts — enter never pressed (OBS-85); pane transcript:\n${transcript}`);
+        throw new DeliveryCorruptedError(pane, `${DELIVERY_ATTEMPTS} typed attempts — enter never pressed (OBS-85)`, transcript);
     }
-    // The narrator launches a perpetual shell watch, not an adapter-backed input interface. Keep
-    // OBS-85's readiness + paste read-back and the historical single Enter, while worker/gate runs
-    // continue through positive post-Enter evidence in submitVerifiedDelivery.
     // OBS-201: liveness nudge — deliver one message into the live worker TUI through the exact
     // pincer every dispatch uses (readiness stable-frame, type-without-Enter, read-back, C-u clear
     // on corruption, verified submit), serialized on the deliveryQueue so it can never interleave
@@ -536,23 +767,24 @@ export class HerdrDriver {
         if (!pinned)
             return false;
         try {
-            await this.deliveryQueue(() => this.deliver(slot, message, pinned));
+            await this.deliveryQueue(() => this.deliverTyped(slot, message, pinned));
             return true;
         }
         catch {
             return false; // the daemon journals worker-nudge-failed and falls back to the stall window
         }
     }
+    // The narrator launches a perpetual shell watch, not an adapter-backed input interface — a shell
+    // dispatch like any other, delivered atomically and acknowledged by its own START nonce.
     async deliverPersistentShellCommand(slot, cmd) {
         return this.deliveryQueue(async () => {
             const pane = await this.paneId(slot);
-            await this.deliver(slot, cmd, pane, false);
+            await this.deliverAtomic(slot, cmd, pane);
             this.deliveredPanes.set(slot, pane);
         });
     }
-    async submitVerifiedDelivery(slot, cmd, pane, readiness) {
+    async submitVerifiedDelivery(slot, pane, inputBox, readiness) {
         let transcript = "";
-        const inputBox = this.inputBoxes.get(slot);
         // The base window preserves OBS-140's bounded behavior. A slow readiness observation grants
         // the same measured time once more for submit paint, capped by the readiness bound itself.
         const baseVerifyMs = (DELIVERY_SETTLE_READ_ATTEMPTS - 1) * DELIVERY_SETTLE_POLL_MS;
@@ -564,15 +796,15 @@ export class HerdrDriver {
             // Reuse the existing settle-read window. A first-read success returns before any timer; only
             // a prompt that still occupies the delivery target spends the bounded settle window. This
             // verification always completes before a possible re-press, so a slow submit cannot duplicate.
-            const settled = await this.settleDeliveryLine(pane, slot.cwd, transcript, inputBox, (candidate) => this.submissionRegistered(candidate, cmd, inputBox), verifyWindowMs);
+            const settled = await this.settleDeliveryLine(pane, slot.cwd, transcript, inputBox, (candidate) => this.submissionRegistered(candidate, inputBox), verifyWindowMs);
             transcript = settled.transcript;
             if (settled.ok)
                 return;
             if (settled.readFailed) {
-                throw new Error(`herdr delivery corrupted — submission verification failed, refusing to re-press Enter (OBS-140); pane transcript:\n${transcript}`);
+                throw new DeliveryCorruptedError(pane, "submission verification read failed, refusing to re-press Enter (OBS-140)", transcript);
             }
         }
-        throw new Error(`herdr delivery corrupted after ${DELIVERY_SUBMIT_ATTEMPTS} submit attempts — submission never registered (OBS-140); pane transcript:\n${transcript}`);
+        throw new DeliveryCorruptedError(pane, `${DELIVERY_SUBMIT_ATTEMPTS} submit attempts — submission never registered (OBS-140)`, transcript);
     }
     async settleDeliveryLine(pane, cwd, initialTranscript, inputBox, accept, settleWindowMs) {
         let transcript = initialTranscript;
@@ -604,10 +836,11 @@ export class HerdrDriver {
         }
         return { ok: false, transcript, recognizedInputBox: false };
     }
-    async awaitDeliveryReadiness(slot, cmd, pane) {
-        const inputBox = this.inputBoxes.get(slot);
-        const requireInputBox = inputBox !== undefined && inputBox.launchCommand?.(cmd) !== true;
-        const timeoutMs = inputBox?.readinessTimeoutMs ?? DELIVERY_READINESS_TIMEOUT_MS;
+    // Readiness now serves typed delivery only, so the target is always the adapter's declared box:
+    // the "no declared box, so assume ready when the pane doesn't already show our command" branch is
+    // gone with the rest of the typed-text inference (v1.85 T5).
+    async awaitDeliveryReadiness(slot, cmd, pane, inputBox) {
+        const timeoutMs = inputBox.readinessTimeoutMs ?? DELIVERY_READINESS_TIMEOUT_MS;
         const started = this.time.now();
         let previous;
         let transcript = "";
@@ -635,11 +868,9 @@ export class HerdrDriver {
             }
             if (previous !== undefined) {
                 const stableFrame = read.stdout === previous;
-                const targetReady = stableFrame && (requireInputBox
-                    ? matchesInputBox(previous, inputBox) && matchesInputBox(read.stdout, inputBox)
-                    : !this.deliveryMatches(read.stdout, cmd));
-                if (targetReady)
+                if (stableFrame && matchesInputBox(previous, inputBox) && matchesInputBox(read.stdout, inputBox)) {
                     return { waitedMs, timeoutMs, transcript: read.stdout };
+                }
             }
             previous = read.stdout;
             const remaining = timeoutMs - waitedMs;
@@ -888,7 +1119,10 @@ export class HerdrDriver {
             /* cosmetic — visibility hygiene never fails the run */
         }
     }
-    worktree(repo, branch, baseRef) {
-        return createWorktree(repo, branch, baseRef);
+    async worktree(repo, branch, baseRef) {
+        const worktree = await createWorktree(repo, branch, baseRef);
+        this.journalRoots.set(repo, repo);
+        this.journalRoots.set(worktree, repo);
+        return worktree;
     }
 }