@agent-compose/sdk 0.8.2 → 0.8.3

package/src/runtimes/_cli-agent.ts

@@ -24,9 +24,15 @@
  * values set via `agentc secrets set` are visible to the CLI.
  */
 
-import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";
+import type { AgentMessage, ModelExecutionContract, RunnerLivenessVerdict, RuntimeOptions, SandboxProvider, ToolCallGateResult, TurnExitNotify } from "../index.js";
 import { defineRuntime } from "../types/runtime.js";
 import { AsyncQueue } from "../agent/async-queue.js";
+// Function-only cycle with perf-sampler.ts (it imports `shellQuote` from
+// here) — safe: both sides are hoisted declarations used at call time.
+import {
+  parsePerfToken, perfSamplerFunctionFragment, PERF_TOKEN_MAX_CHARS,
+} from "../agent/perf-sampler.js";
+import type { GuestPerfSample } from "../agent/perf-sampler.js";
 import { formatError } from "../utils/errors.js";
 import { ndJsonStream, type Stream } from "@agentclientprotocol/sdk";
 import { runProcessorChain } from "../processors/runner.js";
@@ -48,6 +54,385 @@ function now(): string { return new Date().toISOString(); }
  *  this loop — bounds a truly dead sandbox. Exported for tests. */
 export const TAIL_REATTACH_DELAY_MS = 2_000;
 
