@agent-compose/sdk 0.8.2 → 0.8.4

package/dist/runtimes/_cli-agent.d.ts

@@ -23,13 +23,243 @@
  * (see each spec's `authEnv`); `commands.run` inherits the sandbox env, so
  * 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 type { GuestPerfSample } from "../agent/perf-sampler.js";
 import type { ProcessorContext, ToolCall } from "../processors/processor.js";
 /** Backoff between tail re-attach attempts after a mid-turn stream fault
  *  (durable detached transport). Short: the runner is alive and producing,
  *  and each retry costs one exec; the executor's evidence machinery — not
  *  this loop — bounds a truly dead sandbox. Exported for tests. */
 export declare const TAIL_REATTACH_DELAY_MS = 2000;
+/** Cadence of the in-guest heartbeat writer (seconds — it is a shell loop). */
+export declare 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 declare 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 declare 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 declare function runnerBusySentinelFragment(busyPath: string, tasksPath: string): string;
+/** 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 declare const RUNNER_HEARTBEAT_STALE_MS: number;
+/** 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 declare const TAIL_WATCHDOG_INTERVAL_MS = 15000;
+/** Explicit ceiling on one durable-trio probe exec. A probe that can't
+ *  answer is "probe-failed" — never a verdict. */
+export declare const TURN_PROBE_TIMEOUT_MS = 10000;
+/** 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 declare 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 declare const DURABLE_POLL_INTERVAL_MS = 1000;
+/** 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 declare const RESUME_TARGET_MISSING_STDERR: RegExp;
+/** 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 declare function turnLivenessProbeCommand(paths: {
+    outPath: string;
+    hbPath: string;
+    perfPath: string;
+    pid: number;
+    sentinel: string;
+}): string;
+/** 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 declare function parseTurnProbeOutput(raw: string): TurnProbeReading | null;
+/** 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 declare function livenessVerdictFromReading(reading: TurnProbeReading | null): RunnerLivenessVerdict;
+/** 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 declare 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 declare const INJECT_FEEDER_RESULT_TAIL_BYTES = 262144;
+/** 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 declare const INJECT_ACK_POLL_ATTEMPTS = 30;
+export declare const INJECT_ACK_POLL_SECONDS = "0.5";
+export declare const INJECT_ACK_EXEC_TIMEOUT_MS = 25000;
+/** 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 declare function streamInputFeederFragment(paths: {
+    promptPath: string;
+    fifoPath: string;
+    inboxPath: string;
+    deliveredPath: string;
+    outPath: string;
+}): string;
+/** The instructional envelope around a user message delivered INTO a
+ *  running turn. Claude Code's own interactive harness wraps queued
+ *  mid-turn input with an explicit "address this as you continue"
+ *  instruction; a bare `--input-format stream-json` line carries no such
+ *  framing, so an injected message reads like any other transcript text
+ *  and the model tends to continue its work narration without
+ *  acknowledging it. Every mid-turn inject producer (the runner's
+ *  `injectUserMessage` and the workflow lane's `deliverInjectedMessage`
+ *  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 declare function wrapMidTurnUserMessage(text: string): string;
+/** 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 declare function injectAppendAndAckCommand(args: {
+    line: string;
+    target: number;
+    pid: number;
+    inboxPath: string;
+    deliveredPath: string;
+}): string;
+/** SIGTERM grace before escalation: attempts × sleep = 5s. */
+export declare 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 declare const REAP_KILL_WAIT_ATTEMPTS = 8;
+export declare 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 declare const REAP_STILL_ALIVE_EXIT = 7;
+/** Ceiling on the whole kill-and-confirm exec (TERM 5s + KILL 2s + slack). */
+export declare const REAP_EXEC_TIMEOUT_MS = 15000;
+/** 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 declare function reapKillAndConfirmCommand(pid: number): string;
+/** 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 declare const RESIDENT_IDLE_TTL_S = 240;
+/** Watchdog poll cadence (seconds). */
+export declare 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 declare 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 declare function residentResultCountCommand(outPath: string, fromByte?: number): string;
+/** 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 declare function residentFeederFragment(paths: {
+    promptPath: string;
+    fifoPath: string;
+    inboxPath: string;
+    deliveredPath: string;
+    endPath: string;
+}): string;
+/** 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 declare function residentIdleCheckFragment(paths: {
+    outPath: string;
+    inboxPath: string;
+    deliveredPath: string;
+    servedPath: string;
+}): string;
+/** 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 declare function residentIdleWatchdogFragment(paths: {
+    outPath: string;
+    inboxPath: string;
+    deliveredPath: string;
+    servedPath: string;
+}): string;
+/** 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 declare function deferredExitEventPushCommand(notify: {
+    url: string;
+    tokenEnv: string;
+}, turnIdFile: string): string;
 /** 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
@@ -50,8 +280,50 @@ export declare const LAUNCH_PID_RECOVERY_DELAY_MS = 1000;
  *  call in the turn path carries an explicit timeout so no SDK default can
  *  decide a turn's fate. Exported for tests. */
 export declare const INSTALL_PROBE_TIMEOUT_MS = 30000;
+/** 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 declare const CLI_INSTALL_TIMEOUT_MS = 300000;
 /** Single-quote a value for safe interpolation into a `sh -c` command line. */
 export declare function shellQuote(value: string): string;
+/** $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 declare const SESSION_ENV_FILE_RELPATH = ".agent-compose/session-env.sh";
+/** 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 declare function sessionEnvSourceFragment(relPath: string | undefined): string;
+/** 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 declare function credEnvSourceFragment(absPath: string | undefined): string;
+/** 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 declare const EXIT_PUSH_ATTEMPT_TIMEOUT_SECONDS = 5;
+/** Pause before the single retry. */
+export declare 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 declare function exitEventPushCommand(notify: TurnExitNotify): string;
 /**
  * A UNIQUE per-turn prompt path. Uniqueness is load-bearing, not cosmetic:
  * E2B's envd cannot overwrite an existing non-root file in /tmp — it opens
@@ -129,13 +401,18 @@ 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`). */
+     *  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 +
@@ -150,6 +427,16 @@ 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`/
@@ -160,6 +447,27 @@ export interface CliAgentSpec {
         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;
+    };
 }
 export declare class CliAgentRunner implements ModelExecutionContract {
     private readonly sandbox;
@@ -208,6 +516,55 @@ export declare class CliAgentRunner implements ModelExecutionContract {
      *  exercising the real `sendMessageAcp` even while the production default is
      *  dormant. Not a public API. */
     private acpTransportReady;
+    /** 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;
+    /** 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;
+    /** 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. */
+    injectUserMessage(text: string): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+    /** 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. */
+    probeTurnLiveness(): Promise<RunnerLivenessVerdict | null>;
+    /** Wakes the CURRENT tail-watchdog interval early. Armed only while the
+     *  watchdog's wake timer is pending; null between arms / between turns. */
+    private wakeTailWatchdog;
+    /** 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;
+    /** 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;
+    /** 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;
+    detachGuest(): void;
     constructor(sandbox: SandboxProvider, options: RuntimeOptions, spec: CliAgentSpec, configModel?: string | undefined, configEffort?: CliReasoningEffort | undefined);
     /** TEST-ONLY: flip the live-ACP readiness gate on for this runner instance so
      *  the ACP lifecycle / fallback tests can exercise `sendMessageAcp` while the

package/dist/runtimes/claude-code.d.ts

@@ -33,6 +33,7 @@
  *     sessions this is the gateway-minted session virtual key pointed at the
  *     token-metering gateway's Anthropic passthrough (ADR-0039).
  */
+import type { AgentMessageTaskNotification } from "../index.js";
 import { type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 /** Pinned Claude Code ACP adapter (Zed's npm shim — `claude` has no native
  *  ACP mode). Pinned EXACT, not a range: the adapter's README warns of
@@ -40,6 +41,17 @@ import { type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
  *  bridge daemon (cli/src/bridge/acp.ts) imports this same pin so both
  *  executors launch the identical adapter. Verified against 0.16.2. */
 export declare const CLAUDE_CODE_ACP_ADAPTER = "@zed-industries/claude-code-acp@0.16.2";
+/** Parse every `<task-notification>` block out of one user-role text blob.
+ *  Pure and tolerant over untrusted harness text: a block without a task id
+ *  is skipped, absent fields stay absent, everything is clamped. Exported
+ *  for tests. */
+export declare function parseTaskNotifications(text: string, timestamp: string): AgentMessageTaskNotification[];
+/** One `system`/`task_notification` stream-json event mapped onto the same
+ *  structured message the XML parse produces, or null when the event names
+ *  no task id. Pure and tolerant over untrusted harness JSON: absent fields
+ *  stay absent, everything is clamped; `output_file` (internal plumbing) is
+ *  deliberately not forwarded. Exported for tests. */
+export declare function parseSystemTaskNotification(p: Record<string, unknown>, timestamp: string): AgentMessageTaskNotification | null;
 /** Claude Code's real reasoning knob is its own `--effort <level>` flag
  *  (low|medium|high|xhigh|max — verified against `claude -p --help`). The
  *  CliReasoningEffort union IS the CLI's vocabulary, so the level rides the

package/dist/runtimes/codex.d.ts

@@ -16,6 +16,14 @@ import { type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 /** True when an error-item message is a known codex advisory (log-level
  *  noise), not a real error. Exported for tests. */
 export declare function isCodexAdvisoryNoise(text: string): boolean;
+/** Bounded wait for a dying previous writer: attempts × sleep = 5s, matching
+ *  the teardown's SIGTERM grace (sdk _cli-agent.ts REAP_TERM_WAIT_ATTEMPTS). */
+export declare const CODEX_LOCK_WAIT_ATTEMPTS = 20;
+export declare const CODEX_LOCK_WAIT_SECONDS = "0.25";
+/** The sh fragment prepended to a resume launch. `waitAttempts` is a test
+ *  seam (the live-holder test must not sleep 5s); production callers take
+ *  the default. Exported for tests. */
+export declare function codexWriterLockPreflight(threadId: string, waitAttempts?: number): string;
 /** Exported for the fixture-based parity tests (ADR-0020): the legacy JSONL
  *  `mapEvent` is the golden the ACP normaliser is asserted equal to. Not part
  *  of the public runtime surface — `createCodexRuntime` stays the entry point. */