@humwick/server 0.0.0-stage → 0.130.1

package/runner/src/runner-core.ts

@@ -0,0 +1,2955 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { normalizeDeliverResult } from "./delivery-result";
+import { TokenUsageReportCoverage } from "./agent-runner/token-usage-coverage";
+import { spawnWithServiceAccess } from "./service-access";
+import { LifecycleMilestones } from "./agent-runner/lifecycle-milestones";
+import { CommandDispatch } from "./agent-runner/commands/dispatch";
+import { LifecycleCommands } from "./agent-runner/commands/lifecycle";
+import { PromptCommands, promptOrigin } from "./agent-runner/commands/prompt";
+import type { NativeSelfResumeHandoff } from "./native-self-resume";
+import { LifecyclePhase } from "./agent-runner/lifecycle-phase";
+import { startRunnerMcpProxy, runnerWebToolLog, runnerWebSearch, runnerMcpHiddenTools } from "./runner-mcp-proxy";
+import { HttpLiveness } from "./agent-runner/http-liveness";
+import { TaskClaims } from "./agent-runner/task-claims";
+import { TurnReport } from "./agent-runner/turn-report";
+import { SessionMirror } from "./agent-runner/session-mirror";
+import { Registration, runnerIdentityMeta } from "./agent-runner/registration";
+import { RunnerContext, type RunnerOptions } from "./agent-runner/runner-context";
+export type { RunnerOptions } from "./agent-runner/runner-context";
+import { hostname } from "node:os";
+import { resolveEnvLayers, selectProviderConfigEnv } from "@humwick/sdk/child-env";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { type ContextState, type Message, type ProviderState, HELD_FOR_PAYLOAD_KEY, PROVIDER_SUBMIT_UNCONFIRMED, PROXY_AUTH_HOLD_KIND, errMessage, frameSuppressedFromTurn, stringValue } from "@humwick/sdk";
+import { exitRunner } from "./runner-exit";
+import { isResumeWake, ProviderHoldEpisodes } from "./provider-hold";
+import { contextStateFromProbeMetrics, quotaStateFromProbeMetrics } from "@humwick/sdk/context-probe";
+import { isPidAlive } from "@humwick/sdk/process-utils";
+import { HELD_PROMPT_IMAGE_PATHS, providerMessageText, type PromptOfferOptions, type ProviderInputObserver } from "./adapter";
+import { ProviderSubmitFailure, PROVIDER_SUBMIT_MAX_DELIVERIES, providerSubmitRetryDelayMs } from "./provider-submit-failure";
+import { computeLivenessSignal, type LivenessInputs } from "./liveness";
+import type { DeliverResult, ManagedProcess, PaneObservation, ProviderDeliverContext, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, ShutdownOutcome, TerminalAttachSpec } from "./adapter";
+import { messagesWithCachedAttachments } from "./attachment-cache";
+import { AttachmentCacheSweep } from "./attachment-cache-sweep";
+import { resolveTestRunRootPid, TEST_RUN_DEDUP_SWEEP_MS, TestRunDedupSweep } from "./test-run-dedup";
+import { cachedGateRunCommandsForCwd } from "./gate-run-config";
+import { AreaMemoryTracker } from "./area-memory";
+import { GateRunLeaseProbe } from "./gate-run-lease-probe";
+import { ClaimTracker } from "./claim-tracker";
+import { ProviderQuotaHarvest } from "./adapters/provider-quota-harvest";
+import { agentShellLaunchEnv } from "./adapters/project-shell";
+import { isNotificationOnlyInput } from "./inbox-carrier";
+import { readRunnerContextProbeState } from "./context-probe-state";
+import { startControlServer, type ControlServer, type ResolvedPermissionPrompt } from "./control-server";
+import { fileQuestionDecision } from "./question-decision";
+import { ReplyObligationCache, obligationNagEligible, responseCaptureReplyRoute } from "./reply-obligation-cache";
+import { Outbox } from "./outbox";
+import { RefusedPromptStore } from "./refused-prompt-store";
+import { retryParkPost } from "./park-post";
+import { getManifest } from "@humwick/providers";
+import { hostSourcesFor } from "./host-asset-plan";
+import { RELAY_MCP_TOKEN_ENV, relayMcpEndpoint, resolveSharedMcpUrl } from "./relay-mcp";
+import { RelayMcpProxy, isolatedWorkspaceDescriptor } from "./relay-mcp-proxy";
+import { runtimeMetadata } from "./version";
+import { logger } from "./logger";
+import { ensureSessionScratch, type SessionScratchLayout } from "./session-scratch";
+import { sweepRunnerStaleScratch } from "./runner-stale-scratch-sweep";
+import { RunnerInsights } from "./runner-insights";
+import { BusyReconciler } from "./busy-reconciler";
+import { fireAndForget } from "./async-guard";
+import { providerTurnWatchdogTimelineEvent, reconciledTurnTimelineEvent, type RunnerTimelineEvent } from "./turn-reconcile-event";
+import { EMPTY_TURN_NUDGE, EmptyTurnWatch, type EmptyTurnArm } from "./empty-turn";
+import { buildBackgroundTaskLedger, isStaleBackgroundScriptOnlyBusy } from "./background-script-reconcile";
+import { buildRunnerSpawnConfig } from "./runner-spawn-config";
+import { PendingPermissionStore, type PendingPermissionRequestRecord } from "./pending-permission-store";
+import { ProviderInputQueue, type ProviderInputTicket } from "./provider-input-queue";
+import { runnerLaunchInjectionSessionEvents, type RunnerRelayInjectionEvent } from "./relay-injection-events";
+import { providerTerminalSession, providerTerminalSocket } from "./process-meta";
+import { capsFromEnv, mcpProxyEnabledFromEnv, orchestratorBaseDirFromEnv, registrationTimeoutMsFromEnv, runnerLogFileFromEnv, runnerOutboxDirWithInfoFallback, tagsFromEnv, workspaceModeFromEnv } from "./config";
+import { PRE_DESTROY_TIMEOUT_MS, type SessionDestroyReason } from "./session-destroy";
+import { assertClearInjectCommitted, ClearInjectInboxFence, executeCompactCommand, lateClearHookContent, LateClearRecovery } from "./context-command";
+import { ContextResetReporter, ContextSubmitAborted, DeliverySettlements } from "./context-boundary";
+import { EffortReconciler, isEffortNotice, runnerEffortSwitch } from "./effort-command";
+import { isNativeSelfResumeCompact, NativeSelfResumeTracker, recoverNativeSelfResumeExit } from "./native-self-resume";
+import { initializeRunnerTemplates } from "./template-resolver";
+import { publishRuntimeTokenForCli } from "./runtime-token-file";
+import { Credentials } from "./agent-runner/credentials";
+import {
+  csvTags,
+  isContextState,
+  isHttpStatusError,
+  isTurnInProgressDeliveryError,
+  providerExitLastError,
+  providerExitDiagnostics,
+  providerExitResumeId,
+  providerManualRecoveryMessage,
+  providerManualRecoveryReason,
+  providerMonitorUnavailableMessage,
+  providerStateFromActiveWork,
+  registerWithinDeadline,
+  relayBusUrl,
+  runnerAgentStatus,
+  runnerBusErrorAction,
+  runnerMessageMatches,
+  runnerMessageShouldDirtyObligations,
+  runnerShouldResolveProviderExit,
+  runnerShouldRestartUnexpectedProviderExit,
+  runtimeProviderCapabilities,
+  shouldLogDeliveryFailure,
+  stripRunnerClaimedGuidance,
+  taskIdFromMessage,
+  type ProbeModelInfo, type RestartProviderOptions,
+} from "./runner-helpers";
+
+const STALE_PROVIDER_TURN_BUSY_MS = 10 * 60_000;
+
+type HeldSubmit = { messages: Map<number, Message>; resend?: () => Promise<unknown> };
+const emptyHeldSubmit = (): HeldSubmit => ({ messages: new Map() });
+type RunnerStatusFrame = { agentStatus: string; ready?: boolean; meta?: Record<string, unknown> };
+
+// #650: how often to reconcile pid-bearing busy work against actual process liveness.
+const BUSY_LIVENESS_RECONCILE_MS = 5_000;
+const HTTP_LIVENESS_LOG_INTERVAL_MS = 5 * 60 * 1000;
+const UNEXPECTED_EXIT_WINDOW_MS = 2 * 60 * 1000;
+// Bound retries after a terminal provider failure.
+const TERMINAL_FAILURE_RETRY_BASE_MS = 2_000;
+const TERMINAL_FAILURE_RETRY_MAX_MS = 60_000;
+// #2539 live-fire — recency bound for ids this runner has positively SETTLED (acked + marked
+// read). A server list snapshot taken before the settle's markRead (the startup unread poll,
+// any future server-listed lane) can land its stale copy in enqueueMessage AFTER the delivery —
+// re-delivering an already-delivered message (immediately as a steer under the soft-steer
+// default, or at turn-end before it). Insertion-ordered, oldest evicted; the race window is
+// intra-process and short, so a recency cap is generous.
+const SETTLED_MESSAGE_IDS_CAP = 1024;
+// #2539 Phase B — bound on soft-steered ids held between persist and consumption. The adapter's
+// ledger cap backpressures first (it stops accepting new positive persists), so this is the
+// runner-side defense-in-depth ceiling, not the operating bound.
+const AWAITING_MID_TURN_DELIVERY_CAP = 256;
+const RAPID_EXIT_MS = 30 * 1000;
+const MAX_RAPID_UNEXPECTED_EXITS = 3;
+const UNDETERMINED_PROVIDER_EXIT_CONFIRM_MS = 1_500;
+const PROVIDER_EXIT_CONFIRM_POLL_MS = 250;
+// A UserPromptSubmit echo matching a runner-injected prompt within this window is
+// the same prompt arriving back from the provider — drop it to avoid a duplicate.
+const PROMPT_ECHO_DEDUP_MS = 30_000;
+// Relay-injected content (delivered messages, memory context) is wrapped with
+// these markers; a UserPromptSubmit echo starting with one is a runner injection,
+// not a human typing into the terminal, so it must not be mirrored as a prompt.
+// `<task-notification>` is the harness wrapper for async monitor/task wake-ups
+// (which embed a `[relay message #…]` deeper inside, defeating a plain prefix
+// match) — it is emitted only by the harness, never typed by a human, so any
+// echo starting with it is a system injection, not a user prompt (#289).
+const RELAY_INJECTION_MARKERS = ["[relay message #", "[agent-relay", "<task-notification>"];
+// #1116: bounded settle-poll for provider pre-flush anchors. The adapter owns the
+// source-specific read; the runner owns the shared timeout knobs.
+const SETTLE_POLL_INTERVAL_MS = 250;
+const SETTLE_POLL_TIMEOUT_MS = 4_000;
+
+export class AgentRunner {
+  private readonly context: RunnerContext;
+  private get options() { return this.context.options; }
+  private get agentId() { return this.context.agentId; }
+  private get http() { return this.context.http; }
+  private get bus() { return this.context.bus; }
+  private readonly effortRuntime: Pick<RunnerOptions, "instanceId" | "adapter" | "effort">;
+  private readonly claims = new ClaimTracker();
+  // Phase 2 (#196): the Stop hook reads reply obligations from this local snapshot, never
+  // from the server — so a slow server can no longer wedge a turn (the crux fix).
+  private readonly obligationCache: ReplyObligationCache;
+  // Phase 2 (#196): Runner→server append-log events (session turns, reasoning, prompts,
+  // insights, hook-fatal) go through this durable, disk-backed, timestamped queue instead of
+  // direct fire-and-forget HTTP — so nothing is lost across a server/Runner restart.
+  private readonly outbox: Outbox;
+  private readonly sessionMirror: SessionMirror;
+  private readonly turnReport: TurnReport;
+  private readonly commandDispatch: CommandDispatch;
+  private readonly lifecycleCommands: LifecycleCommands;
+  private readonly lifecycleMilestones: LifecycleMilestones;
+  private readonly promptCommands: PromptCommands;
+  private readonly pendingPermissionStore: PendingPermissionStore;
+  // #1565 F1 — the one gate in front of the provider's single input channel. Every payload the
+  // runner delivers (message batch, injected prompt, self-resume continuation, memory preamble)
+  // passes through it, so two payloads for one agent can never interleave at the wire. FIFO, with
+  // the place in line taken synchronously at dispatch, so the payload the relay created first is
+  // the one delivered first.
+  private readonly providerInput = new ProviderInputQueue({
+    onStuck: (heldMs) => logger.warn("delivery", `provider input stream held for ${heldMs}ms; force-releasing so delivery cannot wedge`),
+  });
+  // #2984 — converges the provider on Relay's desired effort between turns; a bus notice only speeds it up.
+  private readonly effort = new EffortReconciler({ http: () => this.http, agentId: () => this.agentId, runner: () => this.effortRuntime, process: () => this.process, publish: () => this.bus.flushHeartbeat(), hasProviderTurn: () => this.claims.activeWork().some((w) => w.kind === "provider-turn"), reserveInput: () => this.providerInput.reserve(), log: (message) => this.sessionLog(message) });
+  // #2389 — "did that turn actually do anything", and what to do when the answer is no. The ledger,
+  // its timers and the nudge/escalate ladder all live in empty-turn.ts; what stays here is the
+  // wiring only AgentRunner can own — the adapter, the process handle and the input queue.
+  private readonly emptyTurns = new EmptyTurnWatch({
+    provider: () => this.options.provider,
+    canNudge: () => Boolean(this.process) && Boolean(this.options.adapter.deliverInitialPrompt),
+    nudge: () => void this.deliverEmptyTurnNudge().catch((error) => this.reportBackgroundRejection("empty-turn nudge", "turn.nudge_failed", "Empty-turn nudge not delivered", error)),
+    capturesInFlight: () => this.sessionMirror.capturesInFlight(),
+    log: (message) => this.sessionLog(message),
+    publishTimeline: (event) => this.publishRunnerTimelineEvent(event),
+    onMarkerCleared: () => this.publishStatus(),
+  });
+  private deliveringEmptyTurnNudge = false;
+  private readonly insights: RunnerInsights;
+  private readonly busyReconciler: BusyReconciler;
+  private readonly providerQuotaHarvest: ProviderQuotaHarvest;
+  private readonly credentials: Credentials;
+  private control?: ControlServer;
+  private registeredAt?: number;
+  // Stage 2 (#215): the local MCP endpoint the agent connects to, fronting the relay so the
+  // Runner owns reconnect/backoff + a durable buffer. Disabled via AGENT_RELAY_MCP_PROXY=0
+  // (then the agent connects to the relay directly, Stage-1 behaviour). The proxy secret is the
+  // bearer the agent presents to the localhost proxy — it decouples the agent from the rotating
+  // relay token (the proxy injects the live token relay-side).
+  private proxy?: RelayMcpProxy;
+  private mcpProxyEndpoint?: string;
+  private readonly mcpProxyEnabled: boolean;
+  private readonly mcpProxySecret: string;
+  private process?: ManagedProcess;
+  private readonly lifecycle = new LifecyclePhase({
+    suspendHeartbeat: () => this.bus.suspendHeartbeat(),
+    stopStatusWatchers: () => this.options.adapter.stopStatusWatchers?.(),
+  });
+  // #633 — set when the provider terminally exits but the runner stays alive (native
+  // auto-compaction / manual-resume hold). Rides on the offline status frame so the server fires a
+  // terminal `agent.exited` event with a #636 diagnosis instead of the death going silent. Cleared
+  // on any genuine restart back to busy/idle.
+  private terminalProviderExit?: Record<string, unknown>;
+  private nativeSelfResume = new NativeSelfResumeTracker();
+  private readonly registration: Registration;
+  private readonly httpLiveness: HttpLiveness;
+  private readonly taskClaims: TaskClaims;
+  private delivering = false;
+  private drainTimer?: Timer;
+  private livenessReconcileTimer?: Timer;
+  private readonly attachmentCacheSweep: AttachmentCacheSweep;
+  private readonly testRunDedupSweep: TestRunDedupSweep;
+  private readonly gateRunLeaseProbe: GateRunLeaseProbe;
+  private processStartedAt = 0;
+  private providerSessionId = crypto.randomUUID();
+  // Last transcript path seen this session — used by end-of-session Insights (#184)
+  // when the SessionEnd hook payload omits it.
+  private lastTranscriptPath?: string;
+  private readonly unexpectedExitTimes: number[] = [];
+  private readonly pendingMessages = new Map<number, Message>();
+  // Hold inbox input through clear+inject and the bounded late-commit grace (#2477/#2849).
+  private readonly continuationFence = new ClearInjectInboxFence(() => { if (this.pendingMessages.size > 0) this.scheduleDrain(); });
+  private readonly lateClearRecovery = new LateClearRecovery((commandId) => this.finishLateClearGrace(commandId));
+  private readonly deliverySettlements = new DeliverySettlements();
+  private readonly contextResets = new ContextResetReporter(this.deliverySettlements, (fact) => this.outbox.enqueue({
+    kind: "context-reset", payload: { agentId: this.agentId, instanceId: this.options.instanceId, ...fact }, idempotencyKey: `context-reset:${fact.resetId}` }), (message) => this.sessionLog(message), () => this.resetContextGeneration());
+  // A drain removes its batch from pendingMessages before its claim and attachment awaits. Keep that
+  // pre-boundary lane visible so a clear that begins during either await fences the same messages.
+  private drainingMessageIds?: Set<number>;
+  private pendingTimelineEvent?: RunnerTimelineEvent;
+  private lastProviderEventAt?: number;
+  // Session-mirror: a synthesized id grouping a turn's reasoning/tool steps and
+  // its final response. Set when a provider-turn starts, cleared when it ends.
+  private currentTurnId?: string;
+  private currentTurnStartedAt?: number;
+  private completedProviderTurns = 0;
+  // True while a turn that was already in flight is being compacted. Some providers
+  // post a transient idle after compaction even though the turn resumes afterward, so
+  // treating that idle as a turn end (flip idle, kill the reasoning tail) makes chat go dark
+  // until the next prompt. Set when `compacting` arrives with a turn running; cleared on the
+  // genuine end (a plain idle with no compaction timeline).
+  private compactionMidTurn = false;
+  // Prompt-echo dedup: a short, time-bounded queue of prompts the runner itself
+  // injected (chat box or initial prompt) that are still awaiting their matching
+  // UserPromptSubmit echo. A single slot dropped earlier entries when several prompts
+  // were injected before their echoes returned (rapid sends while the provider is busy
+  // and queues them) — the evicted ones then double-posted. Match consumes one entry.
+  private injectedPrompts: Array<{ text: string; at: number; imagePaths?: readonly string[] }> = [];
+  // Tracks whether the provider is in a legitimate blocked/approval state, so the
+  // busy reconciler doesn't mistake a permission prompt for a stuck-busy turn.
+  private providerBlocked = false;
+  // Display-only startup modal evidence. It never touches work claims or turn state.
+  private startupPaneDialog?: ProviderState;
+  private deliverySubmitHold?: ProviderState;
+  /** #2664 — what the hold withheld: the unconfirmed item for the operator's resend, and later prompts parked in order behind it. */
+  private heldSubmit: HeldSubmit = emptyHeldSubmit();
+  private readonly submitDeliveryAttempts = new Map<number, number>();
+  private submitRecoveryInFlight = false;
+  private submitRecoveryTurnStarted = false;
+  private submitRecoveryRequested = false;
+  // #2664 — a held submit that did land often leaves no later event to re-run the recovery probe.
+  private submitRecoveryTimer?: ReturnType<typeof setInterval>;
+  private submitRecoveryPollMs = 10_000;
+  private submitRecoveryPollWindowMs = 5 * 60_000;
+  // #2664 — the operator's resend of the held prompt runs ahead of every parked inbox row.
+  private submitResendInFlight = false;
+  // #2664 — set INSIDE the FIFO slot of an unconfirmed submit, so the next queued prompt sees the fence
+  // before the failing caller has published the hold; cleared with the hold.
+  private submitFenceRaised = false;
+  // #2664 — park posts (and their retries) run in the input order, their place taken at the parking decision.
+  private readonly parkPosts = new ProviderInputQueue({ onStuck: (heldMs) => logger.warn("delivery", `parked prompt post held ${heldMs}ms; releasing the next`) });
+  private terminalFailure?: { reason: string; message: string; providerState?: ProviderState };
+  // #286: a usage/rate-limit hold. The turn truly ended (idle), but the agent is
+  // held until the limit resets, so this can't ride an active-work claim like the
+  // permission-blocked state does. publishStatus surfaces it as the agent's
+  // providerState; it clears when a new turn starts (the relay's resume message
+  // wakes one) so the blocked badge lifts on its own.
+  private rateLimitHold?: ProviderState;
+  private pendingRateLimitHold?: ProviderState;
+  // #1173: like rateLimitHold — a deny-then-hold "questions" (AskUserQuestion) prompt's own
+  // turn genuinely ends (the provider reacts to the denial and stops normally) before the human
+  // answers, so the pendingApproval can't ride the provider-turn active-work claim (it would
+  // vanish the instant that claim clears on the real idle). Persists across idles and new turns
+  // (#2913); cleared once the answer is injected (or the prompt is dismissed/times out).
+  private pendingQuestionHold?: ProviderState;
+  // #2919 — the turn-end capture saw accepted input queued behind this turn: its idle opens the next turn.
+  private queuedTurnFollows = false;
+  // Settle-poll cadence for the pre-flush anchor (#1116) — instance fields (not just the
+  // module constants) so tests can shrink them without waiting out the real bound.
+  private settlePollIntervalMs = SETTLE_POLL_INTERVAL_MS;
+  private settlePollTimeoutMs = SETTLE_POLL_TIMEOUT_MS;
+  private scratch?: SessionScratchLayout;
+  // #417: tracks how many times each spawner obligation has been re-injected so a
+  // non-responsive provider can't spin in a re-injection loop.
+  private readonly pendingObligationInjections = new Map<number, number>();
+  // #2539 live-fire — ids positively settled (acked + marked read) by THIS process; enqueueMessage
+  // drops stale re-enqueues of them. Bounded recency (see SETTLED_MESSAGE_IDS_CAP).
+  private readonly settledMessageIds = new Set<number>();
+  // #2550 — defense-in-depth backstop under the server-side decideDelivery rule: content hashes of
+  // the system-owned context payloads (memory/identity/charter/startup-context/self-resume
+  // continuation) already delivered to the CURRENT provider context generation. A byte-identical
+  // re-inject within one generation is skipped (a future double-emitting path must not paste the
+  // same envelope twice); the table is cleared at every generation boundary (provider respawn,
+  // compact, clear) because the new generation legitimately re-receives its charter/memory. Only
+  // successful deliveries are recorded, so a failed attempt's retry still delivers. User/agent
+  // prompts and normal messages never pass through this table — identical prompts legitimately
+  // repeat. This is a safety net, not the primary fix: the server's history classification of the
+  // recovery artifact is what removes the cause.
+  private readonly injectedContextHashes = new Set<string>();
+  // #3411 — which path areas this context generation entered; reset with injectedContextHashes.
+  private readonly areaMemory = new AreaMemoryTracker({ agentId: () => this.agentId, cwd: () => this.options.cwd, providerSessionId: () => this.providerSessionId, http: () => this.http, log: (message) => this.sessionLog(message) });
+  // #2539 Phase B — soft-steered batches accepted by the provider but NOT yet consumed: the
+  // persisted-but-unconsumed window. The runner keeps the offered Message so the adapter's ledger
+  // can settle by id alone ({@link settleSoftSteerConsumption} marks read;
+  // {@link reofferSoftSteerIds} requeues the ORIGINAL message into the normal lane). Bounded —
+  // past the cap settle falls back to the un-acked requeue path (the adapter's own ledger cap
+  // backpressures before this, so the fallback is defense-in-depth).
+  private readonly awaitingMidTurnDelivery = new Map<number, Message>();
+  // #2619 — the hold/resume state machine: hold episodes + the ONE parked queue of refused input
+  // (unread, claim released, never re-drained into the wall). See provider-hold.ts.
+  private readonly hold = new ProviderHoldEpisodes();
+  private readonly refusedPrompts: RefusedPromptStore;
+  // #2619 — refused context injections parked as prompts (by heldPromptKey): what their ACCEPTANCE
+  // must still do that the refused injectContext did not (the #2550 hash, the clear fence release).
+  private readonly parkedContextInjections = new Map<string, { contentHash: string; afterClearCommandId?: string }>();
+  // #2397 round 3 review (MED-3r): same ladder, for a message an adapter reports via
+  // DeliverResult.terminalFailureIds — without this, a re-queued message whose provider just
+  // exhausted a terminal-failure retry budget (e.g. OpenCode against a rate-limited upstream) was
+  // re-attempted on the very next tick, forever, with no backoff. Cleared once it is acknowledged.
+  private readonly providerTerminalFailureAttempts = new Map<number, number>();
+
+  constructor(options: RunnerOptions) {
+    this.context = new RunnerContext(options, { providerSessionId: () => this.providerSessionId, setTimelineEvent: (event) => { this.pendingTimelineEvent = event; }, publishStatus: () => this.publishStatus() });
+    this.effortRuntime = { instanceId: options.instanceId, adapter: options.adapter, effort: options.effort };
+    this.registration = new Registration({ options: this.options, agentId: this.agentId, process: () => this.process, control: () => this.control, registeredAt: () => this.registeredAt, latestProbeMetrics: () => this.latestProbeMetrics(), sessionLog: (message) => this.sessionLog(message), flushHeartbeat: () => this.bus.flushHeartbeat() });
+    this.promptCommands = new PromptCommands({
+      options: this.options, agentId: this.agentId, process: () => this.process, isStopped: () => this.lifecycle.stopped,
+      armInput: (now, mode, initial) => this.emptyTurns.armInput(now, mode, initial), disarmInput: (arm) => this.emptyTurns.disarmInput(arm), inputObserver: (arm) => this.emptyTurns.inputObserver(arm),
+      recordInjectedPrompt: (prompt, images) => this.recordInjectedPrompt(prompt, images),
+      offerPromptOrPark: (prompt, opts, ticket, onHeld, heldFor) => this.offerPromptOrPark(prompt, opts, ticket, onHeld, heldFor),
+      offerProviderInput: (run, offeredNothing) => this.offerProviderInput(run, offeredNothing), terminalFailure: () => this.terminalFailure,
+      sessionLog: (message) => this.sessionLog(message), publishRunnerTimelineEvent: (event) => this.publishRunnerTimelineEvent(event),
+      holdFailedProviderSubmit: (detail, held) => this.holdFailedProviderSubmit(detail, held), resolvePermissionDecision: (input) => this.control?.resolvePermissionDecision(input),
+      reservePark: () => this.parkPosts.reserve(), notePendingPrompt: (messageId) => this.turnReport.notePendingPrompt(messageId),
+      cacheAttachments: (messages) => messagesWithCachedAttachments(messages, this.http, { agentId: this.agentId, onError: (message) => logger.warn("attachments", message) }),
+      parkPromptBehindSubmitHold: (params, key, turn) => this.parkPromptBehindSubmitHold(params, key, turn), waitForProviderTurnClear: () => this.busyReconciler.waitForProviderTurnClear(),
+      pendingQuestionApprovalId: () => typeof this.pendingQuestionHold?.pendingApproval?.id === "string" ? this.pendingQuestionHold.pendingApproval.id : undefined,
+      clearPendingQuestionHold: () => { this.pendingQuestionHold = undefined; }, publishStatus: () => this.publishStatus(),
+    });
+    this.lifecycleMilestones = new LifecycleMilestones({
+      options: this.options, agentId: this.agentId, process: () => this.process,
+      stopAttachmentCacheSweep: () => this.attachmentCacheSweep.stop(), stopTestRunDedupSweep: () => this.testRunDedupSweep.stop(), stopGateRunLeaseProbe: () => this.gateRunLeaseProbe.stop(),
+      disposeEmptyTurns: () => this.emptyTurns.dispose(), resetEmptyTurns: () => this.emptyTurns.reset(), resetLateClearRecovery: () => { this.lateClearRecovery.reset(); this.continuationFence.reset(); },
+      clearLifecycleAction: () => this.lifecycle.setLifecycleAction(undefined), setOffline: () => this.claims.setTerminalStatus("offline"), publishStatus: () => this.publishStatus(),
+      stopDrainTimer: () => { if (this.drainTimer) clearTimeout(this.drainTimer); this.drainTimer = undefined; }, stopSubmitRecoveryPoll: () => this.stopSubmitRecoveryPoll(),
+      stopTaskClaims: () => this.taskClaims.stop(), stopHttpLiveness: () => this.httpLiveness.stop(), stopCredentials: () => this.credentials.stop(),
+      disarmBusyLivenessReconcile: () => this.disarmBusyLivenessReconcile(), disarmBusyReconciler: () => this.busyReconciler.disarm(),
+      disposeProviderInput: () => this.providerInput.dispose(), disposeParkPosts: () => this.parkPosts.dispose(),
+      stopReasoningTail: () => this.sessionMirror.stopReasoningTail(), clearNativeSessionCapture: () => this.sessionMirror.clearNativeSessionCapture(), stopObligationCache: () => this.obligationCache.stop(),
+      closeStores: () => { this.outbox.close(); this.sessionMirror.close(); this.pendingPermissionStore.close(); this.refusedPrompts.close(); }, stopProxy: () => this.proxy?.stop(), stopControl: () => this.control?.stop(), closeBus: () => this.bus.close(),
+      clearTerminalStatus: () => this.claims.clearTerminalStatus(), clearProviderTurnWork: () => this.claims.clearWorkKind("provider-turn"), clearSubagentWork: () => this.claims.clearWorkKind("subagent"), clearBackgroundScriptWork: () => this.claims.clearWorkKind("background-script"),
+      endLateClearGrace: () => this.lateClearRecovery.endGrace(), clearDeliverySubmitHold: () => { this.deliverySubmitHold = undefined; }, clearSubmitFence: () => { this.submitFenceRaised = false; },
+      clearHeldSubmit: () => { this.heldSubmit = emptyHeldSubmit(); }, clearSubmitDeliveryAttempts: () => this.submitDeliveryAttempts.clear(),
+      settleTerminalTokenUsage: () => this.sessionMirror.settleTerminalTokenUsage(), terminalStatusLatched: () => this.lifecycle.terminalStatusLatched,
+      restoreProviderSessionId: (value) => { this.providerSessionId = value; }, restoreLastTranscriptPath: (value) => { this.lastTranscriptPath = value; },
+      clearPreDestroyRun: () => this.turnReport.clearPreDestroyRun(), reopenProviderStatus: () => this.lifecycle.reopenProviderStatus(), resumeHeartbeat: () => this.bus.resumeHeartbeat(),
+    });
+    this.lifecycleCommands = new LifecycleCommands({
+      options: this.options, agentId: this.agentId, process: () => this.process,
+      restartProvider: (opts) => this.restartProvider(opts), shutdownProvider: (hard, timeoutMs) => this.shutdownProvider(hard, timeoutMs), releaseSubmitHold: (resend) => this.releaseSubmitHold(resend),
+      hasProviderTurn: () => this.claims.activeWork().some((work) => work.kind === "provider-turn"), sessionLog: (message) => this.sessionLog(message), resetEmptyTurns: () => this.emptyTurns.reset(),
+      scheduleInterruptReconcile: () => this.busyReconciler.scheduleInterruptReconcile(), waitForProviderTurnClear: () => this.busyReconciler.waitForProviderTurnClear(), injectPrompt: (params) => this.promptCommands.injectPrompt(params),
+      markStopped: () => this.lifecycle.markStopped(), armTerminal: () => this.lifecycle.armTerminal(), setLifecycleAction: (action) => this.lifecycle.setLifecycleAction(action), publishStatus: () => this.publishStatus(),
+    });
+    this.commandDispatch = new CommandDispatch({
+      options: this.options, agentId: this.agentId, reserveInput: () => this.providerInput.reserve(), disarmForcedContext: (type) => this.registration.disarmForcedContext(type),
+      beginExitCommand: () => this.lifecycle.beginExitCommand(), setLifecycleAction: (action) => this.lifecycle.setLifecycleAction(action), isStopped: () => this.lifecycle.stopped,
+      beginNativeSelfResume: (type, params, id) => this.beginNativeSelfResume(type, params, id), runNativeSelfResume: (handoff, operation) => this.nativeSelfResume.run(handoff, operation),
+      rejectNativeSelfResume: (handoff, error) => this.nativeSelfResume.reject(handoff, error), finishNativeSelfResume: (handoff) => this.nativeSelfResume.finish(handoff),
+      beginSelfResumeClearFence: (type, params, id) => this.beginSelfResumeClearFence(type, params, id), startCommandClaim: (id) => this.claims.startClaim("command", id), finishCommandClaim: (id) => this.claims.finishClaim("command", id),
+      runPreSessionDestroy: (reason) => this.turnReport.runPreSessionDestroy(reason), publishStatus: () => this.publishStatus(), restart: (params) => this.lifecycleCommands.restart(params), reconnect: () => this.lifecycleCommands.reconnect(),
+      compactCommand: (params, handoff, id) => this.compactCommand(params, handoff, id), clearContextCommand: (params, ticket, id) => this.clearContextCommand(params, ticket, id),
+      releaseSubmitHold: (params) => this.lifecycleCommands.releaseSubmitHold(params), interrupt: (params) => this.lifecycleCommands.interrupt(params),
+      injectContext: (params, ticket) => { if (!this.process) throw new Error("provider process is unavailable"); return this.injectContext(params, ticket); },
+      respondToPermissionDecision: (params) => this.promptCommands.respondToPermissionDecision(params), injectPrompt: (params, ticket, id) => this.promptCommands.injectPrompt(params, ticket, id),
+      shutdown: (type, params) => this.lifecycleCommands.shutdown(type, params), finishClearCommand: (id) => this.finishClearCommand(id),
+      setOffline: () => this.http.setStatus(this.agentId, "offline", this.options.instanceId), deleteAgent: () => this.http.deleteAgent(this.agentId), stop: () => this.stop(),
+      updateCommand: (id, input) => this.bus.updateCommand(id, input), fetchCommand: (id) => this.http.request("GET", `/api/commands/${encodeURIComponent(id)}`), destructiveInputUnsettled: (id) => this.contextResets.unsettled(id), checkAcknowledgement: (ack, status) => this.nativeSelfResume.checkAcknowledgement(ack, status),
+    });
+    this.attachmentCacheSweep = new AttachmentCacheSweep(this.agentId, (message) => this.logRunnerDiagnostic(message));
+    // #2142 — "latest wins" test-run dedup, scoped to THIS session's command-owning provider
+    // process tree. Interactive Codex exposes a visible TUI pid separately from its App Server;
+    // commands descend from the latter, so resolveTestRunRootPid prefers the runner-owned child.
+    // No pid ⇒ no scope ⇒ no signalling: a sweep that cannot prove ownership must never act.
+    const sessionProviderPid = () => resolveTestRunRootPid(this.process, (managedProcess) => this.options.adapter.resolveBusyPid?.(managedProcess));
+    // #2461 — ancestry alone made this sweep a no-op for `relay_run` gate runs (a disjoint tree
+    // under the orchestrator). It now also owns anything env-tagged with this agent's id, classifies
+    // against the repo's CONFIGURED gate commands, and defers to the launch-time lease holder. The
+    // config read is cached for the session — it is a repo file, so re-reading it every 15s for the
+    // agent's whole life buys nothing. All three helpers live in their own leaves.
+    this.gateRunLeaseProbe = new GateRunLeaseProbe(this.agentId, TEST_RUN_DEDUP_SWEEP_MS);
+    this.testRunDedupSweep = new TestRunDedupSweep({
+      rootPid: sessionProviderPid, agentId: () => this.agentId,
+      gateCommands: () => cachedGateRunCommandsForCwd(this.options.cwd),
+      leaseHolderPid: () => this.gateRunLeaseProbe.pid(),
+      protectedPids: () => [process.pid], log: (message) => this.logRunnerDiagnostic(message),
+    });
+    this.context.configureLogger();
+    this.credentials = new Credentials(options, {
+      isStopped: () => this.lifecycle.stopped,
+      renewRuntimeToken: () => this.http.renewRuntimeToken(),
+      remintRuntimeToken: (reason) => this.http.remintRuntimeToken(reason),
+      onTokenChanged: (token, record) => {
+        publishRuntimeTokenForCli(token, record.expiresAt, (message) => this.logRunnerDiagnostic(message));
+        this.http.setToken(token);
+        this.bus.setToken(token);
+        // The proxy reads the token live via getToken(), so forwarding already uses the new one.
+        // A re-mint can change scope (e.g. a profile change), so refresh the relay tool list and
+        // emit tools/list_changed if the visible set changed (#215 — token-scope transition).
+        // #2973 — a re-register follows a relay restart (a deploy): re-list so changed tools reach the agent.
+    void this.proxy?.refreshTools().catch(() => {});
+      },
+      resumeLivenessAndPublishRotation: (status, jti) => {
+        this.httpLiveness.resetAuthFailure();
+        // An earlier auth failure may have stopped the liveness loop; restart it so the
+        // agent reports live again on the fresh token. startHttpLiveness clears any
+        // existing timer first, so this is safe on the normal (proactive) renew path too.
+        this.startHttpLiveness();
+        this.pendingTimelineEvent = { status, id: jti, timestamp: Date.now() };
+        this.bus.reconnectTransport(status === "runtime-token-reminted" ? "runtime token re-minted" : "runtime token renewed");
+        this.publishStatus();
+      },
+      publishRenewalFailure: () => {
+        this.pendingTimelineEvent = { status: "runtime-token-renewal-failed", timestamp: Date.now() };
+        this.publishStatus();
+      },
+      logRunnerDiagnostic: (message) => this.logRunnerDiagnostic(message),
+      reportBackgroundRejection: (scope, status, title, error) => this.reportBackgroundRejection(scope, status, title, error),
+    });
+    const token = this.credentials.current();
+    if (token) publishRuntimeTokenForCli(token, this.credentials.expiresAt, (message) => this.logRunnerDiagnostic(message));
+    this.mcpProxyEnabled = mcpProxyEnabledFromEnv();
+    this.mcpProxySecret = crypto.randomUUID();
+    const runtime = runtimeMetadata(options.provider);
+    this.context.initializeHttp(this.credentials.current());
+    this.options.adapter.configureTokenUsageReporter?.({
+      report: (record) => this.tokenUsageCoverage.report(record, (r) => this.http.reportTokenUsage(this.agentId, r)),
+      capture: (key, read, pending) => this.tokenUsageCoverage.capture(key, read, pending),
+      debug: (message) => this.sessionDebug(message),
+      // Capture/POST failures must be visible at INFO alongside empty passes (#2491).
+      reportFailure: (error) => this.sessionLog(`token-usage capture failed: ${errMessage(error)}`),
+    });
+    this.providerQuotaHarvest = new ProviderQuotaHarvest({
+      agentId: this.agentId,
+      provider: options.provider,
+      // #2514 — the per-provider config env carries a dedicated-home provider's (claude-b's) own
+      // credential, which the quota harvest needs to key its reports under the B subscription.
+      providerConfigEnv: () => this.options.providerConfig.env,
+      http: () => this.http,
+    });
+    this.httpLiveness = new HttpLiveness({
+      http: this.http, agentId: this.agentId, instanceId: options.instanceId, logIntervalMs: HTTP_LIVENESS_LOG_INTERVAL_MS,
+      isStopped: () => this.lifecycle.stopped, isTerminalStatusLatched: () => this.lifecycle.terminalStatusLatched,
+      currentStatus: () => this.claims.currentStatus(),
+      publishQuota: () => this.providerQuotaHarvest.publish(),
+      bootstrapUnreadMessages: () => this.bootstrapUnreadMessages(), triggerEffort: () => this.effort.trigger(),
+      recoverRuntimeTokenAfterAuthFailure: (source) => this.credentials.recoverRuntimeTokenAfterAuthFailure(source),
+      logRunnerDiagnostic: (message) => this.logRunnerDiagnostic(message),
+    });
+    this.taskClaims = new TaskClaims({
+      http: this.http, agentId: this.agentId,
+      startClaim: (kind, id, expiresAt) => this.claims.startClaim(kind, id, expiresAt),
+      finishClaim: (kind, id) => this.claims.finishClaim(kind, id),
+      isDrainingMessage: (messageId) => this.drainingMessageIds?.has(messageId) === true,
+      updateTaskStatus: async (taskId, input) => { await this.http.updateTaskStatus(taskId, input); },
+      enqueueCompletion: (record) => this.outbox.enqueue(record),
+      publishStatus: () => this.publishStatus(),
+    });
+    this.obligationCache = new ReplyObligationCache({ fetch: () => this.http.listReplyObligations(this.agentId) });
+    // Co-locate the durable outbox with the runner's runtime state (survives reboot) when the
+    // orchestrator told us where that is; otherwise the Outbox falls back to a temp dir.
+    const outboxDir = runnerOutboxDirWithInfoFallback();
+    this.refusedPrompts = new RefusedPromptStore({ agentId: this.agentId, dir: outboxDir });
+    this.outbox = new Outbox({ agentId: this.agentId, dir: outboxDir, send: (record) => record.kind === "task-completion" ? this.taskClaims.deliverCompletion(record) : this.sessionMirror.deliverOutboxEvent(record) });
+    this.sessionMirror = new SessionMirror({
+      agentId: this.agentId, provider: options.provider, instanceId: options.instanceId, startedAt: options.startedAt,
+      relayUrl: options.relayUrl, outboxDir, http: this.http, adapter: options.adapter,
+      getToken: () => this.credentials.current(),
+      updateOutboxPayload: (seq, payload) => this.outbox.updatePayload(seq, payload),
+      recoverRuntimeTokenAfterAuthFailure: (source) => this.credentials.recoverRuntimeTokenAfterAuthFailure(source),
+      sessionLog: (message) => this.sessionLog(message),
+      sessionTurnContext: () => this.turnReport.sessionTurnContext(),
+      lastTranscriptPath: () => this.lastTranscriptPath,
+      currentTurnId: () => this.currentTurnId,
+      reasoningCapture: () => this.options.providerConfig.reasoningCapture,
+      isRunnerInjectedPrompt: (text) => this.isRunnerInjectedPrompt(text),
+      publishProviderResponse: (event, body, turnId) => this.turnReport.publishProviderResponse(event, body, turnId),
+    });
+    this.turnReport = new TurnReport({
+      agentId: this.agentId, provider: options.provider, adapter: options.adapter, providerConfig: options.providerConfig, http: this.http,
+      currentTurnId: () => this.currentTurnId, currentTurnStartedAt: () => this.currentTurnStartedAt,
+      setTurnId: (id) => { this.currentTurnId = id; }, setTurnStartedAt: (at) => { this.currentTurnStartedAt = at; },
+      lastTranscriptPath: () => this.lastTranscriptPath, noteTranscriptPath: (path) => { this.lastTranscriptPath = path; },
+      providerSessionId: () => this.providerSessionId,
+      queuedTurnFollows: () => this.queuedTurnFollows, setQueuedTurnFollows: (queued) => { this.queuedTurnFollows = queued; },
+      settlePollIntervalMs: () => this.settlePollIntervalMs, settlePollTimeoutMs: () => this.settlePollTimeoutMs,
+      beginTurnCapture: () => this.sessionMirror.beginTurnCapture(), endTurnCapture: () => this.sessionMirror.endTurnCapture(),
+      flushSessionEvents: (timeoutMs) => this.sessionMirror.flushSessionEvents(timeoutMs),
+      pendingSessionEventCount: () => this.sessionMirror.pendingSessionEventCount(),
+      publishSessionEvent: (event) => this.sessionMirror.publishSessionEvent(event),
+      reportOutbox: { enqueue: (record) => this.sessionMirror.enqueueResponseReport(record) },
+      flushOutbox: (timeoutMs) => this.outbox.flush(timeoutMs),
+      settleTerminalTokenUsage: (path) => this.sessionMirror.settleTerminalTokenUsage(path),
+      noteOutput: () => this.emptyTurns.noteOutput(), notePrompt: (text, at) => this.nativeSelfResume.notePrompt(text, at),
+      isRunnerInjectedPrompt: (text) => this.isRunnerInjectedPrompt(text),
+      deliverySubmitHold: () => Boolean(this.deliverySubmitHold), tryRecoverProviderSubmitHold: (started) => this.tryRecoverProviderSubmitHold(started),
+      lifecycleAction: () => this.lifecycle.lifecycleAction, isStopped: () => this.lifecycle.stopped, terminalStatusLatched: () => this.lifecycle.terminalStatusLatched,
+      setLifecycleAction: (action) => this.lifecycle.setLifecycleAction(action),
+      noteFinalizing: (action, at) => this.lifecycle.notePublishedFinalizing(action, at),
+      publishRunnerStatus: (update) => this.publishRunnerStatus(update), publishStatus: () => this.publishStatus(),
+      captureContextRatio: (reason, opts) => this.captureContextRatio(reason, opts),
+      captureContinuationArchive: (reason, opts) => this.captureContinuationArchive(reason, opts),
+      responseCaptureReplyRoute: (startedAt, suppressUser) => responseCaptureReplyRoute(this.obligationCache.get(), startedAt, { suppressUser }),
+      dirtyObligations: () => this.obligationCache.markDirty(),
+      sessionLog: (message) => this.sessionLog(message), sessionDebug: (message) => this.sessionDebug(message),
+    });
+    this.pendingPermissionStore = new PendingPermissionStore({ agentId: this.agentId, dir: outboxDir });
+    this.insights = new RunnerInsights({
+      agentId: this.agentId,
+      cwd: options.cwd,
+      workspace: options.workspace,
+      getOutbox: () => this.outbox,
+      getProviderSessionId: () => this.providerSessionId,
+      getProcess: () => this.process,
+      getAdapter: () => this.options.adapter,
+      getLastTranscriptPath: () => this.lastTranscriptPath,
+      sessionLog: (message) => this.sessionLog(message),
+    });
+    this.registerProviderSessionRoutes();
+    this.busyReconciler = new BusyReconciler({
+      isStopped: () => this.lifecycle.stopped,
+      hasProcess: () => Boolean(this.process),
+      currentStatus: () => this.claims.currentStatus(),
+      isProviderBlocked: () => this.providerBlocked,
+      hasProviderTurn: () => this.claims.activeWork().some((w) => w.kind === "provider-turn"),
+      canProbeActivity: () => Boolean(this.options.adapter.probeActivity),
+      probeActivity: () => this.process && this.options.adapter.probeActivity
+        ? this.options.adapter.probeActivity(this.process)
+        : undefined,
+      probePaneBusy: () => this.process && this.options.adapter.probePaneBusy
+        ? this.options.adapter.probePaneBusy(this.process)
+        : undefined,
+      clearProviderTurn: (reason) => this.forceClearProviderTurn(reason),
+      escalateWatchdog: (reason) => this.escalateProviderTurnWatchdog(reason),
+      turnCleared: () => { this.effort.turnCleared(); if (this.pendingMessages.size > 0) this.scheduleDrain(); },
+      sessionDebug: (message) => this.sessionDebug(message),
+    });
+    this.context.initializeBus({
+      url: relayBusUrl(options.relayUrl),
+      role: "provider",
+      componentId: options.runnerId,
+      agentId: this.agentId,
+      instanceId: options.instanceId,
+      token: this.credentials.current(),
+      machine: hostname(),
+      capabilities: [
+        ...new Set([
+          ...options.providerConfig.defaultCapabilities,
+          ...options.capabilities,
+          ...csvTags(capsFromEnv()),
+          "lifecycle.shutdown.hard",
+          "lifecycle.restart.hard",
+          "lifecycle.status.semantic",
+          "lifecycle.heartbeat",
+          "lifecycle.reconnect.transport",
+          "commands.lifecycle",
+          "capabilities.report",
+        ]),
+      ],
+      tags: [...new Set([options.provider, ...csvTags(tagsFromEnv()), ...options.tags, ...options.providerConfig.defaultTags, ...(options.headless ? ["headless"] : [])])],
+      meta: runnerIdentityMeta(this.options, { runtime, agentId: this.agentId, tmuxSession: providerTerminalSession(this.process), tmuxSocket: providerTerminalSocket(this.process), auth: { profileId: this.credentials.profileId, jti: this.credentials.jti, expiresAt: this.credentials.expiresAt } }, "registration"),
+      heartbeatMeta: () => this.heartbeatRuntimeMeta(),
+      heartbeatIntervalMs: 30_000,
+      initialStatus: "idle",
+    });
+  }
+
+  get id(): string {
+    return this.agentId;
+  }
+
+  private registerProviderSessionRoutes(): void {
+    // (#1617) — neither publisher has a try/catch of its own, and both bottom out in
+    // sessionOutbox.enqueue: a synchronous bun:sqlite INSERT that throws outright once the outbox
+    // is closed (teardown ordering in stop(): the adapter keeps emitting after close) or the
+    // database errors. This is the highest-frequency fire-and-forget site in the runner — every
+    // provider session event passes through it — so leaving it unguarded is the likeliest way a
+    // live agent silently stops existing (Bun exits(1) on an unhandled rejection, #1614).
+    // #2389 — turn-output evidence is counted HERE, at the registration seam, not inside the
+    // publish functions: `publishProviderSessionEvents` delegates to the single-event path only for
+    // `prompt`/`response` and handles every other type itself, and Claude's reasoning tail emits
+    // ALL of its tool/reasoning steps through that batch. Counting downstream missed them, so a
+    // Claude turn that ran a dozen tools and produced no extractable closing text counted zero.
+    this.options.adapter.onSessionEvent?.((event) => { this.emptyTurns.noteOutput(event); this.areaMemory.noteToolPaths([event]); if (event.type === "prompt") this.nativeSelfResume.notePrompt(event.body, event.occurredAt); void this.sessionMirror.publishProviderSessionEvent(event).catch((error) => this.reportBackgroundRejection("provider session event publish", "session.publish_failed", "Provider session event not mirrored", error)); });
+    this.options.adapter.onSessionEvents?.((events) => { this.areaMemory.noteToolPaths(events); for (const event of events) { this.emptyTurns.noteOutput(event); if (event.type === "prompt") this.nativeSelfResume.notePrompt(event.body, event.occurredAt); } void this.sessionMirror.publishProviderSessionEvents(events).catch((error) => this.reportBackgroundRejection("provider session event batch publish", "session.publish_failed", "Provider session events not mirrored", error)); });
+    // #2389 — output a provider can observe but cannot mirror (an OpenCode tool part, whose wire
+    // shape we deliberately do not guess at). Evidence only; nothing is published.
+    this.options.adapter.onTurnActivity?.(() => this.emptyTurns.noteOutput());
+  }
+
+  // The adapter's status seam, split out of run() (#1617) so the guarded restart call below is
+  // reachable without booting a whole runner — the crash it guards against is exactly the one a
+  // test has to be able to drive.
+  /** Pane evidence can change only the displayed startup dialog and timeline, never work claims. */
+  private recordPaneObservation(observation: PaneObservation): void {
+    const detail = observation.message ? `: ${observation.message}` : "";
+    this.sessionLog(`pane observation ${observation.eventType}/${observation.detectorId}${detail}`);
+    const displayGate = observation.displayGate;
+    if (this.options.approvalMode !== "open" || !displayGate) return;
+    if (displayGate.phase === "clear") {
+      if (this.startupPaneDialog) { this.startupPaneDialog = undefined; this.publishStatus(); }
+      return;
+    }
+    if (this.startupPaneDialog) return;
+    this.startupPaneDialog = displayGate.providerState;
+    this.publishRunnerTimelineEvent({ status: "provider_blocked", timestamp: observation.observedAt,
+      title: displayGate.timelineTitle, body: this.startupPaneDialog.message });
+  }
+
+  private handleAdapterStatusChange(status: ProviderStatusUpdate): void {
+    // #2505 — stop() publishes the runner's terminal edge directly. Once it has started, an
+    // adapter callback can only be stale: an input already inside ProviderInputQueue may finish
+    // after stopStatusWatchers() and arm a fresh provider watcher, while an older watcher may
+    // still be returning from an async probe. Neither is allowed to reopen terminal status.
+    if (this.lifecycle.stopped || this.lifecycle.restartInProgress || this.lifecycle.restartPending) return;
+    this.contextResets.observeStatus(status);
+    const semanticStatus = typeof status === "string" ? status : status.status;
+    if ((semanticStatus === "busy" || semanticStatus === "offline" || semanticStatus === "error") && this.startupPaneDialog) this.startupPaneDialog = undefined;
+    if (this.shouldRestartUnexpectedProviderExit(semanticStatus)) {
+      // (#1617) — restartUnexpectedProviderExit is an outer try/finally with NO catch wrapped
+      // around awaited work that can still throw (recoverNativeSelfResumeExit, the undetermined-
+      // exit confirmation read, the timeline/status publishes). A reject here used to kill the
+      // runner outright: the crash path for the exact situation this method exists to recover
+      // from, on a runner nothing respawns (#1618).
+      void this.restartUnexpectedProviderExit(semanticStatus).catch((error) => this.reportBackgroundRejection("unexpected provider exit restart", "provider.restart_failed", "Provider restart after unexpected exit failed", error));
+      return;
+    }
+    this.setProviderStatus(status);
+    if (runnerShouldResolveProviderExit(semanticStatus, this.lifecycle.exitCommandInProgress)) {
+      const exitCode = semanticStatus === "offline" ? 0 : 1;
+      // #2443 — a provider-reported terminal failure (model retired/404, auth error, exhausted
+      // retries, ...) used to resolve straight to `onProviderExit` with nothing surfaced beyond
+      // the mirror log: the orchestrator's own exit diagnostics tail the process's stdout/stderr
+      // capture, which held only the provider's OWN startup output, not this. Log it here —
+      // generically, off whatever the adapter's failTurn-equivalent reported via `terminalFailure`,
+      // never provider-specific — and hand the reason to the caller so it can be written to
+      // stdout/stderr before the process actually exits (see index.ts's onProviderExit).
+      const reason = exitCode !== 0 && this.terminalFailure ? `${this.terminalFailure.reason}: ${this.terminalFailure.message}` : undefined;
+      if (reason) logger.error("runner", `exiting after a terminal provider failure: ${reason}`);
+      this.options.onProviderExit?.(exitCode, reason);
+    }
+  }
+
+  async run(): Promise<void> {
+    this.control = startControlServer({
+      onStatus: (status) => { if (!this.options.adapter.reportsContextResets) this.contextResets.observeStatus(status); this.setProviderStatus(status); },
+      onTerminalAttachSpec: () => this.terminalAttachSpec(),
+      // #2459 — the current non-secret attachment generation, resolved from the live process
+      // the same way terminalAttachSpec reads it. Only wired when the adapter declares one;
+      // absent ⇒ the endpoint reports no generation and the orchestrator skips the check.
+      onTerminalGeneration: () => Promise.resolve(this.process ? this.options.adapter.terminalAttachGeneration?.(this.process) : undefined),
+      // Hot-path-safe: answered instantly from the local snapshot, never a server
+      // round-trip. The snapshot is kept warm by the background refresh below (#196).
+      onReplyObligations: () => this.obligationCache.freshForNag(),
+      onSubagentUsage: this.options.adapter.captureSubagentTokenUsage?.bind(this.options.adapter),
+      onSessionTurn: (input) => this.turnReport.publishSessionTurn(input), onPermissionResolved: (input) => this.sessionMirror.publishSessionEvent({ from: this.agentId, to: "user", body: input.body, occurredAt: input.occurredAt, session: { type: "prompt-resolution", origin: "provider", label: input.decisionLabel, ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}), stepId: `prompt-resolution:${input.approvalId}`, promptResolution: input } }),
+      onPermissionAbandoned: (input) => this.publishPermissionAbandonedNotice(input),
+      onAnswerInject: (input) => this.promptCommands.injectAnswerPrompt(input), onQuestionDecision: (input) => fileQuestionDecision({ http: this.http, profile: this.options.profile, log: (message) => this.sessionLog(message) }, input),
+      onUserPrompt: (input) => this.turnReport.handleUserPrompt(input), ...this.areaMemory.controlHooks(this.options.adapter, (input) => this.options.adapter.handleHookCheck?.(input, this.turnReport.sessionTurnContext())),
+      onSessionBoundary: (input) => this.turnReport.handleSessionBoundary(input),
+      onSessionStart: (input) => this.recoverLateClear(input),
+      onHookFatal: (report) => this.reportHookFatal(report),
+      instanceId: this.options.instanceId,
+      pendingPermissionStore: this.pendingPermissionStore,
+      permissionPromptHandler: this.options.adapter.permissionPromptHandler, autoApprovePermissions: this.options.approvalMode === "open",
+      providerSourceId: this.options.adapter.statusSourceId ?? this.options.provider,
+      stopObligationPath: this.options.adapter.stopObligationPath,
+      monitorUnavailableMessage: providerMonitorUnavailableMessage(this.options.provider),
+    });
+    this.startMcpProxy();
+    this.registration.writeRunnerInfoFile();
+    this.options.adapter.onStatusChange((status) => this.handleAdapterStatusChange(status));
+    this.options.adapter.onPaneObservation?.((observation) => this.recordPaneObservation(observation));
+    this.registerProviderSessionRoutes();
+    this.bus.on("message.new", (message) => {
+      // A delivered message may create a new reply obligation — warm the snapshot so the
+      // next turn-end sees it without a hot-path server read.
+      const msg = message as Message;
+      if (runnerMessageShouldDirtyObligations(msg, this.agentId)) this.obligationCache.markDirty();
+      this.enqueueMessage(msg);
+    });
+    this.bus.on("command", (type, params, commandId, command) => {
+      this.commandDispatch.dispatchCommand(type, params, commandId, command);
+    });
+    this.bus.on("registered", () => this.handleBusRegistered());
+    this.bus.on("event", (eventType, data) => {
+      if (eventType.startsWith("command.") && data && typeof data === "object" && "command" in data) this.nativeSelfResume.settleCommand(data.command as Record<string, unknown>);
+      if (isEffortNotice(eventType, data)) this.effort.trigger();
+    });
+    this.bus.on("error", (code, message) => this.handleBusError(String(code), String(message)));
+    await registerWithinDeadline(this.bus, registrationTimeoutMsFromEnv(), this.options.relayUrl, (reason) => logger.fatal("register", reason));
+    await this.bus.subscribe(["command.*"]);
+    this.registeredAt = Date.now();
+    this.registration.writeRunnerInfoFile();
+    await initializeRunnerTemplates(this.http);
+    this.obligationCache.start();
+    this.outbox.start();
+    this.sessionMirror.start();
+    this.ensureScratch();
+    void sweepRunnerStaleScratch({ listAgents: () => this.http.listAgents(), agentId: this.agentId, cwd: this.options.cwd, fallbackBaseDir: orchestratorBaseDirFromEnv(), log: (message) => this.logRunnerDiagnostic(message) });
+    this.scheduleAttachmentCacheSweep();
+    this.adoptProcess(await this.spawnProvider());
+    this.registration.writeRunnerInfoFile();
+    await this.promptCommands.startLaunchSeededTurn();
+    this.publishStatus();
+    await this.promptCommands.deliverInitialPrompt();
+    await this.bootstrapUnreadMessages();
+    this.taskClaims.start();
+    this.startHttpLiveness();
+    this.testRunDedupSweep.start();
+    this.gateRunLeaseProbe.start();
+    this.credentials.scheduleRuntimeTokenRenewal();
+    this.scheduleDrain();
+  }
+
+  markShuttingDown(): void { this.lifecycle.markShuttingDown(); }
+
+  async stop(): Promise<void> {
+    const alreadyStopped = this.lifecycle.beginStop();
+    this.lifecycleMilestones.onStop("teardown-started", alreadyStopped);
+    this.lifecycleMilestones.onStop("background-stopped");
+    if (this.process && !alreadyStopped) await this.lifecycleMilestones.onStop("provider-shut-down");
+    this.lifecycleMilestones.onStop("offline-published", alreadyStopped);
+    this.lifecycleMilestones.onStop("timers-stopped");
+    await this.lifecycleMilestones.onStop("closed");
+  }
+
+  // Start the local MCP proxy the agent connects to (Stage 2, #215). Forwards tool calls to the
+  // relay with the runner's LIVE token, buffers bufferable writes durably during a relay outage,
+  // and narrows the tool list to this agent's workspace context. Best-effort: if it can't bind,
+  // we fall back to a direct relay MCP connection (the agent env still works, no resilience).
+  // #1450 — the on-demand relay set to hide from a lean worker's DIRECT relay client (so only the
+  // eager hot-path set boots), or undefined for any agent that keeps its full relay surface. The
+  // gate MIRRORS the callmux relay-downstream gate (launch-assembly) EXACTLY — worker profile,
+  // runner-managed deferral, sharedMcp on (the metaOnly callmux that fronts these exists), relay mcp
+  // on, no web tool off (#3024) — so the direct client is narrowed only when callmux fronts the set.
+  // ("proxy active" is implicit: only a constructed proxy consults this, and the relay downstream is
+  // added only when the proxy is active — the two are on/off together, never a half state.)
+  private startMcpProxy(): void {
+    if (!this.mcpProxyEnabled) return;
+    const onDemandTools = runnerMcpHiddenTools(this.options.provider, this.options.agentProfile);
+    const started = startRunnerMcpProxy({
+      webToolLog: runnerWebToolLog(Boolean(this.options.agentProfile?.sharedMcp), resolveSharedMcpUrl(),
+        () => ({ agentId: this.agentId, provider: this.options.provider, model: this.options.model ?? this.latestProbeMetrics()?.model ?? null, effort: this.effortRuntime.effort ?? this.latestProbeMetrics()?.effort ?? null }),
+        call => this.http.request("POST", "/api/web-tool-calls", call), process.env, runnerWebSearch(this.http)),
+      redactToolResponse: this.options.adapter.mcpToolResponseRedactor?.(this.options.cwd),
+      relayMcpEndpoint: relayMcpEndpoint(this.options.relayUrl, this.context.mcpToolGeneration),
+      getToken: () => this.credentials.current(),
+      authSecret: this.mcpProxySecret,
+      enqueueBuffered: call => this.outbox.enqueue({ kind: "mcp-tool-call", payload: { tool: call.tool, arguments: call.arguments }, idempotencyKey: call.idempotencyKey }),
+      initialContext: { isolatedWorktree: this.ownsIsolatedWorktree(), workspaceDescriptor: isolatedWorkspaceDescriptor(this.options.workspace, this.ownsIsolatedWorktree()) },
+      ...(onDemandTools ? { onDemandTools } : {}),
+    });
+    this.proxy = started.proxy;
+    this.mcpProxyEndpoint = started.endpoint;
+  }
+
+  private handleBusRegistered(): void {
+    void this.nativeSelfResume.reconcile((id) => this.http.request("GET", `/api/commands/${encodeURIComponent(id)}`)).catch((error) => this.sessionLog(`compact settlement reconcile: ${errMessage(error)}`));
+    // #2973 — a re-register follows a relay restart (a deploy): re-list so changed tools reach the agent.
+    void this.proxy?.refreshTools().catch(() => {}); this.effort.trigger();
+  }
+
+  private ownsIsolatedWorktree(): boolean {
+    const mode = this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? workspaceModeFromEnv();
+    return mode === "isolated";
+  }
+
+  // #2966 — publish the new incarnation's capabilities (effortSwitch) before its first turn: the
+  // heartbeat spawnProvider resumes still describes the previous process, and the next is ~30s away.
+  private adoptProcess(process: ManagedProcess): void {
+    this.process = process;
+    this.processStartedAt = Date.now();
+    this.bus.flushHeartbeat(); this.effort.trigger();
+  }
+
+  private async spawnProvider(opts: RestartProviderOptions = {}): Promise<ManagedProcess> {
+    this.providerSessionId = crypto.randomUUID();
+    // A provider spawn is the incarnation boundary. Old teardown captures and source fences must
+    // not leak into the replacement, while the bus transport itself remains reusable.
+    this.turnReport.clearPreDestroyRun();
+    this.lifecycle.reopenProviderStatus();
+    this.lastTranscriptPath = undefined;
+    // #2550 — a new provider process is a new context generation: its (empty) context may
+    // legitimately receive the same charter/memory bytes again, so the dedupe table resets.
+    this.resetContextGeneration();
+    const providerEnv = selectProviderConfigEnv(this.options.providerConfig.env, hostSourcesFor(this.options).settings);
+    const env = writeChildEnv({}, {
+      ...resolveEnvLayers([process.env, providerEnv]),
+      ...(this.context.mcpToolGeneration === "humwick" ? { AGENT_RELAY_MCP_TOOLS: this.context.mcpToolGeneration } : {}),
+      AGENT_RELAY_RUNNER_PORT: String(this.control!.port),
+      AGENT_RELAY_RUNNER_ID: this.options.runnerId,
+      AGENT_RELAY_PROVIDER_SESSION_ID: this.providerSessionId,
+      AGENT_RELAY_ID: this.agentId,
+      // The repo-name project id the runner uses for insight observations. Exposed so
+      // agent-side signals (e.g. /introspect) tag the SAME project and aggregate together,
+      // instead of the agent's worktree cwd splitting one repo into many "projects".
+      AGENT_RELAY_PROJECT: this.insightProject(),
+      ...(this.scratch ? { AGENT_RELAY_SCRATCH_DIR: this.scratch.tmpDir } : {}),
+      ...await agentShellLaunchEnv(this.agentId, providerEnv),
+      AGENT_RELAY_URL: this.options.relayUrl,
+      AGENT_RELAY_APPROVAL: this.options.approvalMode,
+      ...(this.credentials.current() ? { AGENT_RELAY_TOKEN: this.credentials.current()! } : {}),
+      // Dedicated, un-clobberable credential for the injected MCP endpoint. A rig's
+      // settings.json `env.AGENT_RELAY_TOKEN` would override the scoped token above at
+      // MCP-parse time → server-actor auth, no identity (#233). The MCP config references
+      // ${AGENT_RELAY_SESSION_TOKEN}, which rigs never set. See runner/src/relay-mcp.ts.
+      //
+      // Stage 2 (#215): when the proxy is active the agent connects to the LOCAL proxy, so this
+      // holds the per-session PROXY SECRET (not the relay token). The proxy injects the live
+      // relay token itself — the agent never holds it, and token rotation is invisible. With the
+      // proxy disabled this stays the scoped relay token (Stage-1 direct connection).
+      ...(this.proxy
+        ? { [RELAY_MCP_TOKEN_ENV]: this.mcpProxySecret }
+        : (this.credentials.current() ? { [RELAY_MCP_TOKEN_ENV]: this.credentials.current()! } : {})),
+      ...(this.credentials.jti ? { AGENT_RELAY_TOKEN_JTI: this.credentials.jti } : {}),
+      ...(this.credentials.profileId ? { AGENT_RELAY_TOKEN_PROFILE: this.credentials.profileId } : {}),
+      ...(this.credentials.expiresAt ? { AGENT_RELAY_TOKEN_EXPIRES_AT: String(this.credentials.expiresAt) } : {}),
+    });
+    const config = buildRunnerSpawnConfig({ ...this.options, effort: this.effortRuntime.effort }, {
+      getRelayToken: () => this.credentials.current(),
+      agentId: this.agentId,
+      env,
+      controlPort: this.control!.port,
+      ...(opts.resumeId ? { resumeId: opts.resumeId } : {}),
+      ...(opts.suppressPrompt ? { suppressPrompt: true } : {}),
+      ...(opts.systemPromptAppend ? { systemPromptAppend: opts.systemPromptAppend } : {}),
+      // Stage 2 (#215): the MCP endpoint the agent's client should target — the runner-local
+      // proxy when active, undefined when disabled (adapters fall back to the direct relay URL).
+      ...(this.mcpProxyEndpoint ? { relayMcpEndpoint: this.mcpProxyEndpoint } : {}),
+      // #1450: the proxy secret, exposed to the assembler ONLY when the proxy is active, so the
+      // Codex per-agent metaOnly callmux can reach the relay endpoint on-demand THROUGH the proxy
+      // (live-token-injected — never the relay token on disk, #215).
+      ...(this.mcpProxyEndpoint ? { mcpProxySecret: this.mcpProxySecret } : {}),
+      // #672: the shared host-listener URL the `callmux bridge` connects to (env → default).
+      // Always resolved; the assembler only emits the bridge when `agentProfile.sharedMcp` is on.
+      sharedMcpUrl: this.proxy?.webToolsUrl ?? resolveSharedMcpUrl(),
+      monitor: {
+        deliver: (messages) => this.control!.deliverToMonitor(messages),
+      },
+    });
+    const launchSeededPrompt = this.promptCommands.noteLaunchSeededPrompt(opts);
+    // Provider-owned hydration refreshes every spawn/restart and keeps provider-specific I/O out
+    // of the runner core. Assembly sees only the resulting snapshot.
+    const { hydratedConfig, managedProcess } = await (async () => {
+      try {
+        return await spawnWithServiceAccess(this.http, config, this.options.adapter, this.providerSessionId, Boolean(this.options.profile && this.options.spawnRequestId));
+      } finally {
+        // A failed replacement remains observable through the runner's status projection. Do not
+        // also strand the reusable bus with heartbeats, quota/context metadata, and its ack
+        // watchdog suspended for the rest of this runner process.
+        if (!this.lifecycle.stopped && !this.lifecycle.shuttingDown) this.bus.resumeHeartbeat();
+      }
+    })();
+    if (launchSeededPrompt) managedProcess.meta = { ...managedProcess.meta, launchSeededTurn: true };
+    const injectionEvents = runnerLaunchInjectionSessionEvents({ carried: opts.relayInjectionEvents ?? this.options.relayInjectionEvents, provider: this.options.provider, config: hydratedConfig, providerConfig: this.options.providerConfig, agentId: this.agentId, providerSessionId: this.providerSessionId });
+    for (const event of injectionEvents) {
+      this.sessionMirror.publishSessionEvent(event);
+    }
+    return managedProcess;
+  }
+
+  private async terminalAttachSpec(): Promise<TerminalAttachSpec> {
+    if (!this.process) throw new Error("provider process is unavailable");
+    if (!this.options.adapter.terminalAttachSpec) throw new Error("provider does not support terminal attach");
+    return this.options.adapter.terminalAttachSpec(this.process);
+  }
+
+  private enqueueMessage(message: Message): void {
+    if (!this.matchesMessage(message)) return;
+    // #2539 live-fire — a message this runner is ALREADY delivering (in this snapshot's drain,
+    // so a stale server-list copy racing the offer) or has already SETTLED (acked + marked read)
+    // is DONE: neither may re-enter the queue and be re-delivered (as a soft-steer into the very
+    // turn that consumed it, or at turn-end). The in-flight check clears in the drain's finally,
+    // so every legitimate requeue path (unacked, claim failure) re-enqueues fine.
+    if (this.drainingMessageIds?.has(message.id) || this.heldSubmit.messages.has(message.id)) return;
+    if (this.settledMessageIds.has(message.id)) return;
+    // #2539 Phase B — an id handed to the soft-steer lane (persisted, awaiting consumption) is in
+    // the adapter's ledger custody: a stale snapshot re-enqueue would double-POST the same body
+    // into the live turn. Same class as the settled guard above; the reoffer seam is the only way
+    // an awaiting id returns to this queue.
+    if (this.awaitingMidTurnDelivery.has(message.id)) return;
+    // #2619 — a provider-refused id is parked until the provider takes a turn again; a poll
+    // snapshot re-enqueueing it would re-POST it into the wall.
+    if (this.hold.isParked(message.id)) return;
+    // #2619 — the relay's push of a refused prompt's own inbox row: it binds the pending park (the
+    // push can beat the self-post's response), or — its caller already failed — is settled.
+    const heldPromptKey = message.payload?.heldPromptKey;
+    if (typeof heldPromptKey === "string" && this.hold.isPending(heldPromptKey)) {
+      this.refusedPrompts.confirm(heldPromptKey);
+      this.releaseParked(this.hold.bind(heldPromptKey, message));
+      return;
+    }
+    if (typeof heldPromptKey === "string" && this.refusedPrompts.isUnconfirmed(heldPromptKey)) {
+      void this.settleSilently(message).catch(() => {}); // markRead failures are already swallowed inside
+      return;
+    }
+    // #2029 — the wake:false / kind:session suppression is now decided ONCE server-side (decideDelivery)
+    // and the server no longer emits a turn frame for it, so no client-side `payload.wake` / `kind`
+    // policy branch survives here. What remains is a belt-and-braces structural check, shared with the
+    // SDK provider tail (frameSuppressedFromTurn) so the two clients cannot drift: obey a non-`turn`
+    // delivery stamp if one ever rides in on a frame (e.g. a re-injected obligation, or a stale server).
+    if (frameSuppressedFromTurn(message)) return;
+    const pending = this.pendingMessages.get(message.id);
+    this.pendingMessages.set(message.id, message);
+    if (this.deliverySubmitHold) this.tryRecoverProviderSubmitHold(false);
+    this.scheduleDrain();
+  }
+
+  private async bootstrapUnreadMessages(): Promise<void> {
+    try {
+      const messages = await this.http.pollMessages({ for: this.agentId, unread: true, limit: 100, turnDelivery: true });
+      for (const message of messages) this.enqueueMessage(message);
+    } catch (error) {
+      logger.error("runner", `inbox bootstrap failed: ${error}`);
+    }
+  }
+
+  private scheduleDrain(delayMs = 0): void {
+    if (this.lifecycle.stopped || this.drainTimer || this.deliverySubmitHold || this.submitResendInFlight) return;
+    this.drainTimer = setTimeout(() => {
+      this.drainTimer = undefined;
+      void this.drainMessages();
+    }, delayMs);
+  }
+
+  private holdFailedProviderSubmit(detail: string, held: { messages?: Message[]; resend?: () => Promise<unknown> } = {}): void {
+    for (const message of held.messages ?? []) this.heldSubmit.messages.set(message.id, message);
+    // The FIRST unconfirmed prompt is the one the operator resends; a later refusal must not replace it.
+    this.heldSubmit.resend ??= held.resend;
+    this.deliverySubmitHold = {
+      state: "blocked", reason: PROVIDER_SUBMIT_UNCONFIRMED, label: "Provider prompt needs inspection",
+      message: detail, source: "provider-input-submit", terminal: true,
+      recommendedAction: "Inspect the provider input. If the prompt was not accepted, release the hold and resend it; if it was, release the hold without resending.", enteredAt: Date.now(),
+    };
+    logger.error("delivery", detail);
+    this.startSubmitRecoveryPoll();
+    this.publishRunnerTimelineEvent({ status: "provider_blocked", timestamp: Date.now(), title: "Provider prompt submission unconfirmed", body: detail });
+    this.publishStatus();
+  }
+
+  /** #2664 — the operator's escape hatch: clear the hold and the adapter fence, optionally resend what was held. */
+  private async releaseSubmitHold(resend: boolean): Promise<Record<string, unknown>> {
+    const held = this.heldSubmit;
+    const released = this.deliverySubmitHold !== undefined;
+    this.heldSubmit = emptyHeldSubmit();
+    this.deliverySubmitHold = undefined;
+    this.stopSubmitRecoveryPoll();
+    this.submitFenceRaised = false;
+    if (this.process) this.options.adapter.releaseSubmitHold?.(this.process);
+    this.sessionLog(`provider submit hold released by the operator (${resend ? "resending" : "not resending"} ${held.messages.size} message(s)${held.resend ? " and a prompt" : ""})`);
+    this.publishStatus();
+    if (resend) for (const message of held.messages.values()) { this.submitDeliveryAttempts.delete(message.id); this.pendingMessages.set(message.id, message); }
+    this.submitResendInFlight = resend && held.resend !== undefined;
+    try {
+      if (resend) await held.resend?.();
+    } finally {
+      // Prompts parked behind the hold are inbox rows; they drain after the resend, in id order. A resend
+      // that fails again re-enters the hold, so they stay parked behind it.
+      this.submitResendInFlight = false;
+      if (this.pendingMessages.size > 0) this.scheduleDrain();
+    }
+    return { released, resentMessages: resend ? held.messages.size : 0, resentPrompt: resend && held.resend !== undefined };
+  }
+
+  /**
+   * #2664 — a dashboard prompt that meets the submit hold (at entry, or in its FIFO slot behind the
+   * submit that raised it) parks as a durable self-addressed inbox row: it drains in order once the
+   * hold clears and survives a runner restart like any unread message. Not durable: the command fails.
+   */
+  private async parkPromptBehindSubmitHold(params: Record<string, unknown>, key: string, turn: ProviderInputTicket): Promise<Record<string, unknown>> {
+    return this.parkPosts.run(() => this.postParkedPrompt(params, key), turn);
+  }
+
+  private async postParkedPrompt(params: Record<string, unknown>, key: string): Promise<Record<string, unknown>> {
+    const messageId = typeof params.messageId === "number" ? params.messageId : undefined;
+    const payload = { ...(Array.isArray(params.attachments) ? { attachments: params.attachments } : {}), ...(messageId ? { submitHoldPromptOf: messageId } : {}), [HELD_FOR_PAYLOAD_KEY]: promptOrigin(params) };
+    const posted = await retryParkPost("submit-hold prompt inbox post", () => this.http.sendMessage({ from: this.agentId, to: this.agentId, kind: "chat", subject: "Dashboard prompt held behind an unconfirmed provider submit", body: params.body as string, payload, idempotencyKey: key }));
+    if (!posted) throw new Error("dashboard prompt met the provider submit hold and could not be parked durably; not delivered");
+    this.sessionLog(`dashboard prompt parked behind the provider submit hold as inbox message ${posted.id}`);
+    return { injected: false, parked: true, messageId, parkedMessageId: posted.id };
+  }
+
+  /** Bounded: stops when the hold clears, the runner stops, or the window ends; release/recovery/respawn/teardown stop it too. */
+  private startSubmitRecoveryPoll(): void {
+    if (this.submitRecoveryTimer) return;
+    const until = Date.now() + this.submitRecoveryPollWindowMs;
+    this.submitRecoveryTimer = setInterval(() => {
+      if (!this.deliverySubmitHold || this.lifecycle.stopped || Date.now() >= until) return this.stopSubmitRecoveryPoll();
+      this.tryRecoverProviderSubmitHold(false);
+    }, this.submitRecoveryPollMs);
+  }
+
+  private stopSubmitRecoveryPoll(): void {
+    if (this.submitRecoveryTimer) clearInterval(this.submitRecoveryTimer);
+    this.submitRecoveryTimer = undefined;
+  }
+
+  private tryRecoverProviderSubmitHold(turnStarted: boolean): void {
+    const hold = this.deliverySubmitHold;
+    const process = this.process;
+    const probe = this.options.adapter.confirmSubmitRecovery;
+    if (!hold || !process || !probe) return;
+    this.submitRecoveryTurnStarted ||= turnStarted;
+    if (this.submitRecoveryInFlight) { this.submitRecoveryRequested = true; return; }
+    this.submitRecoveryInFlight = true;
+    const started = this.submitRecoveryTurnStarted;
+    this.submitRecoveryTurnStarted = false;
+    void probe.call(this.options.adapter, process, started).then((recovered) => {
+      if (!recovered || this.deliverySubmitHold !== hold || this.process !== process) return;
+      this.deliverySubmitHold = undefined;
+      this.stopSubmitRecoveryPoll();
+      this.submitFenceRaised = false;
+      this.heldSubmit = emptyHeldSubmit();
+      this.submitRecoveryTurnStarted = false;
+      this.publishStatus();
+      if (this.pendingMessages.size > 0) this.scheduleDrain();
+    }).catch((error) => logger.warn("delivery", `provider submit recovery probe failed: ${error}`)).finally(() => {
+      this.submitRecoveryInFlight = false;
+      const requested = this.submitRecoveryRequested || this.submitRecoveryTurnStarted;
+      this.submitRecoveryRequested = false;
+      if (requested && this.deliverySubmitHold === hold) this.tryRecoverProviderSubmitHold(false);
+    });
+  }
+
+  // =====================================================================  // #2539 Phase A — the ONE provider-input offer/settle seam.
+  //
+  // Everything that puts content in front of the provider's single input channel OFFERS through
+  // {@link offerProviderInput} (arm the empty-turn watch BEFORE the delivery is awaited — see
+  // armInput — serialize through the FIFO `providerInput` queue, roll the arm back when the
+  // offer was rejected), and an inbox batch SETTLES through {@link settleMessageDelivery} — the
+  // single place that records delivery, marks read, releases claims and requeues the un-acked.
+  // drainMessages (persisted messages: claim → attach → offer → settle) and injectPrompt
+  // (dashboard continue/chat: render → offer) are the two callers; the tails exist once, so the
+  // soft-steer partial-ack settlement is written in exactly one place.
+  // =====================================================================
+  /**
+   * Offer one payload to the provider: arm the empty-turn watch for work-bearing input, run
+   * delivery through the FIFO input queue, and disarm the arm if the offer throws. On success
+   * the arm stays because the delivery obliges the agent to produce work (#2389). A notice-only
+   * batch is delivered without an arm because it owes no answer.
+   */
+  private async offerProviderInput<T>(run: (inputObserver?: ProviderInputObserver) => Promise<T>, offeredNothing?: (result: T) => boolean, armEmptyTurn = true): Promise<T> {
+    const arm = armEmptyTurn ? this.emptyTurns.armInput(Date.now(), "ladder", true) : undefined;
+    try {
+      const result = await run(arm ? this.emptyTurns.inputObserver(arm) : undefined);
+      if (arm && arm.evidence?.offeredAt === undefined) this.emptyTurns.inputObserver(arm).offered(Date.now(), false);
+      if (arm && offeredNothing?.(result)) this.emptyTurns.disarmInput(arm);
+      return result;
+    } catch (error) {
+      if (arm) this.emptyTurns.disarmInput(arm);
+      throw error;
+    }
+  }
+
+  // #2619 — the ONLY two places runner code hands input to the provider (runner-input-seam.guard.test.ts
+  // enforces it). A provider may REFUSE input under a quota wall or throttle, so `onHeld` is a required
+  // parameter: no caller can drop a refusal and report the input delivered. Both run in the caller's
+  // FIFO slot (`ticket`), so the refusal outcome is judged in the serialized input order.
+
+  /** Offer a prompt; `onHeld` runs INSIDE the slot, synchronously, when the provider refused it —
+   *  a refusal is parked before any accepted offer can end the episode. */
+  private async offerPromptToProvider(prompt: string, options: PromptOfferOptions, onHeld: () => void, ticket?: ProviderInputTicket, onSubmitHeld?: () => void): Promise<"accepted" | "held" | "submit-held"> {
+    return this.providerInput.run(async () => {
+      await this.lateClearRecovery.ready();
+      if (this.lifecycle.stopped) throw new Error("runner stopped before provider prompt offer");
+      // #2664 — decided in the slot: a prompt queued before the preceding submit raised the hold never reaches the fence.
+      if (onSubmitHeld && (this.deliverySubmitHold || this.submitFenceRaised)) {
+        onSubmitHeld();
+        return "submit-held" as const;
+      }
+      if (!this.currentTurnId) this.turnReport.armTurnOpener([]); // #2840 — a prompt-opened turn answers no relay message
+      if (await this.noteSubmitFence(() => this.options.adapter.deliverInitialPrompt!(this.process!, prompt, options)) !== "held") return "accepted" as const;
+      onHeld();
+      return "held" as const;
+    }, ticket);
+  }
+
+  private async noteSubmitFence<T>(offer: () => Promise<T>): Promise<T> {
+    try {
+      const result = await offer();
+      this.submitFenceRaised = false; // the provider took input, so no submit fence stands
+      return result;
+    } catch (error) {
+      if (error instanceof ProviderSubmitFailure && !error.retrySafe) this.submitFenceRaised = true;
+      throw error;
+    }
+  }
+
+  /** Offer a prompt; a refusal parks it and then makes it durable ("not-durable": the caller fails). */
+  private async offerPromptOrPark(prompt: string, options: PromptOfferOptions, ticket?: ProviderInputTicket, onSubmitHeld?: () => void, heldFor?: string): Promise<"accepted" | "parked" | "not-durable" | "submit-held"> {
+    let key = "";
+    const payload = { ...(options.imagePaths?.length ? { [HELD_PROMPT_IMAGE_PATHS]: options.imagePaths } : {}), ...(heldFor ? { [HELD_FOR_PAYLOAD_KEY]: heldFor } : {}) };
+    const offered = await this.offerPromptToProvider(prompt, options, () => { key = this.parkRefusedPrompt(prompt, payload); }, ticket, onSubmitHeld);
+    if (offered !== "held") return offered;
+    return await this.persistParkedPrompt(key) ? "parked" : "not-durable";
+  }
+
+  /**
+   * Offer messages. `select` runs INSIDE the FIFO slot, immediately before the adapter call, so a
+   * decision taken earlier (a resume wake's continue) is re-validated at the offer instant; an
+   * empty selection offers nothing. `onHeld` gets the ids the provider refused, INSIDE the slot and
+   * synchronously (see offerPromptToProvider).
+   */
+  private async offerMessagesToProvider(select: () => Message[], onHeld: (heldIds: number[], offered: Message[]) => void, options: { ctx?: ProviderDeliverContext; ticket?: ProviderInputTicket; settlement?: Promise<void> } = {}): Promise<{ result: void | number[] | DeliverResult; offered: Message[] }> {
+    let offered: Message[] = [];
+    const result = await this.providerInput.run(async () => {
+      offered = select();
+      this.hold.noteOffered(offered);
+      if (options.settlement && offered.length > 0) this.deliverySettlements.track(options.settlement);
+      // #2840 — armed BEFORE the offer: a synchronous provider starts, or runs, the turn inside deliver.
+      const opening = this.turnReport.openTurnOpener(offered, !this.currentTurnId, options.ctx);
+      const delivered = offered.length > 0 ? await this.noteSubmitFence(() => this.options.adapter.deliver(this.process!, offered, { ...opening.ctx, recordSubmittedPrompt: (text, images) => this.recordInjectedPrompt(text, images) })).catch((error) => { opening.settle(false); throw error; }) : [];
+      const normalized = normalizeDeliverResult(delivered, offered);
+      const acknowledged = new Set(normalized.acknowledgedIds);
+      opening.settle(acknowledged.size > 0);
+      const heldIds = normalized.providerHeldIds.filter((id) => !acknowledged.has(id));
+      if (heldIds.length > 0) onHeld(heldIds, offered);
+      return delivered;
+    }, options.ticket);
+    return { result, offered };
+  }
+
+  /**
+   * Settle an offered message batch (#2539 Phase A): the ONE place that records delivery
+   * attempts, marks acked messages read, releases their claims, and requeues everything the
+   * adapter did not accept (partial acks are the soft-steer contract — the un-acked subset
+   * re-offers toward turn-end). Returns the backoff (ms) to pace the next drain by: 0 for an
+   * immediate reschedule, or the bounded terminal-failure backoff after a failed provider offer.
+   */
+  private async settleMessageDelivery(deliverable: Message[], acknowledged: void | number[] | DeliverResult): Promise<number> {
+    const normalized = normalizeDeliverResult(acknowledged, deliverable);
+    // A refusal read before this settle already re-parked these inputs: they are held, not delivered.
+    const reparked = this.hold.takeReparked(deliverable.map((message) => message.id));
+    if (reparked.size > 0) {
+      normalized.acknowledgedIds = normalized.acknowledgedIds.filter((id) => !reparked.has(id));
+      normalized.providerHeldIds = [...normalized.providerHeldIds, ...reparked];
+    }
+    const acknowledgedIds = new Set(normalized.acknowledgedIds);
+    const terminalFailureIds = new Set(normalized.terminalFailureIds);
+    // #2539 Phase B — soft-steer accepted-but-unconsumed ids: persistence is NOT delivery, so they
+    // are neither acked (no mark read / claim release / settled-id poison) nor un-acked (no requeue —
+    // the provider row exists and must never be re-POSTed). Their settlement completes through
+    // {@link settleSoftSteerConsumption} / {@link reofferSoftSteerIds} when the adapter's ledger
+    // resolves consumption or a session lifecycle loss.
+    const awaitingConsumptionIds = new Set(normalized.awaitingConsumptionIds);
+    // Synchronously, before any await: inputs the provider did not accept leave the live-turn record, accepted ones leave the park.
+    this.hold.forget(deliverable.filter((message) => !acknowledgedIds.has(message.id) || awaitingConsumptionIds.has(message.id)).map((message) => message.id));
+    for (const message of deliverable) if (acknowledgedIds.has(message.id) && !awaitingConsumptionIds.has(message.id)) this.hold.unpark(message.id);
+    let terminalFailureBackoffMs = 0;
+    for (const message of deliverable.filter((item) => awaitingConsumptionIds.has(item.id))) {
+      await this.http.recordMessageDeliveryAttempt(message.id, { agentId: this.agentId, status: "delivered" }).catch(() => undefined);
+      // r3 LOW-1 — settle-before-stash orphan race: the SSE consumption door can fire inside the
+      // awaited recordMessageDeliveryAttempt above, and settleSoftSteerConsumption has then ALREADY
+      // marked read, released the claim, and poisoned the intake guard. Stashing now would insert an
+      // ORPHAN awaiting-map entry for a settled id — a later session swap would reoffer it (duplicate
+      // delivery into the new session) and the orphan would occupy the awaiting map permanently.
+      // The id is settled: nothing left to do.
+      if (this.settledMessageIds.has(message.id)) continue;
+      // Backpressure past the awaiting-map cap: the lane cannot track the id to settlement, so fall
+      // back to the un-acked path (requeue → normal lane). The OpenCode row may ALREADY be persisted —
+      // the adapter POSTs before noting the batch (r1 adjudication) — so this is the designed
+      // at-least-once duplicate-not-loss degradation, never a silent drop.
+      if (!this.trackAwaitingMidTurnDelivery(message)) {
+        awaitingConsumptionIds.delete(message.id);
+        this.taskClaims.clearActiveClaim(message);
+        this.pendingMessages.set(message.id, message);
+      }
+    }
+    for (const message of deliverable.filter((item) => acknowledgedIds.has(item.id) && !awaitingConsumptionIds.has(item.id))) {
+      await this.http.recordMessageDeliveryAttempt(message.id, { agentId: this.agentId, status: "delivered" }).catch(() => undefined);
+      this.providerTerminalFailureAttempts.delete(message.id);
+      this.submitDeliveryAttempts.delete(message.id);
+      await this.http.markRead(message.id, this.agentId).catch(() => {});
+      if (!taskIdFromMessage(message)) this.claims.finishClaim("message", String(message.id));
+      // Delivered + marked read: remember it so a stale server-list copy (a poll snapshot that
+      // raced this markRead) can never re-enqueue it (see SETTLED_MESSAGE_IDS_CAP).
+      this.rememberSettled(message.id);
+      this.parkedContextAccepted(message);
+    }
+    // #2397 round 3 review (MED-3r) — an un-acknowledged id the adapter attributes to a
+    // TERMINAL provider failure (as opposed to an ordinary mid-turn/busy defer) paces its own
+    // re-drain with bounded exponential backoff.
+    // Without this, a message whose provider just exhausted its own retry budget against an
+    // upstream that is ALREADY rate-limiting got re-queued and re-attempted on the very next
+    // tick (`scheduleDrain(0)` below), forever.
+    if (this.taskClaims.hasDeferredCompletion()) {
+      // Queue persistence failures must be visible; PATCH retries belong to the durable outbox.
+      this.taskClaims.completeObservedTaskClaims(acknowledgedIds).catch((error) => logger.error("task", `completion enqueue failed: ${error}`));
+      for (const message of deliverable) this.taskClaims.forgetDeferredCompletion(message.id);
+    }
+    const providerHeldIds = new Set(normalized.providerHeldIds.filter((id) => !acknowledgedIds.has(id)));
+    for (const message of deliverable) {
+      if (!providerHeldIds.has(message.id) && !acknowledgedIds.has(message.id)) this.hold.unpark(message.id);
+      // A refused resume wake is spent (the next wake retries); never parked as input. Refused
+      // input was already parked inside the offer's FIFO slot (drainMessages).
+      else if (isResumeWake(message)) await this.settleSilently(message);
+    }
+    for (const message of deliverable.filter((item) => !acknowledgedIds.has(item.id) && !awaitingConsumptionIds.has(item.id) && !providerHeldIds.has(item.id))) {
+      this.taskClaims.clearActiveClaim(message);
+      this.pendingMessages.set(message.id, message);
+      if (terminalFailureIds.has(message.id)) {
+        const attempts = (this.providerTerminalFailureAttempts.get(message.id) ?? 0) + 1;
+        this.providerTerminalFailureAttempts.set(message.id, attempts);
+        terminalFailureBackoffMs = Math.max(terminalFailureBackoffMs, Math.min(TERMINAL_FAILURE_RETRY_BASE_MS * 2 ** (attempts - 1), TERMINAL_FAILURE_RETRY_MAX_MS));
+      }
+    }
+    return terminalFailureBackoffMs;
+  }
+
+  /** Delivered + marked read: a stale server-list copy may never re-enqueue it (see SETTLED_MESSAGE_IDS_CAP). */
+  private rememberSettled(id: number): void {
+    this.settledMessageIds.delete(id);
+    this.settledMessageIds.add(id);
+    while (this.settledMessageIds.size > SETTLED_MESSAGE_IDS_CAP) {
+      const oldest = this.settledMessageIds.values().next().value;
+      if (oldest === undefined) break;
+      this.settledMessageIds.delete(oldest);
+    }
+  }
+
+  /** Mark read without delivering: a stale server-list copy may never re-enqueue it. */
+  private async settleSilently(message: Message): Promise<void> {
+    await this.http.markRead(message.id, this.agentId).catch(() => {});
+    this.rememberSettled(message.id);
+  }
+
+  /** #2619 — resume wakes, decided by the hold state machine (provider-hold.ts planWakes). */
+  private async resolveResumeWakes(messages: Message[]): Promise<Message[]> {
+    const plan = this.hold.planWakes(messages);
+    for (const wake of plan.settle) await this.settleSilently(wake);
+    for (const message of plan.replay) this.drainingMessageIds?.add(message.id);
+    return plan.batch;
+  }
+
+  /** #2619 — park a refused prompt PENDING, synchronously (call inside the FIFO slot). Returns its
+   *  heldPromptKey; {@link persistParkedPrompt} then makes it durable. */
+  private parkRefusedPrompt(prompt: string, payload: Record<string, unknown> = {}): string {
+    const heldPromptKey = crypto.randomUUID();
+    this.refusedPrompts.begin(heldPromptKey);
+    this.hold.parkPending(heldPromptKey, { from: this.agentId, to: this.agentId, kind: "chat", subject: "Prompt refused by the provider, held for redelivery", body: prompt, payload: { ...payload, heldPromptKey }, readBy: [], createdAt: Date.now() });
+    return heldPromptKey;
+  }
+
+  /**
+   * #2619 — post a pending parked prompt to this agent's own inbox so a restart re-reads it like any
+   * unread message. The relay idempotency key IS the heldPromptKey, so retries and an ambiguous
+   * (committed, response lost) post converge on ONE row. False: it could not be made durable — the
+   * park is dropped and the caller must report failure (never success).
+   */
+  private async persistParkedPrompt(key: string): Promise<boolean> {
+    await retryParkPost("refused prompt inbox post", async () => {
+      const pending = this.hold.pendingMessage(key);
+      if (!pending) return true; // the relay's push of the row bound it meanwhile
+      const posted = await this.http.sendMessage({ from: pending.from, to: pending.to, kind: "chat", subject: pending.subject, body: pending.body, payload: pending.payload, idempotencyKey: key });
+      this.refusedPrompts.confirm(key);
+      this.releaseParked(this.hold.bind(key, posted));
+      return true;
+    });
+    if (!this.hold.isPending(key)) return true;
+    this.hold.drop(key);
+    this.parkedContextInjections.delete(key);
+    logger.error("runner", "refused prompt could not be persisted to the inbox; not parked — its caller fails");
+    return false;
+  }
+
+  /** Parked input released by a bind after the episode ended: deliver it now. */
+  private releaseParked(messages: Message[]): void {
+    for (const message of messages) this.pendingMessages.set(message.id, message);
+    if (messages.length > 0) this.scheduleDrain();
+  }
+
+  /** #2619 — a parked context injection was accepted: finish what its refused injectContext skipped. */
+  private parkedContextAccepted(message: Message): void {
+    const key = message.payload?.heldPromptKey;
+    const parked = typeof key === "string" ? this.parkedContextInjections.get(key) : undefined;
+    if (!parked) return;
+    this.parkedContextInjections.delete(key as string);
+    this.injectedContextHashes.add(parked.contentHash);
+    if (parked.afterClearCommandId) this.releaseSelfResumeClearFence(parked.afterClearCommandId);
+  }
+
+  // #2539 Phase B — stash a soft-steered Message for id-keyed settlement later. False ⇒ over the
+  // cap (caller falls back to the un-acked requeue path).
+  private trackAwaitingMidTurnDelivery(message: Message): boolean {
+    if (this.awaitingMidTurnDelivery.size >= AWAITING_MID_TURN_DELIVERY_CAP) return false;
+    this.awaitingMidTurnDelivery.set(message.id, message);
+    return true;
+  }
+
+  /**
+   * #2539 Phase B — the runner-owned CONSUMED settlement for soft-steered ids, handed to the
+   * adapter through ProviderDeliverContext.settleMidTurnConsumed. Mirrors the acked tail of
+   * {@link settleMessageDelivery} exactly (mark read → release the claim → poison the intake
+   * guard) plus one belt: a pendingMessages entry is dropped, so a requeue racing the consumption
+   * detection can never resurrect an id the model already read. The awaiting-map entry is removed
+   * first so a duplicate callback is a no-op (consume-once, like the ledger's own idempotence).
+   */
+  private async settleSoftSteerConsumption(relayIds: number[]): Promise<void> {
+    for (const id of relayIds) {
+      this.awaitingMidTurnDelivery.delete(id);
+      await this.http.markRead(id, this.agentId).catch(() => {});
+      this.claims.finishClaim("message", String(id));
+      this.pendingMessages.delete(id);
+      this.rememberSettled(id);
+    }
+  }
+
+  /**
+   * #2539 Phase B — the runner-owned REOFFER for soft-steered ids whose persisted row can no
+   * longer be consumed (session clear/compact/reroll swap, shutdown, reconcile-absent). Same
+   * destination as settle's un-acked path (normal queue, turn-end delivery), driven by the
+   * adapter's ledger. Ids no longer tracked (never stashed, or already settled/reoffered) are
+   * ignored — the ledger's at-least-once retries stay idempotent.
+   */
+  private async reofferSoftSteerIds(relayIds: number[]): Promise<void> {
+    let reoffered = 0;
+    for (const id of relayIds) {
+      const message = this.awaitingMidTurnDelivery.get(id);
+      if (!message) continue;
+      this.awaitingMidTurnDelivery.delete(id);
+      this.taskClaims.clearActiveClaim(message);
+      this.pendingMessages.set(message.id, message);
+      reoffered += 1;
+    }
+    if (reoffered > 0) this.scheduleDrain(0);
+  }
+
+  private async drainMessages(): Promise<void> {
+    if (this.lifecycle.stopped || this.delivering || this.deliverySubmitHold || this.submitResendInFlight || this.pendingMessages.size === 0) return;
+    if (!this.process) {
+      this.scheduleDrain(500);
+      return;
+    }
+    this.delivering = true;
+    let messages = [...this.pendingMessages.values()].sort((a, b) => a.id - b.id);
+    this.pendingMessages.clear();
+    this.drainingMessageIds = new Set(messages.map((message) => message.id));
+    messages = this.holdPreClearInboxMessages(messages);
+    // Awaited only when a resume wake is in the batch: every other drain keeps its exact tick timing.
+    if (messages.some(isResumeWake)) messages = await this.resolveResumeWakes(messages);
+    if (messages.length === 0) {
+      this.drainingMessageIds = undefined;
+      this.delivering = false;
+      this.publishStatus();
+      return;
+    }
+    let deliverable: Message[] = [];
+    const providerAlreadyBusy = this.claims.reasons().includes("provider-turn");
+    for (const message of messages) {
+      let toDeliver = message;
+      if (message.claimable) {
+        const claimed = await this.http.claimMessageResult(message.id, this.agentId).catch(() => ({ ok: false, claimExpiresAt: undefined }));
+        if (!claimed.ok) continue;
+        this.claims.startClaim("message", String(message.id), claimed.claimExpiresAt);
+        const taskId = taskIdFromMessage(message);
+        if (taskId) {
+          this.taskClaims.noteClaim(message.id, taskId, providerAlreadyBusy, claimed.claimExpiresAt);
+          await this.http.updateTaskStatus(taskId, {
+            status: "in_progress",
+            agentId: this.agentId,
+            metadata: { messageId: message.id, completedBy: "runner" },
+          }).catch((error) => logger.error("task", `task ${taskId} in_progress update failed: ${error}`));
+          // Runner owns claim + status here; drop the server's self-claim instruction
+          // so the agent doesn't improvise a stray claim send (see stripRunnerClaimedGuidance).
+          toDeliver = { ...message, body: stripRunnerClaimedGuidance(message.body) };
+        }
+      }
+      deliverable.push(toDeliver);
+    }
+    // A clear can have begun while a claim was in flight. Re-check the entire batch before
+    // attachment preparation; the fence owns the pre-boundary input lane, not just the inbox map.
+    deliverable = this.holdPreClearInboxMessages(deliverable, { releaseClaims: true });
+    if (deliverable.length === 0) {
+      this.drainingMessageIds = undefined;
+      this.delivering = false;
+      this.publishStatus();
+      return;
+    }
+    this.publishStatus();
+    let failed = false;
+    let drainBackoffMs = 0;
+    const settlement = Promise.withResolvers<void>();
+    try {
+      let prepared = await messagesWithCachedAttachments(deliverable, this.http, {
+        agentId: this.agentId,
+        onError: (message) => logger.error("runner", message),
+      });
+      // Attachment materialization itself awaits. A clear that arrives in that window must still
+      // keep this old batch out of the fresh provider session, immediately before adapter.deliver.
+      deliverable = this.holdPreClearInboxMessages(deliverable, { releaseClaims: true });
+      if (deliverable.length === 0) return;
+      const deliverableIds = new Set(deliverable.map((message) => message.id));
+      prepared = prepared.filter((message) => deliverableIds.has(message.id));
+      // #1565 F1 — behind the same gate as injected payloads: a message batch and a boundary
+      // inject arriving together must not paste into each other.
+      // Preserve arrival-time evidence across the input queue; adapters decide whether delivery actually deferred.
+      const deliverCtx: ProviderDeliverContext = {
+        isRecipientMidTurn: () => this.claims.reasons().includes("provider-turn"),
+        // #2539 Phase B — the deferred-settlement handoff: the adapter's soft-steer ledger settles
+        // its persisted-but-unconsumed batches through these runner-owned seams (never its own
+        // settlement implementation).
+        settleMidTurnConsumed: (relayIds) => this.deliverySettlements.track(this.settleSoftSteerConsumption(relayIds)),
+        reofferMidTurnIds: (relayIds) => this.reofferSoftSteerIds(relayIds),
+      };
+      // OFFER — arm the empty-turn watch only for work-bearing input, serialize through the FIFO
+      // input queue, disarm on rejection. (#2389 — armed at hand-off, not on resolution.)
+      // #2619 — a resume wake's continue was decided at planning time, before the claim/attachment
+      // awaits above; the episode may have ended (or a new one parked input) since. Re-validated in
+      // the FIFO slot at the offer instant: a continue that no longer holds is dropped and settled
+      // silently. Refused input parks inside the slot (below).
+      const staleWakes: Message[] = [];
+      const { result: acknowledged, offered } = await this.offerProviderInput((inputObserver) => this.offerMessagesToProvider(() => this.holdPreClearInboxMessages(prepared.filter((message) => {
+        if (!isResumeWake(message) || this.hold.continueStillValid(message)) return true;
+        staleWakes.push(message);
+        return false;
+      }), { releaseClaims: true }), (heldIds) => {
+        // #2619 — park refused input NOW, inside the slot: no accepted offer may end the episode first.
+        const held = new Set(heldIds);
+        for (const message of deliverable) {
+          if (!held.has(message.id) || isResumeWake(message)) continue;
+          this.taskClaims.clearActiveClaim(message);
+          this.hold.park([message]);
+        }
+      }, { ctx: { ...deliverCtx, inputObserver }, settlement: settlement.promise }), (outcome) => outcome.offered.length === 0, prepared.some((message) => !isNotificationOnlyInput(message)));
+      for (const wake of staleWakes) await this.settleSilently(wake);
+      const offeredIds = new Set(offered.map((message) => message.id));
+      deliverable = deliverable.filter((message) => offeredIds.has(message.id));
+      // SETTLE — record/read/release-claims/requeue, in ONE place (soft-steer partial acks included).
+      if (deliverable.length > 0) drainBackoffMs = await this.settleMessageDelivery(deliverable, acknowledged);
+    } catch (error) {
+      failed = true;
+      if (error instanceof ProviderSubmitFailure) {
+        const counted = deliverable.map((message) => {
+          const count = (this.submitDeliveryAttempts.get(message.id) ?? 0) + 1;
+          this.submitDeliveryAttempts.set(message.id, count);
+          return { message, count };
+        });
+        const terminal = counted.filter(({ count }) => !error.retrySafe || count >= PROVIDER_SUBMIT_MAX_DELIVERIES);
+        const retry = counted.filter(({ count }) => error.retrySafe && count < PROVIDER_SUBMIT_MAX_DELIVERIES);
+        if (terminal.length > 0) {
+          this.holdFailedProviderSubmit(`Provider prompt submission could not be confirmed: ${error.message}`, { messages: terminal.map(({ message }) => message) });
+          for (const { message, count } of terminal) {
+            const detail = `Provider prompt submission unconfirmed after ${count} delivery attempt(s): ${error.message}`;
+            this.taskClaims.clearActiveClaim(message);
+            this.submitDeliveryAttempts.delete(message.id);
+            await this.http.recordMessageDeliveryAttempt(message.id, { agentId: this.agentId, status: "failed", error: detail }).catch((reportError) => {
+              logger.error("delivery", `could not record failed provider submission for message ${message.id}: ${reportError}`);
+            });
+          }
+        }
+        if (retry.length > 0) {
+          const highestAttempt = Math.max(...retry.map(({ count }) => count));
+          drainBackoffMs = providerSubmitRetryDelayMs(highestAttempt);
+          logger.warn("delivery", `Provider prompt submit failed before paste; ${retry.length} message(s) retry in ${drainBackoffMs}ms: ${error.message}`);
+          for (const { message } of retry) { this.taskClaims.clearActiveClaim(message); this.pendingMessages.set(message.id, message); }
+        }
+      } else {
+        // Other adapter failures retain the existing requeue policy.
+        if (shouldLogDeliveryFailure(error)) logger.warn("delivery", `message delivery failed: ${error}`);
+        for (const message of deliverable) {
+          this.taskClaims.clearActiveClaim(message);
+          this.pendingMessages.set(message.id, message);
+        }
+      }
+    } finally {
+      settlement.resolve();
+      this.drainingMessageIds = undefined;
+      this.delivering = false;
+      this.publishStatus();
+      // Unaccepted input during a live turn waits for turnCleared, rather than reoffering on every tick (#3315).
+      if (this.pendingMessages.size > 0 && (failed || drainBackoffMs > 0 || !this.currentTurnId)) this.scheduleDrain(failed ? Math.max(1000, drainBackoffMs) : drainBackoffMs);
+    }
+  }
+
+  private async compactCommand(params: Record<string, unknown>, nativeSelfResume: NativeSelfResumeHandoff | undefined, commandId: string): Promise<Record<string, unknown>> {
+    let providerResult: Record<string, unknown> | void = undefined;
+    providerResult = await executeCompactCommand(this.options.adapter, this.process, params, this.nativeSelfResume, nativeSelfResume,
+      () => this.awaitContextCommandTurnClear("agent.compact"), () => { this.contextResets.submitting(commandId, "compact"); this.resetContextGeneration(); });
+    providerResult = { ...(providerResult || {}), tokenRemint: await this.remintRuntimeTokenAtBoundary("compact") };
+    return providerResult;
+  }
+
+  private async clearContextCommand(params: Record<string, unknown>, ticket: ProviderInputTicket | undefined, commandId: string): Promise<Record<string, unknown>> {
+    let providerResult: Record<string, unknown> | void = undefined;
+    if (!this.options.adapter.clearContext || !this.process) throw new Error("provider does not support clearContext");
+    if (ticket) await ticket.turn;
+    await this.awaitContextCommandTurnClear("agent.clearContext");
+    // #2550 — same new-generation reset as the compact arm above: cleared before the
+    // destructive step so any failure path still fails open toward re-delivery.
+    this.resetContextGeneration();
+    this.lateClearRecovery.begin(commandId, params, this.options.adapter.couplesClearInjectContinuation);
+    this.contextResets.submitting(commandId, "clear");
+    try { providerResult = await this.options.adapter.clearContext(this.process); }
+    finally { this.lateClearRecovery.finish(commandId, Boolean(providerResult && providerResult.clearConfirmed === true)); }
+    if (providerResult && providerResult.clearConfirmed === true) this.contextResets.confirmed("clear", commandId);
+    // #2043 F2 — commit barrier for the self-resume clear-inject path: a `/clear` whose commit
+    // could not be POSITIVELY confirmed is a possible no-op, so surface it as a FAILED command
+    // (mirroring native's timeout->FAILED) instead of the pre-#2043 silent success. Throw
+    // BEFORE the coupled in-process deliver so we never inject a continuation into a context
+    // that may not have been cleared; the relay's continuation re-injection backstop (now also
+    // armed for a FAILED clear-inject) is then the single recovery path — a false-negative
+    // clear detection recovers rather than wiping working state.
+    this.assertClearInjectCommitted(params, providerResult || undefined);
+    // The cleared context goes to the card now; the ~30s beat would leave the old usage visible meanwhile (#2771).
+    this.bus.flushHeartbeat();
+    // Before the continuation, so the next generation's first turn already sees the re-derived tools.
+    providerResult = { ...(providerResult || {}), tokenRemint: await this.remintRuntimeTokenAtBoundary("clear") };
+    const coupled = await this.deliverCoupledContinuationAfterClear(params, providerResult || undefined, ticket);
+    if (coupled) providerResult = { ...(providerResult ?? {}), ...coupled };
+    if (coupled?.continuationDelivered === true) this.releaseSelfResumeClearFence(commandId);
+    return providerResult;
+  }
+
+  private beginNativeSelfResume(type: string, params: Record<string, unknown>, commandId: string): NativeSelfResumeHandoff | undefined {
+    return isNativeSelfResumeCompact(type, params) || (type === "agent.compact" && this.options.adapter.compactReportsSubmission === true)
+      ? this.nativeSelfResume.begin(commandId, params)
+      : undefined;
+  }
+
+  private finishClearCommand(commandId: string): void {
+    this.continuationFence.finish(commandId, this.lateClearRecovery.holds(commandId));
+  }
+
+  // Fence the predecessor provider turn before a destructive compact/clearContext runs, so the
+  // successor generation never overlaps it. Two provider shapes need two different fences:
+  //
+  // #2043 F1 — a blind context-command submit (Claude's tmux `/compact` // `/clear`) must land on
+  // an IDLE prompt to parse as a slash command. Submitted while a turn is live it queues behind the
+  // turn and dequeues as literal chat, so the compaction silently evaporates — the #2043 runaway.
+  // For those adapters we WAIT for the live turn to clear on its own; a wait that times out THROWS,
+  // so the command fails loudly (F2/F4) rather than blind-submitting into a live turn and no-oping.
+  //
+  // #2569 — an app-server adapter (Codex) whose clearContext starts a FRESH thread / whose compact
+  // rewrites the current one via an awaited handshake. The await confirms the NEW generation is
+  // ready but does NOT settle the OLD turn: relay_compact_and_resume runs from within the model's
+  // own live turn, so that turn keeps writing the worktree on the previous thread while the
+  // successor is armed on the new one — two generations revert each other (the #2569 silent
+  // overlap). A plain wait would time out on the still-live in-turn compaction, so we INTERRUPT the
+  // predecessor turn, then wait for it to reach a terminal state (interrupt-then-settle, mirroring
+  // the redirect path at the agent.interrupt arm) before the destructive step. A settle timeout
+  // THROWS — the command fails closed and the relay re-injects — never opening the overlap window.
+  private async awaitContextCommandTurnClear(type: string): Promise<void> {
+    const adapter = this.options.adapter;
+    if (adapter.awaitsIdleBeforeContextCommand) {
+      try {
+        await this.busyReconciler.waitForProviderTurnClear();
+      } catch (error) {
+        throw new ContextSubmitAborted(`provider turn did not clear before ${type} submit; aborting the submit to avoid a silent no-op (${errMessage(error)})`);
+      }
+      return;
+    }
+    if (adapter.interruptsTurnBeforeContextCommand) {
+      const hasProviderTurn = this.claims.activeWork().some((work) => work.kind === "provider-turn");
+      if (!hasProviderTurn || !adapter.interrupt || !this.process) return;
+      // #2389 — an interrupted turn ends with no output; that state has its own notice
+      // (agent.turn_interrupted) and must not also draw an empty-turn strike.
+      this.emptyTurns.reset();
+      try {
+        await adapter.interrupt(this.process);
+      } catch (error) {
+        // The turn may have raced to terminal between the hasProviderTurn read and here (no active
+        // turn to interrupt). The scheduled reconcile + settle wait below is the authoritative gate.
+        this.sessionLog(`context-command fence: interrupt before ${type} failed: ${errMessage(error)}`);
+      }
+      this.busyReconciler.scheduleInterruptReconcile();
+      try {
+        await this.busyReconciler.waitForProviderTurnClear();
+      } catch (error) {
+        throw new ContextSubmitAborted(`predecessor provider turn did not settle before ${type}; aborting to avoid two generations writing the one worktree (${errMessage(error)})`);
+      }
+    }
+  }
+
+  // #2043 F2 — the clear-inject commit barrier. A self-resume `/clear` whose commit the adapter's
+  // clear-aware barrier could not POSITIVELY confirm (clearConfirmed !== true) is treated as a
+  // possible no-op and surfaced as a FAILED command, never the pre-#2043 silent success. Scoped to
+  // the coupled clear-inject path (couplesClearInjectContinuation) carrying a real continuation —
+  // a manual `/clear` with no self-resume payload keeps its existing best-effort semantics.
+  private assertClearInjectCommitted(params: Record<string, unknown>, clearResult: Record<string, unknown> | undefined): void {
+    assertClearInjectCommitted(this.options.adapter.couplesClearInjectContinuation, params, clearResult, (message) => this.sessionLog(message));
+  }
+
+  // #1588 — couple the self-resume continuation delivery into the SAME clearContext command that
+  // wipes the context, so the two can never race across separate commands/transports again. The
+  // relay embeds the fully-built (identity-augmented) continuation in the clear command's
+  // `selfResume.continuation`; we deliver it in-process, strictly AFTER adapter.clearContext has
+  // returned. `continuationDelivered` tells the relay whether it can skip the redundant reactive
+  // inject or must still fire its #1023 backstop — and it MUST be truthful, because the relay skips
+  // BOTH backstops on continuationDelivered===true, so a false-positive true is a silent-wipe risk
+  // with no recovery. So `true` requires TWO things: (1) the adapter's clear-aware barrier
+  // POSITIVELY confirmed the TUI clear committed (clearResult.clearConfirmed === true — the strong
+  // clear-committed evidence), and (2) the in-process deliver resolved. A settle timeout / uncertain
+  // clear → clearConfirmed !== true → we still deliver in-process (best effort) but report false so
+  // the backstop re-injects. Uncertainty ALWAYS resolves to false (backstop covers), never true.
+  private async deliverCoupledContinuationAfterClear(params: Record<string, unknown>, clearResult: Record<string, unknown> | undefined, ticket?: ProviderInputTicket): Promise<Record<string, unknown> | undefined> {
+    // Opt-in per provider: only adapters whose clearContext is a fire-and-forget keystroke with no
+    // completion barrier (Claude) couple the continuation in-process. Codex's clearContext is an
+    // awaited atomic threadStart (the await IS the barrier), so it keeps the separate confirmed-inject
+    // flow untouched — never sets continuationDelivered, so the relay never skips its reactive inject.
+    if (!this.options.adapter.couplesClearInjectContinuation) return undefined;
+    const selfResume = params.selfResume !== null && typeof params.selfResume === "object" && !Array.isArray(params.selfResume)
+      ? params.selfResume as Record<string, unknown>
+      : undefined;
+    if (!selfResume || selfResume.mode !== "clear-inject") return undefined;
+    const continuation = typeof selfResume.continuation === "string" ? selfResume.continuation.trim() : "";
+    if (!continuation) return undefined;
+    // Only a genuine clear-commit confirmation from the adapter's clear-aware barrier permits a
+    // truthful continuationDelivered:true. Absent/false (older runner, or a settle timeout) → false.
+    const clearConfirmed = clearResult?.clearConfirmed === true;
+    try {
+      // #1607 N3 — reuse the outer clearContext ticket instead of letting injectContext reserve a
+      // fresh one, which would queue behind (and thus deadlock on) the still-held outer ticket.
+      await this.injectContext({ content: continuation, reason: "self-resume-continuation", selfResume }, ticket);
+      if (!clearConfirmed) {
+        // Deliver ran, but the clear was NOT positively confirmed committed — the continuation may
+        // have raced a still-processing clear. Report false so the relay backstop re-injects out of
+        // band. A redundant re-inject is always preferable to a silent wipe.
+        this.sessionLog("coupled self-resume continuation delivered but clear commit was NOT confirmed; relay backstop will re-inject");
+      }
+      return { continuationDelivered: clearConfirmed };
+    } catch (error) {
+      // The clear already ran — reporting the command as failed would strand the agent with the
+      // relay unaware its context is gone. Instead report the clear succeeded WITHOUT
+      // continuationDelivered so the relay's reactive/sweep backstop re-injects out-of-band.
+      this.sessionLog(`coupled self-resume continuation delivery failed, relay backstop will retry: ${errMessage(error)}`);
+      return { continuationDelivered: false };
+    }
+  }
+
+  private async injectContext(params: Record<string, unknown>, ticket?: ProviderInputTicket): Promise<Record<string, unknown>> {
+    const content = typeof params.content === "string" ? params.content.trim() : "";
+    if (!content) throw new Error("content required");
+    const memoryIds = Array.isArray(params.memoryIds) ? params.memoryIds.filter((id): id is string => typeof id === "string") : [];
+    const reason = typeof params.reason === "string" ? params.reason : undefined;
+    const selfResume = params.selfResume !== null && typeof params.selfResume === "object" && !Array.isArray(params.selfResume)
+      ? params.selfResume as Record<string, unknown>
+      : undefined;
+    const isSelfResumeContinuation = reason === "self-resume-continuation" || Boolean(selfResume);
+    const fullContextMessageId = typeof selfResume?.fullContextMessageId === "number"
+      ? selfResume.fullContextMessageId
+      : undefined;
+    // #2550 — the one content-hash backstop for system-owned context injections. injectContext is
+    // the SINGLE chokepoint every such payload flows through (continuation, identity, memory
+    // preamble, startup context — all arrive as agent.injectContext commands), so one check here
+    // covers every path. Byte-identical match only, per current generation. Prompts and messages
+    // use injectPrompt/drainMessages and are never deduped here.
+    const contentHash = createHash("sha256").update(content, "utf8").digest("hex");
+    if (this.injectedContextHashes.has(contentHash)) {
+      this.sessionLog(`context injection (${reason ?? "no reason"}) skipped: byte-identical content already delivered this generation (#2550 backstop)`);
+      this.areaMemory.noteInjected(params, memoryIds);
+      return {
+        memoryIds,
+        injectedMemoryCount: memoryIds.length,
+        duplicateInjectSkipped: true,
+        // Truthful settle evidence: the hash table IS the proof the payload reached this
+        // provider context, so a skipped continuation still reports ingested (the relay's
+        // #2545 fence and transport settle then close the boundary instead of re-arming).
+        ...(isSelfResumeContinuation ? { continuationIngested: true, ...(fullContextMessageId !== undefined ? { fullContextMessageId } : {}) } : {}),
+      } as Record<string, unknown>;
+    }
+    const payload: Message = {
+      id: 0,
+      from: "system",
+      to: this.agentId,
+      kind: "system",
+      subject: isSelfResumeContinuation ? "Agent Relay self-resume continuation" : "Agent Relay memory context",
+      body: content,
+      payload: {
+        memoryInjection: true,
+        reason,
+        memoryIds,
+        ...(isSelfResumeContinuation ? { resumeInjection: true } : {}),
+        ...(selfResume ? { selfResume } : {}),
+      },
+      readBy: [],
+      createdAt: Date.now(),
+    };
+    // #1565 F1 — one payload at a time, in dispatch order (see dispatchCommand). The ticket, when
+    // present, is the place in line this command took the moment it arrived.
+    // #2389 — armed WATCH-ONLY. The turn after a memory block or a self-resume continuation
+    // legitimately produces nothing (a compaction, a silent acknowledgment), so it must take no
+    // strike and provoke no nudge — but a continuation that genuinely strands still has to wake
+    // someone, and the strike ladder can never see that. The timed backstop is what covers it.
+    const contextArm = this.emptyTurns.armInput(Date.now(), "watch-only", true);
+    // #2619 — a context payload the provider REFUSED (a quota wall, a throttle) did not land. It
+    // parks in the hold machine like every other refused input (inbox-persisted, replayed by the
+    // resume wake — never a generic continue, which would run it from the provider's history AND
+    // again on replay). No hash, no `continuationIngested`, no fence release until the parked copy
+    // is ACCEPTED (parkedContextAccepted). Reporting it ingested is how a held continuation vanished.
+    // Not durable (the inbox post failed) → the command FAILS, not ingested: the relay's backstop
+    // replays it (src/self-resume.ts). A parked continuation names its recovery artifact so the relay
+    // promotes it to ingested when the parked copy is delivered.
+    let parkedKey: string | undefined;
+    // #3411 — decided inside the provider-input slot on every attempt: a reset queued ahead of this payload runs first.
+    let staleArea = false;
+    const deliver = (slot?: ProviderInputTicket) => this.offerMessagesToProvider(() => (staleArea = this.areaMemory.isStaleInjection(params)) ? [] : [payload], () => {
+      parkedKey = this.parkRefusedPrompt(content, isSelfResumeContinuation && fullContextMessageId !== undefined ? { selfResumeFullContextMessageId: fullContextMessageId } : {});
+      this.parkedContextInjections.set(parkedKey, { contentHash, ...(typeof selfResume?.afterClearCommandId === "string" ? { afterClearCommandId: selfResume.afterClearCommandId } : {}) });
+    }, { ticket: slot, ctx: { inputObserver: this.emptyTurns.inputObserver(contextArm) } });
+    try {
+      await deliver(ticket);
+    } catch (error) {
+      // Codex has no input buffer: a payload offered during a live turn is rejected rather than
+      // queued (#1339). Serializing the boundary pair means the SECOND payload now meets the turn
+      // the first one started, so re-offer it once the turn ends instead of failing the command —
+      // the same queue-behind-the-turn semantics Claude's transports get for free from the CLI's
+      // own buffer. A timeout waiting for the turn re-throws: the command fails, the memory
+      // delta-gate does not advance, and the relay backstop re-sends. Never a silent drop.
+      if (!isTurnInProgressDeliveryError(error)) { this.emptyTurns.disarmInput(contextArm); throw error; }
+      this.sessionLog(`context injection (${reason ?? "no reason"}) deferred behind the active provider turn; re-delivering when it ends`);
+      await this.busyReconciler.waitForProviderTurnClear();
+      try {
+        await deliver();
+      } catch (retryError) {
+        this.emptyTurns.disarmInput(contextArm);
+        throw retryError;
+      }
+    }
+    if (staleArea) { this.emptyTurns.disarmInput(contextArm); return { memoryIds, injectedMemoryCount: 0, staleAreaGeneration: true }; }
+    if (parkedKey !== undefined) {
+      this.emptyTurns.disarmInput(contextArm);
+      if (!await this.persistParkedPrompt(parkedKey)) throw new Error(`context injection (${reason ?? "no reason"}) refused under a provider hold and could not be parked durably; not delivered`);
+      this.sessionLog(`context injection (${reason ?? "no reason"}) refused under a provider hold; parked for redelivery`);
+      this.areaMemory.noteInjected(params, memoryIds);
+      return { memoryIds, injectedMemoryCount: 0, heldForRedelivery: true };
+    }
+    // Record ONLY after a successful delivery (direct or deferred-retry): a failed attempt must
+    // still be retryable, so it never poisons the table.
+    this.injectedContextHashes.add(contentHash);
+    this.areaMemory.noteInjected(params, memoryIds);
+    if (isSelfResumeContinuation && typeof selfResume?.afterClearCommandId === "string") {
+      this.releaseSelfResumeClearFence(selfResume.afterClearCommandId);
+    }
+    return {
+      memoryIds,
+      injectedMemoryCount: memoryIds.length,
+      ...(isSelfResumeContinuation ? {
+        continuationIngested: true,
+        ...(fullContextMessageId !== undefined ? { fullContextMessageId } : {}),
+      } : {}),
+    };
+  }
+
+  private beginSelfResumeClearFence(type: string, params: Record<string, unknown>, commandId: string): void {
+    if (type !== "agent.clearContext") return;
+    this.continuationFence.begin(type, params, commandId, [...this.pendingMessages.keys(), ...(this.drainingMessageIds ?? [])]);
+  }
+
+  private releaseSelfResumeClearFence(clearCommandId: string): void {
+    this.continuationFence.accept(clearCommandId, this.lateClearRecovery.holds(clearCommandId));
+  }
+
+  private holdPreClearInboxMessages(messages: Message[], options: { releaseClaims?: boolean } = {}): Message[] {
+    if (!this.continuationFence.active) return messages;
+    const allowed: Message[] = [];
+    for (const message of messages) {
+      if (this.continuationFence.holds(message.id)) {
+        if (options.releaseClaims) this.taskClaims.clearActiveClaim(message);
+        this.pendingMessages.set(message.id, message);
+      }
+      else allowed.push(message);
+    }
+    return allowed;
+  }
+
+  /** #2550/#3411 — a new provider context generation: charter/memory may land again, every path area is unentered. */
+  private resetContextGeneration(): void { this.injectedContextHashes.clear(); this.areaMemory.resetGeneration(); }
+
+  private recoverLateClear(input: { source?: string; providerSessionId?: string }): string | undefined {
+    if (input.source !== "clear" || input.providerSessionId !== this.providerSessionId) return;
+    const recovery = this.lateClearRecovery.observe();
+    if (!recovery) return;
+    this.resetContextGeneration();
+    const content = lateClearHookContent(recovery);
+    if (content === recovery.content) this.injectedContextHashes.add(createHash("sha256").update(content, "utf8").digest("hex"));
+    this.releaseSelfResumeClearFence(recovery.clearCommandId);
+    this.sessionLog(`late clear committed after ${recovery.clearCommandId} failed; restoring continuation through SessionStart`);
+    return content;
+  }
+
+  private finishLateClearGrace(commandId: string): void {
+    this.continuationFence.endLateClearGrace(commandId);
+    this.sessionLog(`late clear grace ended for ${commandId}; resuming inbox delivery without a confirmed clear`);
+  }
+
+  private async restartProvider(opts: RestartProviderOptions = {}): Promise<void> {
+    this.lifecycle.beginRestart();
+    this.startupPaneDialog = undefined;
+    const priorProviderSessionId = this.providerSessionId;
+    const priorLastTranscriptPath = this.lastTranscriptPath;
+    let providerShutdownFailed = false;
+    let replacementSpawned = false;
+    try {
+      // Fence the old incarnation before adapter shutdown. spawnProvider() reopens provider
+      // sources and heartbeats only after the old shutdown has completed.
+      this.lifecycle.armTerminal();
+      if (this.process) {
+        try {
+          await this.options.adapter.shutdown(this.process, {
+            graceful: true,
+            timeoutMs: this.options.providerConfig.headless.shutdownTimeoutMs,
+          });
+        } catch (error) {
+          providerShutdownFailed = true;
+          throw error;
+        }
+      }
+      this.lifecycleMilestones.onRestart("work-cleared");
+      // #2414 — also honor a shutdown that began mid-restart (signal-driven, before stop() itself
+      // has run); this.lifecycle.stopped alone lags stop()'s own entry.
+      if (this.lifecycle.stopped || this.lifecycle.shuttingDown) return;
+      this.adoptProcess(await this.spawnProvider(opts));
+      this.lifecycleMilestones.onRestart("replacement-adopted");
+      replacementSpawned = true;
+      await this.promptCommands.startLaunchSeededTurn();
+      this.lifecycleMilestones.onRestart("launch-seeded");
+      this.publishStatus();
+      if (this.pendingMessages.size > 0) this.scheduleDrain();
+    } finally {
+      this.lifecycle.finishRestart();
+      // Only a failed teardown can leave the old provider incarnation alive. Reopen every source
+      // armTerminal() fenced in that case; a confirmed shutdown followed by spawn failure has no
+      // surviving provider to watch, while a successful replacement owns freshly reset sources.
+      if (providerShutdownFailed && !replacementSpawned && !this.lifecycle.stopped && !this.lifecycle.shuttingDown) {
+        await this.lifecycleMilestones.onRestart("teardown-failed", priorProviderSessionId, priorLastTranscriptPath);
+      }
+    }
+  }
+
+  private shouldRestartUnexpectedProviderExit(status: SemanticStatus): boolean {
+    return runnerShouldRestartUnexpectedProviderExit(status, {
+      exitCommandInProgress: this.lifecycle.exitCommandInProgress,
+      // #2414 — this is the actual restart-suppression race: `shuttingDown` (armed synchronously
+      // from the signal handler) must win it even before stop() itself has run and set `stopped`.
+      stopped: this.lifecycle.stopped || this.lifecycle.shuttingDown,
+      restartInProgress: this.lifecycle.restartInProgress,
+      provider: this.options.provider,
+      headless: this.options.headless, lifecycle: this.options.lifecycle,
+      hasTerminalSession: typeof this.process?.meta?.tmuxSession === "string"
+        || (this.options.adapter.supportsUnexpectedExitRestart?.() ?? false),
+    });
+  }
+
+  private async restartUnexpectedProviderExit(status: SemanticStatus): Promise<void> {
+    if (this.lifecycle.restartPending) return;
+    this.lifecycle.beginUnexpectedExitRestart();
+    try {
+      // Best-effort Insights capture for the segment that just ended in a crash (#183). This
+      // path has no controlled teardown, so without it crashed sessions silently drop their
+      // context-ratio datapoint. The process handle is still set (cleared later), so the
+      // provider capture source is readable; the runner stays alive here (restart or offline), so the
+      // durable outbox drains normally — no flush needed.
+      await Promise.race([
+        Promise.all([
+          this.captureContextRatio("crash"),
+          this.sessionMirror.settleTerminalTokenUsage(),
+        ]).then(() => undefined),
+        new Promise<void>((resolve) => setTimeout(resolve, PRE_DESTROY_TIMEOUT_MS)),
+      ]).catch((error) => this.sessionLog(`insights: crash capture failed: ${errMessage(error)}`));
+
+      const now = Date.now();
+      const runtimeMs = this.processStartedAt ? now - this.processStartedAt : Number.POSITIVE_INFINITY;
+      const recent = this.unexpectedExitTimes.filter((time) => now - time <= UNEXPECTED_EXIT_WINDOW_MS);
+      recent.push(now);
+      this.unexpectedExitTimes.splice(0, this.unexpectedExitTimes.length, ...recent);
+      const diagnostics = providerExitDiagnostics({ status, runtimeMs, processMeta: this.process?.meta, hasProcess: Boolean(this.process?.process), exitCommandInProgress: this.lifecycle.exitCommandInProgress, stopped: this.lifecycle.stopped || this.lifecycle.shuttingDown, restartInProgress: this.lifecycle.restartInProgress, restartPending: this.lifecycle.restartPending, headless: this.options.headless, provider: this.options.provider, logFile: runnerLogFileFromEnv() });
+
+      this.publishRunnerTimelineEvent({
+        status: "provider.exit_detected",
+        id: `provider-exit-${this.providerSessionId}-${now}`,
+        timestamp: now,
+        title: "Provider exited",
+        body: `${this.options.provider} reported ${status} after ${Math.round(runtimeMs / 1000)}s`,
+        icon: "ti-plug-off",
+        metadata: {
+          eventType: "provider.exit_detected",
+          ...diagnostics,
+        },
+      });
+
+      const nativeSelfResume = this.nativeSelfResume.active;
+      if (nativeSelfResume && getManifest(this.options.provider)?.resume?.supported) {
+        // suppressPrompt only applies (and only matters) on the no-resumeId branch below — see the
+        // gate-hardening note at the tmux-exit-auto-resume call site further down for why it's a
+        // no-op whenever resumeId is set, and what actually keeps a resume off the bypass gate.
+        await recoverNativeSelfResumeExit({ handoff: nativeSelfResume, tracker: this.nativeSelfResume, providerSessionId: this.providerSessionId, status, diagnostics, now, publishTimeline: (event) => this.publishRunnerTimelineEvent(event), setTerminalProviderExit: (marker) => { this.terminalProviderExit = { ...marker, providerSessionId: this.providerSessionId }; }, setProviderStatus: (update) => this.setProviderStatus(update), restartProvider: (resumeId) => this.restartProvider(resumeId ? { resumeId } : { suppressPrompt: true }), publishStatus: () => this.publishStatus(), scheduleDrain: () => this.scheduleDrain() });
+        return;
+      }
+
+      let restartResumeId: string | undefined;
+      if (this.shouldStopUnexpectedProviderExit(diagnostics)) {
+        const resumeId = providerExitResumeId(diagnostics);
+        const hasResumeId = resumeId !== undefined;
+        if (!hasResumeId) {
+          const recoveredStatus = await this.recoveredStatusAfterUndeterminedProviderExit();
+          if (recoveredStatus) {
+            logger.warn("lifecycle", `${this.options.provider} exit signal recovered as ${recoveredStatus}; suppressing terminal exit`);
+            this.publishRunnerTimelineEvent({
+              status: "provider.restart_decision",
+              id: `provider-restart-decision-${this.providerSessionId}-${now}`,
+              timestamp: Date.now(),
+              title: "Provider exit suppressed",
+              body: `${this.options.provider} reported ${recoveredStatus} during exit confirmation; runner kept the provider live.`,
+              icon: "ti-player-play",
+              metadata: {
+                eventType: "provider.restart_decision",
+                decision: "suppress-recovered",
+                reason: "undetermined-provider-exit-recovered",
+                recoveredStatus,
+                confirmWindowMs: UNDETERMINED_PROVIDER_EXIT_CONFIRM_MS,
+                ...diagnostics,
+              },
+            });
+            this.setProviderStatus(recoveredStatus);
+            return;
+          }
+        }
+        if (!hasResumeId && this.shouldRestartRecoverableProviderExit(diagnostics)) {
+          logger.warn("lifecycle", `${this.options.provider} exit signal is early/recoverable; allowing fresh restart`);
+        } else if (resumeId && this.shouldResumeWithContextProviderExit(diagnostics, recent.length)) {
+          // #1258 (L2): a long-lived agent killed via tmux-session-ended (external SIGTERM, reboot,
+          // OOM, admin cleanup) used to be stranded permanently offline even though the provider CLI printed
+          // a resumable session id. Now, when Layer 3 captured a valid resume id, auto-resume WITH
+          // context instead of surfacing manual recovery. Crash-loop protection reuses the existing
+          // unexpected-exit window: `recent` is capped at MAX_RAPID_UNEXPECTED_EXITS within
+          // UNEXPECTED_EXIT_WINDOW_MS, and the fall-through path below applies backoff + a hard
+          // give-up — so a genuinely broken agent stops resurrecting once the window fills, while a
+          // resume that survives past the window resets the counter (no permanent lockout).
+          restartResumeId = resumeId;
+          logger.warn("lifecycle", `${this.options.provider} exited via tmux; auto-resuming with captured context (resume id ${resumeId})`);
+        } else {
+          logger.warn("lifecycle", `${this.options.provider} exited; leaving agent offline for manual recovery`);
+          this.publishRunnerTimelineEvent({
+            status: "provider.restart_decision",
+            id: `provider-restart-decision-${this.providerSessionId}-${now}`,
+            timestamp: Date.now(),
+            title: "Provider restart skipped",
+            body: providerManualRecoveryMessage(this.options.provider, diagnostics),
+            icon: "ti-player-stop",
+            metadata: {
+              eventType: "provider.restart_decision",
+              decision: "stop-surface",
+              reason: providerManualRecoveryReason(diagnostics),
+              ...diagnostics,
+            },
+          });
+          this.process = undefined;
+          // #633: the runner stays alive (manual-resume hold), so neither the orchestrator tmux-gone
+          // path nor the heartbeat reaper will ever fire. Stamp the terminal marker so the SAME offline
+          // status frame (published by setProviderStatus below) carries it; the server's bus status
+          // handler turns that edge into a terminal `agent.exited` event with a #636 diagnosis.
+          this.terminalProviderExit = {
+            providerSessionId: this.providerSessionId,
+            reason: providerManualRecoveryReason(diagnostics),
+            ...diagnostics,
+          };
+          this.setProviderStatus({
+            status,
+            reason: "provider-turn",
+            id: `provider-exit-${this.providerSessionId}`,
+            clear: ["provider-turn", "subagent", "background-script"],
+          });
+          return;
+        }
+      }
+
+      if (runtimeMs < RAPID_EXIT_MS && recent.length > MAX_RAPID_UNEXPECTED_EXITS) {
+        logger.error("lifecycle", `provider session exited ${recent.length} times within ${Math.round(UNEXPECTED_EXIT_WINDOW_MS / 1000)}s; giving up`);
+        this.publishRunnerTimelineEvent({
+          status: "provider.restart_decision",
+          id: `provider-restart-decision-${this.providerSessionId}-${now}`,
+          timestamp: Date.now(),
+          title: "Provider restart skipped",
+          body: `rapid unexpected exits exceeded ${MAX_RAPID_UNEXPECTED_EXITS}`,
+          icon: "ti-alert-triangle",
+          metadata: {
+            eventType: "provider.restart_decision",
+            decision: "give-up",
+            reason: "rapid-unexpected-provider-exits",
+            rapidExitCount: recent.length,
+            rapidExitWindowMs: UNEXPECTED_EXIT_WINDOW_MS,
+            maxRapidUnexpectedExits: MAX_RAPID_UNEXPECTED_EXITS,
+            ...diagnostics,
+          },
+        });
+        this.setProviderStatus(status);
+        this.options.onProviderExit?.(0);
+        return;
+      }
+
+      const delayMs = Math.min(10_000, Math.max(500, 500 * recent.length));
+      const resuming = restartResumeId !== undefined;
+      logger.warn("lifecycle", `provider session exited unexpectedly after ${Math.round(runtimeMs / 1000)}s; ${resuming ? "resuming with context" : "restarting"} in ${delayMs}ms`);
+      this.publishRunnerTimelineEvent({
+        status: "provider.restart_decision",
+        id: `provider-restart-decision-${this.providerSessionId}-${now}`,
+        timestamp: Date.now(),
+        title: "Provider restart scheduled",
+        body: resuming
+          ? `runner will resume ${this.options.provider} with captured context in ${delayMs}ms`
+          : `runner will start a fresh ${this.options.provider} provider in ${delayMs}ms`,
+        icon: "ti-refresh",
+        metadata: {
+          eventType: "provider.restart_decision",
+          decision: resuming ? "resume-with-context" : "restart-fresh",
+          reason: resuming ? "tmux-exit-auto-resume" : "unexpected-headless-terminal-exit",
+          delayMs,
+          rapidExitCount: recent.length,
+          rapidExitWindowMs: UNEXPECTED_EXIT_WINDOW_MS,
+          ...diagnostics,
+        },
+      });
+      await Bun.sleep(delayMs);
+      if (this.lifecycle.stopped || this.lifecycle.exitCommandInProgress) return;
+      try {
+        // #1368/#harden — a resume relaunch always carries a resumeId here, so passing
+        // suppressPrompt would be a no-op (it's only consumed under !resumeId, see spawnProvider).
+        // What actually keeps a skip-permissions resume off the interactive "Bypass Permissions
+        // mode" gate: the config-seed re-heal in profile-home.ts, which idempotently re-applies
+        // every prompt-gate key on the persisted, instance-keyed provider config home before each
+        // launch, plus the adapter's always-on pane-gate send-keys watcher as a fallback if a gate
+        // still renders.
+        await this.restartProvider(restartResumeId ? { resumeId: restartResumeId } : undefined);
+        this.publishStatus();
+        this.scheduleDrain();
+      } catch (error) {
+        logger.error("lifecycle", `provider restart after unexpected exit failed: ${error}`);
+        this.setProviderStatus("error");
+        this.options.onProviderExit?.(1);
+      }
+    } finally {
+      this.lifecycle.finishUnexpectedExitRestart();
+    }
+  }
+
+  private shouldStopUnexpectedProviderExit(diagnostics: Record<string, unknown>): boolean {
+    return getManifest(this.options.provider)?.launch?.managedPolicyPrompt?.alwaysOn === "append-system-prompt" && diagnostics.exitCommandInProgress !== true;
+  }
+
+  private shouldRestartRecoverableProviderExit(diagnostics: Record<string, unknown>): boolean {
+    return diagnostics.exitSource === "tmux-session-ended"
+      && typeof diagnostics.runtimeMs === "number"
+      && diagnostics.runtimeMs >= 0
+      && diagnostics.runtimeMs < RAPID_EXIT_MS;
+  }
+
+  // #1258 (L2): auto-resume-with-context gate for a tmux-session-ended death at any point in an
+  // agent's life (not just the <30s early-flake window). Requires a captured resume id (the caller
+  // only reaches this when one exists) and bounds crash loops via the shared unexpected-exit window:
+  // once `recent` exceeds MAX_RAPID_UNEXPECTED_EXITS the agent is left offline for manual recovery.
+  private shouldResumeWithContextProviderExit(diagnostics: Record<string, unknown>, recentUnexpectedExits: number): boolean {
+    return diagnostics.exitSource === "tmux-session-ended"
+      && recentUnexpectedExits <= MAX_RAPID_UNEXPECTED_EXITS;
+  }
+
+  private async recoveredStatusAfterUndeterminedProviderExit(): Promise<"busy" | "idle" | undefined> {
+    if (!this.process || !this.options.adapter.probeActivity) return undefined;
+    const deadline = Date.now() + UNDETERMINED_PROVIDER_EXIT_CONFIRM_MS;
+    do {
+      const activity = await this.options.adapter.probeActivity(this.process).catch((error) => {
+        this.sessionLog(`provider-exit confirmation probe failed: ${errMessage(error)}`);
+        return "unknown" as const;
+      });
+      if (activity === "busy" || activity === "idle") return activity;
+      if (Date.now() >= deadline) return undefined;
+      await Bun.sleep(PROVIDER_EXIT_CONFIRM_POLL_MS);
+    } while (!this.lifecycle.stopped && !this.lifecycle.exitCommandInProgress);
+    return undefined;
+  }
+
+  private async shutdownProvider(hard: boolean, timeoutMs = this.options.providerConfig.headless.shutdownTimeoutMs): Promise<ShutdownOutcome> {
+    // Close provider-owned status sources before the graceful await, while keeping the runner's
+    // own transitional projection live until the adapter confirms the outcome (#2505).
+    this.lifecycle.armTerminal();
+    this.lifecycle.setLifecycleAction(hard ? "killing" : "shutting-down");
+    this.publishStatus();
+    // #1746 — no process to kill is vacuously terminal. Otherwise the adapter now returns a
+    // VERIFIED terminal outcome (it re-observes liveness, it does not trust the kill call);
+    // a legacy adapter that returns void is treated as `killed` for back-compat.
+    let outcome: ShutdownOutcome = "killed";
+    if (this.process) {
+      outcome = (await this.options.adapter.shutdown(this.process, { graceful: !hard, timeoutMs })) ?? "killed";
+    }
+    this.lifecycle.markStopped();
+    if (outcome === "failed-to-kill") {
+      // Do NOT clear to a normal terminal state: surface the failure so the operator sees a
+      // "kill-failed" pill instead of an indefinite "shutting-down", and so the confirm-dead
+      // gate in handleCommand keeps the agent on the roster rather than deregistering a zombie.
+      this.lifecycle.setLifecycleAction("kill-failed");
+      this.publishStatus();
+      logger.error("lifecycle", `provider force-kill failed for ${this.agentId}: process survived SIGKILL; keeping agent registered`);
+    } else {
+      this.lifecycle.setLifecycleAction(undefined);
+      this.claims.setTerminalStatus("offline");
+      this.publishStatus();
+    }
+    return outcome;
+  }
+
+  private publishRunnerTimelineEvent(event: RunnerTimelineEvent): void {
+    this.context.publishRunnerTimelineEvent(event);
+  }
+
+  private reportBackgroundRejection(scope: string, status: string, title: string, error: unknown): void {
+    this.context.reportBackgroundRejection(scope, status, title, error);
+  }
+
+  private handleBusError(code: string, message: string): void {
+    const action = runnerBusErrorAction(code, this.lifecycle.stopped);
+    if (action === "ignore") return;
+    logger.error("bus", `bus error ${code}: ${message}`);
+    if (action === "stop") {
+      void this.stop().catch((error) => {
+        logger.error("bus", `stop after bus error failed: ${error}`);
+      }).finally(() => exitRunner(0, `bus error ${code}: ${message}`));
+    }
+  }
+
+  private setProviderStatus(update: ProviderStatusUpdate): void {
+    // Once runner-owned teardown begins, every provider-originated frame is stale — including an
+    // early offline hook. The runner keeps its transitional pill until adapter shutdown confirms
+    // completion, then owns the single terminal projection itself.
+    if (this.lifecycle.stopped || this.lifecycle.terminalStatusLatched) return;
+    const status = typeof update === "string" ? update : update.status;
+    this.lastProviderEventAt = Date.now();
+    const providerSessionId = typeof update === "string" ? undefined : update.providerSessionId;
+    if (providerSessionId && providerSessionId !== this.providerSessionId) return;
+    const reason = typeof update === "string" ? "provider-turn" : update.reason ?? "provider-turn";
+    if (status === "busy" && reason === "provider-turn" && this.deliverySubmitHold) this.tryRecoverProviderSubmitHold(true);
+    let id = typeof update === "string" ? reason : update.id ?? reason;
+    if (typeof update !== "string" && update.timeline) {
+      this.pendingTimelineEvent = {
+        status: update.timeline.status,
+        ...(update.timeline.id ? { id: update.timeline.id } : {}),
+        timestamp: update.timeline.timestamp ?? Date.now(),
+        ...(update.timeline.title ? { title: update.timeline.title } : {}),
+        ...(update.timeline.body ? { body: update.timeline.body } : {}),
+        ...(update.timeline.icon ? { icon: update.timeline.icon } : {}),
+        ...(update.timeline.metadata ? { metadata: update.timeline.metadata } : {}),
+      };
+    }
+    let deferredRateLimitHold = false, openQueuedTurn = false;
+    // #2619 — a turn the provider REFUSED (it ends in a rate-limit hold) did not run: it is neither
+    // an empty turn to nudge (the nudge would hit the same wall) nor a completion of claimed work.
+    // The relay's resume turn is the one that gets judged/credited.
+    const providerRefusedTurn = status === "idle" && typeof update !== "string" && update.providerState?.state === "blocked" && update.providerState.reason === "rate_limit";
+    if (typeof update !== "string" && update.providerState) {
+      const ps = update.providerState;
+      // A rate-limit hold persists across the idle the turn ends on; any other
+      // providerState supersedes it (clears a stale hold).
+      if (ps.state === "blocked" && ps.reason === "rate_limit") {
+        const paneRateLimitHold = typeof ps.source === "string" && ps.source.startsWith(`${this.options.adapter.statusSourceId ?? this.options.provider}-pane`);
+        if (status === "idle" && reason === "provider-turn" && paneRateLimitHold && this.claims.activeWork().some((work) => work.kind === "provider-turn")) {
+          this.pendingRateLimitHold = update.providerState;
+          this.providerBlocked = false;
+          deferredRateLimitHold = true;
+          this.sessionLog(`rate-limit hold deferred until active turn finishes (turn ${this.currentTurnId ?? "?"})`);
+        } else {
+          this.providerBlocked = true;
+          this.pendingRateLimitHold = undefined;
+          const fresh = !this.rateLimitHold;
+          this.rateLimitHold = { ...update.providerState, holdEpisodeId: this.hold.refused() };
+          for (const message of this.hold.reparkAcked(update.refusedInputIds ?? [])) {
+            this.taskClaims.clearActiveClaim(message);
+            this.settledMessageIds.delete(message.id);
+          }
+          if (fresh) this.publishRateLimitNotice(update.providerState);
+        }
+      } else if (ps.state === "blocked" && ps.reason === "pendingQuestion") {
+        // #1173: set directly (never deferred) — unlike the rate-limit hold, this always
+        // arrives while the turn that asked is still busy, well before the real idle it must
+        // survive. Any other providerState (a fresh question, a plain approval, etc.) still
+        // supersedes it via the `else` branch below.
+        this.providerBlocked = true;
+        this.pendingQuestionHold = update.providerState;
+      } else {
+        this.providerBlocked = ps.state === "blocked";
+        this.pendingRateLimitHold = undefined;
+        this.rateLimitHold = undefined;
+        this.pendingQuestionHold = undefined;
+      }
+    } else if (status === "idle") {
+      this.providerBlocked = false;
+    }
+    // After the refusal re-park above: a finished turn's input can no longer be refused.
+    if ((status === "idle" && reason === "provider-turn" && !deferredRateLimitHold) || status === "error") this.hold.endTurn();
+    // Forward progress (a real turn) lifts the hold so the blocked badge clears.
+    if (status === "busy") this.rateLimitHold = undefined;
+    if (deferredRateLimitHold) {
+      if (typeof update !== "string") {
+        for (const kind of update.clear ?? []) this.claims.clearWorkKind(kind);
+      }
+      this.publishStatus();
+      return;
+    }
+    if (status === "error") this.emptyTurns.reset();
+    if (typeof update !== "string" && status === "error") {
+      const terminalReason = stringValue(update.metadata?.terminalFailureReason) ?? stringValue(update.providerState?.reason) ?? "provider-error";
+      const terminalMessage = stringValue(update.metadata?.terminalFailureMessage) ?? stringValue(update.providerState?.message) ?? "Provider reported an unrecoverable error.";
+      this.terminalFailure = {
+        reason: terminalReason,
+        message: terminalMessage,
+        ...(update.providerState ? { providerState: update.providerState } : {}),
+      };
+    } else if (status === "idle" || status === "busy") {
+      this.terminalFailure = undefined;
+    }
+    // Compaction lifecycle (`compacting` busy / `compacted` idle timeline) is separate
+    // idle). A `compacted` idle for a turn that predated compaction is a hook artifact — the
+    // turn resumes — so it must NOT end the turn. Discriminate on whether a turn was running,
+    // captured BEFORE the busy logic below mints a currentTurnId (it does for /compact at idle).
+    const timelineStatus = typeof update !== "string" ? update.timeline?.status : undefined;
+    if (timelineStatus === "compacting") {
+      this.compactionMidTurn = this.currentTurnId !== undefined;
+    } else if (timelineStatus === "compacted") {
+      // #3411 — a native compaction drops what area memory delivered, not what the dedupe table proves.
+      this.areaMemory.resetGeneration();
+      this.nativeSelfResume.noteCompacted(typeof update !== "string" && typeof update.timeline?.timestamp === "number" ? update.timeline.timestamp : Date.now());
+      this.publishCompactionNotice();
+      if (this.compactionMidTurn) {
+        // Keep the turn (and its live reasoning tail) alive; the genuine Stop hook ends it.
+        // pendingTimelineEvent (the marker) was set above and is consumed by publishStatus.
+        this.sessionLog(`compaction completed mid-turn (turn ${this.currentTurnId ?? "?"}) — staying busy`);
+        this.publishStatus();
+        return;
+      }
+    }
+    if (status === "busy" && reason === "provider-turn") {
+      // #2482 — a launch-seeded, monitorless Claude turn can discover its transcript only after
+      // the initial synthetic busy edge: Claude writes sessions/<pid>.json asynchronously after
+      // its launcher gate opens. Accept a path on every busy edge, not just the edge that mints
+      // the turn, so the terminal drain still knows where to settle the one/last turn's usage.
+      const nativeTranscriptPath = typeof update !== "string" ? update.transcriptPath : undefined;
+      const startNativeSessionCapture = Boolean(nativeTranscriptPath) && !this.sessionMirror.nativeCaptureActive();
+      if (nativeTranscriptPath) this.lastTranscriptPath = nativeTranscriptPath;
+      if (!this.currentTurnId) {
+        // `update.id` carries a provider-native turn id when available. Falls back
+        // to a random mint only when no native id was supplied.
+        this.currentTurnId = typeof update !== "string" && update.id ? update.id : crypto.randomUUID();
+        this.currentTurnStartedAt = Date.now();
+        this.compactionMidTurn = false;
+        this.emptyTurns.noteTurnStarted(this.currentTurnId, this.currentTurnStartedAt);
+        this.turnReport.noteTurnStarted(this.currentTurnId);
+        this.sessionLog(`turn started (turn ${this.currentTurnId})`);
+        // #2913: never clear pendingQuestionHold here — the busy edge that sets it can mint a turn.
+        // #1235 — a hookless (monitorless) adapter turn carries its live transcript path on the
+        // busy edge. Drive the reasoning tail natively so lean/isolated Claude workers, which
+        // never install the Stop/UserPromptSubmit hooks, still stream chat. Hook-driven agents
+        // never set transcriptPath here, so their hook-triggered capture is untouched.
+      }
+      // startNativeSessionCapture snapshots sessionTurnContext synchronously. It must run after
+      // the branch above mints currentTurnId so native reasoning/tool events retain their turn
+      // correlation on the normal first-probe-success path.
+      if (nativeTranscriptPath && startNativeSessionCapture) {
+        void this.sessionMirror.startNativeSessionCapture(nativeTranscriptPath);
+      }
+      id = this.currentTurnId;
+      this.busyReconciler.arm();
+    } else if (status === "idle" && reason === "provider-turn") {
+      id = typeof update !== "string" && update.id ? update.id : this.currentTurnId ?? reason;
+      openQueuedTurn = this.queuedTurnFollows;
+      this.queuedTurnFollows = false;
+      // A watcher may resolve the transcript on its final idle edge, after its initial busy edge
+      // raced Claude's session-probe creation. Preserve it before deciding whether native capture
+      // is active, so terminal token-usage draining has the same late-bound path.
+      const lateNativeTranscriptPath = typeof update !== "string" ? update.transcriptPath : undefined;
+      if (lateNativeTranscriptPath) this.lastTranscriptPath = lateNativeTranscriptPath;
+      if (this.currentTurnId) {
+        this.completedProviderTurns += 1;
+        this.sessionLog(`turn ended via provider idle (turn ${this.currentTurnId})`);
+        // #2389 — "the provider says idle" is NOT the same as "the turn did something". Take the
+        // verdict after a settle delay, because several capture paths publish the closing response
+        // asynchronously, after this edge.
+        //
+        // A compaction or a context clear is exempt: both mint a provider-turn busy and end it with
+        // an idle (codex.ts emits exactly that pair for `compacted` and `context-cleared`), so the
+        // turn is genuinely output-free and means nothing is wrong. Discarding rather than judging
+        // leaves the undischarged marker intact, so the real turn that follows is still judged.
+        if (timelineStatus === "compacted" || timelineStatus === "context-cleared" || this.compactionMidTurn || providerRefusedTurn) this.emptyTurns.noteTurnDiscarded(this.currentTurnId);
+        else this.emptyTurns.noteTurnEnded(this.currentTurnId, Date.now());
+      }
+      // #1235 — for a native (hookless) turn, capture the final assistant response from the
+      // transcript BEFORE tearing down the tail. Snapshot the ctx while currentTurnId is still
+      // set so the closing response is tagged with the correct turn.
+      const nativeFinish = this.sessionMirror.nativeCaptureActive() || Boolean(lateNativeTranscriptPath);
+      const nativeTranscriptPath = nativeFinish ? (lateNativeTranscriptPath ?? this.lastTranscriptPath) : undefined;
+      const nativeCtx = nativeFinish ? { ...this.turnReport.sessionTurnContext(), opener: this.turnReport.takeTurnOpener(this.currentTurnId) ?? null } : undefined;
+      this.currentTurnId = undefined;
+      this.currentTurnStartedAt = undefined;
+      this.compactionMidTurn = false;
+      this.busyReconciler.disarm();
+      if (nativeFinish) {
+        this.sessionMirror.clearNativeSessionCapture();
+        void this.sessionMirror.finishNativeSessionCapture(nativeTranscriptPath, nativeCtx!);
+      } else {
+        this.sessionMirror.stopReasoningTail();
+      }
+      // Providers with append-system-prompt policy use lifecycle hooks for obligation handling;
+      // others need the runner to re-inject pending obligations on idle.
+      // (#1614) — this delivery can suspend on the FIFO (#1607 N1) and, once resumed, reject if
+      // the process died out from under it or the adapter is mid-turn; reported the same way
+      // attemptInitialPromptDelivery reports its own adapter.deliver failures, so it can never
+      // reach the top as an unhandled rejection (Bun exits(1) on those) and never vanish silently.
+      // (#1617) folded onto the shared reportBackgroundRejection shape — same channel, same
+      // status/title/body, one less hand-rolled copy of the reporting block.
+      if (getManifest(this.options.provider)?.launch?.managedPolicyPrompt?.alwaysOn !== "append-system-prompt") {
+        void this.reInjectPendingObligation().catch((error) => this.reportBackgroundRejection("re-inject pending obligation", "obligation.reinject_failed", "Pending reply obligation not re-injected", error));
+      }
+    }
+    // #2389 — work of any other kind starting inside a live turn (a background script, tracked
+    // subprocess work) is independent proof the model acted, even if nothing was ever mirrored.
+    if (status === "busy" && reason !== "provider-turn" && this.currentTurnId) this.emptyTurns.noteOutput();
+    // A genuine restart back to forward progress clears the terminal-exit marker so a later offline
+    // doesn't re-announce a stale provider exit.
+    if (status === "busy" || status === "idle") this.terminalProviderExit = undefined;
+    if (status === "busy") {
+      this.claims.clearTerminalStatus();
+      // #650: liveness-track the pids a reporter explicitly supplied; otherwise, for a
+      // provider-turn, fall back to the managed provider process itself. If that process
+      // dies out-of-band with no exit event reaching the runner (crash/orphan/external
+      // kill), the reconcile clears the stuck turn → idle. A dead pid means the turn is
+      // definitively over, so this can never falsely clear a live turn (#653's hazard).
+      const reportedPids = typeof update === "string" ? undefined : update.pids;
+      // #1138: process.pid is undefined for tmux-launched providers (Claude) — only
+      // the adapter can resolve a real pid from the tmux session/socket. Without this,
+      // an ordinary hook-driven turn tracks no pid at all, so the stale-turn backstop
+      // below has nothing but elapsed time to go on.
+      const fallbackPid = reason === "provider-turn"
+        ? (typeof this.process?.pid === "number" && this.process.pid > 0
+            ? this.process.pid
+            : this.process ? this.options.adapter.resolveBusyPid?.(this.process) : undefined)
+        : undefined;
+      const livenessPids = reportedPids?.length ? reportedPids : (fallbackPid ? [fallbackPid] : undefined);
+      this.claims.startWork(reason, id, typeof update === "string" ? (livenessPids ? { pids: livenessPids } : {}) : {
+        label: update.label,
+        role: update.role,
+        parentId: update.parentId,
+        ...(livenessPids ? { pids: livenessPids } : {}),
+        metadata: {
+          ...(update.metadata ?? {}),
+          ...(update.providerState ? { providerState: update.providerState } : {}),
+          // #2034 (#2031 L3): stamp/preserve each background task's startedAt — the hook
+          // can only ever report the current snapshot, so age has to be tracked here,
+          // against the prior background-script work record. Pure merge lives in
+          // background-script-reconcile.ts beside this record's other reconcile logic.
+          ...(reason === "background-script" && Array.isArray(update.metadata?.backgroundTasks)
+            ? { backgroundTasks: buildBackgroundTaskLedger(update.metadata.backgroundTasks, this.claims.activeWork().find((work) => work.kind === "background-script" && work.id === id)?.metadata?.backgroundTasks, Date.now()) }
+            : {}),
+        },
+      });
+      // A busy report with liveness-trackable pids arms the periodic reconcile (self-disarms
+      // once no pid-bearing work remains, so idle/untracked agents pay nothing). #1856 — a
+      // `background-script` busy also arms it, even with no pids: it is the ONLY signal that ever
+      // runs the no-pid stale backstop that unwedges a leftover background-script (Claude's hook
+      // can never supply pids for CC background tasks).
+      if (livenessPids?.length || reason === "background-script") this.armBusyLivenessReconcile();
+      if (reason === "provider-turn") {
+        this.taskClaims.observeProviderBusy();
+      }
+    } else if (status === "idle") {
+      this.claims.clearTerminalStatus();
+      if (reason === "provider-turn") this.claims.clearWorkKind("provider-turn");
+      else this.claims.finishWork(reason, id);
+      if (reason === "provider-turn" && !providerRefusedTurn) {
+        this.taskClaims.completeObservedTaskClaims().catch((error) => logger.error("task", `completion enqueue failed: ${error}`));
+        // #2619 — the provider took a turn: the hold episode ends, parked input goes out. Not while
+        // a hold is still standing or pending (a pane-detected wall can land before its turn's idle):
+        // the published hold names this episode and its wake must still act.
+        if (!this.rateLimitHold && !this.pendingRateLimitHold) {
+          const released = this.hold.turnAccepted();
+          for (const message of released) this.pendingMessages.set(message.id, message);
+          if (released.length > 0) this.scheduleDrain();
+        }
+      }
+    }
+    else if (status === "offline" || status === "error") this.claims.setTerminalStatus(status);
+    if (typeof update !== "string") {
+      for (const kind of update.clear ?? []) this.claims.clearWorkKind(kind);
+    }
+    if (!this.claims.activeWork().some((work) => work.kind === "provider-turn")) this.busyReconciler.providerTurnCleared();
+    // #329: the provider just went idle (ready). If a first initial-prompt delivery timed out on
+    // a cold-start TUI, re-attempt now — the ready wait should resolve almost immediately.
+    if (status === "idle") this.promptCommands.retryInitialPrompt();
+    if (status === "idle" && this.pendingRateLimitHold && !this.claims.activeWork().some((work) => work.kind === "provider-turn")) {
+      const hold = this.pendingRateLimitHold;
+      this.pendingRateLimitHold = undefined;
+      this.providerBlocked = true;
+      const fresh = !this.rateLimitHold;
+      this.rateLimitHold = { ...hold, holdEpisodeId: this.hold.refused() };
+      if (fresh) this.publishRateLimitNotice(hold);
+    }
+    // #1146: native self-resume is invoked by the agent itself mid-turn (a tool call from
+    // within its own active response), so the very next idle is almost always the CALLING
+    // turn's own natural end — long before Claude Code even starts processing the queued
+    // `/compact <continuation>`. Resolving on any idle here raced that unrelated end against
+    // the real compaction and (de facto always) won, marking the command "succeeded" and
+    // firing the continuation injection before compaction ever ran — a silent no-op. Gate on
+    // `compactedAt` (stamped only by the genuine PostCompact "compacted" timeline event, via
+    // noteCompacted) so this only resolves once compaction has actually happened.
+    if (status === "idle" && this.nativeSelfResume.active?.compactedAt !== undefined) {
+      this.nativeSelfResume.resolve(this.nativeSelfResume.active, { resumed: true, via: "provider-idle" });
+    }
+    if (openQueuedTurn) return this.openQueuedTurn();
+    this.publishStatus();
+  }
+
+  // #2919 — Claude runs a prompt it queued during the turn's end without a UserPromptSubmit of its own.
+  // The ended turn is settled above; mint the queued turn now. Its tail starts with no turn id so its
+  // steps carry Claude's fresh prompt id, the id its final gets from the Stop (#1086).
+  private openQueuedTurn(): void {
+    this.sessionLog("prompt queued behind the turn end — opening its turn");
+    this.setProviderStatus({ status: "busy", reason: "provider-turn" });
+    const { turnId: _, ...ctx } = this.turnReport.sessionTurnContext(), transcriptPath = this.lastTranscriptPath;
+    if (transcriptPath) void fireAndForget("queued turn reasoning tail", () => this.options.adapter.handleUserPrompt?.({ prompt: "", transcriptPath }, ctx));
+  }
+
+  private publishRunnerStatus(update: RunnerStatusFrame): boolean {
+    // This is the only runner→bus status seam. Once completion pins the claims projection terminal,
+    // no delayed runner callback may publish a non-terminal frame after that edge. During teardown
+    // intent (before completion), runner-owned lifecycle pills are still allowed.
+    const terminal = update.agentStatus === "offline" || update.agentStatus === "error";
+    const projected = this.claims.currentStatus();
+    if ((projected === "offline" || projected === "error") && !terminal) {
+      return false;
+    }
+    // HumwickBusClient.status() only derives semanticStatus from idle/busy frames. Normalize every
+    // accepted terminal frame here as well, otherwise a provider-reported offline edge leaves a
+    // prior busy value alive and the next unsuspended heartbeat resurrects the row as busy.
+    this.bus.setSemanticStatus(terminal ? "idle" : (update.agentStatus as "idle" | "busy"));
+    this.bus.status(update);
+    return true;
+  }
+
+  // #417: when a provider finishes a turn with a pending spawner obligation still
+  // unresolved, re-inject the obligation as a synthetic message so providerMessageText
+  // surfaces the specific `humwick /reply <id>` command.
+  private async reInjectPendingObligation(): Promise<void> {
+    // Filter to spawner obligations only — user obligations go through the existing
+    // prompt-capture path (publishProviderSessionEvent) and the session mirror (#418), never
+      // an explicit /reply. Shared predicate so this rule stays in lockstep with
+      // the stop-hook nag exemption (control-server.replyObligationStopDecision).
+    const obligations = (await this.obligationCache.freshForNag()).filter(obligationNagEligible);
+    if (!this.process) return;
+    // #2619 — no re-injection into a provider hold: it would only be refused.
+    if (this.rateLimitHold || this.hold.activeEpisode) return;
+    if (!obligations.length) return;
+    const MAX_REINJECTIONS = 3;
+    for (const obligation of obligations) {
+      // #2029 — the obligation carries the server's delivery decision. A non-`turn` obligation (wake:false
+      // / session) must never be re-surfaced as a turn nudge: this re-injection path builds a synthetic
+      // frame and calls `adapter.deliver` directly, BYPASSING the fanout seam, so the decision that would
+      // otherwise be lost to the `payload: {}` reconstruction is honored explicitly here instead.
+      if (obligation.deliverySurface && obligation.deliverySurface !== "turn") continue;
+      const count = this.pendingObligationInjections.get(obligation.messageId) ?? 0;
+      if (count >= MAX_REINJECTIONS) continue;
+      this.pendingObligationInjections.set(obligation.messageId, count + 1);
+      this.sessionLog(`re-injecting pending reply obligation #${obligation.messageId} from ${obligation.from} (attempt ${count + 1}/${MAX_REINJECTIONS})`);
+      const replayMessage = {
+        id: obligation.messageId,
+        from: obligation.from,
+        to: this.agentId,
+        kind: obligation.kind,
+        ...(obligation.subject ? { subject: obligation.subject } : {}),
+        body: obligation.bodyPreview,
+        payload: {},
+        // No deliverySurface stamp needed on the replay frame: a non-`turn` obligation is `continue`d
+        // above (and the server only ever stamps a non-`turn` surface), so every frame reaching here is a
+        // plain `turn` re-injection. The decision was honored by the skip, not carried onto the frame.
+        readBy: [] as string[],
+        createdAt: obligation.createdAt,
+      };
+      // Suppress the userMessage echo that providers can reflect back when
+      // a turn is started with relay-formatted content — the echo body is exactly what
+      // providerMessageText produces, which starts with "[relay message #" and is caught
+      // by the RELAY_INJECTION_MARKERS prefix check, but record it explicitly as
+      // defense-in-depth for adapters that might echo only the unformatted body text.
+      this.recordInjectedPrompt(providerMessageText([replayMessage]));
+      // #1607 N1 — route through the FIFO like every other deliver/deliverInitialPrompt call site.
+      // #2389 — a re-injected obligation is the runner asking for work the agent still owes, so it
+      // arms — but as a RETRY, not a fresh ladder arm. This fires up to MAX_REINJECTIONS times per
+      // message; opening a new strike budget each time would let one message earn four nudges and
+      // keep consecutiveEmpty below the escalation threshold indefinitely, on exactly the agents
+      // this feature exists to catch (an outstanding obligation plus empty turns).
+      const arm = this.emptyTurns.armInput(Date.now(), "retry", true);
+      let held = false;
+      try {
+        // #2619 — a refused re-injection spends no attempt and leaves the obligation standing.
+        await this.offerMessagesToProvider(() => [replayMessage], () => {
+          held = true;
+          this.pendingObligationInjections.set(obligation.messageId, count);
+        }, { ctx: { inputObserver: this.emptyTurns.inputObserver(arm) } });
+      } catch (error) {
+        this.emptyTurns.disarmInput(arm);
+        throw error;
+      }
+      if (held) {
+        this.emptyTurns.disarmInput(arm);
+        this.sessionLog(`pending reply obligation #${obligation.messageId} re-injection refused under a provider hold; kept for the next idle`);
+        break;
+      }
+      // Kick off a cache refresh so a cleared obligation (agent replied) is detected
+      // before the next idle fires — without this, the stale snapshot re-injects up to
+      // MAX_REINJECTIONS times even after the agent has already /reply-ed.
+      this.obligationCache.markDirty();
+      // One obligation at a time — let the provider reply before nudging again.
+      break;
+    }
+  }
+
+  // A hook reported an unhandled failure (#198 seam). Already logged FATAL by the control
+  // server; here we additionally surface it durably to the server as a generic insight so
+  // it shows up in observability rather than only in the per-agent log (#196).
+  private reportHookFatal(report: { hook: string; error: string }): void {
+    try {
+      this.insights.queueHookFatal(report);
+    } catch (error) {
+      logger.error("outbox", `failed to queue hook-fatal report: ${errMessage(error)}`);
+    }
+  }
+
+  // Repo-name project id for insight observations, resolved once by the insights collaborator.
+  private insightProject(): string {
+    return this.insights.project();
+  }
+
+  private async captureContinuationArchive(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    await this.insights.captureContinuationArchive(reason, opts);
+  }
+
+  private async captureContextRatio(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    await this.insights.captureContextRatio(reason, opts);
+  }
+
+  // Remember an injected prompt so its UserPromptSubmit echo can be suppressed. Prunes
+  // expired entries first; a defensive length cap guards against echoes that never
+  // arrive (e.g. the provider drops a queued prompt) so the queue can't grow unbounded.
+  private recordInjectedPrompt(text: string, imagePaths?: readonly string[]): void {
+    const now = Date.now();
+    this.injectedPrompts = this.injectedPrompts.filter((p) => now - p.at < PROMPT_ECHO_DEDUP_MS);
+    this.injectedPrompts.push({ text, at: now, imagePaths });
+    if (this.injectedPrompts.length > 50) this.injectedPrompts.shift();
+  }
+
+  private isRunnerInjectedPrompt(text: string): boolean {
+    if (RELAY_INJECTION_MARKERS.some((marker) => text.startsWith(marker))) return true;
+    const now = Date.now();
+    this.injectedPrompts = this.injectedPrompts.filter((p) => now - p.at < PROMPT_ECHO_DEDUP_MS);
+    const matches = this.options.adapter.matchesSubmittedPrompt ?? ((echo: string, sent: string) => echo === sent);
+    const idx = this.injectedPrompts.findIndex((p) => matches(text, p.text, p.imagePaths));
+    if (idx !== -1) {
+      this.injectedPrompts.splice(idx, 1); // consume one — identical repeats each match once
+      return true;
+    }
+    return false;
+  }
+
+  // Force-clear a stuck provider-turn claim directly. Unlike the idle status path
+  // it does NOT depend on a matching claim id (the Stop hook keys busy as
+  // provider-turn:provider-turn, but reconciliation has no specific id), and it
+  // deliberately leaves the reasoning tail alone so a late clear can't truncate
+  // a turn's activity stream.
+  private forceClearProviderTurn(reason: string): void {
+    const work = this.claims.activeWork().find((w) => w.kind === "provider-turn");
+    if (!work) return;
+    this.sessionLog(`force-clearing stuck provider-turn (${reason})`);
+    // #2389 — the OTHER producer of `agent.turn_interrupted`, and the same reason the interrupt
+    // command resets: a force-cleared turn ended with no output through no fault of the model, and
+    // that state already has its own notice. Resetting also drops the turn record this path would
+    // otherwise leave open forever, which would wedge the timed backstop.
+    this.emptyTurns.reset();
+    this.queuedTurnFollows = false;
+    const event = reconciledTurnTimelineEvent({ turnId: this.currentTurnId ?? work.id, reason, startedAt: work.startedAt });
+    this.claims.clearWorkKind("provider-turn");
+    this.busyReconciler.providerTurnCleared();
+    this.currentTurnId = undefined;
+    this.compactionMidTurn = false;
+    // #1621: the clear is EMITTED, not silently applied — publishRunnerTimelineEvent publishes
+    // the status too, so the idle edge and its explanation travel in the same frame.
+    this.publishRunnerTimelineEvent(event);
+  }
+
+  // #2389 — the recovery. NOT a re-send: the instruction is already in the provider's session
+  // history (which is why the stranded agent ran its original spawn prompt the moment a human typed
+  // "hello" at it hours later), so this carries no copy of it. Delivered with origin "runner" so it
+  // does NOT arm the ledger — a nudge that armed a fresh nudge budget would loop without bound
+  // against a provider returning consecutive empty turns, which is the exact scenario this exists
+  // for. The ledger's own one-per-input bound is the primary guard; this is the second.
+  private async deliverEmptyTurnNudge(): Promise<void> {
+    if (this.lifecycle.stopped || this.deliveringEmptyTurnNudge) return;
+    if (!this.process || !this.options.adapter.deliverInitialPrompt) return;
+    this.deliveringEmptyTurnNudge = true;
+    try {
+      this.recordInjectedPrompt(EMPTY_TURN_NUDGE);
+      // Deliberately does NOT call armInput. That is the whole bound: the original input stays
+      // undischarged (so the nudge's own turn is still judged, and a second empty turn escalates),
+      // but the per-input `nudged` flag is not reset — so a provider returning empty turn after
+      // empty turn gets exactly one nudge, never a nudge → empty → nudge runaway.
+      // A refused nudge is simply not sent: it carries no content, and the hold's resume wake is
+      // what continues the agent once the provider takes input again.
+      const outcome = await this.offerPromptToProvider(EMPTY_TURN_NUDGE, { isInitial: false }, () => this.sessionLog("empty-turn nudge refused under a provider hold; the resume wake continues the agent"));
+      if (outcome === "accepted") this.sessionLog("empty-turn nudge delivered (no prompt content re-sent)");
+    } finally {
+      this.deliveringEmptyTurnNudge = false;
+    }
+  }
+
+  // #1980 U2 — the busy backstop has HELD a live provider turn past its prolonged-hold threshold
+  // instead of cancelling it (a frozen-active `shell` gate, or a pane-scrape-only long tool the
+  // runner cannot positively prove idle). Emit a NOTIFY-ONLY watchdog: the turn is untouched (the
+  // card stays busy, no work-kind is cleared, currentTurnId is preserved) — this only tells a
+  // coordinator waiting on the turn that it is being held, not that it ended. The reconciler fires
+  // this at most once per turn, so no de-dup is needed here.
+  private escalateProviderTurnWatchdog(reason: string): void {
+    const work = this.claims.activeWork().find((w) => w.kind === "provider-turn");
+    if (!work) return;
+    this.sessionLog(`busy backstop holding live provider-turn past threshold (${reason}); escalating watchdog notice`);
+    this.publishRunnerTimelineEvent(providerTurnWatchdogTimelineEvent({
+      turnId: this.currentTurnId ?? work.id,
+      reason,
+      startedAt: work.startedAt,
+    }));
+  }
+
+  // #650: reconcile pid-bearing busy work against actual process liveness. A tracked
+  // command/shell that dies out-of-band (killed by the operator, crashes, orphaned)
+  // sends no exit event, so its busy marker would otherwise never clear and the agent
+  // shows `busy` forever — blocking transient auto-reap and holding provider quota.
+  // #1856 — this timer ALSO runs the no-pid `background-script` backstop: Claude's Stop
+  // hook can only post a pid-less `background-script` busy (its `background_tasks[]` payload
+  // exposes no OS pid), which #650's pid reconcile can never touch. So the timer is armed for
+  // ANY background-script busy too, and stays armed while one exists. It self-disarms once
+  // neither pid-bearing work nor a background-script busy remains, so idle agents pay nothing.
+  private armBusyLivenessReconcile(): void {
+    if (this.livenessReconcileTimer || this.lifecycle.stopped) return;
+    this.livenessReconcileTimer = setInterval(() => this.runBusyLivenessReconcile(), BUSY_LIVENESS_RECONCILE_MS);
+  }
+
+  private disarmBusyLivenessReconcile(): void {
+    if (this.livenessReconcileTimer) clearInterval(this.livenessReconcileTimer);
+    this.livenessReconcileTimer = undefined;
+  }
+
+  private runBusyLivenessReconcile(): void {
+    if (this.lifecycle.stopped) {
+      this.disarmBusyLivenessReconcile();
+      return;
+    }
+    let changed = false;
+    const removed = this.claims.reconcileLiveness(isPidAlive);
+    if (removed.length > 0) {
+      changed = true;
+      this.sessionLog(`cleared ${removed.length} stuck busy work item(s) whose tracked process died out-of-band: ${removed.map((w) => `${w.kind}:${w.id}`).join(", ")}`);
+      // A cleared provider-turn must also reset the turn bookkeeping so a later idle
+      // doesn't double-end it and the reasoning tail stops.
+      if (removed.some((w) => w.kind === "provider-turn")) {
+        this.currentTurnId = undefined;
+        this.currentTurnStartedAt = undefined;
+        this.compactionMidTurn = false;
+        this.busyReconciler.disarm();
+        this.sessionMirror.stopReasoningTail();
+        this.busyReconciler.providerTurnCleared();
+      }
+    }
+    // #1856 — the no-pid backstop: a leftover `background-script` busy that outlived its work
+    // (background task finished or was killed manually) leaves the agent wedged busy forever,
+    // because it carries no pid to reconcile and only the next turn's Stop hook would clear it.
+    // Once the busy state is background-script ALONE (the provider turn already ended) and has
+    // gone quiet past the stale window, force-clear it so the agent reconciles to idle on its
+    // own — no human nudge, and the held turn-final report can flush on the resulting reap.
+    if (isStaleBackgroundScriptOnlyBusy({ activeWork: this.claims.activeWork(), lastProgressAt: this.lastProviderEventAt, now: Date.now(), isPidAlive })) {
+      changed = true;
+      this.sessionLog("clearing stale background-script busy: provider idle past the stale window with no live background work — reconciling to idle");
+      this.claims.clearWorkKind("background-script");
+    }
+    if (changed) this.publishStatus();
+    // Stay armed while a background-script busy remains (its no-pid backstop above needs the timer);
+    // otherwise self-disarm once no pid-bearing work is left, so idle agents pay nothing.
+    if (!this.claims.hasLivenessTrackedWork() && !this.claims.activeWork().some((work) => work.kind === "background-script")) this.disarmBusyLivenessReconcile();
+  }
+
+  // Mirror a discreet, durable "context compacted" marker into chat via the existing
+  // session-mirror lane (not a parallel channel). `notice` renders as an inline timeline
+  // marker (never a bubble) and survives reload, unlike the ephemeral timeline-status one.
+  private publishCompactionNotice(): void {
+    this.sessionMirror.publishSessionEvent({
+      from: this.agentId,
+      to: "user",
+      body: "🗜 Context compacted",
+      session: { type: "notice", origin: "provider", label: "compacted", ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}) },
+    });
+  }
+
+  private publishPermissionAbandonedNotice(input: PendingPermissionRequestRecord & { reason: string }): void {
+    const title = input.view.title || "permission request";
+    this.sessionMirror.publishSessionEvent({
+      from: this.agentId,
+      to: "user",
+      body: `Permission request denied after runner restart: ${title}. ${input.reason}`,
+      occurredAt: Date.now(),
+      session: {
+        type: "notice",
+        origin: "provider",
+        label: "permission-denied",
+        stepId: `permission-abandoned:${input.approvalId}`,
+        ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}),
+      },
+    });
+  }
+
+  // #286: a discreet, durable chat marker when a usage/rate-limit hold begins, via
+  // the same session-mirror lane as the compaction notice. Outbound session event
+  // (NOT an inbound message) so it shows in the dashboard chat WITHOUT waking a turn
+  // — waking a still-limited agent would just re-fail. The relay sends the waking
+  // resume message later, once the window has reset.
+  private publishRateLimitNotice(providerState: ProviderState): void {
+    const label = providerState.label || "usage limit reached";
+    this.sessionMirror.publishSessionEvent({
+      from: this.agentId,
+      to: "user",
+      body: `⏳ ${label} — ${providerState.kind === PROXY_AUTH_HOLD_KIND ? "holding until its Vault access is fixed and the agent restarts." : "holding; Humwick will auto-resume at reset."}`,
+      session: { type: "notice", origin: "provider", label: "rate-limit", ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}) },
+    });
+  }
+
+  private isStaleProviderTurnOnlyBusy(
+    status: SemanticStatus,
+    activeWork: Array<{ kind: string; pids?: number[] }>,
+    busyReasons: string[],
+    liveness: { hasLiveWork: boolean; lastProgressAt: number },
+  ): boolean {
+    if (status !== "busy") return false;
+    if (activeWork.length === 0 || activeWork.some((work) => work.kind !== "provider-turn")) return false;
+    if (busyReasons.some((reason) => reason !== "provider-turn")) return false;
+    if (liveness.hasLiveWork || !liveness.lastProgressAt) return false;
+    // #1138: a turn whose tracked pid is still alive is definitively still running — a
+    // silent single Claude turn (no subagents, no compaction event) must not be
+    // force-healed to idle purely because it's been quiet past the threshold. Only fall
+    // back to the elapsed-time heuristic when there's no pid evidence to check; the #650
+    // reconcile independently clears a confirmed-dead pid's work the instant it dies, so
+    // this can never mask a genuine leak.
+    if (activeWork.some((work) => work.pids?.some((pid) => isPidAlive(pid)))) return false;
+    return Date.now() - liveness.lastProgressAt >= STALE_PROVIDER_TURN_BUSY_MS;
+  }
+
+  private readonly tokenUsageCoverage = new TokenUsageReportCoverage(() => this.publishStatus());
+  private publishStatus(): void {
+    this.claims.expire();
+    const status = this.claims.currentStatus();
+    const activeWork = this.claims.activeWork();
+    const activeSubagents = activeWork.filter((item) => item.kind === "subagent");
+    const terminalFailure = this.terminalFailure;
+    const timelineEvent = this.pendingTimelineEvent;
+    // §4.1 Runner↔provider liveness contract (#725 / #746): fold the raw transport/timeline/
+    // token/work-kind signals into ONE normalized verdict the server reads instead of six raw
+    // `meta` fields. The adapter owns what counts as progress for its provider (#713/#724);
+    // mock adapters fall back to the shared fold.
+    const livenessInputs: LivenessInputs = {
+      transport: this.bus.transportState,
+      ...(this.lastProviderEventAt !== undefined ? { lastProviderEventAt: this.lastProviderEventAt } : {}),
+      ...(timelineEvent ? { timelineEvent } : {}),
+      activeWork,
+      // #1980 U3 — feed the runner's coarse status + provider-hold flag so the fold can derive
+      // busyPhase (active/passive/blocked) beside hasLiveWork, provider-agnostically.
+      providerStatus: status,
+      providerBlocked: this.providerBlocked || this.startupPaneDialog !== undefined || this.deliverySubmitHold !== undefined,
+    };
+    const liveness = this.options.adapter.liveness
+      ? this.options.adapter.liveness(livenessInputs)
+      : computeLivenessSignal(livenessInputs);
+    const busyReasons = this.claims.reasons();
+    const staleProviderTurnBusy = this.isStaleProviderTurnOnlyBusy(status, activeWork, busyReasons, liveness);
+    const effectiveStatus = staleProviderTurnBusy ? "idle" : status;
+    // Teardown keeps the process registered but deliberately non-addressable until its outcome is
+    // confirmed. Project every teardown pill through this one seam as idle+ready:false; if provider
+    // state was already terminal, keep that terminal frame so the shared publish guard cannot drop it.
+    const teardownLifecycle = this.lifecycle.lifecycleAction === "shutting-down"
+      || this.lifecycle.lifecycleAction === "killing"
+      || this.lifecycle.lifecycleAction === "kill-failed";
+    const agentStatus = teardownLifecycle && effectiveStatus !== "offline" && effectiveStatus !== "error"
+      ? "idle"
+      : runnerAgentStatus(effectiveStatus);
+    // #2389 — `emptyTurnState` is the LAST fallback: a live hold, a pending question or real active
+    // work all describe the agent better than "the previous turn was empty", and any of them means
+    // it is no longer sitting idle having produced nothing.
+    const providerState = this.deliverySubmitHold ?? terminalFailure?.providerState ?? this.startupPaneDialog ?? this.rateLimitHold ?? this.pendingQuestionHold
+      ?? (staleProviderTurnBusy ? null : providerStateFromActiveWork(activeWork))
+      ?? (activeWork.length === 0 ? this.emptyTurns.providerState() ?? null : null);
+    const published = this.publishRunnerStatus({
+      agentStatus,
+      ready: agentStatus !== "offline" && !this.lifecycle.stopped && !teardownLifecycle && !this.startupPaneDialog && !this.deliverySubmitHold,
+      meta: {
+        ...runnerIdentityMeta(this.options, { tmuxSession: providerTerminalSession(this.process), tmuxSocket: providerTerminalSocket(this.process), auth: { profileId: this.credentials.profileId, jti: this.credentials.jti, expiresAt: this.credentials.expiresAt } }, "status"),
+        lifecycleAction: this.lifecycle.lifecycleAction ?? null,
+        lifecycleActionAt: this.lifecycle.lifecycleActionAt ?? null,
+        ...(status === "error" ? { terminalStatus: "error" } : {}),
+        ...(terminalFailure ? {
+          lastError: terminalFailure.message,
+          terminalFailureReason: terminalFailure.reason,
+          terminalFailureMessage: terminalFailure.message,
+        } : {}),
+        // #633 — terminal provider-exit marker (runner alive, provider gone). Drives the server's
+        // silent-death terminal event + #636 post-mortem.
+        ...(this.terminalProviderExit ? {
+          terminalProviderExit: this.terminalProviderExit,
+          lastError: providerExitLastError(this.options.provider, this.terminalProviderExit),
+        } : {}),
+        busyReasons: staleProviderTurnBusy ? busyReasons.filter((reason) => reason !== "provider-turn") : busyReasons,
+        completedProviderTurns: this.completedProviderTurns,
+        // #2389 — machine-readable beside the displayed providerState, so a coordinator polling the
+        // roster can tell "idle having produced nothing" from "idle having finished work" without
+        // reading the timeline. 0 once any turn produces output again.
+        consecutiveEmptyTurns: this.emptyTurns.consecutiveEmptyTurns(),
+        unreportedTokenUsage: this.tokenUsageCoverage.unreported, // #3351
+        activeWork,
+        activeSubagents,
+        activeSubagentCount: activeSubagents.length,
+        ...(this.lastProviderEventAt !== undefined ? { lastProviderEventAt: this.lastProviderEventAt } : {}),
+        providerState,
+        // #2365 — this is a one-shot marker. An explicit null lets Relay's merge-patch status
+        // ingress delete the previously consumed event on the next frame instead of auditing the
+        // same latched watchdog transition for every subsequent provider update.
+        timelineEvent: timelineEvent ?? null,
+        transport: this.bus.transportState,
+        // #746 — normalized liveness verdict; the server reads ONLY this for stuck-busy.
+        // The raw fields above stay for other consumers (timeline rendering, diagnostics).
+        liveness,
+      },
+    });
+    // A dropped post-terminal frame must defer its timeline evidence, not consume it. Clear only
+    // the exact event carried by a successfully published frame; a newer event wins the race.
+    if (published && this.pendingTimelineEvent === timelineEvent) this.pendingTimelineEvent = undefined;
+  }
+
+  private startHttpLiveness(): void { this.httpLiveness.start(); }
+
+  private logRunnerDiagnostic(message: string): void { this.context.logRunnerDiagnostic(message); }
+  private sessionLog(message: string): void { this.context.sessionLog(message); }
+  private sessionDebug(message: string): void { this.context.sessionDebug(message); }
+
+  private ensureScratch(): void {
+    try {
+      this.scratch = ensureSessionScratch({
+        agentId: this.agentId,
+        cwd: this.options.cwd,
+        fallbackBaseDir: orchestratorBaseDirFromEnv(),
+      });
+    } catch (error) {
+      this.logRunnerDiagnostic(`session scratch setup failed: ${errMessage(error)}`);
+    }
+  }
+
+  private scheduleAttachmentCacheSweep(): void { this.attachmentCacheSweep.start(); }
+
+  // #1245 — a newly allowed tool group or scope reaches the next generation without a restart.
+  private remintRuntimeTokenAtBoundary(reason: "clear" | "compact"): Promise<Record<string, unknown>> {
+    return this.credentials.remintRuntimeTokenAtBoundary(reason);
+  }
+
+  private heartbeatRuntimeMeta(): Record<string, unknown> | undefined {
+    const processContext = this.latestProcessContext();
+    const probeMetrics = this.latestProbeMetrics();
+    const probeContext = probeMetrics ? contextStateFromProbeMetrics(probeMetrics) : undefined;
+    let context = processContext ?? probeContext;
+    // #1512: when a provider has no event-stream context of its own, fall back to
+    // the transcript so context.lastUpdatedAt keeps advancing after an in-process
+    // compact/clear/native-resume freezes the status-line probe. Freshest wins, so
+    // a live probe still takes precedence (source stays "statusline").
+    if (!processContext) {
+      const derived = this.sessionMirror.transcriptContext(probeMetrics?.tokensMax);
+      if (derived && (!probeContext || derived.lastUpdatedAt > probeContext.lastUpdatedAt)) {
+        context = derived;
+      }
+    }
+    // #2095 test rig — override the reported context with the forced synthetic while the one-shot
+    // latch is armed. Applied AFTER the real context is resolved (so tokensMax/window carry over) and
+    // BEFORE providerCapabilities + meta.context are built from it, so the server ingests the forced
+    // utilization and its REAL lifecycle tick drives the REAL advisory + forced clear-inject.
+    context = this.registration.applyForcedContext(context);
+    const quota = probeMetrics ? quotaStateFromProbeMetrics(probeMetrics) : undefined;
+    const terminalSession = providerTerminalSession(this.process);
+    const terminalSocket = providerTerminalSocket(this.process);
+    const probeModel: ProbeModelInfo | undefined = probeMetrics?.model || probeMetrics?.effort
+      ? { model: probeMetrics.model, effort: probeMetrics.effort }
+      : undefined;
+    const meta: Record<string, unknown> = {
+      providerCapabilities: runtimeProviderCapabilities({ ...this.options, effort: this.effortRuntime.effort, effortSwitch: runnerEffortSwitch(this.options.adapter, this.process) }, context, probeModel, quota),
+      ...runnerIdentityMeta(this.options, { tmuxSession: terminalSession, tmuxSocket: terminalSocket }, "heartbeat"),
+    };
+    if (context) meta.context = context;
+    return meta;
+  }
+
+  private latestProcessContext(): ContextState | undefined {
+    const getContext = this.process?.meta?.getContext;
+    if (typeof getContext === "function") {
+      const context = getContext();
+      if (isContextState(context)) return context;
+    }
+    const context = this.process?.meta?.context;
+    return isContextState(context) ? context : undefined;
+  }
+
+  private latestProbeMetrics() {
+    return readRunnerContextProbeState(this.agentId);
+  }
+
+  private matchesMessage(message: Message): boolean {
+    return runnerMessageMatches(message, {
+      agentId: this.agentId,
+      label: this.options.label,
+      provider: this.options.provider,
+      tags: this.options.tags,
+      capabilities: this.options.capabilities,
+      defaultTags: this.options.providerConfig.defaultTags,
+      defaultCapabilities: this.options.providerConfig.defaultCapabilities,
+      allowBroadTargets: this.options.agentProfile?.relay?.context !== false,
+    });
+  }
+
+}