+// ── Durable-truth liveness (2026-08-15 incident, turn 18dc5261) ─────────────
+// DURABLE STATE IS THE ONLY TRUTH; STREAMS ARE A LATENCY OPTIMIZATION.
+// The incident: the attached tail's connect-web stream wedged SILENTLY —
+// `wait()` never settled, no error, no EOF — while the runner finished its
+// answer into the durable file (full transcript + exit sentinel on disk at
+// +87s). Every recovery arm lived AFTER `await handle.wait()`, so the
+// transport was blind forever; the finished turn sat unharvested for ten
+// minutes until the next dispatch superseded it. The pieces below make the
+// durable plane authoritative:
+//   - the detached runner writes a HEARTBEAT file (epoch ms, every ~10s,
+//     from a subshell inside the setsid session that self-terminates with
+//     the wrapper) next to the stdout/pid/sentinel files;
+//   - an attached tail is WATCHED, never trusted: a fixed-cadence probe (one
+//     fresh short exec) reads the durable trio, and durable bytes the stream
+//     failed to deliver across a full interval prove the stream dead — kill
+//     the tail (never the runner) and catch up from the byte offset;
+//   - `probeTurnLiveness` serves the same durable reading to the executor's
+//     evidence ticker as a three-valued verdict (alive / dead /
+//     probe-failed), replacing process-grep guesswork.
+
+/** Cadence of the in-guest heartbeat writer (seconds — it is a shell loop). */
+export const RUNNER_HEARTBEAT_INTERVAL_SECONDS = 10;
+/** How recently a file under the CLI's own task state dir (~/.claude/tasks)
+ *  must have been touched to count as a LIVE background task in the busy
+ *  sentinel (minutes — it is `find -mmin`). A running task's state/output
+ *  files are written continuously, so two minutes is generous; a finished
+ *  task's files go quiet and age out on their own. */
+export const RUNNER_BUSY_TASK_FRESH_MINUTES = 2;
+/** Cap on the task-id list the busy sentinel publishes — the ids are for
+ *  server-side log attribution, not an inventory. */
+export const RUNNER_BUSY_TASK_ID_LIMIT = 16;
+/** The sh fragment the heartbeat subshell runs each beat to maintain the
+ *  busy sentinel — the guest half of the background-work marker contract:
+ *    - `<promptPath>.busy`  — the COUNT of recently-active files under the
+ *      CLI's task state dir (`$ac_busy` stays set in-shell for the loop's
+ *      own exit decision);
+ *    - `<promptPath>.tasks` — the task IDS those files belong to (first
+ *      path segment under tasks/, deduped, capped).
+ *  The marker's freshness stamp is the files' own mtime (each beat rewrites
+ *  them; the server probe gates on `-mmin -1`). Cheap (one bounded find
+ *  over a small dir), and read by the server's park path so a VM hosting
+ *  live background work is never frozen mid-flight (2026-08-15 forensics:
+ *  a 3-min idle park suspended a VM with three research agents mid-flight).
+ *  A missing tasks dir counts 0. Exported for tests. */
+export function runnerBusySentinelFragment(busyPath: string, tasksPath: string): string {
+  return `ac_task_files=$(find "$HOME/.claude/tasks" -type f -mmin -${RUNNER_BUSY_TASK_FRESH_MINUTES} 2>/dev/null); `
+    + `if [ -n "$ac_task_files" ]; then ac_busy=$(printf '%s\\n' "$ac_task_files" | wc -l | tr -cd 0-9); else ac_busy=0; fi; `
+    + `printf '%s' "$ac_busy" > ${shellQuote(busyPath)} 2>/dev/null; `
+    + `printf '%s\\n' "$ac_task_files" | sed 's|.*/tasks/||; s|/.*||' | grep . | sort -u `
+    + `| head -${RUNNER_BUSY_TASK_ID_LIMIT} > ${shellQuote(tasksPath)} 2>/dev/null`;
+}
+/** A heartbeat older than this (by the GUEST's own clock — the probe reads
+ *  `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;
+/** 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;
+/** Explicit ceiling on one durable-trio probe exec. A probe that can't
+ *  answer is "probe-failed" — never a verdict. */
+export const TURN_PROBE_TIMEOUT_MS = 10_000;
+/** After this many stream deaths in ONE turn, stop re-attaching tails and
+ *  finish the turn on durable-file polling alone (the GHA permanent-
+ *  fallback pattern): a wire that killed three streams will kill the
+ *  fourth, and the durable plane already delivers everything. */
+export const TAIL_ABANDON_AFTER_STREAM_DEATHS = 3;
+/** Poll cadence once streaming is abandoned — a full durable read per poll
+ *  (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;
+
+/** One durable-trio reading, parsed from the probe exec's single line. */
+export interface TurnProbeReading {
+  /** Bytes currently in the durable stdout file (-1: unreadable/absent). */
+  size: number;
+  /** Is the detached runner's process group leader alive (kill -0)? */
+  alive: boolean;
+  /** Last heartbeat value (epoch ms, guest clock; 0 = no heartbeat yet). */
+  hbMs: number;
+  /** The guest's own clock at probe time (epoch ms). */
+  nowMs: number;
+  /** Is the exit sentinel already in the durable file (turn FINISHED)? */
+  sentinelSeen: boolean;
+  /** Latest guest perf sample (the trailing `.perf` token field), when the
+   *  guest wrote one AND it parsed clean. Absent = older guest image, no
+   *  sample yet, or a garbled token — evidence-absent, never an error.
+   *  Telemetry-only: no liveness verdict may ever read it. */
+  perf?: GuestPerfSample;
+}
+
+/** The probe exec: one line, six fields, always exit 0 — faults surface as
+ *  parse failures, not exec failures. Reads the guest's own clock in the
+ *  same exec so staleness math never involves the host clock. The sixth
+ *  field is the perf token (perf-sampler.ts), `-` when absent; the char
+ *  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 },
+): string {
+  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:--}"`;
+}
+
+/** Parse the probe's line. Null = unusable output (a wedged or faulted exec)
+ *  — the caller treats that as "probe-failed", never as a verdict. The
+ *  sixth field (perf token) is OPTIONAL both ways: a five-field line from
+ *  an old guest parses fine, and a token that fails its own clamp simply
+ *  leaves `perf` absent — perf can never fail a liveness reading. */
+export function parseTurnProbeOutput(raw: string): TurnProbeReading | null {
+  const fields = raw.trim().split(/\s+/);
+  if (fields.length < 5) return null;
+  const size = Number.parseInt(fields[0]!, 10);
+  const alive = fields[1] === "1" ? true : fields[1] === "0" ? false : null;
+  const hbMs = Number.parseInt(fields[2]!, 10);
+  const nowMs = Number.parseInt(fields[3]!, 10);
+  const sentinelCount = Number.parseInt(fields[4]!, 10);
+  if (!Number.isFinite(size) || alive === null || !Number.isFinite(hbMs)
+    || !Number.isFinite(nowMs) || !Number.isFinite(sentinelCount)) return null;
+  const perfTok = fields[5];
+  const perf = perfTok !== undefined && perfTok !== "-" ? parsePerfToken(perfTok) : null;
+  return {
+    size, alive, hbMs, nowMs, sentinelSeen: sentinelCount > 0,
+    ...(perf ? { perf } : {}),
+  };
+}
+
+/** The three-valued verdict from one durable reading. A FINISHED turn
+ *  (sentinel durable in the file) is ALIVE — the transport's watchdog
+ *  harvests it within one interval; reporting it dead is exactly the
+ *  incident's ten-minute blindness. */
+export function livenessVerdictFromReading(reading: TurnProbeReading | null): RunnerLivenessVerdict {
+  if (reading === null) return "probe-failed";
+  if (reading.alive) return "alive";
+  if (reading.sentinelSeen) return "alive";
+  if (reading.hbMs > 0 && reading.nowMs - reading.hbMs <= RUNNER_HEARTBEAT_STALE_MS) return "alive";
+  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.
+
+/** Feeder poll cadence (seconds — it is a shell `sleep`; GNU sleep accepts
+ *  fractions and the durable transport only runs on the GNU guest image). */
+export const INJECT_FEEDER_POLL_SECONDS = "0.3";
+/** How much of the durable stdout tail the feeder greps for the terminal
+ *  result line each poll — bounded so a long transcript never turns the
+ *  poll into a full-file scan. Comfortably above the JSONL guard's line cap,
+ *  so a capped result line still fits whole. */
+export const INJECT_FEEDER_RESULT_TAIL_BYTES = 262_144;
+/** One in-guest delivery-ack exec: append the line, then poll the delivered
+ *  counter until it covers this append (delivered), the runner dies, or the
+ *  attempts run out (both: not delivered — the message stays owed). */
+export const INJECT_ACK_POLL_ATTEMPTS = 30;
+export const INJECT_ACK_POLL_SECONDS = "0.5";
+export const INJECT_ACK_EXEC_TIMEOUT_MS = 25_000;
+
+/** 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. */
+export function streamInputFeederFragment(paths: {
+  promptPath: string; fifoPath: string; inboxPath: string;
+  deliveredPath: string; outPath: string;
+}): string {
+  const q = shellQuote;
+  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; `
+    + `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; `
+    + `sleep ${INJECT_FEEDER_POLL_SECONDS}; done ) > ${q(paths.fifoPath)} 2>/dev/null </dev/null & `;
+}
+
+/** 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. */
+export function injectAppendAndAckCommand(args: {
+  line: string; target: number; pid: number;
+  inboxPath: string; deliveredPath: string;
+}): string {
+  const q = shellQuote;
+  return `printf '%s\\n' ${q(args.line)} >> ${q(args.inboxPath)}; i=0; `
+    + `while [ "$i" -lt ${INJECT_ACK_POLL_ATTEMPTS} ]; do `
+    + `d=$(cat ${q(args.deliveredPath)} 2>/dev/null || echo 0); `
+    + `[ "\${d:-0}" -ge ${args.target} ] && exit 0; `
+    + `kill -0 ${args.pid} 2>/dev/null || exit 4; `
+    + `sleep ${INJECT_ACK_POLL_SECONDS}; i=$((i+1)); done; exit 5`;
+}
+
+// ── 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`)
+// for exactly as long as the process lives; the old fire-and-forget SIGTERM
+// gave a slow-dying (or TERM-handling) CLI no deadline and never escalated,
+// so a canceled turn could leave the writer alive — and the NEXT turn's
+// `codex exec resume` died with `thread-store conflict: … already has an
+// active writer`. The reap is now ONE guest exec that TERMs the detached
+// group, waits bounded for the group leader to exit, escalates to SIGKILL,
+// and confirms — and the transport AWAITS that confirmation in its unwind
+// path, so the generator (and the executor's turn settle behind it) never
+// completes while the guest tree may still be running.
+
+/** SIGTERM grace before escalation: attempts × sleep = 5s. */
+export const REAP_TERM_WAIT_ATTEMPTS = 20;
+/** Post-SIGKILL confirm window: attempts × sleep = 2s (a KILLed process only
+ *  lingers as an unreaped zombie, which `kill -0` still sees — brief). */
+export const REAP_KILL_WAIT_ATTEMPTS = 8;
+export const REAP_POLL_SECONDS = "0.25";
+/** The confirm exec's "still alive after SIGKILL" exit code (surfaced as a
+ *  warn — the launch preflight is the backstop for whatever survived). */
+export const REAP_STILL_ALIVE_EXIT = 7;
+/** Ceiling on the whole kill-and-confirm exec (TERM 5s + KILL 2s + slack). */
+export const REAP_EXEC_TIMEOUT_MS = 15_000;
+
+/** The one kill-and-confirm exec: TERM the group (setsid made `pid` the
+ *  leader) and the leader itself, poll for exit, escalate to KILL, poll
+ *  again. Exit 0 = confirmed dead; REAP_STILL_ALIVE_EXIT = it survived
+ *  SIGKILL's confirm window. Exported for tests. */
+export function reapKillAndConfirmCommand(pid: number): string {
+  const alive = `kill -0 ${pid} 2>/dev/null`;
+  return `kill -TERM -- -${pid} 2>/dev/null; kill -TERM ${pid} 2>/dev/null; ac_ri=0; `
+    + `while [ "$ac_ri" -lt ${REAP_TERM_WAIT_ATTEMPTS} ]; do ${alive} || exit 0; `
+    + `sleep ${REAP_POLL_SECONDS}; ac_ri=$((ac_ri+1)); done; `
+    + `kill -KILL -- -${pid} 2>/dev/null; kill -KILL ${pid} 2>/dev/null; ac_ri=0; `
+    + `while [ "$ac_ri" -lt ${REAP_KILL_WAIT_ATTEMPTS} ]; do ${alive} || exit 0; `
+    + `sleep ${REAP_POLL_SECONDS}; ac_ri=$((ac_ri+1)); done; `
+    + `exit ${REAP_STILL_ALIVE_EXIT}`;
+}
+
+// ── Resident harness (docs/specs/resident-harness-turns.md, P1) ─────────────
+// A RESIDENT keeps one live CLI process serving consecutive turns inside the
+// hot window: the feeder's result-break is replaced by an END-FILE break
+// (`<prompt>.end` → close the FIFO → the CLI EOFs stdin and exits with a
+// 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
+//                           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.
+
+/** 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
+ *  watchdog only answers a dead server / lost record. */
+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"';
+
+/** 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
+ *  count (a missing file reads as 0). Hint-grade by design. */
+export function residentResultCountCommand(outPath: string, fromByte = 0): string {
+  const q = shellQuote;
+  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}"`;
+}
+
+/** 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`). */
+export function residentFeederFragment(paths: {
+  promptPath: string; fifoPath: string; inboxPath: string;
+  deliveredPath: string; endPath: 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 `
+    + `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; `
+    + `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. */
+export function residentIdleCheckFragment(paths: {
+  outPath: string; inboxPath: string; deliveredPath: 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}; `
+    + `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; `;
+}
+
+/** Guest idle watchdog: reap the whole process group after
+ *  RESIDENT_IDLE_TTL_S of CONTINUOUS idleness (any busy reading resets the
+ *  clock — a long-running TURN is never reaped; the parity check reads
+ *  busy mid-turn). The park gate's graceful `.end` normally wins; this is
+ *  the orphan backstop for a dead server or a lost durable record.
+ *
+ *  BACKGROUND TASKS ARE NOT IDLE (2026-08-19 forensics: a user's
+ *  between-turns background search died to a harness teardown while its
+ *  journal was still advancing). The turn-parity predicate alone reads a
+ *  resident BETWEEN turns as idle even while harness background tasks it
+ *  tracks are hard at work — and this watchdog's group-kill would take
+ *  those children with the tree. So idle additionally requires the CLI's
+ *  own task journal (`$HOME/.claude/tasks`) to be QUIET: any file touched
+ *  within RUNNER_BUSY_TASK_FRESH_MINUTES resets the clock — the exact
+ *  journal-freshness license the server's park gate honors
+ *  (guestBusyProbeCommand). A stalled task goes stale within the window
+ *  and the TTL resumes on its own; liveness alone never counts (the
+ *  2026-08-17 wake-loop damper is a SERVER rule about waking — this is a
+ *  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;
+}): string {
+  return `( ac_idle_s=0; while kill -0 "$$" 2>/dev/null; do `
+    + residentIdleCheckFragment(paths)
+    + `if [ "$ac_idle" = 1 ] && find "$HOME/.claude/tasks" -type f -mmin -${RUNNER_BUSY_TASK_FRESH_MINUTES} 2>/dev/null | grep -q .; then ac_idle=0; fi; `
+    + `if [ "$ac_idle" = 1 ]; then ac_idle_s=$((ac_idle_s+${RESIDENT_WATCHDOG_POLL_S})); else ac_idle_s=0; fi; `
+    + `if [ "$ac_idle_s" -ge ${RESIDENT_IDLE_TTL_S} ]; then kill -- -$$ 2>/dev/null; exit 0; fi; `
+    + `sleep ${RESIDENT_WATCHDOG_POLL_S}; done ) >/dev/null 2>&1 </dev/null & `;
+}
+
+/** Exit-event doorbell with the turnId read from a guest FILE at push time
+ *  (a resident serves many turns; each adoption rewrites `<prompt>.turnid`
+ *  so a mid-turn death rings the turn actually being served). Same
+ *  validation posture as `exitEventPushCommand`; an empty turnid file
+ *  pushes nothing. */
+export function deferredExitEventPushCommand(
+  notify: { url: string; tokenEnv: string }, turnIdFile: string,
+): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(notify.tokenEnv)) return "";
+  const q = shellQuote;
+  return `( ac_tid=$(cat ${q(turnIdFile)} 2>/dev/null | tr -cd 'A-Za-z0-9-'); `
+    + `if [ -n "$ac_tid" ] && [ -n "$${notify.tokenEnv}" ] && command -v curl >/dev/null 2>&1; then `
+    + `curl -fsS -m ${EXIT_PUSH_ATTEMPT_TIMEOUT_SECONDS} -o /dev/null -X POST `
+    + `-H "Authorization: Bearer $${notify.tokenEnv}" `
+    + `-H 'Content-Type: application/json' --data "{\\"turnId\\":\\"$ac_tid\\",\\"exitCode\\":$ac_rc}" ${q(notify.url)}; `
+    + `fi ) >/dev/null 2>&1 || true`;
+}
+
 /** Provider deadline on the detached LAUNCH exec. The launch shell only
  *  truncates the durable files, forks the detached runner (stdio fully
  *  redirected — see the launch command), writes the pidfile, and echoes the
@@ -71,6 +456,13 @@ export const LAUNCH_PID_RECOVERY_DELAY_MS = 1_000;
  *  decide a turn's fate. Exported for tests. */
 export const INSTALL_PROBE_TIMEOUT_MS = 30_000;
 
+/** Deadline on the on-demand CLI install itself (`spec.install`). Shared by
+ *  this transport's ensureInstalled and the server's CloudTurnWorkflow launch
+ *  path (turn-workflow/tailer.ts), which provisions the same way before a
+ *  detached launch — the session images bake only `claude`, so codex/
+ *  opencode/cursor/droid MUST be installable at launch on a fresh machine. */
+export const CLI_INSTALL_TIMEOUT_MS = 300_000;
+
 /** Parse a pid out of captured stdout (last non-empty line). NaN when absent. */
 function parsePid(raw: string): number {
   const pid = Number.parseInt(raw.trim().split("\n").pop() ?? "", 10);
@@ -99,6 +491,80 @@ export function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+// ── Session env file (session secrets) ──────────────────────────────────────
+
+/** $HOME-relative path of the platform-managed session env file. The server
+ *  writes it at sandbox acquire (session secrets → `export KEY='…'` lines);
+ *  the detached turn launch sources it fresh EVERY turn, so a secret set or
+ *  rotated between turns lands on the next turn with no VM recycle. Shared
+ *  constant so the writer (server) and the reader (this runtime) can never
+ *  drift. */
+export const SESSION_ENV_FILE_RELPATH = ".agent-compose/session-env.sh";
+
+/** Only plain relative paths make it into the script — no quotes/spaces/`..`
+ *  (a malformed option must not break the launch or escape $HOME). */
+const SESSION_ENV_FILE_SAFE = /^[A-Za-z0-9._\/-]+$/;
+
+/** The `. $HOME/<file>;` fragment sourced ahead of the CLI command, or ""
+ *  when no env file is configured. Errors are swallowed — a missing or
+ *  unreadable file must never fail a turn. */
+export function sessionEnvSourceFragment(relPath: string | undefined): string {
+  if (!relPath || !SESSION_ENV_FILE_SAFE.test(relPath) || relPath.includes("..")) return "";
+  return `[ -f "$HOME/${relPath}" ] && . "$HOME/${relPath}" >/dev/null 2>&1 || true; `;
+}
+
+/** 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.
+ *  Same swallow-errors posture: a missing file must never fail a turn. */
+export function credEnvSourceFragment(absPath: string | undefined): string {
+  if (!absPath || !absPath.startsWith("/") || !SESSION_ENV_FILE_SAFE.test(absPath.slice(1))
+    || absPath.includes("..")) return "";
+  return `[ -f "${absPath}" ] && . "${absPath}" >/dev/null 2>&1 || true; `;
+}
+
+// ── Exit-event push (the completion doorbell, v0.10.43) ─────────────────────
+// THE PUSH IS A DOORBELL, NEVER A VERDICT. The detached wrapper announces
+// {turnId, exitCode} to the server with ONE best-effort POST immediately
+// AFTER the exit sentinel is durably written, so the server's watchdog can
+// run its verification pass at event latency (~1-2s) instead of its poll
+// cadence. The durable file stays the only truth: a lost push costs nothing
+// (the poll ladder is the unchanged backstop), and the server treats every
+// push as "go verify the durable state now", never as an outcome.
+
+/** Ceiling on ONE curl attempt (seconds — it is `curl -m`). Short: the file
+ *  is the truth and a slow push must not keep the wrapper alive for long. */
+export const EXIT_PUSH_ATTEMPT_TIMEOUT_SECONDS = 5;
+/** Pause before the single retry. */
+export const EXIT_PUSH_RETRY_DELAY_SECONDS = 1;
+
+/**
+ * The sh fragment appended to the detached wrapper AFTER the sentinel
+ * `printf` — never before it, and never in a way that can fail the wrapper:
+ *   - reads the credential from the guest env at push time (`$<tokenEnv>`;
+ *     the token never appears in the script text, argv-visible command
+ *     lines the server logs, or any log line);
+ *   - silently skips when the credential or curl is absent;
+ *   - two attempts max (`-m 5`, one retry after 1s), then gives up silently
+ *     — all output discarded, exit status swallowed (`|| true`).
+ * `$ac_rc` is the wrapper-local capture of the guarded pipeline's exit code
+ * (the same value the sentinel line carries). Returns "" — push disabled —
+ * for any `tokenEnv`/`turnId` that is not a plain identifier/uuid shape, so
+ * hostile config can never become shell injection.
+ */
+export function exitEventPushCommand(notify: TurnExitNotify): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(notify.tokenEnv)) return "";
+  if (!/^[A-Za-z0-9-]{1,64}$/.test(notify.turnId)) return "";
+  const token = `"$${notify.tokenEnv}"`;
+  const body = `"{\\"turnId\\":\\"${notify.turnId}\\",\\"exitCode\\":$ac_rc}"`;
+  const attempt = `curl -fsS -m ${EXIT_PUSH_ATTEMPT_TIMEOUT_SECONDS} -o /dev/null -X POST`
+    + ` -H "Authorization: Bearer $${notify.tokenEnv}"`
+    + ` -H 'Content-Type: application/json' --data ${body} ${shellQuote(notify.url)}`;
+  return `( if [ -n ${token} ] && command -v curl >/dev/null 2>&1; then `
+    + `${attempt} || { sleep ${EXIT_PUSH_RETRY_DELAY_SECONDS}; ${attempt}; }; `
+    + `fi ) >/dev/null 2>&1 || true`;
+}
+
 /** Monotonic discriminator for prompt-file names within this process. */
 let promptFileCounter = 0;
 
@@ -208,8 +674,12 @@ export interface CliAgentSpec {
   /** Build the one-shot shell command for a turn. `promptPath` is a file in the
    *  sandbox holding `promptPayload(prompt)`; `sessionId` continues a thread.
    *  `effort` is present only when the caller configured a reasoning effort
-   *  AND the spec has a real knob for it (see `CliReasoningEffort`). */
-  buildCommand(args: { promptPath: string; sessionId?: string; model?: string; cwd?: string; effort?: CliReasoningEffort }): string;
+   *  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`). */
+  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 +
    *  usage (text / thinking / tool_use / tool_result / usage).
@@ -223,12 +693,43 @@ export interface CliAgentSpec {
    *  resume it (codex `thread.started.thread_id`, amp `session_id`).
    *  LEGACY FALLBACK PATH (see `mapEvent`). */
   extractSessionId(parsed: Record<string, unknown>): string | undefined;
+  /** The runtime's thread persistence admits only ONE live writer per thread
+   *  (codex: an OS advisory flock per thread id, held for the holding
+   *  process's whole lifetime — codex-rs thread-store writer_lock.rs). A
+   *  platform that wants a SUCCESSOR turn to resume the same thread must
+   *  therefore KILL the predecessor's process tree first — a merely-detached
+   *  live predecessor blocks every `thread/resume` with "already has an
+   *  active writer" (the 2026-08-22 superseded-codex-turn incident). Absent
+   *  ⇒ concurrent resume is safe (claude-code: append-only session JSONL)
+   *  and a superseded runner may be detached alive as an asset. */
+  exclusiveSessionWriter?: boolean;
   /** ACP-mode invocation (the Zed `agent_servers` shape). When present, the
    *  runner spawns the CLI in ACP agent mode and delegates the whole wire
    *  protocol to `AcpClientPeer`; the legacy `promptPayload`/`buildCommand`/
    *  `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;
+  };
 }
 
 /** A spawned ACP-mode CLI: the read side of its stdout and a delivery for its
@@ -294,6 +795,108 @@ export class CliAgentRunner implements ModelExecutionContract {
    *  dormant. Not a public API. */
   private acpTransportReady = ACP_TRANSPORT_READY;
 
+  /** The CURRENT turn's durable-trio reader (set once the detached runner is
+   *  launched, replaced by the next launch). Null = no durable transport is
+   *  active for this runner (boot phase, ACP path, single-exec providers) —
+   *  `probeTurnLiveness` then answers null and the executor keeps its own
+   *  fallback probe. */
+  private turnProbe: (() => Promise<TurnProbeReading | null>) | null = null;
+
+  /** The CURRENT turn's mid-turn injection state (durable stream-input
+   *  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;
+
+  /** 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"> {
+    const inject = this.turnInject;
+    const streamInput = this.spec.streamInput;
+    if (!inject || !streamInput || this.guestDetached) return "unsupported";
+    const line = streamInput.messageLine(text);
+    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
+      // counter advances unconditionally: a later injection must never aim
+      // at a line number the feeder has already passed.
+      const target = inject.appended + 1;
+      inject.appended = target;
+      try {
+        const res = await this.sandbox.commands.run(
+          injectAppendAndAckCommand({
+            line, target, pid: inject.pid,
+            inboxPath: inject.inboxPath, deliveredPath: inject.deliveredPath,
+          }),
+          { 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).
+        // 4 = the runner died first; anything else is a fault — both closed.
+        return res.exitCode === 5 ? "pending" : "closed";
+      } catch { return "closed"; }
+    });
+    inject.chain = attempt.catch(() => undefined);
+    return attempt;
+  }
+
+  /** 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());
+  }
+
+  /** Wakes the CURRENT tail-watchdog interval early. Armed only while the
+   *  watchdog's wake timer is pending; null between arms / between turns. */
+  private wakeTailWatchdog: (() => void) | null = null;
+  /** A doorbell that rang while no watchdog wake was armed — consumed at the
+   *  next arm (immediate wake), dropped at the start of a new turn. */
+  private nudgePending = false;
+
+  /** DOORBELL, NEVER A VERDICT (contract doc: types/runtime.ts). Wake the
+   *  tail watchdog NOW so its normal verification pass — durable probe, then
+   *  harvest-on-sentinel / honest no-sentinel death — runs immediately
+   *  instead of at the next TAIL_WATCHDOG_INTERVAL_MS tick. Carries no
+   *  information: a nudge for a live mid-turn runner probes alive and is a
+   *  no-op; a spurious/duplicate nudge costs at most one probe exec. No-op
+   *  when no durable watchdog is armed (boot phase, ACP path, single-exec
+   *  transports, abandoned-streaming polling) — those phases already carry
+   *  their own bounds. */
+  nudgeTurnProbe(): void {
+    const wake = this.wakeTailWatchdog;
+    if (wake) {
+      this.wakeTailWatchdog = null;
+      wake();
+    } else {
+      this.nudgePending = true;
+    }
+  }
+
+  /** RESUME HANDOFF, NEVER A KILL (contract doc: types/runtime.ts). Once
+   *  set, abort/early-exit unwinds the transport WITHOUT reaping the
+   *  detached guest tree and WITHOUT the opportunistic durable-file cleanup
+   *  — the successor turn resumes the same guest session, and the park
+   *  path's busy signal keeps reading the surviving heartbeat/busy files.
+   *  One-way for this runner instance (a runner is per-turn on the cloud
+   *  path). */
+  private guestDetached = false;
+
+  detachGuest(): void {
+    this.guestDetached = true;
+  }
+
   constructor(
     private readonly sandbox: SandboxProvider,
     private readonly options: RuntimeOptions,
@@ -358,7 +961,7 @@ export class CliAgentRunner implements ModelExecutionContract {
     const probe = await this.sandbox.commands.run(
       `command -v ${this.spec.bin}`, { timeoutMs: INSTALL_PROBE_TIMEOUT_MS });
     if (probe.exitCode === 0) { this.installed = true; return; }
-    const res = await this.sandbox.commands.run(this.spec.install, { timeoutMs: 300_000 });
+    const res = await this.sandbox.commands.run(this.spec.install, { timeoutMs: CLI_INSTALL_TIMEOUT_MS });
     if (res.exitCode !== 0) {
       throw new Error(`failed to install ${this.spec.bin}: ${(res.stderr || res.stdout || "").slice(-500)}`);
     }
@@ -662,13 +1265,33 @@ export class CliAgentRunner implements ModelExecutionContract {
       await this.ensureInstalled();
 
       const promptPath = uniquePromptPath(this.spec.kind, this.options.agentId ?? "agent", opts.iteration ?? 0);
-      await this.sandbox.files.write(promptPath, this.spec.promptPayload(opts.prompt));
+      // A NEW turn invalidates any previous turn's durable probe — re-armed
+      // below once (and only if) this turn's detached runner launches. A
+      // stale doorbell is dropped with it: a new turn owes nothing to the
+      // previous turn's push.
+      this.turnProbe = null;
+      this.turnInject = 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;
+      const fifoPath = `${promptPath}.fifo`;
+      const promptWrite = this.sandbox.files.write(promptPath, streamInput
+        ? `${this.spec.streamInput!.promptLine(opts.prompt)}\n`
+        : this.spec.promptPayload(opts.prompt));
       const cmd = this.spec.buildCommand({
-        promptPath,
+        // 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,
         sessionId: opts.sessionId,
         model: this.model,
         cwd: this.options.cwd,
         effort: this.configEffort,
+        ...(streamInput ? { streamInput: true } : {}),
       });
 
       // Frame guard (see _jsonl-guard.ts): the CLI's stdout is piped through
@@ -687,7 +1310,11 @@ export class CliAgentRunner implements ModelExecutionContract {
       // uniquePromptPath) and the same opportunistic cleanup below.
       const guardPath = `${promptPath}.guard.js`;
       const sentinel = `__AC_JSONL_EXIT_${Math.random().toString(36).slice(2, 10)}__`;
-      await this.sandbox.files.write(guardPath, jsonlGuardScript());
+      // Both file-transport writes ride in parallel: each is a full envd
+      // HTTP round trip (~65ms measured against E2B from the dev host), and
+      // they are independent — the launch below is the only consumer of
+      // either path. One RTT shaved off every turn's first-token path.
+      await Promise.all([promptWrite, this.sandbox.files.write(guardPath, jsonlGuardScript())]);
       const guardedCmd = wrapJsonlCommand({
         cmd, guardPath, sentinel,
         maxBytes: JSONL_GUARD_LINE_CAP_BYTES,
@@ -723,6 +1350,10 @@ export class CliAgentRunner implements ModelExecutionContract {
       let transportError: unknown = null;
       let consumerStopped = false;
       let reap: () => void = () => { /* set per transport */ };
+      // The reap's kill-and-confirm exec, latched on first fire (reap runs
+      // from BOTH the abort listener and the finally — one exec, not two).
+      // The unwind awaits it so the turn never settles over a live tree.
+      let reapConfirm: Promise<void> | null = null;
       let transport: Promise<void>;
 
       const durableRead = this.sandbox.files.read?.bind(this.sandbox.files);
@@ -735,9 +1366,65 @@ export class CliAgentRunner implements ModelExecutionContract {
         // every server↔sandbox stream is dead by then. In node-guard mode the
         // pipeline's exit code is already the CLI's (the guard re-raises the
         // inner sentinel, including NO_SENTINEL_EXIT for a mid-pipe death).
+        // The heartbeat subshell rides INSIDE the setsid session (group kill
+        // reaps it with the tree). It is keyed to the wrapper sh's own pid
+        // (`$$` — the pidfile pid) and DIES WITH it: heartbeat and busy
+        // marker both stop within one interval of the wrapper exiting (see
+        // the loop comment below for why outliving the wrapper was a bug).
+        // Its writes are the durable "the runner tree is alive" signals the
+        // probes read — signals no server↔sandbox stream can wedge.
+        const hbPath = `${promptPath}.hb`;
+        // Exit-event doorbell (see exitEventPushCommand): SENTINEL FIRST,
+        // PUSH AFTER. The push rides behind the sentinel append so the
+        // durable truth exists before anything is announced, and its whole
+        // failure surface is swallowed — the runner lifecycle cannot see it.
+        const exitPush = this.options.turnExitNotify
+          ? exitEventPushCommand(this.options.turnExitNotify)
+          : "";
+        // Busy sentinel (park-defers-while-busy): each beat also writes the
+        // background-work marker next to the heartbeat — task count
+        // (<prompt>.busy) and task ids (<prompt>.tasks). The server's park
+        // probe reads the task JOURNALS (~/.claude/tasks) directly plus the
+        // heartbeat/pid pair; the marker files are in-guest receipts.
+        //
+        // The subshell DIES WITH the wrapper. It used to outlive it while
+        // fresh task files existed (so a clean turn end would not take the
+        // busy marker down with running background tasks) — but the server
+        // probe stopped reading the marker files (journal mtimes carry the
+        // busy signal), and the lingering subshell kept the setsid GROUP
+        // alive minutes past turn end, which the probe's live-group gating
+        // reads as work: every turn that touched its task list became its
+        // own "background work" and armed a spurious wake (the 2026-08-17
+        // loop). Genuine background children launched by the CLI live in
+        // this same setsid group and keep it alive by THEMSELVES — that,
+        // plus their fresh journals, is the honest busy signal. A
+        // 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
+        // streamInputFeederFragment) rides at the FRONT of the detached
+        // script so the FIFO exists before the CLI opens it as stdin.
+        const inboxPath = `${promptPath}.inbox`;
+        const deliveredPath = `${promptPath}.delivered`;
+        const feeder = streamInput
+          ? streamInputFeederFragment({ promptPath, fifoPath, inboxPath, deliveredPath, outPath })
+          : "";
+        // 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`;
         const detachedScript =
-          `{ ${guardedCmd}; } >> ${shellQuote(outPath)} 2>> ${shellQuote(errPath)} </dev/null; `
-          + `printf '\\n%s %s\\n' ${shellQuote(sentinel)} "$?" >> ${shellQuote(outPath)}`;
+          feeder
+          + `( ${perfSamplerFunctionFragment({ perfPath })}while kill -0 "$$" 2>/dev/null; do `
+          + `date +%s%3N > ${shellQuote(hbPath)}; `
+          + `${runnerBusySentinelFragment(busyPath, tasksPath)}; `
+          + `ac_perf_tick; `
+          + `sleep ${RUNNER_HEARTBEAT_INTERVAL_SECONDS}; done ) >/dev/null 2>&1 </dev/null & `
+          + sessionEnvSourceFragment(this.options.sessionEnvFile)
+          + credEnvSourceFragment(this.options.credEnvFile)
+          + `{ ${guardedCmd}; } >> ${shellQuote(outPath)} 2>> ${shellQuote(errPath)} </dev/null; ac_rc=$?; `
+          + `printf '\\n%s %s\\n' ${shellQuote(sentinel)} "$ac_rc" >> ${shellQuote(outPath)}`
+          + (exitPush ? `; ${exitPush}` : "");
         // `setsid` detaches the runner into its own session/process group so
         // it survives the launch exec ending AND gives `kill -- -pid` a whole
         // tree to terminate. The fallback keeps working where setsid is
@@ -761,7 +1448,7 @@ export class CliAgentRunner implements ModelExecutionContract {
         // below.
         const pidPath = `${promptPath}.pid`;
         const launchCmd =
-          `: > ${shellQuote(outPath)}; : > ${shellQuote(errPath)}; `
+          `: > ${shellQuote(outPath)}; : > ${shellQuote(errPath)}; date +%s%3N > ${shellQuote(hbPath)}; `
           + `if command -v setsid >/dev/null 2>&1; then setsid sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & `
           + `else sh -c ${shellQuote(detachedScript)} >/dev/null 2>&1 </dev/null & fi; `
           + `echo "$!" > ${shellQuote(pidPath)}; echo "$!"`;
@@ -791,6 +1478,24 @@ export class CliAgentRunner implements ModelExecutionContract {
             + `(pid ${pid} via ${pidPath}) — continuing on the durable transport: ${formatError(launchErr)}`);
         }
 
+        // Arm the durable-trio probe for this turn: the watchdog below and the
+        // 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 runTurnProbe = async (): Promise<TurnProbeReading | null> => {
+          try {
+            const res = await this.sandbox.commands.run(probeCmd, { timeoutMs: TURN_PROBE_TIMEOUT_MS });
+            return parseTurnProbeOutput(res.stdout ?? "");
+          } catch { return null; }
+        };
+        this.turnProbe = runTurnProbe;
+        // Arm mid-turn injection now that the detached runner (and its
+        // feeder) exist; cleared with the turn in the finally below.
+        if (streamInput) {
+          this.turnInject = { inboxPath, deliveredPath, pid, appended: 0, chain: Promise.resolve() };
+        }
+
         // Bytes of COMPLETE lines already consumed from outPath — a re-attach
         // tails from here, so a dead stream never duplicates or drops lines.
         let offset = 0;
@@ -808,16 +1513,31 @@ export class CliAgentRunner implements ModelExecutionContract {
         };
 
         reap = () => {
-          // Kill the detached tree (group first — setsid made pid the group
-          // leader), then whatever tail is currently attached. Fresh execs,
-          // deliberately independent of any possibly-dead stream.
-          void this.sandbox.commands.run(
-            `kill -TERM -- -${pid} 2>/dev/null; kill -TERM ${pid} 2>/dev/null; true`,
-            { timeoutMs: 10_000 }).catch(() => { /* best-effort */ });
+          // Kill the detached tree AND CONFIRM it died (group first — setsid
+          // made pid the group leader; TERM → bounded wait → KILL escalation,
+          // see reapKillAndConfirmCommand), then whatever tail is currently
+          // attached. Fresh execs, deliberately independent of any
+          // possibly-dead stream. The confirm promise is latched so the
+          // finally below can await it — the turn must not settle while the
+          // tree may still be alive (it holds e.g. codex's thread-store
+          // writer flock until it actually exits).
+          reapConfirm ??= this.sandbox.commands.run(
+            reapKillAndConfirmCommand(pid), { timeoutMs: REAP_EXEC_TIMEOUT_MS })
+            .then((res) => {
+              if (res.exitCode === REAP_STILL_ALIVE_EXIT) {
+                console.warn(`[cli-agent] ${this.spec.kind} runner ${pid} survived SIGKILL's confirm window `
+                  + "— the next launch's preflight is the backstop");
+              }
+            })
+            .catch(() => { /* best-effort exec — the launch preflight covers a missed kill */ });
           void currentTail?.kill().catch(() => { /* already gone */ });
         };
 
         transport = (async () => {
+          // Stream deaths this turn — past the abandon bound the turn stops
+          // re-attaching tails and finishes on durable polling alone (a wire
+          // that killed three streams will kill the fourth).
+          let streamDeaths = 0;
           while (exitCode === null && !consumerStopped && !opts.signal?.aborted) {
             let buf = "";
             let handle: SandboxBackgroundProcess | null = null;
@@ -830,15 +1550,98 @@ export class CliAgentRunner implements ModelExecutionContract {
                 if (exitCode !== null) { void handle?.kill().catch(() => { /* racing exit */ }); return; }
               }
             };
-            try {
-              handle = await this.sandbox.commands.runBackground!(
-                `tail -c +${offset + 1} -f ${shellQuote(outPath)}`,
-                { timeoutMs: 0, onStdout });
-            } catch { /* attach failed at the wire — durable catch-up below */ }
+            if (streamDeaths < TAIL_ABANDON_AFTER_STREAM_DEATHS) {
+              try {
+                // `-s 0.05` tightens ONLY tail's polling fallback: the guest's
+                // GNU tail (coreutils 9.1, verified on the agent-env image)
+                // follows /tmp via inotify — measured delivery is event-driven
+                // (~46ms p50 write→server, one line per callback, S2 bench
+                // 2026-08-14) — but if inotify were ever unavailable, the
+                // default fallback polls at 1s, which WOULD become the stream's
+                // burstiness. GNU tail accepts fractional seconds; this
+                // transport only runs on providers with runBackground (E2B),
+                // whose image is Debian/GNU — never busybox.
+                handle = await this.sandbox.commands.runBackground!(
+                  `tail -s 0.05 -c +${offset + 1} -f ${shellQuote(outPath)}`,
+                  { timeoutMs: 0, onStdout });
+              } catch { /* attach failed at the wire — durable catch-up below */ }
+            }
             if (handle) {
               if (exitCode !== null) void handle.kill().catch(() => { /* done */ });
               currentTail = handle;
-              await handle.wait().catch(() => undefined);
+              // ── The watchdog: never TRUST an attached stream ─────────────
+              // (2026-08-15 incident, turn 18dc5261: the tail's connect-web
+              // stream wedged silently — wait() never settled, no error, no
+              // EOF — while the finished answer + exit sentinel sat in the
+              // durable file for ten minutes.) wait() is raced against a
+              // fixed-cadence durable probe; the probe's DURABLE reading —
+              // never the stream's health — decides:
+              //   - bytes in the file the stream failed to deliver across a
+              //     full interval (offset frozen since the previous tick)
+              //     prove the stream dead → kill the TAIL (never the runner)
+              //     and fall through to the durable catch-up + re-attach;
+              //   - runner process gone → nothing more will be written: kill
+              //     the tail and let the catch-up read the sentinel (or
+              //     surface the honest no-sentinel death);
+              //   - probe fault/timeout → NO verdict: keep streaming (the
+              //     executor's evidence machinery bounds an unreachable
+              //     sandbox, not this loop);
+              //   - abort/consumer-stop wakes the race immediately, so a
+              //     wedged wait() can no longer leak the whole transport.
+              await (async (tail: SandboxBackgroundProcess): Promise<void> => {
+                let waitSettled = false;
+                const waitP = tail.wait().catch(() => undefined)
+                  .then(() => { waitSettled = true; });
+                let lastTickOffset = -1;
+                while (!waitSettled) {
+                  let onAbort: (() => void) | undefined;
+                  const wake = new Promise<void>((resolve) => {
+                    const t = setTimeout(resolve, TAIL_WATCHDOG_INTERVAL_MS);
+                    (t as { unref?: () => void }).unref?.();
+                    const fire = () => { clearTimeout(t); resolve(); };
+                    // Exit-event doorbell (nudgeTurnProbe): a nudge wakes
+                    // THIS interval immediately — its only effect is running
+                    // the durable probe below NOW. One that rang while no
+                    // wake was armed is consumed here.
+                    if (this.nudgePending) {
+                      this.nudgePending = false;
+                      fire();
+                    } else {
+                      this.wakeTailWatchdog = fire;
+                    }
+                    if (opts.signal) {
+                      onAbort = fire;
+                      opts.signal.addEventListener("abort", onAbort, { once: true });
+                    }
+                  });
+                  await Promise.race([waitP, wake]);
+                  this.wakeTailWatchdog = null;
+                  if (onAbort) opts.signal?.removeEventListener("abort", onAbort);
+                  if (waitSettled || exitCode !== null || consumerStopped || opts.signal?.aborted) return;
+                  const tickOffset = offset;
+                  const reading = await runTurnProbe();
+                  if (offset !== tickOffset) { lastTickOffset = offset; continue; }  // stream delivered meanwhile — healthy
+                  if (reading === null) { lastTickOffset = tickOffset; continue; }   // probe-failed — no verdict
+                  // HARVEST-ON-PROBE (one strike — THE fix for the incident's
+                  // ten-minute blindness): a durable exit sentinel means the
+                  // turn is FINISHED and no more bytes are coming; any stream
+                  // that hasn't delivered it is done being useful. Likewise a
+                  // runner process that is gone. Mid-turn starvation keeps a
+                  // two-tick grace (offset frozen since the previous tick) so
+                  // a byte-burst racing the probe never kills a healthy tail.
+                  const streamStarved = reading.size > offset && tickOffset === lastTickOffset;
+                  if (reading.sentinelSeen || !reading.alive || streamStarved) {
+                    console.warn(`[cli-agent] ${this.spec.kind} tail stream ${reading.sentinelSeen
+                      ? "outlived the FINISHED turn (durable sentinel unharvested)"
+                      : !reading.alive ? "outlived the runner"
+                      : `starved (durable file at ${reading.size} bytes, stream stuck at ${offset})`}`
+                      + " — killing the tail and catching up from the durable file");
+                    void tail.kill().catch(() => { /* best-effort; catch-up follows regardless */ });
+                    return;
+                  }
+                  lastTickOffset = tickOffset;
+                }
+              })(handle);
               currentTail = null;
             }
             if (exitCode !== null || consumerStopped || opts.signal?.aborted) break;
@@ -873,8 +1676,17 @@ export class CliAgentRunner implements ModelExecutionContract {
               exitCode = JSONL_GUARD_NO_SENTINEL_EXIT;
               break;
             }
-            console.warn(`[cli-agent] ${this.spec.kind} turn stream lost with the runner alive — re-tailing ${outPath} from byte ${offset}`);
-            await new Promise((r) => setTimeout(r, TAIL_REATTACH_DELAY_MS));
+            streamDeaths += 1;
+            if (streamDeaths < TAIL_ABANDON_AFTER_STREAM_DEATHS) {
+              console.warn(`[cli-agent] ${this.spec.kind} turn stream lost with the runner alive — re-tailing ${outPath} from byte ${offset}`);
+              await new Promise((r) => setTimeout(r, TAIL_REATTACH_DELAY_MS));
+            } else {
+              if (streamDeaths === TAIL_ABANDON_AFTER_STREAM_DEATHS) {
+                console.warn(`[cli-agent] ${this.spec.kind} turn abandoning streaming after `
+                  + `${streamDeaths} stream deaths — finishing on durable polling from byte ${offset}`);
+              }
+              await new Promise((r) => setTimeout(r, DURABLE_POLL_INTERVAL_MS));
+            }
           }
           if (exitCode !== null && exitCode !== 0 && durableRead) {
             try { exitStderr = (await durableRead(errPath)).slice(-2000); }
@@ -898,7 +1710,8 @@ export class CliAgentRunner implements ModelExecutionContract {
           onStdout,
           timeoutMs: 0,   // no provider deadline — see the doc comment above
         };
-        transport = this.sandbox.commands.run(guardedCmd, runOpts).then(
+        transport = this.sandbox.commands.run(
+          credEnvSourceFragment(this.options.credEnvFile) + guardedCmd, runOpts).then(
           (res) => {
             const tail = buf.trim();
             if (tail) lines.push(tail);
@@ -912,11 +1725,22 @@ export class CliAgentRunner implements ModelExecutionContract {
       // observed so an aborted turn can never surface an unhandled rejection.
       void transport.catch(() => { /* observed via `await transport` when consumed */ });
 
+      // Detach-aware reap seam: a runner marked for resume handoff
+      // (`detachGuest`) unwinds WITHOUT killing the guest tree — the
+      // successor turn resumes that exact guest session.
+      const reapUnlessDetached = (): void => { if (!this.guestDetached) reap(); };
       if (opts.signal) {
-        if (opts.signal.aborted) reap();
-        else opts.signal.addEventListener("abort", reap, { once: true });
+        if (opts.signal.aborted) reapUnlessDetached();
+        else opts.signal.addEventListener("abort", reapUnlessDetached, { once: true });
       }
       try {
+        // The guest session id ALREADY ANNOUNCED to the consumer (the
+        // synthesized init above carried opts.sessionId). A CLI that forks a
+        // NEW session id (claude --resume forks; codex threads) announces it
+        // mid-stream below, so the executor can durably record the id even
+        // 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) {
           let parsed: Record<string, unknown>;
           try {
@@ -926,6 +1750,10 @@ export class CliAgentRunner implements ModelExecutionContract {
           }
           const sid = this.spec.extractSessionId(parsed);
           if (sid) sessionId = sid;
+          if (sid && sid !== announcedSessionId) {
+            announcedSessionId = sid;
+            yield { type: "init", sessionId: sid, timestamp: now() };
+          }
           for (const msg of this.spec.mapEvent(parsed)) {
             if (msg.type === "error") sawError = true;
             yield msg;
@@ -948,23 +1776,51 @@ export class CliAgentRunner implements ModelExecutionContract {
           yield { type: "error", text: `${this.spec.kind} exited with code ${exitCode}${detail}${exitStderr ? `: ${exitStderr}` : ""}`, timestamp: now() };
           return;
         }
+        if (exitCode !== 0 && sawError && RESUME_TARGET_MISSING_STDERR.test(exitStderr)) {
+          // The CLI reported a bare result error on stdout (claude's
+          // `error_during_execution` with num_turns 0) while its REAL
+          // complaint — the missing `--resume` target — went to stderr
+          // (the 2026-08-18 split-brain forensic). Surface the stderr as
+          // the LAST error event: the consumer's terminal close keeps the
+          // last error text, so the classifier sees the truth instead of a
+          // generic runner death it would call transient forever.
+          yield { type: "error", text: `${this.spec.kind} exited with code ${exitCode}: ${exitStderr}`, timestamp: now() };
+          return;
+        }
         if (!sawError) yield { type: "done", sessionId: sessionId ?? "", timestamp: now() };
       } finally {
         // Runs on completion AND on early generator exit (the caller broke
         // out of its for-await: abort, turn closed under the executor,
-        // supersede). Reap only while the runner hasn't reported an exit.
-        opts.signal?.removeEventListener("abort", reap);
+        // supersede). Reap only while the runner hasn't reported an exit —
+        // and NEVER when the guest was detached for a resume handoff: the
+        // successor turn resumes this exact guest session, and the park
+        // path's busy signal reads the surviving heartbeat/busy files.
+        opts.signal?.removeEventListener("abort", reapUnlessDetached);
         consumerStopped = true;
-        if (exitCode === null) reap();
+        if (exitCode === null && !this.guestDetached) reap();
+        // Teardown hygiene (2026-08-18 incident): a reaped turn's unwind
+        // WAITS for the kill-and-confirm exec, so the generator's return —
+        // and the executor's turn settle behind it — never completes while
+        // the guest tree may still be alive holding e.g. codex's
+        // thread-store writer flock. Bounded by the exec's own ceiling
+        // (REAP_EXEC_TIMEOUT_MS); a clean exit never armed it.
+        if (reapConfirm) await reapConfirm;
         // Opportunistic prompt-file + guard-script + transcript cleanup:
         // paths are never reused (see uniquePromptPath), so this is hygiene,
         // not correctness — fire and forget, and a dead sandbox / failed rm
         // is fine. The shell holds an open fd on the redirect, so unlinking
-        // under a still-exiting CLI is harmless.
-        void this.sandbox.commands.run(
-          `rm -f ${shellQuote(promptPath)} ${shellQuote(guardPath)} ${shellQuote(`${promptPath}.out`)} ${shellQuote(`${promptPath}.err`)} ${shellQuote(`${promptPath}.pid`)}`,
-          { timeoutMs: 10_000 })
-          .catch(() => { /* best-effort */ });
+        // under a still-exiting CLI is harmless. Skipped on a detach: the
+        // handed-off runner's durable trio must survive it.
+        // The turn's injection window is over either way: a caller landing
+        // after this point must get "unsupported", never a write into a
+        // dead (or handed-off) turn's inbox.
+        this.turnInject = null;
+        if (!this.guestDetached) {
+          void this.sandbox.commands.run(
+            `rm -f ${shellQuote(promptPath)} ${shellQuote(guardPath)} ${shellQuote(`${promptPath}.out`)} ${shellQuote(`${promptPath}.err`)} ${shellQuote(`${promptPath}.pid`)} ${shellQuote(`${promptPath}.hb`)} ${shellQuote(`${promptPath}.busy`)} ${shellQuote(`${promptPath}.tasks`)} ${shellQuote(`${promptPath}.fifo`)} ${shellQuote(`${promptPath}.inbox`)} ${shellQuote(`${promptPath}.delivered`)}`,
+            { timeoutMs: 10_000 })
+            .catch(() => { /* best-effort */ });
+        }
       }
     } catch (err) {
       yield { type: "error", text: formatError(err), timestamp: now() };