@agent-compose/sdk 0.8.4 → 0.8.6

package/src/runtimes/_cli-agent.ts

@@ -4,7 +4,7 @@
  * contract.
  *
  * This is a different *mechanism* from the other runtimes: `claudeRuntime`
- * drives the Anthropic Agent SDK and `vercelRuntime` drives the Vercel AI SDK,
+ * drives the Anthropic Agent SDK and `createVercelRuntime` drives the Vercel AI SDK,
  * but a CLI-agent runtime spawns the provider's own CLI (`codex exec --json`,
  * `amp -x --stream-json`) — the CLI brings its own agent loop + tools, and we
  * only stream-parse the events it prints. Codex and Amp are the first two; this
@@ -109,6 +109,67 @@ export function runnerBusySentinelFragment(busyPath: string, tasksPath: string):
  *  `date +%s%3N` in the same exec, so host clock skew is irrelevant) is
  *  stale: three missed writes. */
 export const RUNNER_HEARTBEAT_STALE_MS = RUNNER_HEARTBEAT_INTERVAL_SECONDS * 1000 * 3;
+
+// ── The tool-run pulse (child-telemetry contract, 2026-08-29) ───────────────
+// The "no signal 4m" report: a long foreground tool (`bun install`) emits
+// NOTHING on the stream — the CLI only speaks at tool boundaries — so the
+// transcript decayed to "no signal" over a provably-working machine. The
+// heartbeat subshell already beats every 10s; this fragment rides the same
+// beat and samples the RUNNER'S OWN SESSION (every process the setsid tree
+// holds): aggregate CPU jiffies + written bytes + live process count. The
+// durable-trio probe carries the newest sample as its trailing field; the
+// executor compares successive samples — counters ADVANCING is proof the
+// foreground tool is working, fanned to the client as a cheap live
+// `tool_pulse` frame (~one per activity tick, no output content). Absence
+// of advancing pulses while a tool is nominally running is then the REAL
+// no-signal. Cost: one `ps` + a few bounded /proc reads per beat; every
+// read degrades quiet (a guest without procps/proc writes nothing, and
+// the field parses absent — evidence-absent, never an error).
+
+/** The sh fragment the heartbeat subshell runs each beat to rewrite the
+ *  pulse file: `<guest epoch ms>,<cpu jiffies>,<written bytes>,<procs>`
+ *  for every process in the runner's own session (the setsid tree — the
+ *  CLI, its foreground tool, their children). Comma-separated so the
+ *  probe can carry it as ONE whitespace-delimited field. Exported for
+ *  tests. */
+export function toolPulseFragment(pulsePath: string): string {
+  return `ac_sid=$(ps -o sess= -p $$ 2>/dev/null | tr -cd 0-9); `
+    // sid "0" would match every process on a platform without real session
+    // ids — no sample beats a wrong one.
+    + `if [ -n "$ac_sid" ] && [ "$ac_sid" != "0" ]; then `
+    + `ac_pp=$(ps -eo pid=,sess= 2>/dev/null | awk -v s="$ac_sid" '$2==s{print $1}'); `
+    + `ac_cpu=$(for ac_p in $ac_pp; do sed 's/^.*) //' "/proc/$ac_p/stat" 2>/dev/null; done | awk '{s+=$12+$13} END{printf "%d", s}'); `
+    + `ac_io=$(for ac_p in $ac_pp; do cat "/proc/$ac_p/io" 2>/dev/null; done | awk '/^wchar:/{s+=$2} END{printf "%d", s}'); `
+    + `ac_np=$(printf '%s\\n' "$ac_pp" | grep -c .); `
+    + `printf '%s,%s,%s,%s' "$(date +%s%3N)" "\${ac_cpu:-0}" "\${ac_io:-0}" "\${ac_np:-0}" > ${shellQuote(pulsePath)} 2>/dev/null; `
+    + `fi`;
+}
+
+/** One tool-run pulse sample, parsed off the probe's trailing field. */
+export interface TurnToolPulse {
+  /** Guest epoch ms when the sample was written. */
+  atMs: number;
+  /** Aggregate utime+stime jiffies across the runner's session. */
+  cpuJiffies: number;
+  /** Aggregate written bytes (wchar) across the runner's session. */
+  ioBytes: number;
+  /** Live processes in the session. */
+  procs: number;
+}
+
+/** Parse the pulse token (`at,cpu,io,procs`). Null on anything malformed —
+ *  evidence-absent, never an error. Exported for tests. */
+export function parseToolPulseToken(token: string): TurnToolPulse | null {
+  const fields = token.split(",");
+  if (fields.length !== 4) return null;
+  const [atMs, cpuJiffies, ioBytes, procs] = fields.map((f) => Number.parseInt(f, 10));
+  if (!Number.isFinite(atMs) || atMs <= 0 || !Number.isFinite(cpuJiffies)
+    || !Number.isFinite(ioBytes) || !Number.isFinite(procs)) return null;
+  return { atMs: atMs!, cpuJiffies: cpuJiffies!, ioBytes: ioBytes!, procs: procs! };
+}
+
+/** Bound on the pulse token read (4 numeric fields + commas). */
+export const TOOL_PULSE_TOKEN_MAX_CHARS = 96;
 /** Watchdog cadence while a tail stream is attached. Each tick is one fresh
  *  short exec; a healthy stream makes every tick a no-op. */
 export const TAIL_WATCHDOG_INTERVAL_MS = 15_000;
@@ -124,13 +185,72 @@ export const TAIL_ABANDON_AFTER_STREAM_DEATHS = 3;
  *  (envd HTTP, ~65ms RTT), consumed from the byte offset. Latency-tuned:
  *  this is the degraded path, correctness never depends on it being fast. */
 export const DURABLE_POLL_INTERVAL_MS = 1_000;
-/** The claude CLI's stderr complaint when `--resume <id>` names a thread
- *  that does not exist on this machine (the 2026-08-18 split-brain
- *  forensic). When a nonzero exit's stderr carries it, the transport
- *  surfaces the stderr as the turn's LAST error event even though a bare
- *  result error already streamed — the consumer's classifier needs the
- *  specific complaint, not the generic `error_during_execution` token. */
-export const RESUME_TARGET_MISSING_STDERR = /no conversation found with session id/i;
+// ── Durable-poll death door (chaos S13 run 3, 2026-08-31) ───────────────────
+// The poll loop's `kill -0` probe answers "pid gone" ONLY through a
+// SUCCESSFUL exec; a DEAD sandbox's exec THROWS, which used to leave the
+// verdict at "unknown" forever — the transport polled a corpse until
+// something outside the SDK killed the turn. These bounds are the honest
+// exit. The K8s-Unknown philosophy still holds: a transport blip is never a
+// death verdict — the generic streak is deliberately generous (a count AND a
+// time window must BOTH be met, and any successful probe or durable read
+// resets everything), while provider-attested not-found evidence
+// (SandboxNotFoundError / "sandbox … not found") is trusted on a much
+// shorter streak because it names the sandbox, not the wire.
+
+/** Consecutive provider-attested "sandbox gone" probe failures ⇒ dead. */
+export const PROBE_DEATH_GONE_STREAK = 3;
+/** Not-found evidence must also persist this long (guards a momentary
+ *  control-plane 404 blip from killing a live turn). */
+export const PROBE_DEATH_GONE_WINDOW_MS = 15_000;
+/** Consecutive GENERIC probe-transport failures (timeouts, connection
+ *  faults) ⇒ dead — only together with the window below. */
+export const PROBE_DEATH_FAIL_STREAK = 20;
+/** …and the failure run must span at least this long with zero durable
+ *  evidence of any kind. */
+export const PROBE_DEATH_FAIL_WINDOW_MS = 120_000;
+
+/** Provider evidence that the SANDBOX itself is gone — E2B's
+ *  SandboxNotFoundError / NotFoundError classes (matched by name so no
+ *  provider import rides in the runtime layer), or their messages after any
+ *  wrapping ("Paused sandbox X not found" was run 3's exact shape). */
+export function isSandboxGoneError(err: unknown): boolean {
+  const name = (err as { name?: unknown } | null)?.name;
+  if (name === "SandboxNotFoundError" || name === "NotFoundError") return true;
+  const msg = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  return /sandbox[^\n]{0,120}not found|not found[^\n]{0,120}sandbox/i.test(msg);
+}
+
+/** One probe-failure run's bookkeeping (reset to zeros on ANY evidence). */
+export interface ProbeDeathState {
+  /** Consecutive probe execs that THREW (no verdict at all). */
+  failStreak: number;
+  /** Consecutive throws that were provider "sandbox gone" evidence. */
+  goneStreak: number;
+  /** Wall-clock start of the current failure run (0 = no run). */
+  firstFailAtMs: number;
+}
+
+/** The death-door decision, pure for tests. Null = keep polling. */
+export function probeDeathVerdict(
+  s: ProbeDeathState, nowMs: number,
+): "dead-gone" | "dead-silent" | null {
+  if (s.firstFailAtMs <= 0) return null;
+  const windowMs = nowMs - s.firstFailAtMs;
+  if (s.goneStreak >= PROBE_DEATH_GONE_STREAK && windowMs >= PROBE_DEATH_GONE_WINDOW_MS) return "dead-gone";
+  if (s.failStreak >= PROBE_DEATH_FAIL_STREAK && windowMs >= PROBE_DEATH_FAIL_WINDOW_MS) return "dead-silent";
+  return null;
+}
+
+/** The CLI's stderr complaint when the thread it was told to resume does
+ *  not exist on this machine: claude's `--resume <id>` "No conversation
+ *  found with session ID" (the 2026-08-18 split-brain forensic) and
+ *  opencode's `--session <id>` "Error: Session not found" (in the CLI's
+ *  red-bold ANSI dressing; 1.18.34). When a nonzero exit's stderr carries
+ *  it, the transport surfaces the stderr as the turn's LAST error event
+ *  even though a bare result error already streamed — the consumer's
+ *  classifier needs the specific complaint, not the generic
+ *  `error_during_execution` token. */
+export const RESUME_TARGET_MISSING_STDERR = /no conversation found with session id|error:\s*(?:\x1b\[[0-9;]*m)*\s*session not found/i;
 
 /** One durable-trio reading, parsed from the probe exec's single line. */
 export interface TurnProbeReading {
@@ -149,6 +269,10 @@ export interface TurnProbeReading {
    *  sample yet, or a garbled token — evidence-absent, never an error.
    *  Telemetry-only: no liveness verdict may ever read it. */
   perf?: GuestPerfSample;
+  /** Latest tool-run pulse (the `.pulse` token field, 2026-08-29), when the
+   *  guest wrote one AND it parsed clean. Telemetry-only, same rule as
+   *  `perf`: no liveness verdict may ever read it. */
+  pulse?: TurnToolPulse;
 }
 
 /** The probe exec: one line, six fields, always exit 0 — faults surface as
@@ -158,15 +282,23 @@ export interface TurnProbeReading {
  *  whitelist (`tr -cd`) collapses any garbled write to at most one token —
  *  it can never add whitespace and desync the field positions. */
 export function turnLivenessProbeCommand(
-  paths: { outPath: string; hbPath: string; perfPath: string; pid: number; sentinel: string },
+  paths: { outPath: string; hbPath: string; perfPath: string; pid: number; sentinel: string;
+    pulsePath?: string },
 ): string {
+  // The 7th field is the tool-run pulse token (`.pulse`, 2026-08-29), `-`
+  // when absent — same optional-trailing-field contract as perf; the char
+  // whitelist collapses garbled writes to at most one token.
+  const pulseRead = paths.pulsePath
+    ? `pu=$(head -c ${TOOL_PULSE_TOKEN_MAX_CHARS} ${shellQuote(paths.pulsePath)} 2>/dev/null | tr -cd '0-9,'); `
+    : `pu=; `;
   return `sz=$(wc -c < ${shellQuote(paths.outPath)} 2>/dev/null || echo -1); `
     + `alive=0; kill -0 ${paths.pid} 2>/dev/null && alive=1; `
     + `hb=$(cat ${shellQuote(paths.hbPath)} 2>/dev/null || echo 0); `
     + `now=$(date +%s%3N); `
     + `sent=$(grep -c -F ${shellQuote(paths.sentinel)} ${shellQuote(paths.outPath)} 2>/dev/null || echo 0); `
     + `pf=$(head -c ${PERF_TOKEN_MAX_CHARS} ${shellQuote(paths.perfPath)} 2>/dev/null | tr -cd 'A-Za-z0-9=,.-'); `
-    + `printf '%s %s %s %s %s %s\\n' "$sz" "$alive" "$hb" "$now" "$sent" "\${pf:--}"`;
+    + pulseRead
+    + `printf '%s %s %s %s %s %s %s\\n' "$sz" "$alive" "$hb" "$now" "$sent" "\${pf:--}" "\${pu:--}"`;
 }
 
 /** Parse the probe's line. Null = unusable output (a wedged or faulted exec)
@@ -186,9 +318,12 @@ export function parseTurnProbeOutput(raw: string): TurnProbeReading | null {
     || !Number.isFinite(nowMs) || !Number.isFinite(sentinelCount)) return null;
   const perfTok = fields[5];
   const perf = perfTok !== undefined && perfTok !== "-" ? parsePerfToken(perfTok) : null;
+  const pulseTok = fields[6];
+  const pulse = pulseTok !== undefined && pulseTok !== "-" ? parseToolPulseToken(pulseTok) : null;
   return {
     size, alive, hbMs, nowMs, sentinelSeen: sentinelCount > 0,
     ...(perf ? { perf } : {}),
+    ...(pulse ? { pulse } : {}),
   };
 }
 
@@ -204,18 +339,24 @@ export function livenessVerdictFromReading(reading: TurnProbeReading | null): Ru
   return "dead";
 }
 
-// ── Mid-turn stream input (the delivery half of injectUserMessage) ──────────
-// The durable transport's stdin, when the spec declares `streamInput`, is a
-// FIFO fed by an in-guest subshell: the prompt line first, then any complete
-// lines appended to the turn's durable INBOX file. A steering-capable CLI
-// (claude -p --input-format stream-json) folds a message that arrives while
-// the turn runs into the RUNNING turn at its next tool boundary — verified
-// live against claude 2.1.233. The feeder checks for the CLI's terminal
-// `result` line BEFORE each delivery (a message that races the result stays
-// owed for the follow-up turn, never half-consumed) and stops on it; closing
-// the FIFO is what EOFs the CLI's stdin and lets it exit. The DELIVERED
-// counter file is the ack the server trusts: it advances only after the
-// feeder forwarded those inbox lines into the CLI's stdin.
+// ── Mid-turn input (the delivery half of injectUserMessage) ─────────────────
+// A message for a RUNNING turn is appended as one line to the turn's durable
+// INBOX file; the DELIVERED counter file beside it is the ack the server
+// trusts, advancing only once the line was handed to the CLI. Two transports
+// hand it over (CliAgentSpec.midTurnInput):
+//   - "stdin-stream": the durable transport's stdin is a FIFO fed by an
+//     in-guest subshell — the prompt line first, then any complete inbox
+//     lines. A steering-capable CLI (claude -p --input-format stream-json)
+//     folds a message that arrives while the turn runs into the RUNNING turn
+//     at its next tool boundary — verified live against claude 2.1.233. The
+//     feeder checks for the CLI's terminal `result` line BEFORE each delivery
+//     (a message that races the result stays owed for the follow-up turn,
+//     never half-consumed) and stops on it; closing the FIFO is what EOFs the
+//     CLI's stdin and lets it exit.
+//   - "tool-hook": the CLI runs a platform hook after every tool call it
+//     completes (codex: a PostToolUse command hook); the hook forwards the
+//     unfed inbox lines to the model as additional context and advances the
+//     counter. The CLI's stdin stays the plain prompt file.
 
 /** Feeder poll cadence (seconds — it is a shell `sleep`; GNU sleep accepts
  *  fractions and the durable transport only runs on the GNU guest image). */
@@ -232,10 +373,40 @@ export const INJECT_ACK_POLL_ATTEMPTS = 30;
 export const INJECT_ACK_POLL_SECONDS = "0.5";
 export const INJECT_ACK_EXEC_TIMEOUT_MS = 25_000;
 
+/** How the guest recognises the CLI's terminal `result` event in the durable
+ *  .out: a line that carries the `"type":"result"` pair and does not open
+ *  with another event's type, as an awk condition over `$0` (POSIX awk, so
+ *  dash, busybox and the macOS test hosts read it alike). The CLI does not
+ *  keep its key order: 2.1.212 wrote `{"type":"result",…` but 2.1.278 and
+ *  later write the pair near the END of the object
+ *  (`{"duration_api_ms":…,"result":"…","type":"result","duration_ms":…}`), so
+ *  the anchored prefix the resident contract used matched nothing on the
+ *  pinned 2.1.283. Every other event the CLI writes opens with its own type
+ *  (`{"type":"assistant",…`, `{"type":"stream_event",…`), which keeps a tool
+ *  call whose input holds the same pair from counting; tool output and model
+ *  text ride inside JSON strings, where the quotes are escaped. */
+export const CLI_RESULT_LINE_AWK =
+  'index($0, "\\"type\\":\\"result\\"") > 0 && '
+  + '(index($0, "{\\"type\\":\\"") != 1 || index($0, "{\\"type\\":\\"result\\"") == 1)';
+
+/** An awk program over the lines on stdin (or the files after it) that
+ *  applies `action` to each result line and runs `end` at the end. */
+function resultLineAwk(action: string, end: string): string {
+  return `awk ${shellQuote(`${CLI_RESULT_LINE_AWK} { ${action} } END { ${end} }`)}`;
+}
+
 /** The in-guest feeder fragment, prepended to the detached wrapper script.
  *  Runs inside the setsid session (group-kill reaps it) and keys its loop to
  *  the wrapper's own pid (`$$`), like the heartbeat subshell. Exported for
- *  tests. */
+ *  tests.
+ *
+ *  The forward is GUARDED: the fed and delivered counters advance only
+ *  when `sed` wrote the lines. The loop keys on the wrapper, which outlives
+ *  a CLI that died without a result line by the sentinel write and the
+ *  exit push; in that window the FIFO has no reader, `sed` dies of SIGPIPE,
+ *  and an unguarded counter still advanced, so the ack exited 0 for a line
+ *  nobody could read and the settle sealed it (review C1). Guarded, the ack
+ *  sees no advance and exits 4 or 5, and the message stays owed. */
 export function streamInputFeederFragment(paths: {
   promptPath: string; fifoPath: string; inboxPath: string;
   deliveredPath: string; outPath: string;
@@ -244,11 +415,11 @@ export function streamInputFeederFragment(paths: {
   return `rm -f ${q(paths.fifoPath)}; mkfifo ${q(paths.fifoPath)}; `
     + `: > ${q(paths.inboxPath)}; echo 0 > ${q(paths.deliveredPath)}; `
     + `( cat ${q(paths.promptPath)}; ac_fed=0; while kill -0 "$$" 2>/dev/null; do `
-    + `if tail -c ${INJECT_FEEDER_RESULT_TAIL_BYTES} ${q(paths.outPath)} 2>/dev/null | grep -q '"type":"result"'; then break; fi; `
+    + `if tail -c ${INJECT_FEEDER_RESULT_TAIL_BYTES} ${q(paths.outPath)} 2>/dev/null | ${resultLineAwk("f = 1", "exit f ? 0 : 1")}; then break; fi; `
     + `ac_lines=$(wc -l < ${q(paths.inboxPath)} 2>/dev/null || echo 0); ac_lines=\${ac_lines:-0}; `
     + `if [ "$ac_lines" -gt "$ac_fed" ]; then `
-    + `sed -n "$((ac_fed+1)),$((ac_lines))p" ${q(paths.inboxPath)}; ac_fed=$ac_lines; `
-    + `echo "$ac_fed" > ${q(paths.deliveredPath)}; fi; `
+    + `sed -n "$((ac_fed+1)),$((ac_lines))p" ${q(paths.inboxPath)} && { ac_fed=$ac_lines; `
+    + `echo "$ac_fed" > ${q(paths.deliveredPath)}; }; fi; `
     + `sleep ${INJECT_FEEDER_POLL_SECONDS}; done ) > ${q(paths.fifoPath)} 2>/dev/null </dev/null & `;
 }
 
@@ -263,18 +434,44 @@ export function streamInputFeederFragment(paths: {
  *  activity) MUST wrap through here — the wrapper rides only the wire to
  *  the model; the stored conversation row keeps the user's raw text.
  *  The text is pinned by tests: change it deliberately or not at all. */
-export function wrapMidTurnUserMessage(text: string): string {
-  return "The user sent a new message while you were working:\n\n"
+export function wrapMidTurnUserMessage(text: string, opts?: MidTurnEnvelopeOptions): string {
+  const relayedFrom = opts?.relayedFrom?.trim();
+  // A person's own words RELAYED by the agent that owns the worker's thread
+  // (review D2, 2026-09-25): the envelope names who said them, because they
+  // are not the session user's words and "The user sent" would misattribute
+  // them. The relayed row's own text carries the SAID marker and its frame.
+  // The thread agent that owns this worker, in its own words (owner decision
+  // 2026-09-27): not the session user either. The row's own text closes with
+  // its trust frame.
+  const head = relayedFrom
+    ? `A message relaying ${relayedFrom}'s own words arrived while you were working:\n\n`
+    : opts?.fromOwnerAgent
+      ? "The agent that owns your thread sent a message while you were working:\n\n"
+      : "The user sent a new message while you were working:\n\n";
+  return head
     + text
     + "\n\nAddress the message above as you continue this turn.";
 }
 
+/** Who a mid-turn message speaks for, when it is not the session user.
+ *  `relayedFrom` = the display name of the person whose own words an agent
+ *  relayed verbatim; `fromOwnerAgent` = the thread agent that owns this
+ *  worker, in its own words; both absent = the session user's own message. */
+export interface MidTurnEnvelopeOptions {
+  relayedFrom?: string | null;
+  fromOwnerAgent?: boolean;
+}
+
 /** The one delivery-ack exec `injectUserMessage` runs: append the message
  *  line to the durable inbox, then wait for the feeder's delivered counter
- *  to cover it. Exit 0 = delivered into the CLI's stdin pre-result; 4 = the
- *  runner died first; 5 = not delivered within the ack window (feeder
- *  stopped on the result, or the guest is crawling) — both non-zero exits
- *  mean "leave the message owed". Exported for tests. */
+ *  to cover it. Exit 0 = written into the CLI's stdin pipe pre-result,
+ *  which is NOT "the model saw it": the CLI surfaces the line at its next
+ *  tool boundary, so a kill before then loses it, and the settle's kill
+ *  terminals hold the anchor at the pre-inject dispatch head for that
+ *  reason (review D8). 4 = the runner died first; 5 = not forwarded within
+ *  the ack window (the feeder is not forwarding: it stopped on the result,
+ *  the resident turn gate is closed, or the guest is crawling). Both
+ *  non-zero exits mean "leave the message owed". Exported for tests. */
 export function injectAppendAndAckCommand(args: {
   line: string; target: number; pid: number;
   inboxPath: string; deliveredPath: string;
@@ -288,6 +485,71 @@ export function injectAppendAndAckCommand(args: {
     + `sleep ${INJECT_ACK_POLL_SECONDS}; i=$((i+1)); done; exit 5`;
 }
 
+// ── Mid-turn input transports (CliAgentSpec.midTurnInput) ───────────────────
+
+/** stdin is a live message stream: the FIFO feeder above delivers the prompt
+ *  line first and inbox lines after (claude: `--input-format stream-json`). */
+export interface StdinStreamInputSpec {
+  transport: "stdin-stream";
+  /** Serialise the opening prompt into ONE stream-input stdin line
+   *  (claude: a stream-json user message). No trailing newline — the
+   *  transport owns line framing. */
+  promptLine(prompt: string): string;
+  /** Serialise one mid-turn user message into ONE stdin line. No
+   *  trailing newline. */
+  messageLine(text: string): string;
+  /** Serialise ONE in-band interrupt control line (claude: a stream-json
+   *  `control_request` with subtype "interrupt") — the ESC equivalent.
+   *  The CLI's control layer handles these immediately, MID-STEP
+   *  included: the running tool call aborts (its tool_result records the
+   *  harness's own rejection text), the run ends with an
+   *  `error_during_execution` result within ~100ms, and the session file
+   *  stays `--resume`-able with the whole turn context. Verified live
+   *  against claude 2.1.236. Absent → the runtime has no in-band
+   *  interrupt; callers fall back to kill semantics. */
+  interruptLine?(requestId: string): string;
+}
+
+/** The CLI hands the inbox to the model itself, through a hook it runs after
+ *  each tool call it completes (codex: the platform's PostToolUse command
+ *  hook, CODEX_MID_TURN_HOOK_COMMAND in codex.ts). The launch creates the
+ *  inbox and exports its paths into the CLI's environment
+ *  (toolHookInboxFragment); the hook reads them back, prints the unfed lines
+ *  as its additional context for the model and advances the delivered
+ *  counter. stdin stays the plain prompt file, so there is no in-band
+ *  interrupt on this transport. */
+export interface ToolHookInputSpec {
+  transport: "tool-hook";
+  /** Serialise one mid-turn user message into ONE inbox line the hook can
+   *  splice into its JSON output without decoding: a JSON string literal. */
+  messageLine(text: string): string;
+}
+
+export type MidTurnInputSpec = StdinStreamInputSpec | ToolHookInputSpec;
+
+/** The stdin-stream transport of a spec, or undefined. The FIFO feeder, the
+ *  resident harness, the prewarm lane and the in-band interrupt exist only
+ *  for this transport; the inject lane itself reads `midTurnInput`. */
+export function stdinStreamInputOf(spec: Pick<CliAgentSpec, "midTurnInput">): StdinStreamInputSpec | undefined {
+  return spec.midTurnInput?.transport === "stdin-stream" ? spec.midTurnInput : undefined;
+}
+
+/** The environment the tool-hook lane hands the CLI, and so the hook: codex
+ *  runs a command hook with the CLI process's own environment (codex-rs
+ *  hooks/src/registry.rs Hooks::new, engine/command_runner.rs at
+ *  rust-v0.160.0). The turn's inbox and delivered-counter paths. */
+export const MID_TURN_INBOX_ENV = "AC_MID_TURN_INBOX";
+export const MID_TURN_DELIVERED_ENV = "AC_MID_TURN_DELIVERED";
+
+/** The tool-hook lane's launch fragment, prepended to the detached wrapper
+ *  script (the shell the CLI starts in): a fresh inbox, the counter at 0,
+ *  and both paths exported for the hook. Exported for tests. */
+export function toolHookInboxFragment(paths: { inboxPath: string; deliveredPath: string }): string {
+  const q = shellQuote;
+  return `: > ${q(paths.inboxPath)}; echo 0 > ${q(paths.deliveredPath)}; `
+    + `export ${MID_TURN_INBOX_ENV}=${q(paths.inboxPath)} ${MID_TURN_DELIVERED_ENV}=${q(paths.deliveredPath)}; `;
+}
+
 // ── Reap = kill AND CONFIRM (2026-08-18 incident: codex writer lock) ────────
 // A reaped runner must be CONFIRMED dead before the turn unwinds. codex holds
 // a kernel flock on its thread store (`~/.codex/thread-writer-locks/<id>.lock`)
@@ -335,14 +597,19 @@ export function reapKillAndConfirmCommand(pid: number): string {
 // clean sentinel — the probe measured 625ms), and a guest idle watchdog
 // reaps the group if the server's durable record is ever lost. Turn
 // accounting rides two guest numbers next to the inbox:
-//   `<prompt>.served`     — turns DELIVERED into this process (1 at launch,
-//                           +1 per adoption; the server mirrors it durably
+//   `<prompt>.served`     — turns DELIVERED into this process (1 at launch;
+//                           each adoption rebases it to the result lines it
+//                           counted + 1, so a result the CLI wrote on its
+//                           own, such as a background task's wake turn,
+//                           never desyncs it; the server mirrors it durably
 //                           as the runner stamp's `turnsServed`);
-//   result lines in .out  — turns FINISHED (anchored grep — hint-grade; the
-//                           server-side stream-json parse is authoritative).
-// idle ⇔ results ≥ served AND the inbox is fully fed. Mid-turn injects ride
-// the same inbox WITHOUT bumping served, and fold into the running turn
-// producing no result of their own — the parity holds.
+//   result lines in .out  — turns FINISHED (CLI_RESULT_LINE_AWK — hint-
+//                           grade; the server-side stream-json parse is
+//                           authoritative).
+// idle ⇔ results ≥ served. Mid-turn injects ride the same inbox WITHOUT
+// bumping served, and fold into the running turn producing no result of
+// their own. The feeder forwards inbox lines only while results < served,
+// so a line that raced the result is never fed into an idle CLI.
 
 /** Guest idle TTL for a resident with no new inbox line: hot window (180s)
  *  + margin, so the park gate's graceful `.end` normally wins and the
@@ -350,11 +617,14 @@ export function reapKillAndConfirmCommand(pid: number): string {
 export const RESIDENT_IDLE_TTL_S = 240;
 /** Watchdog poll cadence (seconds). */
 export const RESIDENT_WATCHDOG_POLL_S = 15;
-/** Anchored prefix of the CLI's terminal result event line. Anchoring keeps
- *  the guest-side counts honest against tool output that merely CONTAINS
- *  the substring; a serialization-order change fails SAFE (parity check
- *  refuses adoption → cold launch — a latency cost, never correctness). */
-export const RESIDENT_RESULT_LINE_PREFIX = '{"type":"result"';
+
+/** Shell command printing how many result lines the durable .out holds —
+ *  the guest's turn accounting (feeder gate, idle check, adoption parity).
+ *  Prints nothing when the file is missing: callers default an empty count
+ *  to 0. */
+export function cliResultCountCommand(outPath: string): string {
+  return `${resultLineAwk("n++", "print n + 0")} ${shellQuote(outPath)} 2>/dev/null`;
+}
 
 /** One bounded exec printing the count of result lines at or past
  *  `fromByte` (0-based) in the durable .out. Always exits 0; stdout is the
@@ -364,41 +634,82 @@ export function residentResultCountCommand(outPath: string, fromByte = 0): strin
   const src = fromByte > 0
     ? `tail -c +${fromByte + 1} ${q(outPath)} 2>/dev/null`
     : `cat ${q(outPath)} 2>/dev/null`;
-  return `ac_res=$(${src} | grep -c ${q(`^${RESIDENT_RESULT_LINE_PREFIX}`)}); echo "\${ac_res:-0}"`;
+  return `ac_res=$(${src} | ${resultLineAwk("n++", "print n + 0")}); echo "\${ac_res:-0}"`;
+}
+
+/** One bounded exec reporting the LAST result line in the durable .out
+ *  window [`fromByte`, `toByte`): prints `none` (no result line), `error`
+ *  (its `is_error` is true) or `ok`. Always exits 0 and never prints the
+ *  line itself. The harvest's confirm for a resident result the tailer never
+ *  parsed (review C2): a count alone cannot say whether the turn failed. The
+ *  whole line is searched for `"is_error":true`, wherever the CLI put it
+ *  (key order is not fixed). `toByte` bounds the window to bytes a drain
+ *  already walked past, so a result the drain never reached (or a line still
+ *  being written past its line-aligned offset) is not confirmed; omitted,
+ *  the window runs to the end of the file. A window with `toByte <= fromByte`
+ *  is empty. */
+export function residentLastResultCommand(outPath: string, fromByte = 0, toByte?: number): string {
+  const q = shellQuote;
+  const read = fromByte > 0
+    ? `tail -c +${fromByte + 1} ${q(outPath)} 2>/dev/null`
+    : `cat ${q(outPath)} 2>/dev/null`;
+  const src = toByte === undefined ? read : `${read} | head -c ${Math.max(0, toByte - fromByte)}`;
+  return `${src} | ${resultLineAwk("last = $0",
+    'if (last == "") print "none"; else if (index(last, "\\"is_error\\":true") > 0) print "error"; else print "ok"')}`;
 }
 
 /** The resident feeder: `streamInputFeederFragment` with the result-break
- *  REPLACED by the end-file break — the ONLY guest-contract change the
- *  resident shape needs (verified live by the spec's probe: two messages,
- *  one process, one session file, graceful exit on `.end`). */
+ *  REPLACED by the end-file break (verified live by the spec's probe: two
+ *  messages, one process, one session file, graceful exit on `.end`), plus
+ *  the TURN GATE: inbox lines are forwarded only while a delivered turn is
+ *  still unanswered (the result count in .out is below `.served`),
+ *  the same two numbers the idle predicate reads. Without the gate, a line
+ *  appended after the turn's result line but before the server settled the
+ *  turn was fed into the idle CLI, started a turn nobody tails, and was
+ *  acked as delivered: the message was never answered, and the extra result
+ *  line broke the next adoption's parity. With the gate that line stays
+ *  unfed, the inject ack exits 5, and the message stays owed for the
+ *  follow-up turn. Adoption bumps `.served` BEFORE it appends, so the next
+ *  turn's prompt still flows. The count is a full-file grep, re-run
+ *  only on a poll that has unfed lines AND a changed (.out size, .served)
+ *  pair, so an idle resident holding a gated line never rescans. The
+ *  forward is guarded like the plain feeder's: the counters advance only
+ *  when `sed` wrote the lines into the FIFO. */
 export function residentFeederFragment(paths: {
   promptPath: string; fifoPath: string; inboxPath: string;
-  deliveredPath: string; endPath: string;
+  deliveredPath: string; endPath: string; outPath: string; servedPath: string;
 }): string {
   const q = shellQuote;
   return `rm -f ${q(paths.fifoPath)}; mkfifo ${q(paths.fifoPath)}; `
     + `: > ${q(paths.inboxPath)}; echo 0 > ${q(paths.deliveredPath)}; rm -f ${q(paths.endPath)}; `
-    + `( cat ${q(paths.promptPath)}; ac_fed=0; while kill -0 "$$" 2>/dev/null; do `
+    + `( cat ${q(paths.promptPath)}; ac_fed=0; ac_gk=; ac_gr=0; while kill -0 "$$" 2>/dev/null; do `
     + `if [ -f ${q(paths.endPath)} ]; then break; fi; `
     + `ac_lines=$(wc -l < ${q(paths.inboxPath)} 2>/dev/null || echo 0); ac_lines=\${ac_lines:-0}; `
     + `if [ "$ac_lines" -gt "$ac_fed" ]; then `
-    + `sed -n "$((ac_fed+1)),$((ac_lines))p" ${q(paths.inboxPath)}; ac_fed=$ac_lines; `
-    + `echo "$ac_fed" > ${q(paths.deliveredPath)}; fi; `
+    + `ac_gs=$(wc -c < ${q(paths.outPath)} 2>/dev/null); ac_gv=$(cat ${q(paths.servedPath)} 2>/dev/null); ac_gv=\${ac_gv:-1}; `
+    + `if [ "$ac_gs:$ac_gv" != "$ac_gk" ]; then ac_gk="$ac_gs:$ac_gv"; `
+    + `ac_gr=$(${cliResultCountCommand(paths.outPath)}); ac_gr=\${ac_gr:-0}; fi; `
+    + `if [ "$ac_gr" -lt "$ac_gv" ]; then `
+    + `sed -n "$((ac_fed+1)),$((ac_lines))p" ${q(paths.inboxPath)} && { ac_fed=$ac_lines; `
+    + `echo "$ac_fed" > ${q(paths.deliveredPath)}; }; fi; fi; `
     + `sleep ${INJECT_FEEDER_POLL_SECONDS}; done ) > ${q(paths.fifoPath)} 2>/dev/null </dev/null & `;
 }
 
-/** Sets `ac_idle` (1 = between turns: every delivered turn has its result
- *  and the inbox is fully fed). Embedded by the watchdog and the resident
- *  heartbeat gate — one idle predicate, stated once. */
+/** Sets `ac_idle` (1 = between turns: every delivered turn has its result).
+ *  Embedded by the watchdog and the resident heartbeat gate: one idle
+ *  predicate, stated once. Unfed inbox lines do not make a resident busy:
+ *  the feeder's turn gate forwards a line only while results < served, so
+ *  a line still unfed once results >= served is held until the next
+ *  adoption bumps `.served` (a message that raced the result, owed on the
+ *  server). Reading it as work would keep the heartbeat fresh and the
+ *  watchdog quiet for as long as the line sat there. */
 export function residentIdleCheckFragment(paths: {
-  outPath: string; inboxPath: string; deliveredPath: string; servedPath: string;
+  outPath: string; servedPath: string;
 }): string {
   const q = shellQuote;
-  return `ac_res=$(grep -c ${q(`^${RESIDENT_RESULT_LINE_PREFIX}`)} ${q(paths.outPath)} 2>/dev/null); ac_res=\${ac_res:-0}; `
+  return `ac_res=$(${cliResultCountCommand(paths.outPath)}); ac_res=\${ac_res:-0}; `
     + `ac_srv=$(cat ${q(paths.servedPath)} 2>/dev/null); ac_srv=\${ac_srv:-1}; `
-    + `ac_in=$(wc -l < ${q(paths.inboxPath)} 2>/dev/null); ac_in=\${ac_in:-0}; `
-    + `ac_del=$(cat ${q(paths.deliveredPath)} 2>/dev/null); ac_del=\${ac_del:-0}; `
-    + `if [ "$ac_res" -ge "$ac_srv" ] && [ "$ac_in" -eq "$ac_del" ]; then ac_idle=1; else ac_idle=0; fi; `;
+    + `if [ "$ac_res" -ge "$ac_srv" ]; then ac_idle=1; else ac_idle=0; fi; `;
 }
 
 /** Guest idle watchdog: reap the whole process group after
@@ -422,7 +733,7 @@ export function residentIdleCheckFragment(paths: {
  *  guest rule about not killing, and journal advance is required, not mere
  *  process existence). */
 export function residentIdleWatchdogFragment(paths: {
-  outPath: string; inboxPath: string; deliveredPath: string; servedPath: string;
+  outPath: string; servedPath: string;
 }): string {
   return `( ac_idle_s=0; while kill -0 "$$" 2>/dev/null; do `
     + residentIdleCheckFragment(paths)
@@ -489,8 +800,10 @@ function parsePid(raw: string): number {
 /** Recover the detached runner's pid from its durable pidfile after the
  *  launch exec's STREAM died (deadline_exceeded, canceled context, any wire
  *  fault). Reads over the file transport with a short retry so the race
- *  where the launch shell is still writing the pidfile is absorbed. */
-async function recoverLaunchPid(read: (path: string) => Promise<string>, pidPath: string): Promise<number> {
+ *  where the launch shell is still writing the pidfile is absorbed.
+ *  Exported for the server's workflow-lane launch (turn-workflow/tailer.ts
+ *  launchDetachedRunner), which recovers the same way. */
+export async function recoverLaunchPid(read: (path: string) => Promise<string>, pidPath: string): Promise<number> {
   for (let attempt = 0; attempt < LAUNCH_PID_RECOVERY_ATTEMPTS; attempt++) {
     try {
       const pid = parsePid(await read(pidPath));
@@ -530,6 +843,23 @@ export function sessionEnvSourceFragment(relPath: string | undefined): string {
   return `[ -f "$HOME/${relPath}" ] && . "$HOME/${relPath}" >/dev/null 2>&1 || true; `;
 }
 
+/** Shell command printing a fingerprint of the session env file's current
+ *  bytes (POSIX `cksum`), or `absent` when there is no file. A resident
+ *  records it next to its prompt immediately BEFORE sourcing the file, and
+ *  an adoption compares the file's fingerprint at that moment with it: a
+ *  fresh launch would source the file as it is now, the resident only ever
+ *  saw the one it started with. Recording before the source keeps the
+ *  comparison conservative — a write that lands between the two reads as a
+ *  change. The guest file is the one truth every replica writes to, so the
+ *  verdict never depends on which server process wrote it. */
+export function sessionEnvFingerprintCommand(relPath: string): string {
+  if (!SESSION_ENV_FILE_SAFE.test(relPath) || relPath.includes("..")) {
+    throw new Error(`unsafe session env path: ${relPath}`);
+  }
+  // One group, so a redirect after it (`> <prompt>.envsum`) takes either arm.
+  return `{ { cksum < "$HOME/${relPath}"; } 2>/dev/null || echo absent; }`;
+}
+
 /** The per-turn model-credential source fragment (`RuntimeOptions.
  *  credEnvFile` — an ABSOLUTE guest path), or "" when none is configured.
  *  Sourced AFTER the session env file so the turn actor's credential wins.
@@ -693,9 +1023,9 @@ export interface CliAgentSpec {
    *  `effort` is present only when the caller configured a reasoning effort
    *  AND the spec has a real knob for it (see `CliReasoningEffort`).
    *  `streamInput` is true when the durable transport is feeding stdin as a
-   *  live message stream (see `CliAgentSpec.streamInput`): `promptPath` is
-   *  then the FIFO the feeder writes, and the CLI must be invoked in its
-   *  stream-input mode (claude: `--input-format stream-json`). */
+   *  live message stream (the "stdin-stream" `midTurnInput` transport):
+   *  `promptPath` is then the FIFO the feeder writes, and the CLI must be
+   *  invoked in its stream-input mode (claude: `--input-format stream-json`). */
   buildCommand(args: { promptPath: string; sessionId?: string; model?: string; cwd?: string; effort?: CliReasoningEffort; streamInput?: boolean }): string;
   /** Map one parsed JSONL stdout event to `AgentMessage`s. The base emits
    *  `init`/`done`/`error` lifecycle itself, so a spec maps only content +
@@ -726,27 +1056,22 @@ export interface CliAgentSpec {
    *  `extractSessionId`/`mapEvent` members are used only as the version-mismatch
    *  fallback. Absent → the spec is JSONL-only (legacy path always). */
   acp?: { command: string; args: string[]; env?: Record<string, string> };
-  /** Mid-turn STREAM-INPUT support (the delivery half of
-   *  `injectUserMessage`). When present AND the durable detached transport
-   *  is in play, the CLI's stdin is fed from a FIFO by an in-guest feeder:
-   *  the prompt line first, then any lines appended to the turn's durable
-   *  inbox file — so a steering-capable CLI (claude: queued user input is
-   *  folded into the RUNNING turn at the next tool boundary; verified live
-   *  against claude 2.1.233) receives user messages while the turn runs.
-   *  The feeder stops at the CLI's terminal result line (a message that
-   *  races the result is NOT forwarded — it stays owed) and closes the
-   *  FIFO, which is what ends the CLI process (stream-input CLIs exit on
-   *  stdin EOF, not after a result). Absent → the prompt file is the whole
-   *  stdin, exactly as before. */
-  streamInput?: {
-    /** Serialise the opening prompt into ONE stream-input stdin line
-     *  (claude: a stream-json user message). No trailing newline — the
-     *  transport owns line framing. */
-    promptLine(prompt: string): string;
-    /** Serialise one mid-turn user message into ONE stdin line. No
-     *  trailing newline. */
-    messageLine(text: string): string;
-  };
+  /** Mid-turn INPUT support (the delivery half of `injectUserMessage`): how
+   *  a line appended to the turn's durable inbox reaches the CLI while its
+   *  turn runs — see the transports above. Engages only on the durable
+   *  detached transport (the inbox, the delivered counter and the feeder or
+   *  hook live in the guest; single-exec transports keep the plain
+   *  prompt-file stdin). Absent → the runtime cannot take a message
+   *  mid-turn: every inject answers "unsupported" and the message waits for
+   *  the turn boundary. */
+  midTurnInput?: MidTurnInputSpec;
+}
+
+/** The CURRENT turn's mid-turn injection state (durable stream-input
+ *  transport only) — see the `turnInject` field. */
+interface TurnInjectState {
+  inboxPath: string; deliveredPath: string; pid: number;
+  appended: number; chain: Promise<unknown>;
 }
 
 /** A spawned ACP-mode CLI: the read side of its stdout and a delivery for its
@@ -823,27 +1148,74 @@ export class CliAgentRunner implements ModelExecutionContract {
    *  transport only). Null = no live stream-input turn — `injectUserMessage`
    *  answers "unsupported" and the caller leaves the message owed. `chain`
    *  serializes appends so each delivery targets a deterministic line count. */
-  private turnInject: {
-    inboxPath: string; deliveredPath: string; pid: number;
-    appended: number; chain: Promise<unknown>;
-  } | null = null;
+  private turnInject: TurnInjectState | null = null;
+
+  /** The CURRENT turn's detached-runner wrapper pid (the setsid group
+   *  leader echoed by the launch / recovered from the durable pidfile) —
+   *  durable-transport turns only. Null between turns and on transports
+   *  without a detached guest. See the contract doc (types/runtime.ts). */
+  private turnPid: number | null = null;
+
+  /** Advisory guest-pid identity for the live turn's runner tree — see the
+   *  contract doc (types/runtime.ts). Never a liveness verdict. */
+  currentRunnerPid(): number | null {
+    return this.turnPid;
+  }
+
+  /** Safe-to-persist durable byte offset — end of the last line whose
+   *  messages have ALL been yielded (boot-time turn adoption; contract in
+   *  types/runtime.ts). One line behind the parse cursor by design. */
+  private turnConsumedOffset: number | null = null;
+  /** End offset of the line currently being yielded from — promoted to
+   *  `turnConsumedOffset` when the NEXT line is pulled (or at stream end). */
+  private turnPendingLineEnd: number | null = null;
+
+  currentTurnDurableOffset(): number | null {
+    return this.turnConsumedOffset;
+  }
 
   /** Deliver one user message INTO the live turn — see the contract doc
    *  (types/runtime.ts). Appends a stream-input line to the turn's durable
    *  inbox and waits for the in-guest feeder's delivered-counter ack; only
-   *  an acked forward (pre-result, into the CLI's stdin) reports
-   *  "delivered". Guest exit 5 (ack window exhausted with the runner still
-   *  alive — a CLI that is not draining stdin mid-step) reports "pending":
-   *  the appended line may still be read when the current step finishes,
-   *  but it was NOT seen yet. Never throws. */
-  async injectUserMessage(text: string): Promise<"delivered" | "pending" | "closed" | "unsupported"> {
+   *  an acked forward (pre-result, written into the CLI's stdin pipe)
+   *  reports "delivered", and even then the model reads the line only at
+   *  its next tool boundary (review D8). Guest exit 5 (ack window exhausted
+   *  with the runner still alive: the feeder is not forwarding) reports
+   *  "pending": the appended line may still be forwarded later, but it was
+   *  NOT seen yet. Never throws. */
+  async injectUserMessage(text: string, opts?: MidTurnEnvelopeOptions): Promise<"delivered" | "pending" | "closed" | "unsupported"> {
     const inject = this.turnInject;
-    const streamInput = this.spec.streamInput;
-    if (!inject || !streamInput || this.guestDetached) return "unsupported";
+    const input = this.spec.midTurnInput;
+    if (!inject || !input || this.guestDetached) return "unsupported";
     // The address-this envelope (wrapMidTurnUserMessage): a raw injected
     // line carries no framing, and the model continues its narration
     // without acknowledging the message.
-    const line = streamInput.messageLine(wrapMidTurnUserMessage(text));
+    return this.appendTurnStreamLine(inject, input.messageLine(wrapMidTurnUserMessage(text, opts)));
+  }
+
+  /** Request an in-band step interrupt of the LIVE turn — the ESC
+   *  equivalent; see the contract doc (types/runtime.ts). Appends the
+   *  spec's interrupt control line to the turn's durable inbox; the guest
+   *  feeder forwards it into the CLI's stdin, whose control layer handles
+   *  it immediately — MID-STEP included, unlike queued user messages (the
+   *  inject "pending" wall applies to turn-loop consumption, not the
+   *  control layer). Only "delivered" means the control line reached the
+   *  CLI's stdin; callers escalate anything else to kill semantics. Never
+   *  throws. */
+  async interruptTurn(): Promise<"delivered" | "pending" | "closed" | "unsupported"> {
+    const inject = this.turnInject;
+    const interruptLine = stdinStreamInputOf(this.spec)?.interruptLine;
+    if (!inject || !interruptLine || this.guestDetached) return "unsupported";
+    return this.appendTurnStreamLine(inject, interruptLine(`itr-${Date.now().toString(36)}`));
+  }
+
+  /** The one durable append+ack path both mid-turn producers share
+   *  (`injectUserMessage`'s enveloped message line, `interruptTurn`'s raw
+   *  control line). Serialized on the inject chain so every append targets
+   *  a deterministic inbox line count. */
+  private appendTurnStreamLine(
+    inject: TurnInjectState, line: string,
+  ): Promise<"delivered" | "pending" | "closed"> {
     const attempt = inject.chain.then(async (): Promise<"delivered" | "pending" | "closed"> => {
       if (this.turnInject !== inject) return "closed";
       // The append lands whether or not the ack times out, so the target
@@ -860,7 +1232,7 @@ export class CliAgentRunner implements ModelExecutionContract {
           { timeoutMs: INJECT_ACK_EXEC_TIMEOUT_MS });
         if (res.exitCode === 0) return "delivered";
         // 5 = ack window exhausted, runner alive: the line is in the inbox
-        // and may be fed when the CLI next drains stdin (the mid-step wall).
+        // and the feeder is not forwarding it (stopped, or gated).
         // 4 = the runner died first; anything else is a fault — both closed.
         return res.exitCode === 5 ? "pending" : "closed";
       } catch { return "closed"; }
@@ -869,13 +1241,29 @@ export class CliAgentRunner implements ModelExecutionContract {
     return attempt;
   }
 
+  /** The most recent probe reading's tool-run pulse (2026-08-29), plus the
+   *  guest clock it was read against — telemetry only, refreshed by each
+   *  `probeTurnLiveness` call. Null between turns / before any probe. */
+  private lastTurnPulse: (TurnToolPulse & { guestNowMs: number }) | null = null;
+
+  /** Peek the newest tool-run pulse the durable probe carried — the
+   *  executor's evidence ticker reads it AFTER its liveness check to fan
+   *  the tool-progress fact to clients. Never probes on its own. */
+  peekTurnPulse(): (TurnToolPulse & { guestNowMs: number }) | null {
+    return this.lastTurnPulse;
+  }
+
   /** Durable three-valued liveness for the current turn — see the contract
    *  doc (types/runtime.ts). Never throws; never blocks past the probe's
    *  explicit exec timeout. */
   async probeTurnLiveness(): Promise<RunnerLivenessVerdict | null> {
     const probe = this.turnProbe;
     if (!probe) return null;
-    return livenessVerdictFromReading(await probe());
+    const reading = await probe();
+    if (reading?.pulse) {
+      this.lastTurnPulse = { ...reading.pulse, guestNowMs: reading.nowMs };
+    }
+    return livenessVerdictFromReading(reading);
   }
 
   /** Wakes the CURRENT tail-watchdog interval early. Armed only while the
@@ -1291,27 +1679,32 @@ export class CliAgentRunner implements ModelExecutionContract {
       // previous turn's push.
       this.turnProbe = null;
       this.turnInject = null;
+      this.turnPid = null;
+      this.turnConsumedOffset = null;
+      this.turnPendingLineEnd = null;
       this.nudgePending = false;
       this.wakeTailWatchdog = null;
-      // Mid-turn stream input engages only where BOTH halves exist: a spec
-      // that can serialise stream-input lines AND the durable detached
-      // transport (the feeder, inbox, and result-watch live in the guest;
-      // single-exec transports keep the plain prompt-file stdin).
-      const streamInput = this.spec.streamInput !== undefined
-        && this.sandbox.commands.runBackground !== undefined;
+      // Mid-turn input engages only where BOTH halves exist: a spec that
+      // declares a mid-turn input transport AND the durable detached
+      // transport (the inbox, the delivered counter and the feeder or hook
+      // live in the guest; single-exec transports keep the plain
+      // prompt-file stdin).
+      const durable = this.sandbox.commands.runBackground !== undefined;
+      const stdinStream = durable ? stdinStreamInputOf(this.spec) : undefined;
+      const toolHook = durable && this.spec.midTurnInput?.transport === "tool-hook";
       const fifoPath = `${promptPath}.fifo`;
-      const promptWrite = this.sandbox.files.write(promptPath, streamInput
-        ? `${this.spec.streamInput!.promptLine(opts.prompt)}\n`
+      const promptWrite = this.sandbox.files.write(promptPath, stdinStream
+        ? `${stdinStream.promptLine(opts.prompt)}\n`
         : this.spec.promptPayload(opts.prompt));
       const cmd = this.spec.buildCommand({
         // Stream-input turns read stdin from the feeder's FIFO; the prompt
         // file is the feeder's first delivery, not the CLI's stdin.
-        promptPath: streamInput ? fifoPath : promptPath,
+        promptPath: stdinStream ? fifoPath : promptPath,
         sessionId: opts.sessionId,
         model: this.model,
         cwd: this.options.cwd,
         effort: this.configEffort,
-        ...(streamInput ? { streamInput: true } : {}),
+        ...(stdinStream ? { streamInput: true } : {}),
       });
 
       // Frame guard (see _jsonl-guard.ts): the CLI's stdout is piped through
@@ -1362,12 +1755,20 @@ export class CliAgentRunner implements ModelExecutionContract {
       //   - SINGLE-EXEC STREAMING (everything else: local child_process,
       //     Vercel): the pre-incident shape — one exec, stdout streamed,
       //     exit code from the exec result.
-      const lines = new AsyncQueue<string>();
+      const lines = new AsyncQueue<{ line: string; end: number | null }>();
       // How the turn ended: the CLI's exit code once known (null while
       // running), plus a best-effort stderr tail for the error message.
       let exitCode: number | null = null;
       let exitStderr = "";
       let transportError: unknown = null;
+      /** True when the death door closed on PROVIDER-ATTESTED "sandbox
+       *  gone" evidence (dead-gone) — the machine itself died, not the CLI.
+       *  The error detail then says so in the classifier's sandbox_gone
+       *  vocabulary (turn-failure-class.ts), which routes the settle to the
+       *  unconditional machine-loss auto-continue lane; an answered
+       *  "pid gone" on a LIVE machine (a CLI that crashed on its own) stays
+       *  the evidence-gated runner_exit family. */
+      let sandboxGoneDeath = false;
       let consumerStopped = false;
       let reap: () => void = () => { /* set per transport */ };
       // The reap's kill-and-confirm exec, latched on first fire (reap runs
@@ -1421,23 +1822,32 @@ export class CliAgentRunner implements ModelExecutionContract {
         // supersede group-kill still reaps this subshell with the tree.
         const busyPath = `${promptPath}.busy`;
         const tasksPath = `${promptPath}.tasks`;
-        // Mid-turn stream input: the feeder subshell (see
+        // Mid-turn input: the stdin-stream feeder subshell (see
         // streamInputFeederFragment) rides at the FRONT of the detached
-        // script so the FIFO exists before the CLI opens it as stdin.
+        // script so the FIFO exists before the CLI opens it as stdin; the
+        // tool-hook lane creates the inbox here and exports its paths into
+        // the CLI's environment, for the hook the CLI runs at each tool step.
         const inboxPath = `${promptPath}.inbox`;
         const deliveredPath = `${promptPath}.delivered`;
-        const feeder = streamInput
+        const feeder = stdinStream
           ? streamInputFeederFragment({ promptPath, fifoPath, inboxPath, deliveredPath, outPath })
-          : "";
+          : toolHook
+            ? toolHookInboxFragment({ inboxPath, deliveredPath })
+            : "";
         // Perf sampling rides the same beat: every 6th beat (~60s) the
         // subshell burst-reads /proc and rewrites the `.perf` token the
         // durable-trio probe carries as its trailing field (perf-sampler.ts).
         const perfPath = `${promptPath}.perf`;
+        // The tool-run pulse (2026-08-29, child-telemetry contract): the
+        // same beat samples the session's own process tree so a long
+        // foreground tool proves it is working — see toolPulseFragment.
+        const pulsePath = `${promptPath}.pulse`;
         const detachedScript =
           feeder
           + `( ${perfSamplerFunctionFragment({ perfPath })}while kill -0 "$$" 2>/dev/null; do `
           + `date +%s%3N > ${shellQuote(hbPath)}; `
           + `${runnerBusySentinelFragment(busyPath, tasksPath)}; `
+          + `${toolPulseFragment(pulsePath)}; `
           + `ac_perf_tick; `
           + `sleep ${RUNNER_HEARTBEAT_INTERVAL_SECONDS}; done ) >/dev/null 2>&1 </dev/null & `
           + sessionEnvSourceFragment(this.options.sessionEnvFile)
@@ -1502,7 +1912,7 @@ export class CliAgentRunner implements ModelExecutionContract {
         // executor's evidence ticker (`probeTurnLiveness`) both read through
         // it — one fresh short exec per call, explicit timeout, faults map to
         // null ("probe-failed"), never to a verdict.
-        const probeCmd = turnLivenessProbeCommand({ outPath, hbPath, perfPath, pid, sentinel });
+        const probeCmd = turnLivenessProbeCommand({ outPath, hbPath, perfPath, pid, sentinel, pulsePath });
         const runTurnProbe = async (): Promise<TurnProbeReading | null> => {
           try {
             const res = await this.sandbox.commands.run(probeCmd, { timeoutMs: TURN_PROBE_TIMEOUT_MS });
@@ -1510,9 +1920,19 @@ export class CliAgentRunner implements ModelExecutionContract {
           } catch { return null; }
         };
         this.turnProbe = runTurnProbe;
+        // Advisory pid identity for the platform's background-work declare
+        // (in-harness Workflow tasks) — armed with the probe, cleared at the
+        // next turn's start (the tree may legitimately outlive this turn).
+        this.turnPid = pid;
+        // Durable launch report (boot-time turn adoption): hand the caller
+        // the guest prompt path + sentinel + pid so it can stamp them on
+        // the turn row — a successor process can then find the runner's
+        // durable files without this process's memory.
+        this.options.onDetachedLaunch?.({ promptPath, sentinel, pid });
         // Arm mid-turn injection now that the detached runner (and its
-        // feeder) exist; cleared with the turn in the finally below.
-        if (streamInput) {
+        // feeder or hook inbox) exist; cleared with the turn in the finally
+        // below.
+        if (stdinStream !== undefined || toolHook) {
           this.turnInject = { inboxPath, deliveredPath, pid, appended: 0, chain: Promise.resolve() };
         }
 
@@ -1529,7 +1949,7 @@ export class CliAgentRunner implements ModelExecutionContract {
             exitCode = Number.isFinite(code) ? code : 0;
             return;
           }
-          lines.push(line);
+          lines.push({ line, end: offset });
         };
 
         reap = () => {
@@ -1558,6 +1978,13 @@ export class CliAgentRunner implements ModelExecutionContract {
           // re-attaching tails and finishes on durable polling alone (a wire
           // that killed three streams will kill the fourth).
           let streamDeaths = 0;
+          // Death-door bookkeeping (see probeDeathVerdict): the current
+          // run of consecutive probe failures. ANY evidence — a probe exec
+          // that answered, a durable read that succeeded — resets it.
+          const probeDeath: ProbeDeathState = { failStreak: 0, goneStreak: 0, firstFailAtMs: 0 };
+          const resetProbeDeath = (): void => {
+            probeDeath.failStreak = 0; probeDeath.goneStreak = 0; probeDeath.firstFailAtMs = 0;
+          };
           while (exitCode === null && !consumerStopped && !opts.signal?.aborted) {
             let buf = "";
             let handle: SandboxBackgroundProcess | null = null;
@@ -1672,6 +2099,9 @@ export class CliAgentRunner implements ModelExecutionContract {
             if (durableRead) {
               try {
                 const bytes = Buffer.from(await durableRead(outPath), "utf8");
+                // The file plane answered — the sandbox is reachable, so no
+                // probe-failure run may accumulate toward the death door.
+                resetProbeDeath();
                 let rest = bytes.subarray(offset).toString("utf8");
                 let nl: number;
                 while (exitCode === null && (nl = rest.indexOf("\n")) >= 0) {
@@ -1681,18 +2111,43 @@ export class CliAgentRunner implements ModelExecutionContract {
               } catch { /* file plane briefly unreachable — retried below */ }
             }
             if (exitCode !== null) break;
-            // Runner still alive? A FRESH exec answers; unknown (wire fault)
-            // keeps retrying — the executor's evidence machinery bounds a
-            // truly dead sandbox, not this loop.
+            // Runner still alive? A FRESH exec answers; a wire-fault throw
+            // is no verdict and keeps retrying — but never FOREVER (chaos
+            // S13 run 3, 2026-08-31: a DEAD sandbox's probe exec THROWS, so
+            // `alive` stayed null and this loop polled the corpse blind
+            // until the executor closed the turn from outside). The death
+            // door: provider-attested "sandbox gone" evidence on a short
+            // streak, or a long generous window of nothing-but-failures
+            // (probeDeathVerdict) ⇒ the same honest abnormal-death terminal
+            // as an answered "pid gone" — never a clean done, never an
+            // eternal poll. Any evidence (an answered probe, a durable
+            // read) resets the run, so a live sandbox behind a flaky wire
+            // is never killed (the K8s-Unknown rule).
             let alive: boolean | null = null;
             try {
               const probe = await this.sandbox.commands.run(
-                `kill -0 ${pid} 2>/dev/null`, { timeoutMs: 10_000 });
+                `kill -0 ${pid} 2>/dev/null`, { timeoutMs: TURN_PROBE_TIMEOUT_MS });
               alive = probe.exitCode === 0;
-            } catch { alive = null; }
-            if (alive === false) {
+              resetProbeDeath();
+            } catch (probeErr) {
+              alive = null;
+              probeDeath.failStreak += 1;
+              if (probeDeath.firstFailAtMs === 0) probeDeath.firstFailAtMs = Date.now();
+              probeDeath.goneStreak = isSandboxGoneError(probeErr) ? probeDeath.goneStreak + 1 : 0;
+            }
+            const deathVerdict = probeDeathVerdict(probeDeath, Date.now());
+            if (deathVerdict !== null) {
+              console.warn(`[cli-agent] ${this.spec.kind} durable-poll death door: ${deathVerdict === "dead-gone"
+                ? `the provider reports the sandbox gone (${probeDeath.goneStreak} consecutive not-found probes over ${Math.round((Date.now() - probeDeath.firstFailAtMs) / 1000)}s)`
+                : `${probeDeath.failStreak} consecutive probe-transport failures over ${Math.round((Date.now() - probeDeath.firstFailAtMs) / 1000)}s with no durable evidence`
+              } — treating the runner as dead`);
+            }
+            if (alive === false || deathVerdict !== null) {
               // Dead with no exit line even in the durable file: abnormal
-              // death — surfaces as an error, never a clean done.
+              // death — surfaces as an error, never a clean done. A
+              // provider-attested gone verdict marks the death as the
+              // MACHINE's (sandbox_gone), not the CLI's.
+              if (deathVerdict === "dead-gone") sandboxGoneDeath = true;
               exitCode = JSONL_GUARD_NO_SENTINEL_EXIT;
               break;
             }
@@ -1722,7 +2177,7 @@ export class CliAgentRunner implements ModelExecutionContract {
           while ((nl = buf.indexOf("\n")) >= 0) {
             const line = buf.slice(0, nl).trim();
             buf = buf.slice(nl + 1);
-            if (line) lines.push(line);
+            if (line) lines.push({ line, end: null });
           }
         };
         const runOpts = {
@@ -1734,7 +2189,7 @@ export class CliAgentRunner implements ModelExecutionContract {
           credEnvSourceFragment(this.options.credEnvFile) + guardedCmd, runOpts).then(
           (res) => {
             const tail = buf.trim();
-            if (tail) lines.push(tail);
+            if (tail) lines.push({ line: tail, end: null });
             exitCode = res.exitCode;
             exitStderr = (res.stderr ?? "").slice(-2000);
           },
@@ -1761,7 +2216,16 @@ export class CliAgentRunner implements ModelExecutionContract {
         // when the turn never reaches its `done` (a reaped/superseded turn
         // must still be resumable by its redispatch).
         let announcedSessionId = opts.sessionId ?? "";
-        for await (const line of lines) {
+        for await (const item of lines) {
+          // Consumed-offset bookkeeping (boot-time turn adoption): pulling
+          // line N proves lines 1..N-1 are FULLY yielded, so the byte
+          // offset just past line N-1 is the safe harvest watermark — see
+          // `currentTurnDurableOffset` in types/runtime.ts.
+          if (item.end !== null) {
+            this.turnConsumedOffset = this.turnPendingLineEnd;
+            this.turnPendingLineEnd = item.end;
+          }
+          const line = item.line;
           let parsed: Record<string, unknown>;
           try {
             parsed = JSON.parse(line) as Record<string, unknown>;
@@ -1781,6 +2245,9 @@ export class CliAgentRunner implements ModelExecutionContract {
         }
 
         await transport;
+        // Stream fully consumed — the final line's messages are all
+        // yielded, so its end offset graduates to the safe watermark.
+        this.turnConsumedOffset = this.turnPendingLineEnd;
         if (transportError) throw transportError;
         if (exitCode === null) {
           // Aborted/reaped before an exit line existed — honest terminal,
@@ -1792,7 +2259,15 @@ export class CliAgentRunner implements ModelExecutionContract {
         }
         if (exitCode !== 0 && !sawError) {
           const detail = exitCode === JSONL_GUARD_NO_SENTINEL_EXIT
-            ? " (the runner died without reporting an exit code)" : "";
+            ? sandboxGoneDeath
+              // The classifier's sandbox_gone vocabulary, verbatim on
+              // purpose (turn-failure-class.ts:"machine went away" /
+              // "sandbox gone") — this is what routes the settle to the
+              // machine-loss auto-continue lane instead of the
+              // evidence-gated runner_exit family.
+              ? " (the machine went away mid-turn — the provider reports the sandbox gone)"
+              : " (the runner died without reporting an exit code)"
+            : "";
           yield { type: "error", text: `${this.spec.kind} exited with code ${exitCode}${detail}${exitStderr ? `: ${exitStderr}` : ""}`, timestamp: now() };
           return;
         }