agent-relay-runner 0.62.3 → 0.63.0

package/src/runner.ts

@@ -1,2660 +1,14 @@
-import { hostname } from "node:os";
-import { closeSync, mkdirSync, openSync, readSync, statSync, writeFileSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import type { AgentLifecycle, AgentProfile, ContextState, Message, MessageSessionMeta, ProviderCapabilities, SendMessageInput, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
-import { errMessage, RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
-import { contextStateFromProbeMetrics, readContextProbeState } from "agent-relay-sdk/context-probe";
-import { providerAttachmentText, providerMessageText } from "./adapter";
-import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
-import { messagesWithCachedAttachments } from "./attachment-cache";
-import { resolveProjectName } from "./config";
-import { ClaimTracker } from "./claim-tracker";
-import { startControlServer, type ControlServer } from "./control-server";
-import { ReplyObligationCache, obligationRequiresExplicitReply } from "./reply-obligation-cache";
-import { Outbox, type OutboxRecord } from "./outbox";
-import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, countTranscriptEntries, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
-import { computeContextRatio } from "./session-insights";
-import { agentProfileProjectionReport } from "./profile-projection";
-import { profileUsesHostProviderGlobals } from "./profile-home";
-import { RELAY_MCP_TOKEN_ENV, relayMcpEndpoint } from "./relay-mcp";
-import { RelayMcpProxy } from "./relay-mcp-proxy";
-import { runtimeMetadata } from "./version";
-import { logger, parseLogLevel } from "./logger";
-import { ensureSessionScratch, reapSessionScratch, sweepStaleSessions, type SessionScratchLayout } from "./session-scratch";
-import { boundContinuationArchiveSegment, deliverContinuationArchiveRecord } from "./continuation-archive";
-
-// A destructive session transition. The runner runs end-of-session work (Insights
-// capture, #183/#184) before the invasive operation and, during that window, presents a
-// distinct non-addressable lifecycle state. Bus commands and provider hooks (Claude
-// PreCompact / SessionEnd) both normalize to one of these.
-type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill" | "crash";
-
-// Reasons after which the runner process won't survive to drain the durable outbox (and the
-// per-agent outbox is never reopened once the agent is gone). For these, pre-destroy must
-// block on delivery of the just-captured Insights datapoint, not just enqueue it (#183).
-// `restart` (bus command) deliberately excluded: the runner stays alive and drains normally.
-function reasonExitsRunner(reason: SessionDestroyReason): boolean {
-  return reason === "shutdown" || reason === "kill" || reason === "crash";
-}
-
-// `finalizing-<reason>` is the transient pre-destroy window; the others are the executing
-// teardown states the dashboard already renders.
-type LifecycleAction =
-  | "shutting-down" | "killing" | "restarting"
-  | `finalizing-${SessionDestroyReason}`;
-
-// Pre-destroy work is best-effort and must never hang teardown. Capping it keeps a slow
-// transcript read or a wedged provider from stalling a shutdown the operator asked for.
-const PRE_DESTROY_TIMEOUT_MS = 4_000;
-
-// Bounded window to deliver the durable outbox before an exit-bound teardown (#183). Kept
-// short so a wedged/down server can't stall an operator-requested shutdown for long; a
-// row that still can't land is logged, not silently dropped.
-const OUTBOX_FLUSH_TIMEOUT_MS = 3_000;
-
-// Map a lifecycle bus command to its destructive boundary reason, or undefined for
-// non-destructive commands (interrupt, inject, reconnect, permission decisions).
-function boundaryReasonForCommand(type: string): SessionDestroyReason | undefined {
-  switch (type) {
-    case "agent.compact": return "compact";
-    case "agent.clearContext": return "clear";
-    case "agent.restart": return "restart";
-    case "agent.shutdown": return "shutdown";
-    case "agent.kill": return "kill";
-    default: return undefined;
-  }
-}
-
-interface RunnerOptions {
-  provider: string;
-  model?: string;
-  effort?: string;
-  runnerId: string;
-  instanceId: string;
-  agentId?: string;
-  relayUrl: string;
-  token?: string;
-  tokenJti?: string;
-  tokenProfileId?: string;
-  tokenExpiresAt?: number;
-  rootTokenFallback?: boolean;
-  cwd: string;
-  headless: boolean;
-  approvalMode: string;
-  label?: string;
-  rig?: string;
-  profile?: string;
-  agentProfile?: AgentProfile;
-  prompt?: string;
-  systemPromptAppend?: string;
-  tags: string[];
-  capabilities: string[];
-  providerArgs: string[];
-  policyName?: string;
-  spawnRequestId?: string;
-  automationId?: string; automationRunId?: string;
-  workspace?: WorkspaceMetadata; lifecycle?: AgentLifecycle;
-  tmuxSession?: string;
-  startedAt: number;
-  providerConfig: ProviderConfig;
-  adapter: ProviderAdapter;
-  onProviderExit?: (code: number | null) => void;
-  exitProcessOnShutdown?: boolean;
-}
-
-interface ActiveTaskClaim {
-  messageId: number;
-  taskId: number;
-  observedProviderBusy: boolean;
-}
-
-const CLAIM_RENEW_INTERVAL_MS = 5 * 60 * 1000;
-const HTTP_LIVENESS_INTERVAL_MS = 20_000;
-const HTTP_LIVENESS_LOG_INTERVAL_MS = 5 * 60 * 1000;
-const TOKEN_RENEW_RETRY_MS = 60_000;
-// Debounce reactive token recovery so a burst of 401-ing calls in the same window
-// triggers a single re-mint attempt, not one per failing request.
-const REACTIVE_TOKEN_RECOVERY_DEBOUNCE_MS = 10_000;
-const UNEXPECTED_EXIT_WINDOW_MS = 2 * 60 * 1000;
-const RAPID_EXIT_MS = 30 * 1000;
-const MAX_RAPID_UNEXPECTED_EXITS = 3;
-const MAX_TIMER_DELAY_MS = 2_147_483_647;
-const LOG_TAIL_BYTES = 128 * 1024;
-// 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;
-// Busy reconciler: a conservative LAST-RESORT backstop for a turn that ended
-// without the provider's Stop hook clearing busy (e.g. ESC straight into the web
-// terminal). It must never fire during a live turn, so it requires a long,
-// unbroken idle streak — an active turn shows its working spinner well within
-// this window, which resets the streak. ~32s of uninterrupted idle = really done.
-const BUSY_RECONCILE_POLL_MS = 4_000;
-const BUSY_RECONCILE_IDLE_CONFIRM = 8;
-// When the reconciler never observed the provider busy this turn (a turn faster
-// than the 4s poll — common for short voice/autosend replies), it can't trust a
-// quick idle the way it does after seeing the spinner. But refusing forever wedged
-// fast turns in "busy" when the Stop hook's idle was lost (#199). So we still
-// force-clear, just after a much longer unbroken-idle window — an active turn would
-// have flashed its spinner into at least one of these probes and reset the streak.
-const BUSY_RECONCILE_IDLE_CONFIRM_NO_BUSY = 15;
-// After a dashboard interrupt, give the provider a moment to drop out of its turn,
-// then reconcile immediately so the user sees "stopped" without waiting for the backstop.
-const INTERRUPT_RECONCILE_DELAY_MS = 1_500;
-// 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>"];
-// #329: a cold isolated profile (first-run trust/onboarding/install gates) can take far longer
-// than the warm-restart window to render an input-ready TUI, so the first prompt delivery gets a
-// generous timeout. If it still misses, the prompt is re-attempted on the next provider ready
-// signal (short timeout, since it just went idle), up to a bounded number of attempts.
-const INITIAL_PROMPT_FIRST_READY_TIMEOUT_MS = 30_000;
-const INITIAL_PROMPT_RETRY_READY_TIMEOUT_MS = 10_000;
-const MAX_INITIAL_PROMPT_ATTEMPTS = 6;
-// Reasoning tailer poll cadence (item 5). Coarse on purpose — reasoning is a
-// discreet progress signal, not a token stream, so ~1.2s keeps it light.
-const REASONING_POLL_MS = 1_200;
-const CLAUDE_RESUME_RE = /\bclaude\s+--resume\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/gi;
-
-interface RunnerTimelineEvent {
-  status: string;
-  id?: string;
-  timestamp: number;
-  title?: string;
-  body?: string;
-  icon?: string;
-  metadata?: Record<string, unknown>;
-}
-
-export class AgentRunner {
-  private readonly agentId: string;
-  private readonly claims = new ClaimTracker();
-  private readonly http: RelayHttpClient;
-  private readonly bus: RelayBusClient;
-  // 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;
-  // #332: a fast-lane outbox for display-only session-mirror trace events. Routing them through
-  // their own FIFO queue stops one transient trace failure from head-of-line blocking real-message
-  // delivery (and vice versa); its backoff is capped low since a stale live-mirror frame is cheap.
-  private readonly sessionOutbox: Outbox;
-  private currentToken?: string;
-  private currentTokenJti?: string;
-  private currentTokenProfileId?: string;
-  private currentTokenExpiresAt?: number;
-  private control?: ControlServer;
-  // 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 stopped = false;
-  private exitCommandInProgress = false;
-  private restartInProgress = false;
-  // Set for the whole unexpected-exit restart, including the pre-restart backoff
-  // sleep, so a second exit during that window can't launch a parallel restart.
-  private restartPending = false;
-  private delivering = false;
-  private drainTimer?: Timer;
-  private claimRenewTimer?: Timer;
-  private httpLivenessTimer?: Timer;
-  private httpLivenessInFlight = false;
-  private httpLivenessAuthFailed = false;
-  private httpLivenessLastLog?: { key: string; at: number };
-  private tokenRenewTimer?: Timer;
-  private tokenRenewInFlight = false;
-  private tokenRenewLastLog?: { key: string; at: number };
-  private reactiveTokenRecoveryAt?: number;
-  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 lifecycleAction?: LifecycleAction;
-  // #183/#184 per-segment cursor: how many of the current session's normalized events
-  // have already been folded into an observation, and the key (transcript path / Codex
-  // session) that count belongs to. A boundary captures only events since the last one,
-  // so each datapoint is one work chunk between context resets; a key change or a shrink
-  // (transcript rotated, Codex buffer trimmed) resets the cursor.
-  private insightsObserved = 0;
-  private insightsCursorKey = "";
-  private archiveObservedChars = 0;
-  private archiveCursorKey = "";
-  // Memoized repo-name project id for insight observations (resolved once; involves a
-  // git toplevel lookup for direct agents). Aggregates by repo, not per-session worktree.
-  private insightProjectName?: string;
-  // Coalesces concurrent pre-session-destroy runs (e.g. the shutdown bus command and the
-  // SessionEnd hook both fire for the same teardown) so the cursor isn't raced.
-  private preDestroyPromise?: Promise<void>;
-  private readonly unexpectedExitTimes: number[] = [];
-  private readonly pendingMessages = new Map<number, Message>();
-  private readonly activeTaskClaims = new Map<number, ActiveTaskClaim>();
-  private pendingTimelineEvent?: RunnerTimelineEvent;
-  private pendingPromptMessageId?: number;
-  // #329: a spawn-time initial prompt whose first delivery timed out before the TUI was
-  // ready. Held (not dropped) for a ready-signal-driven re-attempt; cleared on success.
-  private pendingInitialPrompt?: string;
-  private deliveringInitialPrompt = false;
-  private initialPromptAttempts = 0;
-  // 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;
-  // #435: high-water-mark for the pre-turn narrative flush. Counts how many
-  // valid JSONL entries were in the transcript at last pre-flush time so the
-  // Stop-hook capture (full mode) can skip what was already emitted.
-  private narrativeFlushEntryCount = 0;
-  // True while a turn that was already in flight is being compacted. Claude's PostCompact
-  // hook posts a single `idle`, but a mid-turn compaction RESUMES the turn 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 }> = [];
-  // Busy reconciler: consecutive idle probes observed while claims still say busy.
-  private busyReconcileIdleStreak = 0;
-  private busyReconcileTimer?: ReturnType<typeof setInterval>;
-  // The reconciler only trusts an "idle" reading once it has seen the provider
-  // actually busy this turn — so a flaky/always-idle probe can never false-clear.
-  private busyReconcileSawBusy = false;
-  // Verbose session-mirror diagnostics (turn lifecycle, reconciler probes, tail
-  // emits) → a dedicated clean log. Always on for key transitions; AGENT_RELAY_SESSION_DEBUG=1 adds the high-frequency probe/emit lines.
-  private readonly sessionDebugVerbose = process.env.AGENT_RELAY_SESSION_DEBUG === "1";
-  // 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;
-  private terminalFailure?: { reason: string; message: string; providerState?: Record<string, unknown> };
-  // #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?: Record<string, unknown>;
-  // Reasoning tailer (item 5): streams the in-flight turn's reasoning/tool steps
-  // from the Claude transcript into chat as discreet session events.
-  private reasoningTail?: { timer: ReturnType<typeof setInterval>; seen: Set<string> };
-  private scratch?: SessionScratchLayout;
-  // #417: for non-claude providers, tracks how many times each spawner obligation has
-  // been re-injected so a non-responsive agent can't spin in a re-injection loop.
-  private readonly pendingObligationInjections = new Map<number, number>();
-
-  constructor(private readonly options: RunnerOptions) {
-    this.agentId = options.agentId ?? options.runnerId;
-    // Bind the process-global logger to this agent. AGENT_RELAY_SESSION_DEBUG=1 is
-    // kept as a back-compat alias for the verbose probe/emit lines, now expressed
-    // as log level "debug" (AGENT_RELAY_LOG_LEVEL still wins when both are set).
-    logger.configure({
-      agentId: this.agentId,
-      headless: options.headless,
-      ...(this.sessionDebugVerbose && !parseLogLevel(process.env.AGENT_RELAY_LOG_LEVEL) ? { level: "debug" as const } : {}),
-    });
-    this.currentToken = options.token;
-    this.currentTokenJti = options.tokenJti;
-    this.currentTokenProfileId = options.tokenProfileId;
-    this.currentTokenExpiresAt = options.tokenExpiresAt;
-    this.mcpProxyEnabled = !["0", "false", "off"].includes((process.env.AGENT_RELAY_MCP_PROXY ?? "").trim().toLowerCase());
-    this.mcpProxySecret = crypto.randomUUID();
-    const runtime = runtimeMetadata(options.provider);
-    this.http = new RelayHttpClient({ baseUrl: options.relayUrl, token: this.currentToken });
-    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 = process.env.AGENT_RELAY_RUNNER_OUTBOX_DIR
-      ?? (process.env.AGENT_RELAY_RUNNER_INFO_FILE ? join(dirname(process.env.AGENT_RELAY_RUNNER_INFO_FILE), "outbox") : undefined);
-    this.outbox = new Outbox({ agentId: this.agentId, dir: outboxDir, send: (record) => this.deliverOutboxEvent(record) });
-    this.sessionOutbox = new Outbox({
-      agentId: `${this.agentId}-session`,
-      dir: outboxDir,
-      send: (record) => this.deliverOutboxEvent(record),
-      // Ephemeral trace frames: cap the per-row stall low and poison sooner than the main queue.
-      maxBackoffMs: 5_000,
-      maxAttempts: 6,
-    });
-    this.bus = new RelayBusClient({
-      url: relayBusUrl(options.relayUrl),
-      role: "provider",
-      componentId: options.runnerId,
-      agentId: this.agentId,
-      instanceId: options.instanceId,
-      token: this.currentToken,
-      machine: hostname(),
-      capabilities: [
-        ...new Set([
-          ...options.providerConfig.defaultCapabilities,
-          ...options.capabilities,
-          ...csvTags(process.env.AGENT_RELAY_CAPS),
-          "lifecycle.shutdown.hard",
-          "lifecycle.restart.hard",
-          "lifecycle.status.semantic",
-          "lifecycle.heartbeat",
-          "lifecycle.reconnect.transport",
-          "commands.lifecycle",
-          "capabilities.report",
-        ]),
-      ],
-      tags: [...new Set([options.provider, ...csvTags(process.env.AGENT_RELAY_TAGS), ...options.tags, ...options.providerConfig.defaultTags, ...(options.headless ? ["headless"] : [])])],
-      meta: {
-        ...runtime,
-        version: runtime.package.version,
-        provider: options.provider,
-        model: options.model ?? null,
-        effort: options.effort ?? null,
-        profile: options.profile ?? null,
-        agentProfile: options.agentProfile ? appliedAgentProfileMetadata(options.provider, options.agentProfile) : null,
-        runnerId: options.runnerId,
-        startedAt: options.startedAt,
-        tmuxSession: this.providerTerminalSession() ?? options.tmuxSession ?? null,
-        tmuxSocket: this.providerTerminalSocket() ?? null,
-        policyName: options.policyName ?? null,
-        spawnRequestId: options.spawnRequestId ?? null,
-        automationId: options.automationId ?? null,
-        automationRunId: options.automationRunId ?? null,
-        workspace: options.workspace ?? null,
-        lifecycle: options.lifecycle ?? "persistent",
-        workspaceMode: options.workspace?.requestedMode ?? options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE ?? null,
-        runnerManaged: true,
-        cwd: options.cwd,
-        approvalMode: options.approvalMode,
-        label: options.label ?? null,
-        auth: {
-          profileId: this.currentTokenProfileId ?? null,
-          jti: this.currentTokenJti ?? null,
-          expiresAt: this.currentTokenExpiresAt ?? null,
-          rootTokenFallback: options.rootTokenFallback === true,
-        },
-        lifecycleCapabilities: lifecycleCapabilities(),
-        providerCapabilities: runtimeProviderCapabilities(options),
-      },
-      heartbeatMeta: () => this.heartbeatRuntimeMeta(),
-      heartbeatIntervalMs: 30_000,
-      initialStatus: "idle",
-    });
-  }
-
-  get id(): string {
-    return this.agentId;
-  }
-
-  async run(): Promise<void> {
-    this.control = startControlServer({
-      onStatus: (status) => this.setProviderStatus(status),
-      onTerminalAttachSpec: () => this.terminalAttachSpec(),
-      // 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: () => Promise.resolve(this.obligationCache.get()),
-      onSessionTurn: (input) => this.publishSessionTurn(input),
-      onUserPrompt: (input) => this.handleUserPrompt(input),
-      onSessionBoundary: (input) => this.handleSessionBoundary(input),
-      onHookFatal: (report) => this.reportHookFatal(report),
-    });
-    this.startMcpProxy();
-    this.writeRunnerInfoFile();
-    this.options.adapter.onStatusChange((status) => {
-      if (this.restartInProgress || this.restartPending) return;
-      const semanticStatus = typeof status === "string" ? status : status.status;
-      if (this.shouldRestartUnexpectedProviderExit(semanticStatus)) {
-        void this.restartUnexpectedProviderExit(semanticStatus);
-        return;
-      }
-      this.setProviderStatus(status);
-      if (runnerShouldResolveProviderExit(semanticStatus, this.exitCommandInProgress)) this.options.onProviderExit?.(semanticStatus === "offline" ? 0 : 1);
-    });
-    this.options.adapter.onSessionEvent?.((event) => { void this.publishProviderSessionEvent(event); });
-    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.
-      this.obligationCache.markDirty();
-      this.enqueueMessage(message as Message);
-    });
-    this.bus.on("command", (type, params, commandId, command) => {
-      void this.handleCommand(type, params, commandId, command);
-    });
-    this.bus.on("error", (code, message) => this.handleBusError(String(code), String(message)));
-    await this.bus.connect();
-    this.obligationCache.start();
-    this.outbox.start();
-    this.sessionOutbox.start();
-    this.ensureScratch();
-    void this.sweepStaleScratch();
-    this.process = await this.spawnProvider();
-    this.writeRunnerInfoFile();
-    this.processStartedAt = Date.now();
-    this.publishStatus();
-    await this.deliverInitialPrompt();
-    await this.bootstrapUnreadMessages();
-    this.startClaimRenewer();
-    this.startHttpLiveness();
-    this.scheduleRuntimeTokenRenewal();
-    this.scheduleDrain();
-  }
-
-  async stop(): Promise<void> {
-    const alreadyStopped = this.stopped;
-    this.stopped = true;
-    reapSessionScratch({
-      agentId: this.agentId,
-      cwd: this.options.cwd,
-      fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
-    });
-    if (!alreadyStopped) await this.bus.statusAsync({ agentStatus: "offline", ready: false });
-    if (this.process && !alreadyStopped) {
-      await this.options.adapter.shutdown(this.process, {
-        graceful: true,
-        timeoutMs: this.options.providerConfig.headless.shutdownTimeoutMs,
-      });
-    }
-    if (this.drainTimer) clearTimeout(this.drainTimer);
-    this.drainTimer = undefined;
-    if (this.claimRenewTimer) clearInterval(this.claimRenewTimer);
-    this.claimRenewTimer = undefined;
-    if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
-    this.httpLivenessTimer = undefined;
-    if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
-    this.tokenRenewTimer = undefined;
-    this.disarmBusyReconciler();
-    this.stopReasoningTail();
-    this.obligationCache.stop();
-    this.outbox.close();
-    this.sessionOutbox.close();
-    this.proxy?.stop();
-    this.control?.stop();
-    await this.bus.close();
-  }
-
-  // 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).
-  private startMcpProxy(): void {
-    if (!this.mcpProxyEnabled) return;
-    try {
-      this.proxy = new RelayMcpProxy({
-        relayMcpEndpoint: relayMcpEndpoint(this.options.relayUrl),
-        getToken: () => this.currentToken,
-        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() },
-      });
-      this.mcpProxyEndpoint = this.proxy.start().url;
-      logger.info("mcp-proxy", `runner MCP proxy listening at ${this.mcpProxyEndpoint} (worktree=${this.ownsIsolatedWorktree()})`);
-    } catch (error) {
-      this.proxy = undefined;
-      this.mcpProxyEndpoint = undefined;
-      logger.warn("mcp-proxy", `failed to start MCP proxy; agent will connect to the relay directly: ${errMessage(error)}`);
-    }
-  }
-
-  private ownsIsolatedWorktree(): boolean {
-    const mode = this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE;
-    return mode === "isolated";
-  }
-
-  private async spawnProvider(): Promise<ManagedProcess> {
-    this.providerSessionId = crypto.randomUUID();
-    this.lastTranscriptPath = undefined;
-    const includeProviderGlobals = profileUsesHostProviderGlobals(this.options);
-    const env = {
-      ...process.env as Record<string, string>,
-      ...(includeProviderGlobals ? this.options.providerConfig.env : {}),
-      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 } : {}),
-      AGENT_RELAY_URL: this.options.relayUrl,
-      AGENT_RELAY_APPROVAL: this.options.approvalMode,
-      ...(this.currentToken ? { AGENT_RELAY_TOKEN: this.currentToken } : {}),
-      // 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.currentToken ? { [RELAY_MCP_TOKEN_ENV]: this.currentToken } : {})),
-      ...(this.currentTokenJti ? { AGENT_RELAY_TOKEN_JTI: this.currentTokenJti } : {}),
-      ...(this.currentTokenProfileId ? { AGENT_RELAY_TOKEN_PROFILE: this.currentTokenProfileId } : {}),
-      ...(this.currentTokenExpiresAt ? { AGENT_RELAY_TOKEN_EXPIRES_AT: String(this.currentTokenExpiresAt) } : {}),
-    };
-    const config: RunnerSpawnConfig = {
-      provider: this.options.provider,
-      model: this.options.model,
-      effort: this.options.effort,
-      runnerId: this.options.runnerId,
-      instanceId: this.options.instanceId,
-      agentId: this.agentId,
-      relayUrl: this.options.relayUrl,
-      cwd: this.options.cwd,
-      headless: this.options.headless,
-      approvalMode: this.options.approvalMode,
-      ...(this.options.label ? { label: this.options.label } : {}),
-      ...(this.options.rig ? { rig: this.options.rig } : {}),
-      ...(this.options.profile ? { profile: this.options.profile } : {}),
-      ...(this.options.agentProfile ? { agentProfile: this.options.agentProfile } : {}),
-      ...(this.options.prompt ? { prompt: this.options.prompt } : {}),
-      ...(this.options.systemPromptAppend ? { systemPromptAppend: this.options.systemPromptAppend } : {}),
-      ...(this.options.tmuxSession ? { tmuxSession: this.options.tmuxSession } : {}),
-      providerArgs: this.options.providerArgs,
-      providerConfig: this.options.providerConfig,
-      env,
-      controlPort: this.control!.port,
-      // 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 } : {}),
-      monitor: {
-        deliver: (messages) => this.control!.deliverToMonitor(messages),
-      },
-    };
-    const launchSeededPrompt = this.options.adapter.seedsInitialPromptAtLaunch ? this.options.prompt?.trim() : ""; if (launchSeededPrompt) this.recordInjectedPrompt(launchSeededPrompt);
-    return this.options.adapter.spawn(config);
-  }
-
-  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 writeRunnerInfoFile(): void {
-    const file = process.env.AGENT_RELAY_RUNNER_INFO_FILE;
-    if (!file || !this.control) return;
-    try {
-      mkdirSync(dirname(file), { recursive: true });
-      writeFileSync(file, JSON.stringify({
-        agentId: this.agentId,
-        runnerId: this.options.runnerId,
-        provider: this.options.provider,
-        controlUrl: this.control.url,
-        pid: process.pid,
-        ...(this.providerTerminalSession() ? { tmuxSession: this.providerTerminalSession() } : {}),
-        ...(this.providerTerminalSocket() ? { tmuxSocket: this.providerTerminalSocket() } : {}),
-        startedAt: this.options.startedAt,
-      }, null, 2) + "\n", { mode: 0o600 });
-    } catch (error) {
-      logger.error("runner", `failed to write runner info file: ${error}`);
-    }
-  }
-
-  private enqueueMessage(message: Message): void {
-    if (!this.matchesMessage(message)) return;
-    if (message.kind === "session") return;
-    this.pendingMessages.set(message.id, message);
-    this.scheduleDrain();
-  }
-
-  private async bootstrapUnreadMessages(): Promise<void> {
-    try {
-      const messages = await this.http.pollMessages({ for: this.agentId, unread: true, limit: 100 });
-      for (const message of messages) this.enqueueMessage(message);
-    } catch (error) {
-      logger.error("runner", `inbox bootstrap failed: ${error}`);
-    }
-  }
-
-  private async deliverInitialPrompt(): Promise<void> {
-    const prompt = this.options.prompt?.trim();
-    if (!prompt || this.options.adapter.seedsInitialPromptAtLaunch) return;
-    await this.attemptInitialPromptDelivery(prompt, INITIAL_PROMPT_FIRST_READY_TIMEOUT_MS);
-  }
-
-  // Deliver the spawn-time first prompt, surviving a cold-start TUI that isn't input-ready yet
-  // (#329). Timeout stashes it for ready-signal retry and surfaces the stall on the timeline.
-  private async attemptInitialPromptDelivery(prompt: string, readyTimeoutMs: number): Promise<void> {
-    if (this.deliveringInitialPrompt || this.stopped || !this.process || !this.options.adapter.deliverInitialPrompt) return;
-    this.deliveringInitialPrompt = true;
-    const attempt = (this.initialPromptAttempts += 1);
-    try {
-      this.recordInjectedPrompt(prompt); await this.options.adapter.deliverInitialPrompt(this.process, prompt, { readyTimeoutMs });
-      this.pendingInitialPrompt = undefined;
-    } catch (error) {
-      const giveUp = attempt >= MAX_INITIAL_PROMPT_ATTEMPTS;
-      this.pendingInitialPrompt = giveUp ? undefined : prompt;
-      logger.error("runner", `initial prompt attempt ${attempt} failed${giveUp ? " (giving up)" : "; will retry on next ready signal"}: ${errMessage(error)}`);
-      this.publishRunnerTimelineEvent({ status: "prompt_failed", timestamp: Date.now(), title: "Initial prompt not delivered", body: errMessage(error), metadata: { attempts: attempt, terminal: giveUp } });
-    } finally {
-      this.deliveringInitialPrompt = false;
-    }
-  }
-
-  private scheduleDrain(delayMs = 0): void {
-    if (this.stopped || this.drainTimer) return;
-    this.drainTimer = setTimeout(() => {
-      this.drainTimer = undefined;
-      void this.drainMessages();
-    }, delayMs);
-  }
-
-  private async drainMessages(): Promise<void> {
-    if (this.stopped || this.delivering || this.pendingMessages.size === 0) return;
-    if (!this.process) {
-      this.scheduleDrain(500);
-      return;
-    }
-    this.delivering = true;
-    const messages = [...this.pendingMessages.values()].sort((a, b) => a.id - b.id);
-    this.pendingMessages.clear();
-    const 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.activeTaskClaims.set(message.id, { messageId: message.id, taskId, observedProviderBusy: providerAlreadyBusy });
-          this.claims.startClaim("task", String(taskId), claimed.claimExpiresAt);
-          await this.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);
-    }
-    if (deliverable.length === 0) {
-      this.delivering = false;
-      this.publishStatus();
-      return;
-    }
-    this.publishStatus();
-    let failed = false;
-    try {
-      const prepared = await messagesWithCachedAttachments(deliverable, this.http, {
-        agentId: this.agentId,
-        onError: (message) => logger.error("runner", message),
-      });
-      await this.options.adapter.deliver(this.process, prepared);
-      for (const message of deliverable) {
-        await this.http.markRead(message.id, this.agentId).catch(() => {});
-        if (!taskIdFromMessage(message)) this.claims.finishClaim("message", String(message.id));
-      }
-    } catch (error) {
-      failed = true;
-      if (shouldLogDeliveryFailure(error)) logger.warn("delivery", `message delivery failed: ${error}`);
-      for (const message of deliverable) {
-        this.clearActiveClaim(message);
-        this.pendingMessages.set(message.id, message);
-      }
-    } finally {
-      this.delivering = false;
-      this.publishStatus();
-      if (this.pendingMessages.size > 0) this.scheduleDrain(failed ? 1000 : 0);
-    }
-  }
-
-  private async handleCommand(type: string, params: Record<string, unknown>, commandId: string, command?: Record<string, unknown>): Promise<void> {
-    const target = typeof command?.target === "string" ? command.target : this.agentId;
-    if (target !== this.agentId && target !== this.options.runnerId) return;
-    if (type !== "agent.shutdown" && type !== "agent.restart" && type !== "agent.reconnect" && type !== "agent.kill" && type !== "agent.compact" && type !== "agent.clearContext" && type !== "agent.injectContext" && type !== "agent.permissionDecision" && type !== "agent.interrupt" && type !== "prompt.inject") return;
-
-    const exitAfterCommand = type === "agent.shutdown" || type === "agent.kill";
-    if (exitAfterCommand) this.exitCommandInProgress = true;
-    this.claims.startClaim("command", commandId);
-    try {
-      await this.updateCommand(commandId, "accepted");
-      await this.updateCommand(commandId, "running");
-      // Pre-session-destroy seam (#183): for destructive transitions, run end-of-session
-      // work (Insights capture, #184) BEFORE the invasive operation, surfaced as a
-      // non-addressable "finalizing" state so the agent isn't mistaken for merely busy.
-      const destroyReason = boundaryReasonForCommand(type);
-      if (destroyReason) await this.runPreSessionDestroy(destroyReason);
-      // Move from the transient finalizing window to the executing teardown state (or drop
-      // it entirely for compact/clear, which complete promptly once capture is done).
-      if (exitAfterCommand) this.lifecycleAction = type === "agent.kill" ? "killing" : "shutting-down";
-      else if (type === "agent.restart") this.lifecycleAction = "restarting";
-      else this.lifecycleAction = undefined;
-      this.publishStatus();
-      let providerResult: Record<string, unknown> | void = undefined;
-      if (type === "agent.restart") await this.restartProvider();
-      else if (type === "agent.reconnect") this.publishStatus();
-      else if (type === "agent.compact") {
-        if (!this.options.adapter.compact || !this.process) throw new Error("provider does not support compact");
-        providerResult = await this.options.adapter.compact(this.process, {
-          instructions: typeof params.instructions === "string" ? params.instructions : undefined,
-        });
-      } else if (type === "agent.clearContext") {
-        if (!this.options.adapter.clearContext || !this.process) throw new Error("provider does not support clearContext");
-        providerResult = await this.options.adapter.clearContext(this.process);
-      } else if (type === "agent.interrupt") {
-        if (!this.options.adapter.interrupt || !this.process) throw new Error("provider does not support interrupt");
-        this.sessionLog("interrupt requested from dashboard");
-        providerResult = await this.options.adapter.interrupt(this.process);
-        this.scheduleInterruptReconcile();
-      } else if (type === "agent.injectContext") {
-        if (!this.process) throw new Error("provider process is unavailable");
-        providerResult = await this.injectContext(params);
-      } else if (type === "agent.permissionDecision") {
-        providerResult = await this.respondToPermissionDecision(params);
-      } else if (type === "prompt.inject") {
-        providerResult = await this.injectPrompt(params);
-      } else await this.shutdownProvider(type === "agent.kill", commandTimeoutMs(params));
-      await this.updateCommand(commandId, "succeeded", {
-        action: type,
-        agentId: this.agentId,
-        runnerId: this.options.runnerId,
-        policyName: this.options.policyName,
-        spawnRequestId: this.options.spawnRequestId,
-        reason: typeof params.reason === "string" ? params.reason : undefined,
-        ...(providerResult ? { providerResult } : {}),
-      });
-    } catch (error) {
-      await this.updateCommand(commandId, "failed", undefined, errMessage(error)).catch(() => {});
-    } finally {
-      this.claims.finishClaim("command", commandId);
-      if (exitAfterCommand) {
-        if (params.preserveRegistration === true) {
-          await this.http.setStatus(this.agentId, "offline", this.options.instanceId).catch(() => {});
-        } else {
-          await this.http.deleteAgent(this.agentId).catch(() => {});
-        }
-        if (this.options.exitProcessOnShutdown !== false) {
-          setTimeout(() => void this.stop().catch((error) => {
-            logger.error("lifecycle", `stop after command failed: ${error}`);
-          }).finally(() => process.exit(0)), 10);
-        }
-      } else if (!this.stopped) {
-        this.lifecycleAction = undefined;
-        this.publishStatus();
-      }
-    }
-  }
-
-  private async injectContext(params: Record<string, unknown>): 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") : [];
-    await this.options.adapter.deliver(this.process!, [{
-      id: 0,
-      from: "system",
-      to: this.agentId,
-      kind: "system",
-      subject: "Agent Relay memory context",
-      body: content,
-      payload: {
-        memoryInjection: true,
-        reason: typeof params.reason === "string" ? params.reason : undefined,
-        memoryIds,
-      },
-      readBy: [],
-      createdAt: Date.now(),
-    }]);
-    return { memoryIds, injectedMemoryCount: memoryIds.length };
-  }
-
-  private async respondToPermissionDecision(params: Record<string, unknown>): Promise<Record<string, unknown>> {
-    const approvalId = typeof params.approvalId === "string" ? params.approvalId : "";
-    const decision = typeof params.decision === "string" ? params.decision : "";
-    if (!approvalId) throw new Error("approvalId required");
-    if (decision !== "approve" && decision !== "approve-session" && decision !== "deny" && decision !== "abort" && decision !== "answer") {
-      throw new Error("decision must be approve, approve-session, deny, abort, or answer");
-    }
-    const answersRaw = params.answers;
-    const answers = answersRaw && typeof answersRaw === "object" && !Array.isArray(answersRaw)
-      ? Object.fromEntries(
-          Object.entries(answersRaw as Record<string, unknown>).filter(([, v]) => typeof v === "string") as [string, string][],
-        )
-      : undefined;
-    if (decision === "answer" && (!answers || Object.keys(answers).length === 0)) {
-      throw new Error("answers required for answer decision");
-    }
-    const input: ProviderPermissionDecisionInput = {
-      approvalId,
-      decision: decision as ProviderPermissionDecision,
-      ...(typeof params.reason === "string" ? { reason: params.reason } : {}),
-      ...(answers ? { answers } : {}),
-    };
-    if (this.control?.resolvePermissionDecision(input)) {
-      return { approvalId, decision, provider: "claude" };
-    }
-    if (!this.process) throw new Error("provider process is unavailable");
-    if (!this.options.adapter.respondToPermissionDecision) throw new Error("provider does not support permission decisions");
-    const result = await this.options.adapter.respondToPermissionDecision(this.process, input);
-    return { approvalId, decision, ...(result ? { providerResult: result } : {}) };
-  }
-
-  private async injectPrompt(params: Record<string, unknown>): Promise<Record<string, unknown>> {
-    const body = typeof params.body === "string" ? params.body : "";
-    if (!body) throw new Error("body required");
-    if (!this.process) throw new Error("provider process is unavailable");
-    if (!this.options.adapter.deliverInitialPrompt) throw new Error("provider does not support prompt injection");
-    const messageId = typeof params.messageId === "number" ? params.messageId : undefined;
-    const attachments = Array.isArray(params.attachments)
-      ? params.attachments.filter((item): item is Record<string, unknown> => item !== null && typeof item === "object" && !Array.isArray(item))
-      : [];
-    if (messageId) this.pendingPromptMessageId = messageId;
-    const prompt = await this.promptInjectionText(body, messageId, attachments);
-    // Mark so the matching UserPromptSubmit echo isn't double-posted: a chat-box
-    // prompt already created its own session message shown in the dashboard.
-    this.recordInjectedPrompt(prompt.trim());
-    await this.options.adapter.deliverInitialPrompt(this.process, prompt);
-    return { injected: true, messageId, attachmentCount: attachments.length };
-  }
-
-  private async promptInjectionText(body: string, messageId: number | undefined, attachments: Record<string, unknown>[]): Promise<string> {
-    if (!attachments.length) return body;
-    const messages = await messagesWithCachedAttachments([{
-      id: messageId ?? 0,
-      from: "user",
-      to: this.agentId,
-      kind: "session",
-      body,
-      payload: { attachments },
-      readBy: [],
-      createdAt: Date.now(),
-    }], this.http, {
-      agentId: this.agentId,
-      onError: (message) => logger.warn("attachments", message),
-    });
-    const attachmentText = providerAttachmentText(messages[0]!);
-    return attachmentText ? `${body}\n\n${attachmentText}` : body;
-  }
-
-  private async restartProvider(): Promise<void> {
-    this.restartInProgress = true;
-    try {
-      if (this.process) {
-        await this.options.adapter.shutdown(this.process, {
-          graceful: true,
-          timeoutMs: this.options.providerConfig.headless.shutdownTimeoutMs,
-        });
-      }
-      this.claims.clearTerminalStatus();
-      this.claims.clearWorkKind("provider-turn");
-      this.claims.clearWorkKind("subagent");
-      if (this.stopped) return;
-      this.process = await this.spawnProvider();
-      this.processStartedAt = Date.now();
-    } finally {
-      this.restartInProgress = false;
-    }
-  }
-
-  private shouldRestartUnexpectedProviderExit(status: SemanticStatus): boolean {
-    return runnerShouldRestartUnexpectedProviderExit(status, {
-      exitCommandInProgress: this.exitCommandInProgress,
-      stopped: this.stopped,
-      restartInProgress: this.restartInProgress,
-      provider: this.options.provider,
-      headless: this.options.headless,
-      hasTerminalSession: typeof this.process?.meta?.tmuxSession === "string"
-        || (this.options.adapter.supportsUnexpectedExitRestart?.() ?? false),
-    });
-  }
-
-  private async restartUnexpectedProviderExit(status: SemanticStatus): Promise<void> {
-    if (this.restartPending) return;
-    this.restartPending = true;
-    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
-      // Claude transcript is readable; the runner stays alive here (restart or offline), so the
-      // durable outbox drains normally — no flush needed.
-      await Promise.race([
-        this.captureContextRatio("crash"),
-        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 = this.providerExitDiagnostics(status, runtimeMs);
-
-      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,
-        },
-      });
-
-      if (this.shouldStopUnexpectedProviderExit(diagnostics)) {
-        const hasResumeId = typeof diagnostics.claudeResumeId === "string" && diagnostics.claudeResumeId.length > 0;
-        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: hasResumeId
-            ? "Claude exited; runner will not auto-resume. Resume id captured for manual recovery."
-            : "Claude exited; runner will not restart automatically.",
-          icon: "ti-player-stop",
-          metadata: {
-            eventType: "provider.restart_decision",
-            decision: "stop-surface",
-            reason: hasResumeId ? "claude-exit-manual-resume-available" : "claude-exit-manual-intervention-required",
-            ...diagnostics,
-          },
-        });
-        this.process = undefined;
-        this.setProviderStatus({
-          status,
-          reason: "provider-turn",
-          id: `provider-exit-${this.providerSessionId}`,
-          clear: ["provider-turn", "subagent"],
-        });
-        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));
-      logger.warn("lifecycle", `provider session exited unexpectedly after ${Math.round(runtimeMs / 1000)}s; 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: `runner will start a fresh ${this.options.provider} provider in ${delayMs}ms`,
-        icon: "ti-refresh",
-        metadata: {
-          eventType: "provider.restart_decision",
-          decision: "restart-fresh",
-          reason: "unexpected-headless-terminal-exit",
-          delayMs,
-          rapidExitCount: recent.length,
-          rapidExitWindowMs: UNEXPECTED_EXIT_WINDOW_MS,
-          ...diagnostics,
-        },
-      });
-      await Bun.sleep(delayMs);
-      if (this.stopped || this.exitCommandInProgress) return;
-      try {
-        await this.restartProvider();
-        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.restartPending = false;
-    }
-  }
-
-  private shouldStopUnexpectedProviderExit(diagnostics: Record<string, unknown>): boolean {
-    return this.options.provider === "claude" && diagnostics.exitCommandInProgress !== true;
-  }
-
-  private async shutdownProvider(hard: boolean, timeoutMs = this.options.providerConfig.headless.shutdownTimeoutMs): Promise<void> {
-    this.lifecycleAction = hard ? "killing" : "shutting-down";
-    this.publishStatus();
-    await this.bus.statusAsync({ agentStatus: "idle", ready: false, meta: { lifecycleAction: this.lifecycleAction, lifecycleActionAt: Date.now() } });
-    if (this.process) {
-      await this.options.adapter.shutdown(this.process, {
-        graceful: !hard,
-        timeoutMs,
-      });
-    }
-    this.claims.setTerminalStatus("offline");
-    this.publishStatus();
-    this.stopped = true;
-  }
-
-  private publishRunnerTimelineEvent(event: RunnerTimelineEvent): void {
-    this.pendingTimelineEvent = {
-      ...event,
-      metadata: {
-        source: "runner",
-        provider: this.options.provider,
-        runnerId: this.options.runnerId,
-        agentId: this.agentId,
-        policyName: this.options.policyName ?? null,
-        spawnRequestId: this.options.spawnRequestId ?? null,
-        label: this.options.label ?? null,
-        providerSessionId: this.providerSessionId,
-        ...(event.metadata ?? {}),
-      },
-    };
-    this.publishStatus();
-  }
-
-  private providerExitDiagnostics(status: SemanticStatus, runtimeMs: number): Record<string, unknown> {
-    const tmuxSession = typeof this.process?.meta?.tmuxSession === "string" ? this.process.meta.tmuxSession : undefined;
-    const tmuxSocket = typeof this.process?.meta?.tmuxSocket === "string" ? this.process.meta.tmuxSocket : undefined;
-    const exitSource = tmuxSession ? "tmux-session-ended" : this.process?.process ? "process-exit" : "provider-status";
-    const logFile = typeof process.env.AGENT_RELAY_LOG_FILE === "string" ? process.env.AGENT_RELAY_LOG_FILE : undefined;
-    const claudeResumeId = this.options.provider === "claude" && logFile ? latestClaudeResumeIdFromLogFile(logFile) : undefined;
-    return {
-      status,
-      runtimeMs: Number.isFinite(runtimeMs) ? runtimeMs : null,
-      exitSource,
-      exitCommandInProgress: this.exitCommandInProgress,
-      stopped: this.stopped,
-      restartInProgress: this.restartInProgress,
-      restartPending: this.restartPending,
-      headless: this.options.headless,
-      hasTerminalSession: Boolean(tmuxSession),
-      tmuxSession: tmuxSession ?? null,
-      tmuxSocket: tmuxSocket ?? null,
-      claudeResumeId: claudeResumeId ?? null,
-    };
-  }
-
-  private async updateCommand(commandId: string, status: string, result?: Record<string, unknown>, error?: string): Promise<void> {
-    await this.bus.updateCommand(commandId, { status, ...(result ? { result } : {}), ...(error ? { error } : {}) });
-  }
-
-  private handleBusError(code: string, message: string): void {
-    const action = runnerBusErrorAction(code, this.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(() => process.exit(0));
-    }
-  }
-
-  private setProviderStatus(update: ProviderStatusUpdate): void {
-    const status = typeof update === "string" ? update : update.status;
-    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";
-    const 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 } : {}),
-      };
-    }
-    if (typeof update !== "string" && update.providerState) {
-      const ps = update.providerState as { state?: unknown; reason?: unknown };
-      this.providerBlocked = ps.state === "blocked";
-      // 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 fresh = !this.rateLimitHold;
-        this.rateLimitHold = update.providerState;
-        if (fresh) this.publishRateLimitNotice(update.providerState);
-      } else {
-        this.rateLimitHold = undefined;
-      }
-    } else if (status === "idle") {
-      this.providerBlocked = false;
-    }
-    // Forward progress (a real turn) lifts the hold so the blocked badge clears.
-    if (status === "busy") this.rateLimitHold = undefined;
-    if (typeof update !== "string" && status === "error") {
-      const terminalReason = typeof update.metadata?.terminalFailureReason === "string"
-        ? update.metadata.terminalFailureReason
-        : typeof update.providerState?.reason === "string"
-          ? update.providerState.reason
-          : "provider-error";
-      const terminalMessage = typeof update.metadata?.terminalFailureMessage === "string"
-        ? update.metadata.terminalFailureMessage
-        : typeof update.providerState?.message === "string"
-          ? 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 (Claude PreCompact→`compacting` busy / PostCompact→`compacted`
-    // 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") {
-      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") {
-      if (!this.currentTurnId) {
-        this.currentTurnId = typeof update !== "string" && update.id ? update.id : crypto.randomUUID();
-        this.currentTurnStartedAt = Date.now();
-        this.compactionMidTurn = false;
-        this.sessionLog(`turn started (turn ${this.currentTurnId})`);
-      }
-      this.armBusyReconciler();
-    } else if (status === "idle" && reason === "provider-turn") {
-      if (this.currentTurnId) this.sessionLog(`turn ended via provider idle (turn ${this.currentTurnId})`);
-      this.currentTurnId = undefined;
-      this.currentTurnStartedAt = undefined;
-      this.compactionMidTurn = false;
-      this.disarmBusyReconciler();
-      this.stopReasoningTail();
-      // #417: claude enforces obligations via the stop.sh hook; for every other provider
-      // re-inject any pending spawner obligation so it surfaces the /reply command.
-      if (this.options.provider !== "claude") void this.reInjectPendingObligation();
-    }
-    if (status === "busy") {
-      this.claims.clearTerminalStatus();
-      this.claims.startWork(reason, id, typeof update === "string" ? {} : {
-        label: update.label,
-        role: update.role,
-        parentId: update.parentId,
-        metadata: {
-          ...(update.metadata ?? {}),
-          ...(update.providerState ? { providerState: update.providerState } : {}),
-        },
-      });
-      if (reason === "provider-turn") {
-        for (const claim of this.activeTaskClaims.values()) claim.observedProviderBusy = true;
-      }
-    } else if (status === "idle") {
-      this.claims.clearTerminalStatus();
-      this.claims.finishWork(reason, id);
-      if (reason === "provider-turn") void this.completeObservedTaskClaims();
-    }
-    else if (status === "offline" || status === "error") this.claims.setTerminalStatus(status);
-    if (typeof update !== "string") {
-      for (const kind of update.clear ?? []) this.claims.clearWorkKind(kind);
-    }
-    // #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.pendingInitialPrompt && !this.deliveringInitialPrompt) {
-      void this.attemptInitialPromptDelivery(this.pendingInitialPrompt, INITIAL_PROMPT_RETRY_READY_TIMEOUT_MS);
-    }
-    this.publishStatus();
-  }
-
-  // #417: when a non-claude provider finishes a turn with a pending spawner obligation
-  // still unresolved, re-inject the obligation as a synthetic message so providerMessageText
-  // surfaces the specific `agent-relay /reply <id>` command. Claude handles this via the
-  // stop.sh hook; every other provider needs this in-process nudge.
-  private async reInjectPendingObligation(): Promise<void> {
-    if (!this.process) return;
-    // Filter to spawner obligations only — user obligations go through the existing codex
-    // prompt-capture path (publishProviderSessionEvent) and the session mirror (#418), never
-    // an explicit /reply. Shared predicate so this rule stays in lockstep with the Claude
-    // Stop-hook nag exemption (control-server.replyObligationStopDecision).
-    const obligations = this.obligationCache.get().filter(obligationRequiresExplicitReply);
-    if (!obligations.length) return;
-    const MAX_REINJECTIONS = 3;
-    for (const obligation of obligations) {
-      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: {},
-        readBy: [] as string[],
-        createdAt: obligation.createdAt,
-      };
-      // Suppress the userMessage echo that providers (e.g. Codex) 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]));
-      await this.options.adapter.deliver(this.process, [replayMessage]);
-      // 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;
-    }
-  }
-
-  // Session-mirror lane: capture the assistant turn from the Claude transcript and
-  // post it as a "session" message so it shows in the dashboard chat with zero
-  // agent tokens. Capture is UNCONDITIONAL — it no longer depends on a triggering
-  // relay message existing, so turns started from the web terminal (which create
-  // no relay message) are mirrored too. A reply obligation, when present, is still
-  // used as replyTo so the Stop hook stops nagging the agent to /reply.
-  //
-  // isPreFlush: true (#435) — mid-turn call from a PreToolUse hook (AskUserQuestion /
-  // ExitPlanMode / permission). Emits any un-mirrored narrative from the transcript
-  // tail immediately, before the interactive form appears in chat, then updates the
-  // entry-count cursor so the eventual Stop-hook call (full mode) skips it.
-  private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown; isPreFlush?: boolean }): Promise<void> {
-    if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
-
-    if (input.isPreFlush) {
-      if (!input.transcriptPath) return;
-      let jsonl: string | undefined;
-      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { return; }
-      if (!jsonl) return;
-      const body = extractLastAssistantTurnAfterEntry(jsonl, this.narrativeFlushEntryCount);
-      this.narrativeFlushEntryCount = countTranscriptEntries(jsonl);
-      if (!body) return;
-      const turnId = this.currentTurnId;
-      this.sessionLog(`pre-flush narrative for turn ${turnId ?? "?"} (${body.length} chars)`);
-      await this.publishSessionEvent({
-        from: this.agentId,
-        to: "user",
-        body,
-        session: { type: "response", origin: "provider", ...(turnId ? { turnId } : {}) },
-      });
-      return;
-    }
-
-    const turnId = this.currentTurnId;
-    this.stopReasoningTail();
-    // Optional correlation for threading + obligation clearing — never a capture gate.
-    let replyToMessageId: number | undefined;
-    const pendingPrompt = this.pendingPromptMessageId;
-    if (pendingPrompt) {
-      replyToMessageId = pendingPrompt;
-      this.pendingPromptMessageId = undefined;
-    } else {
-      // Correlation-only (threading + obligation clearing) — the local snapshot is fresh
-      // enough and never blocks the response-capture path (#196).
-      const obligation = [...this.obligationCache.get()].reverse().find((o) => o.from === "user");
-      replyToMessageId = obligation?.messageId;
-    }
-
-    // Grab and reset the pre-flush cursor before extraction: the cursor may be
-    // non-zero when a PreToolUse hook flushed narrative earlier this turn (#435).
-    // In "full" mode, skip those already-emitted entries so they don't duplicate.
-    const flushCount = this.narrativeFlushEntryCount;
-    this.narrativeFlushEntryCount = 0;
-
-    // The Stop hook can fire before the final assistant entry is flushed to disk.
-    // Claude writes thinking and text as separate entries (both with end_turn), so
-    // the transcript can "look complete" while the text entry is still pending.
-    // Retry until both the transcript has an end_turn AND extraction yields text.
-    let body = "";
-    let jsonl: string | undefined;
-    try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
-    if (jsonl !== undefined) {
-      for (let attempt = 0; attempt < 5; attempt++) {
-        if (attempt > 0) {
-          await new Promise((r) => setTimeout(r, 100));
-          try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { break; }
-        }
-        if (!transcriptLooksComplete(jsonl)) continue;
-        // Full mode: if a pre-flush already emitted entries 1..flushCount, only
-        // collect text from entries after that mark to avoid double-emit (#435).
-        const extract = this.options.providerConfig.chatCaptureMode === "full"
-          ? (j: string) => (flushCount > 0 ? extractLastAssistantTurnAfterEntry(j, flushCount) : extractLastAssistantTurn(j))
-          : extractFinalAssistantMessage;
-        body = extract(jsonl);
-        if (body) break;
-      }
-    }
-    // Fallback: last_assistant_message from the Stop hook payload, which bypasses
-    // the transcript file race entirely.
-    if (!body && input.lastAssistantMessage) {
-      body = extractHookAssistantMessage(input.lastAssistantMessage);
-    }
-    // A pure tool-use turn with no closing text is fine to skip — its reasoning and
-    // tool steps already carried the visibility into chat.
-    if (!body) {
-      this.sessionLog(`response capture: no closing text for turn ${turnId ?? "?"} (skipped)`);
-      return;
-    }
-
-    this.sessionLog(`response captured for turn ${turnId ?? "?"} (${body.length} chars${replyToMessageId ? `, replyTo #${replyToMessageId}` : ", no replyTo"})`);
-    await this.publishSessionEvent({
-      from: this.agentId,
-      to: "user",
-      body,
-      ...(replyToMessageId ? { replyTo: replyToMessageId } : {}),
-      session: { type: "response", origin: "provider", ...(turnId ? { turnId } : {}) },
-    });
-    // The agent's reply may have cleared an obligation — refresh the snapshot so the next
-    // turn-end doesn't re-prompt for a message already answered (#196).
-    if (replyToMessageId) this.obligationCache.markDirty();
-  }
-
-  // Post one session-mirror event (prompt echo, assistant response, reasoning or
-  // tool step) as a `kind: "session"` relay message tagged with payload.session so
-  // the dashboard can render the live provider session faithfully. Display-only:
-  // session messages are never delivered back into a provider.
-  private publishSessionEvent(input: {
-    from: string;
-    to: string;
-    body: string;
-    session: MessageSessionMeta;
-    replyTo?: number;
-  }): void {
-    // Durable, ordered, timestamped (#196): the actual POST happens in deliverOutboxEvent,
-    // retried until it lands. occurredAt is stamped now so a queued event reports when it
-    // truly happened, not when the server finally accepted it. Routed through the fast-lane
-    // sessionOutbox (#332) so a transient trace failure can't head-of-line block real messages.
-    // A stepId-bearing step (Codex tool running→completed, streamed reasoning/response) uses a
-    // STABLE idempotency key so the server upserts the row in place instead of appending a dup.
-    const stepId = input.session.stepId;
-    this.sessionOutbox.enqueue({
-      kind: "session-message",
-      ...(stepId ? { idempotencyKey: `session-step:${input.from}:${input.session.turnId ?? ""}:${stepId}` } : {}),
-      payload: {
-        from: input.from,
-        to: input.to,
-        ...(input.replyTo ? { replyTo: input.replyTo } : {}),
-        kind: "session",
-        body: input.body,
-        payload: { session: { provider: this.options.provider, ...input.session } },
-      } satisfies SendMessageInput,
-    });
-  }
-
-  // Map queued records to HTTP calls. Throw to retry, return to ack/delete.
-  private async deliverOutboxEvent(record: OutboxRecord): Promise<void> {
-    try {
-      if (record.kind === "session-message") {
-        await this.http.sendMessage({
-          ...(record.payload as SendMessageInput),
-          occurredAt: record.occurredAt,
-          idempotencyKey: record.idempotencyKey,
-        });
-        return;
-      }
-      if (record.kind === "insight") {
-        await this.http.recordInsightObservation({
-          ...(record.payload as Parameters<RelayHttpClient["recordInsightObservation"]>[0]),
-          occurredAt: record.occurredAt,
-        });
-        return;
-      }
-      if (record.kind === "continuation-archive") {
-        await deliverContinuationArchiveRecord({ record, http: this.http, updatePayload: (seq, payload) => this.outbox.updatePayload(seq, payload), sessionLog: (message) => this.sessionLog(message) });
-        return;
-      }
-      if (record.kind === "mcp-tool-call") {
-        await this.deliverBufferedMcpCall(record);
-        return;
-      }
-      logger.warn("outbox", `dropping event with unknown kind: ${record.kind}`);
-    } catch (error) {
-      // 409 = the server intentionally rejected it (e.g. Insights/feature toggled off). That
-      // is a permanent "don't want this", not a transient failure — ack so it doesn't retry.
-      if (isHttpStatusError(error, 409)) return;
-      if (isHttpAuthError(error)) this.recoverRuntimeTokenAfterAuthFailure("outbox");
-      throw error; // transient (or auth, post-recovery) → let the outbox retry with backoff
-    }
-  }
-
-  // Replay a buffered MCP tool call (Stage 2, #215) that the proxy queued while the relay was
-  // unreachable. POST it to the relay MCP endpoint with the LIVE token — same path the live call
-  // would have taken. Throw to retry (transient), return to ack (delivered or permanently
-  // rejected). The proxy stamped an idempotencyKey into the arguments so a retry that already
-  // landed server-side is deduped, not double-sent.
-  private async deliverBufferedMcpCall(record: OutboxRecord): Promise<void> {
-    const payload = record.payload as { tool: string; arguments: Record<string, unknown> };
-    const headers: Record<string, string> = { "content-type": "application/json" };
-    if (this.currentToken) headers.authorization = `Bearer ${this.currentToken}`;
-    const response = await fetch(relayMcpEndpoint(this.options.relayUrl), {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: payload.tool, arguments: payload.arguments } }),
-    });
-    if (response.status === 401 || response.status === 403) {
-      this.recoverRuntimeTokenAfterAuthFailure("mcp-outbox");
-      throw new Error(`relay rejected buffered ${payload.tool} with ${response.status}`);
-    }
-    if (response.status >= 500) throw new Error(`relay ${response.status} on buffered ${payload.tool}`);
-    if (!response.ok) {
-      // A 4xx (e.g. target gone, validation) is a permanent rejection — retrying won't help.
-      // Ack so it doesn't block the queue, but log loudly: a queued write did not land.
-      const body = await response.text().catch(() => "");
-      logger.warn("mcp-outbox", `buffered ${payload.tool} permanently rejected (${response.status}); dropping: ${body.slice(0, 200)}`);
-      return;
-    }
-    // HTTP 200 but the JSON-RPC body may still carry a tool-level error. Those reflect the same
-    // permanent-rejection semantics (bad target, validation) — ack and log, don't loop.
-    const json = await response.json().catch(() => null) as { error?: { message?: string } } | null;
-    if (json?.error) {
-      logger.warn("mcp-outbox", `buffered ${payload.tool} returned a tool error; dropping: ${json.error.message ?? "(no detail)"}`);
-    }
-  }
-
-  // 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.outbox.enqueue({
-        kind: "insight",
-        payload: {
-          sessionId: this.providerSessionId,
-          project: this.insightProject(),
-          agentId: this.agentId,
-          signal: "hook_fatal",
-          value: { hook: report.hook, error: report.error },
-          source: "server",
-        },
-      });
-    } catch (error) {
-      logger.error("outbox", `failed to queue hook-fatal report: ${errMessage(error)}`);
-    }
-  }
-
-  // A human typed a prompt directly into the provider (web terminal / TUI). Mirror
-  // it into the dashboard chat so both surfaces stay in sync, and kick off reasoning
-  // tailing for the turn. Skips prompts the runner itself injected (chat box, relay
-  // deliveries) so those aren't double-posted.
-  private async handleUserPrompt(input: { prompt: string; transcriptPath?: string }): Promise<void> {
-    if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
-    if (!this.currentTurnId) {
-      this.currentTurnId = crypto.randomUUID();
-      this.currentTurnStartedAt = Date.now();
-    }
-    const text = input.prompt.trim();
-    if (text && !this.isRunnerInjectedPrompt(text)) {
-      this.sessionLog(`prompt echoed from terminal (${text.length} chars)`);
-      await this.publishSessionEvent({
-        from: "user",
-        to: this.agentId,
-        body: text,
-        session: { type: "prompt", origin: "terminal", turnId: this.currentTurnId },
-      });
-    } else if (text) {
-      this.sessionDebug("user-prompt hook: skipped echo (runner-injected)");
-    }
-    if (input.transcriptPath) this.startReasoningTail(input.transcriptPath);
-  }
-
-  // A provider lifecycle hook reported a session boundary (Claude PreCompact / SessionEnd
-  // → control server). Normalize the raw provider reason to a SessionDestroyReason and run
-  // the same pre-destroy seam the bus commands use. `clear`/`compact` continue the session;
-  // anything else (logout, prompt_input_exit, other) is a real termination.
-  private async handleSessionBoundary(input: { reason?: string; transcriptPath?: string }): Promise<void> {
-    // Reason mapping is fail-safe-toward-termination: only the two known session-
-    // CONTINUING reasons are special-cased; everything else (logout, prompt_input_exit,
-    // other, AND any future reason) maps to "shutdown" → full pre-destroy capture.
-    // ⚠ If Claude Code adds a new BENIGN/continuing boundary reason, add it here — until
-    // then it will trigger a (harmless but wasteful) full context capture on a session
-    // that isn't actually ending.
-    const reason = input.reason === "compact" ? "compact"
-      : input.reason === "clear" ? "clear"
-      : "shutdown";
-    await this.runPreSessionDestroy(reason, { transcriptPath: input.transcriptPath });
-    // clear/compact CONTINUE the session — the finalizing window is transient. The bus-command
-    // path (handleCommand) restores the addressable status in its finally; the hook path has no
-    // such teardown, so without this the dashboard stays stuck on "wrapping up — messaging
-    // paused" with the composer disabled forever. Only restore if we're still in the exact
-    // finalizing state we published — a concurrent bus command (kill/restart/shutdown) may have
-    // transitioned lifecycleAction since, and that must win. "shutdown" reasons end the session,
-    // so their finalizing state is superseded by going offline; leave it be.
-    if ((reason === "clear" || reason === "compact") && this.lifecycleAction === `finalizing-${reason}` && !this.stopped) {
-      this.lifecycleAction = undefined;
-      this.publishStatus();
-    }
-  }
-
-  // The pre-session-destroy seam (#183): the single place end-of-session work runs before
-  // an invasive transition (compact/clear/restart/shutdown/kill). Best-effort and
-  // time-boxed so it never hangs teardown; concurrent calls for the same teardown coalesce
-  // (a shutdown bus command and the SessionEnd hook can both fire). During the window the
-  // agent is published non-addressable so the operator sees "wrapping up", not "busy".
-  private runPreSessionDestroy(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
-    if (this.preDestroyPromise) return this.preDestroyPromise;
-    const run = (async () => {
-      this.publishFinalizing(reason);
-      try {
-        await Promise.race([
-          Promise.all([
-            this.captureContextRatio(reason, opts),
-            this.captureContinuationArchive(reason, opts),
-          ]).then(() => undefined),
-          new Promise<void>((resolve) => setTimeout(resolve, PRE_DESTROY_TIMEOUT_MS)),
-        ]);
-      } catch (error) {
-        this.sessionLog(`pre-destroy capture failed: ${errMessage(error)}`);
-      }
-      // For exit-bound transitions the runner won't be alive afterward to drain the durable
-      // outbox, so block (bounded) on delivering what capture just enqueued. This runs before
-      // handleCommand's finally deletes the agent, so the runtime token is still valid here.
-      if (reasonExitsRunner(reason)) {
-        try {
-          const delivered = await this.outbox.flush(OUTBOX_FLUSH_TIMEOUT_MS);
-          if (!delivered) this.sessionLog(`insights: outbox flush incomplete before ${reason} (${this.outbox.pendingCount()} pending)`);
-        } catch (error) {
-          this.sessionLog(`insights: outbox flush failed: ${errMessage(error)}`);
-        }
-      }
-    })();
-    this.preDestroyPromise = run;
-    void run.finally(() => { this.preDestroyPromise = undefined; });
-    return run;
-  }
-
-  // Publish the transient pre-destroy state: a non-offline status with ready:false (so the
-  // agent drops out of isAgentOnline fan-out targeting without going "offline") plus a
-  // finalizing-<reason> lifecycleAction the dashboard renders as "wrapping up" with the
-  // composer disabled.
-  private publishFinalizing(reason: SessionDestroyReason): void {
-    this.lifecycleAction = `finalizing-${reason}`;
-    void this.bus.statusAsync({ agentStatus: "busy", ready: false, meta: { lifecycleAction: this.lifecycleAction, lifecycleActionAt: Date.now() } });
-  }
-
-  // Compute the #184 context-gathering ratio for the segment since the last boundary and
-  // queue it (durable outbox, #196). Provider-agnostic: the adapter normalizes its session
-  // into the shared SessionEvent stream; the math + classifier live in session-insights.ts.
-  // Per-segment via a runner-side cursor, so each datapoint is one work chunk between
-  // context resets. Mechanical, model-free → zero agent tokens, un-gameable.
-  // Repo-name project id for insight observations, resolved once. Aggregating by the raw
-  // cwd would split one repo across many "projects" (each isolated agent runs from a
-  // unique per-session worktree dir). See resolveProjectName.
-  private insightProject(): string {
-    return (this.insightProjectName ??= resolveProjectName(this.options.cwd, this.options.workspace));
-  }
-
-  private async captureContinuationArchive(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
-    const adapter = this.options.adapter;
-    if (!adapter.collectSessionArchiveSegment || !this.process) return;
-    const transcriptPath = opts?.transcriptPath ?? this.lastTranscriptPath;
-    const archive = await adapter.collectSessionArchiveSegment(this.process, { transcriptPath });
-    if (!archive) return;
-    const key = transcriptPath ?? `session:${this.providerSessionId}`;
-    if (key !== this.archiveCursorKey || archive.length < this.archiveObservedChars) {
-      this.archiveCursorKey = key;
-      this.archiveObservedChars = 0;
-    }
-    const segment = archive.slice(this.archiveObservedChars).trim();
-    this.archiveObservedChars = archive.length;
-    if (!segment) return;
-    const bounded = boundContinuationArchiveSegment(segment);
-    if (bounded.droppedBytes > 0) this.sessionLog(`continuation archive truncated at ${bounded.keptBytes} bytes; dropped ${bounded.droppedBytes} bytes (${reason})`);
-    this.outbox.enqueue({
-      kind: "continuation-archive",
-      payload: {
-        agentId: this.agentId,
-        segment: bounded.segment,
-      },
-    });
-    this.sessionLog(`continuation archive queued (${bounded.segment.length} chars, ${reason})`);
-  }
-
-  private async captureContextRatio(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
-    const adapter = this.options.adapter;
-    if (!adapter.collectSessionEvents || !this.process) return;
-    const transcriptPath = opts?.transcriptPath ?? this.lastTranscriptPath;
-    const events = await adapter.collectSessionEvents(this.process, { transcriptPath });
-    if (!events) return;
-    // Reset the cursor when the underlying log changed identity (transcript rotated on
-    // resume) or shrank (Codex buffer trimmed) — otherwise the slice would be wrong.
-    const key = transcriptPath ?? `session:${this.providerSessionId}`;
-    if (key !== this.insightsCursorKey || events.length < this.insightsObserved) {
-      this.insightsCursorKey = key;
-      this.insightsObserved = 0;
-    }
-    const segment = events.slice(this.insightsObserved);
-    this.insightsObserved = events.length;
-    const analysis = computeContextRatio(segment);
-    if (!analysis) return; // no tool calls this segment = nothing substantive to measure
-    this.outbox.enqueue({
-      kind: "insight",
-      payload: {
-        sessionId: this.providerSessionId,
-        project: this.insightProject(),
-        agentId: this.agentId,
-        signal: "context_ratio",
-        value: { ...analysis.metric, endReason: reason },
-        outcome: { ...analysis.outcome },
-        source: "server",
-      },
-    });
-    this.sessionLog(`insights: context_ratio ${analysis.metric.ratio.toFixed(2)} (${analysis.metric.gatheringCalls}/${analysis.metric.totalToolCalls} gathering, ${reason}) queued`);
-  }
-
-  // Route a provider-emitted session event (Codex app-server) into the chat mirror.
-  // Mirrors the same semantics as the Claude lane: prompts are echoed with dedup,
-  // and a response is only auto-captured when the agent won't separately reply to a
-  // relay obligation (so relay-triggered turns aren't double-posted).
-  private async publishProviderSessionEvent(event: ProviderSessionEvent): Promise<void> {
-    const body = event.body.trim();
-    if (!body) return;
-    const turnId = event.turnId ?? this.currentTurnId;
-    if (event.type === "prompt") {
-      if (this.isRunnerInjectedPrompt(body)) return;
-      await this.publishSessionEvent({
-        from: "user",
-        to: this.agentId,
-        body,
-        session: { type: "prompt", origin: event.origin ?? "terminal", ...(turnId ? { turnId } : {}) },
-      });
-      return;
-    }
-    if (event.type === "response") {
-      // Dashboard prompt injection is already answered by this captured App Server
-      // response. Other Relay inbox obligations still belong to the agent's explicit
-      // reply path, so those keep suppressing auto-capture to avoid duplicates.
-      let replyToMessageId: number | undefined;
-      const pendingPrompt = this.pendingPromptMessageId;
-      if (pendingPrompt) {
-        replyToMessageId = pendingPrompt;
-        this.pendingPromptMessageId = undefined;
-      } else if (this.obligationCache.get().some((o) => o.from === "user" && this.obligationPredatesCurrentTurn(o))) {
-        // The agent will answer the relay obligation itself — don't double-post (#196).
-        return;
-      }
-      await this.publishSessionEvent({
-        from: this.agentId,
-        to: "user",
-        body,
-        ...(replyToMessageId ? { replyTo: replyToMessageId } : {}),
-        session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}) },
-      });
-      if (replyToMessageId) this.obligationCache.markDirty();
-      return;
-    }
-    if (this.options.providerConfig.reasoningCapture === false) return;
-    await this.publishSessionEvent({
-      from: this.agentId,
-      to: "user",
-      body,
-      session: {
-        type: event.type,
-        origin: event.origin ?? "provider",
-        ...(turnId ? { turnId } : {}),
-        ...(event.label ? { label: event.label } : {}),
-        ...(event.status ? { status: event.status } : {}),
-        ...(event.streaming !== undefined ? { streaming: event.streaming } : {}),
-        ...(event.stepId ? { stepId: event.stepId } : {}),
-      },
-    });
-  }
-
-  // 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): void {
-    const now = Date.now();
-    this.injectedPrompts = this.injectedPrompts.filter((p) => now - p.at < PROMPT_ECHO_DEDUP_MS);
-    this.injectedPrompts.push({ text, at: now });
-    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 idx = this.injectedPrompts.findIndex((p) => p.text === text);
-    if (idx !== -1) {
-      this.injectedPrompts.splice(idx, 1); // consume one — identical repeats each match once
-      return true;
-    }
-    return false;
-  }
-
-  private obligationPredatesCurrentTurn(obligation: { createdAt: number }): boolean {
-    return this.currentTurnStartedAt === undefined || obligation.createdAt <= this.currentTurnStartedAt;
-  }
-
-  // --- Busy-state reconciler (item 2) -------------------------------------------------
-  // A safety net for turns that end out of band (interrupted from the web terminal,
-  // a hook that never fired) where the runner would otherwise stay stuck "busy".
-  private armBusyReconciler(): void {
-    if (this.busyReconcileTimer || !this.options.adapter.probeActivity) return;
-    this.busyReconcileIdleStreak = 0;
-    this.busyReconcileSawBusy = false;
-    this.busyReconcileTimer = setInterval(() => { void this.runBusyReconcile(); }, BUSY_RECONCILE_POLL_MS);
-  }
-
-  private disarmBusyReconciler(): void {
-    if (this.busyReconcileTimer) clearInterval(this.busyReconcileTimer);
-    this.busyReconcileTimer = undefined;
-    this.busyReconcileIdleStreak = 0;
-    this.busyReconcileSawBusy = false;
-  }
-
-  private async runBusyReconcile(): Promise<void> {
-    if (this.stopped || !this.process || !this.options.adapter.probeActivity) { this.disarmBusyReconciler(); return; }
-    // Only act while the runner still believes a provider turn is in flight, and
-    // never override a legitimate approval/blocked state.
-    if (this.claims.currentStatus() !== "busy" || this.providerBlocked) { this.busyReconcileIdleStreak = 0; return; }
-    if (!this.claims.activeWork().some((w) => w.kind === "provider-turn")) { this.disarmBusyReconciler(); return; }
-    let activity: "busy" | "idle" | "unknown";
-    try { activity = await this.options.adapter.probeActivity(this.process); } catch { return; }
-    if (activity === "busy") this.busyReconcileSawBusy = true;
-    // Reset the streak on anything that isn't a confident idle.
-    if (activity !== "idle") {
-      this.busyReconcileIdleStreak = 0;
-      this.sessionDebug(`reconcile probe=${activity} sawBusy=${this.busyReconcileSawBusy} streak=${this.busyReconcileIdleStreak}`);
-      return;
-    }
-    this.busyReconcileIdleStreak += 1;
-    // Confirm faster once we've seen the spinner this turn; otherwise demand a much
-    // longer all-idle window before trusting it (rescues fast turns without
-    // false-clearing a live turn that simply hasn't flashed busy into a probe yet).
-    const confirm = this.busyReconcileSawBusy ? BUSY_RECONCILE_IDLE_CONFIRM : BUSY_RECONCILE_IDLE_CONFIRM_NO_BUSY;
-    this.sessionDebug(`reconcile probe=idle sawBusy=${this.busyReconcileSawBusy} streak=${this.busyReconcileIdleStreak}/${confirm}`);
-    if (this.busyReconcileIdleStreak < confirm) return;
-    this.disarmBusyReconciler();
-    this.forceClearProviderTurn(this.busyReconcileSawBusy ? "backstop reconciler" : "backstop reconciler (no-busy-observed)");
-  }
-
-  // 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 {
-    if (!this.claims.activeWork().some((w) => w.kind === "provider-turn")) return;
-    this.sessionLog(`force-clearing stuck provider-turn (${reason})`);
-    this.claims.clearWorkKind("provider-turn");
-    this.currentTurnId = undefined;
-    this.compactionMidTurn = false;
-    this.publishStatus();
-  }
-
-  // After a dashboard interrupt, the provider should drop out of its turn; reconcile
-  // promptly so the busy indicator clears even if the Stop hook doesn't fire.
-  private scheduleInterruptReconcile(): void {
-    setTimeout(() => {
-      if (this.stopped || !this.process) return;
-      void (async () => {
-        if (this.claims.currentStatus() !== "busy" || this.providerBlocked) return;
-        let activity: "busy" | "idle" | "unknown" = "unknown";
-        try { if (this.options.adapter.probeActivity) activity = await this.options.adapter.probeActivity(this.process!); } catch { return; }
-        this.sessionDebug(`post-interrupt reconcile probe=${activity}`);
-        if (activity === "idle") this.forceClearProviderTurn("post-interrupt");
-      })();
-    }, INTERRUPT_RECONCILE_DELAY_MS);
-  }
-
-  // --- Turn-step tailer (item 5) ------------------------------------------------------
-  // Tail the in-flight turn's Claude transcript and surface new narration/reasoning/tool
-  // steps as session events, in transcript order. `narration` (the agent's intermediate
-  // text) is the primary visible content; reasoning visibility is a client-side toggle.
-  // Coalesced and coarse; the final response still comes through publishSessionTurn.
-  // `reasoningCapture: false` disables the whole live trace (server-side kill switch).
-  private startReasoningTail(transcriptPath: string): void {
-    if (this.options.providerConfig.reasoningCapture === false) return;
-    this.stopReasoningTail();
-    // Track emitted steps by content signature, not by index/count: the "latest
-    // turn" window in the transcript can shrink/reset (a tool_result entry, a
-    // mid-turn user line), and an index cursor would then either re-emit or stall
-    // and drop the rest of the turn. A seen-set is idempotent under any reshuffle.
-    // The signature is salted with each step's occurrence-within-window (stepDedupKeys)
-    // so two identical steps in one turn — same tool, same input — both surface (#265).
-    const seen = new Set<string>();
-    const turnIdAtStart = this.currentTurnId;
-    // On the first poll the new prompt usually hasn't landed in the transcript yet,
-    // so extractLatestTurnSteps still returns the PRIOR (completed) turn. Seed those
-    // signatures as already-seen so we don't replay last turn's reasoning/tools as
-    // this turn's activity. Once our prompt lands the window resets at the new user
-    // boundary and genuinely-new steps emit normally. Only seed when the transcript
-    // is complete (last entry is an end_turn assistant) — otherwise we're already
-    // inside the new turn and those steps are legitimately ours.
-    let seeded = false;
-    const poll = async (): Promise<void> => {
-      let jsonl: string;
-      try { jsonl = await readFile(transcriptPath, "utf8"); } catch { return; }
-      let steps: ReturnType<typeof extractLatestTurnSteps>;
-      try { steps = extractLatestTurnSteps(jsonl); } catch { return; }
-      const keyed = stepDedupKeys(steps).map((sig, i) => ({ sig, step: steps[i]! }));
-      if (!seeded) {
-        seeded = true;
-        if (transcriptLooksComplete(jsonl)) {
-          for (const { sig } of keyed) seen.add(sig);
-        }
-      }
-      const turnId = this.currentTurnId ?? turnIdAtStart;
-      let emitted = 0;
-      for (const { sig, step } of keyed) {
-        if (seen.has(sig)) continue;
-        seen.add(sig);
-        emitted += 1;
-        void this.publishSessionEvent({
-          from: this.agentId,
-          to: "user",
-          body: step.text,
-          session: { type: step.type, origin: "provider", ...(turnId ? { turnId } : {}), ...(step.label ? { label: step.label } : {}) },
-        });
-      }
-      if (emitted) this.sessionDebug(`reasoning tail emitted ${emitted} step(s) (turn ${turnId ?? "?"}, ${seen.size} total)`);
-    };
-    this.reasoningTail = { seen, timer: setInterval(() => { void poll(); }, REASONING_POLL_MS) };
-    this.sessionLog(`reasoning tail started (turn ${turnIdAtStart ?? "?"})`);
-    void poll();
-  }
-
-  private stopReasoningTail(): void {
-    if (this.reasoningTail) clearInterval(this.reasoningTail.timer);
-    this.reasoningTail = undefined;
-  }
-
-  // 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.publishSessionEvent({
-      from: this.agentId,
-      to: "user",
-      body: "🗜 Context compacted",
-      session: { type: "notice", origin: "provider", label: "compacted", ...(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: Record<string, unknown>): void {
-    const label = typeof providerState.label === "string" && providerState.label ? providerState.label : "usage limit reached";
-    this.publishSessionEvent({
-      from: this.agentId,
-      to: "user",
-      body: `⏳ ${label} — holding; agent-relay will auto-resume at reset.`,
-      session: { type: "notice", origin: "provider", label: "rate-limit", ...(this.currentTurnId ? { turnId: this.currentTurnId } : {}) },
-    });
-  }
-
-  private publishStatus(): void {
-    this.claims.expire();
-    const status = this.claims.currentStatus();
-    const agentStatus = runnerAgentStatus(status);
-    const activeWork = this.claims.activeWork();
-    const activeSubagents = activeWork.filter((item) => item.kind === "subagent");
-    const terminalFailure = this.terminalFailure;
-    const providerState = terminalFailure?.providerState ?? this.rateLimitHold ?? providerStateFromActiveWork(activeWork);
-    this.bus.setSemanticStatus(status === "offline" || status === "error" ? "idle" : status);
-    const timelineEvent = this.pendingTimelineEvent;
-    this.pendingTimelineEvent = undefined;
-    this.bus.status({
-      agentStatus,
-      ready: agentStatus !== "offline" && !this.stopped,
-      meta: {
-        runnerId: this.options.runnerId,
-        startedAt: this.options.startedAt,
-        tmuxSession: this.providerTerminalSession() ?? this.options.tmuxSession ?? null,
-        tmuxSocket: this.providerTerminalSocket() ?? null,
-        policyName: this.options.policyName ?? null,
-        spawnRequestId: this.options.spawnRequestId ?? null,
-        automationId: this.options.automationId ?? null,
-        automationRunId: this.options.automationRunId ?? null,
-        workspace: this.options.workspace ?? null,
-        lifecycle: this.options.lifecycle ?? "persistent", workspaceMode: this.options.workspace?.requestedMode ?? this.options.workspace?.mode ?? process.env.AGENT_RELAY_WORKSPACE_MODE ?? null,
-        lifecycleAction: this.lifecycleAction ?? null,
-        profile: this.options.profile ?? null,
-        ...(status === "error" ? { terminalStatus: "error" } : {}),
-        ...(terminalFailure ? {
-          lastError: terminalFailure.message,
-          terminalFailureReason: terminalFailure.reason,
-          terminalFailureMessage: terminalFailure.message,
-        } : {}),
-        busyReasons: this.claims.reasons(),
-        activeWork,
-        activeSubagents,
-        activeSubagentCount: activeSubagents.length,
-        providerState,
-        auth: {
-          profileId: this.currentTokenProfileId ?? null,
-          jti: this.currentTokenJti ?? null,
-          expiresAt: this.currentTokenExpiresAt ?? null,
-          rootTokenFallback: this.options.rootTokenFallback === true,
-        },
-        ...(timelineEvent ? { timelineEvent } : {}),
-        transport: this.bus.transportState,
-      },
-    });
-  }
-
-  private startHttpLiveness(): void {
-    if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
-    void this.publishHttpLiveness();
-    this.httpLivenessTimer = setInterval(() => {
-      void this.publishHttpLiveness();
-    }, HTTP_LIVENESS_INTERVAL_MS);
-  }
-
-  private async publishHttpLiveness(): Promise<void> {
-    if (this.stopped || this.httpLivenessInFlight || this.httpLivenessAuthFailed) return;
-    this.httpLivenessInFlight = true;
-    const status = this.claims.currentStatus();
-    const agentStatus = runnerAgentStatus(status);
-    try {
-      await this.http.setStatus(this.agentId, agentStatus, this.options.instanceId);
-      await this.http.setReady(this.agentId, agentStatus !== "offline", this.options.instanceId);
-      await this.http.heartbeat(this.agentId, this.options.instanceId);
-      await this.bootstrapUnreadMessages();
-    } catch (error) {
-      if (!this.stopped) this.handleHttpLivenessFailure(error);
-    } finally {
-      this.httpLivenessInFlight = false;
-    }
-  }
-
-  private handleHttpLivenessFailure(error: unknown): void {
-    const authFailed = isHttpAuthError(error);
-    this.logHttpLivenessFailure(error, authFailed);
-    if (!authFailed) return;
-    this.httpLivenessAuthFailed = true;
-    if (this.httpLivenessTimer) clearInterval(this.httpLivenessTimer);
-    this.httpLivenessTimer = undefined;
-    // A 401/403 here is the only timely signal that the token died — stopping the
-    // liveness timer means there is no second chance, so recover from THIS failure.
-    this.recoverRuntimeTokenAfterAuthFailure("http-liveness");
-  }
-
-  // A definitive relay auth failure (401/403) means the runtime token is dead right
-  // now — expired, or (the common case) revoked when the relay marked this agent
-  // stale across its own restart/reconnect. The proactive renew timer is keyed to
-  // TTL and structurally cannot catch a revocation, so the auth failure itself must
-  // drive recovery. renewRuntimeToken() prefers an orchestrator re-mint, which heals
-  // an expired token AND a token revoked-as-"stale" (the restart strand, #484) —
-  // but NOT a hard kill (admin revoke / rotation / agent removal), which stays dead
-  // by design. Debounced so a burst of failing calls re-mints once.
-  private recoverRuntimeTokenAfterAuthFailure(source: string): void {
-    if (this.stopped || this.tokenRenewInFlight) return;
-    if (!this.isRuntimeTokenRenewable() && !this.canRemintViaOrchestrator()) return;
-    const now = Date.now();
-    if (this.reactiveTokenRecoveryAt && now - this.reactiveTokenRecoveryAt < REACTIVE_TOKEN_RECOVERY_DEBOUNCE_MS) return;
-    this.reactiveTokenRecoveryAt = now;
-    this.logRunnerDiagnostic(`[runner] relay auth failure on ${source}; recovering runtime token`);
-    void this.renewRuntimeToken();
-  }
-
-  private logHttpLivenessFailure(error: unknown, authFailed: boolean): void {
-    const key = httpErrorKey(error);
-    const now = Date.now();
-    if (
-      this.httpLivenessLastLog?.key === key &&
-      now - this.httpLivenessLastLog.at < HTTP_LIVENESS_LOG_INTERVAL_MS
-    ) return;
-    this.httpLivenessLastLog = { key, at: now };
-    const suffix = authFailed ? "auth failed; stopping HTTP liveness retries until restart" : String(error);
-    this.logRunnerDiagnostic(`[runner] HTTP liveness update failed: ${suffix}`);
-  }
-
-  // Runner operational diagnostics (HTTP liveness, token renewal failures). Routed
-  // through the leveled logger at warn — see logger.ts. Kept as a thin wrapper so
-  // the existing call sites and their `[runner]` framing stay put.
-  private logRunnerDiagnostic(message: string): void {
-    logger.warn("runner", message.replace(/^\[runner\]\s*/, ""));
-  }
-
-  // Session-mirror diagnostics → the leveled logger (component "mirror"), written
-  // to the dashboard-surfaced session-mirror-<agent>.log. Key transitions log at
-  // info; the single place to look when chat/terminal sync misbehaves.
-  private sessionLog(message: string): void {
-    logger.info("mirror", message);
-  }
-
-  // Verbose, high-frequency lines (per-probe, per-emit) — surfaced only at log
-  // level "debug" (AGENT_RELAY_LOG_LEVEL=debug, or flip live via /log-level).
-  private sessionDebug(message: string): void {
-    logger.debug("mirror", message);
-  }
-
-  private ensureScratch(): void {
-    try {
-      this.scratch = ensureSessionScratch({
-        agentId: this.agentId,
-        cwd: this.options.cwd,
-        fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
-      });
-    } catch (error) {
-      this.logRunnerDiagnostic(`session scratch setup failed: ${errMessage(error)}`);
-    }
-  }
-
-  private async sweepStaleScratch(): Promise<void> {
-    try {
-      const agents = await this.http.listAgents().catch(() => [] as Awaited<ReturnType<RelayHttpClient["listAgents"]>>);
-      const keep = new Set(agents.map((a) => a.id));
-      keep.add(this.agentId);
-      const removed = sweepStaleSessions({
-        cwd: this.options.cwd,
-        fallbackBaseDir: process.env.AGENT_RELAY_ORCHESTRATOR_BASE_DIR,
-        keepAgentIds: keep,
-        now: Date.now(),
-      });
-      if (removed.length) this.logRunnerDiagnostic(`swept ${removed.length} stale session scratch dir(s)`);
-    } catch {}
-  }
-
-  private scheduleRuntimeTokenRenewal(delayMs?: number): void {
-    if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
-    this.tokenRenewTimer = undefined;
-    if (this.stopped) return;
-    const canSelfRenew = this.isRuntimeTokenRenewable();
-    const canRemint = this.canRemintViaOrchestrator();
-    // Keep the renewal clock ticking as long as the session can recover its token
-    // by EITHER path. Without the re-mint fallback an expired token would stop the
-    // timer forever (the old deadlock that stranded live agents off the bus).
-    if (!canSelfRenew && !canRemint) return;
-    let computedDelay = delayMs;
-    if (computedDelay === undefined) {
-      computedDelay = canSelfRenew
-        ? runtimeTokenRenewDelayMs(this.currentTokenExpiresAt!, Date.now())
-        : TOKEN_RENEW_RETRY_MS; // expired but re-mintable → retry via orchestrator soon
-      if (computedDelay === undefined) computedDelay = TOKEN_RENEW_RETRY_MS;
-    }
-    const schedule = runtimeTokenRenewTimerSchedule(computedDelay);
-    if (!schedule) return;
-    this.tokenRenewTimer = setTimeout(() => {
-      this.tokenRenewTimer = undefined;
-      if (!schedule.renew) {
-        this.scheduleRuntimeTokenRenewal();
-        return;
-      }
-      void this.renewRuntimeToken();
-    }, schedule.delayMs);
-  }
-
-  // Can the runner self-renew right now? Requires a non-expired runner-profile token
-  // (the relay rejects renewal of an expired token).
-  private isRuntimeTokenRenewable(): boolean {
-    return Boolean(
-      this.currentToken &&
-      this.currentTokenExpiresAt &&
-      this.currentTokenExpiresAt * 1000 > Date.now() &&
-      (this.currentTokenProfileId === "provider-agent" || this.currentTokenProfileId === "provider-interactive"),
-    );
-  }
-
-  // Can the runner recover its token via the orchestrator? Works even when the token
-  // is already expired — the orchestrator's standing credential is the authority.
-  private canRemintViaOrchestrator(): boolean {
-    return Boolean(
-      process.env.AGENT_RELAY_ORCHESTRATOR_URL &&
-      this.currentToken &&
-      (this.currentTokenProfileId === "provider-agent" || this.currentTokenProfileId === "provider-interactive"),
-    );
-  }
-
-  private async renewRuntimeToken(): Promise<void> {
-    if (this.stopped || this.tokenRenewInFlight || !this.currentToken) return;
-    this.tokenRenewInFlight = true;
-    try {
-      // Preferred path: self-renew directly against the relay while the token is
-      // still valid. Cheapest and needs no orchestrator round-trip.
-      if (this.isRuntimeTokenRenewable()) {
-        try {
-          const renewed = await this.http.renewRuntimeToken();
-          this.applyRenewedToken(renewed.token, renewed.record, "runtime-token-renewed");
-          return;
-        } catch (error) {
-          this.logRuntimeTokenRenewalFailure(error);
-          // Relay unreachable or token rejected — fall through to orchestrator re-mint.
-        }
-      }
-      // Recovery path: token expired, or self-renew failed. Ask the orchestrator —
-      // it holds a long-lived credential and can mint a fresh runner token, so a
-      // live session heals instead of being stranded off the bus.
-      if (this.canRemintViaOrchestrator() && await this.remintViaOrchestrator()) return;
-      this.pendingTimelineEvent = {
-        status: "runtime-token-renewal-failed",
-        timestamp: Date.now(),
-      };
-      this.publishStatus();
-      this.scheduleRuntimeTokenRenewal(TOKEN_RENEW_RETRY_MS);
-    } finally {
-      this.tokenRenewInFlight = false;
-    }
-  }
-
-  // Apply a freshly issued token across every live surface — runner state, the
-  // RunnerOptions bag (re-injected into the provider on respawn), the HTTP client,
-  // the bus client — then force a bus handshake with the new token and reschedule.
-  private applyRenewedToken(
-    token: string,
-    record: { jti: string; profileId?: string; expiresAt?: number },
-    status: "runtime-token-renewed" | "runtime-token-reminted",
-  ): void {
-    this.currentToken = token;
-    this.currentTokenJti = record.jti;
-    this.currentTokenProfileId = record.profileId ?? this.currentTokenProfileId;
-    this.currentTokenExpiresAt = record.expiresAt;
-    this.options.token = token;
-    this.options.tokenJti = record.jti;
-    this.options.tokenProfileId = this.currentTokenProfileId;
-    this.options.tokenExpiresAt = this.currentTokenExpiresAt;
-    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).
-    void this.proxy?.refreshTools().catch(() => {});
-    this.httpLivenessAuthFailed = false;
-    this.reactiveTokenRecoveryAt = undefined;
-    // 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: record.jti, timestamp: Date.now() };
-    this.bus.reconnectTransport(status === "runtime-token-reminted" ? "runtime token re-minted" : "runtime token renewed");
-    this.publishStatus();
-    this.scheduleRuntimeTokenRenewal();
-  }
-
-  // Recover the runtime token through the orchestrator. The runner proxies its own
-  // (possibly expired) token; the orchestrator re-mints it via the relay using its
-  // standing credential. Returns true on success.
-  private async remintViaOrchestrator(): Promise<boolean> {
-    const orchUrl = process.env.AGENT_RELAY_ORCHESTRATOR_URL;
-    if (!orchUrl || !this.currentToken) return false;
-    try {
-      const res = await fetch(`${orchUrl.replace(/\/+$/, "")}/api/runtime-tokens/runner-renew`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ token: this.currentToken }),
-        signal: AbortSignal.timeout(10_000),
-      });
-      if (!res.ok) return false;
-      const renewed = await res.json() as { token?: string; record?: { jti: string; profileId?: string; expiresAt?: number } };
-      if (!renewed?.token || !renewed.record) return false;
-      this.applyRenewedToken(renewed.token, renewed.record, "runtime-token-reminted");
-      this.logRunnerDiagnostic(`[runner] runtime token re-minted via orchestrator (jti ${renewed.record.jti})`);
-      return true;
-    } catch (error) {
-      this.logRuntimeTokenRenewalFailure(error);
-      return false;
-    }
-  }
-
-  private logRuntimeTokenRenewalFailure(error: unknown): void {
-    const key = httpErrorKey(error);
-    const now = Date.now();
-    if (
-      this.tokenRenewLastLog?.key === key &&
-      now - this.tokenRenewLastLog.at < HTTP_LIVENESS_LOG_INTERVAL_MS
-    ) return;
-    this.tokenRenewLastLog = { key, at: now };
-    this.logRunnerDiagnostic(`[runner] runtime token renewal failed: ${String(error)}`);
-  }
-
-  private heartbeatRuntimeMeta(): Record<string, unknown> | undefined {
-    const processContext = this.latestProcessContext();
-    const probeMetrics = this.latestProbeMetrics();
-    const probeContext = probeMetrics ? contextStateFromProbeMetrics(probeMetrics) : undefined;
-    const context = processContext ?? probeContext;
-    const terminalSession = this.providerTerminalSession();
-    const terminalSocket = this.providerTerminalSocket();
-    const probeModel: ProbeModelInfo | undefined = probeMetrics?.model || probeMetrics?.effort
-      ? { model: probeMetrics.model, effort: probeMetrics.effort }
-      : undefined;
-    const meta: Record<string, unknown> = {
-      providerCapabilities: runtimeProviderCapabilities(
-        this.options,
-        context,
-        probeModel,
-      ),
-      ...(terminalSession ? { tmuxSession: terminalSession } : {}),
-      ...(terminalSocket ? { tmuxSocket: terminalSocket } : {}),
-    };
-    if (context) meta.context = context;
-    return meta;
-  }
-
-  private providerTerminalSession(): string | undefined {
-    return typeof this.process?.meta?.tmuxSession === "string" ? this.process.meta.tmuxSession : undefined;
-  }
-
-  private providerTerminalSocket(): string | undefined {
-    return typeof this.process?.meta?.tmuxSocket === "string" ? this.process.meta.tmuxSocket : undefined;
-  }
-
-  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() {
-    const stateDir = process.env.AGENT_RELAY_CONTEXT_STATE_DIR;
-    return readContextProbeState(this.agentId, stateDir);
-  }
-
-  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,
-    });
-  }
-
-  private startClaimRenewer(): void {
-    if (this.claimRenewTimer) return;
-    this.claimRenewTimer = setInterval(() => {
-      void this.renewActiveTaskClaims();
-    }, CLAIM_RENEW_INTERVAL_MS);
-  }
-
-  private async renewActiveTaskClaims(): Promise<void> {
-    for (const claim of this.activeTaskClaims.values()) {
-      const renewed = await this.http.renewMessageClaim(claim.messageId, this.agentId).catch(() => ({ ok: false, claimExpiresAt: undefined }));
-      if (renewed.ok) {
-        this.claims.startClaim("message", String(claim.messageId), renewed.claimExpiresAt);
-        this.claims.startClaim("task", String(claim.taskId), renewed.claimExpiresAt);
-      }
-    }
-    this.publishStatus();
-  }
-
-  private async completeObservedTaskClaims(): Promise<void> {
-    const completed = [...this.activeTaskClaims.values()].filter((claim) => claim.observedProviderBusy);
-    for (const claim of completed) {
-      const ok = await this.updateTaskStatus(claim.taskId, {
-        status: "done",
-        agentId: this.agentId,
-        body: `Runner observed provider completion for message #${claim.messageId}`,
-        metadata: { messageId: claim.messageId, completedBy: "runner" },
-      })
-        .then(() => true)
-        .catch((error) => {
-          logger.error("task", `task ${claim.taskId} completion update failed: ${error}`);
-          return false;
-        });
-      if (!ok) continue;
-      this.activeTaskClaims.delete(claim.messageId);
-      this.claims.finishClaim("message", String(claim.messageId));
-      this.claims.finishClaim("task", String(claim.taskId));
-    }
-    if (completed.length > 0) this.publishStatus();
-  }
-
-  private async updateTaskStatus(taskId: number, input: TaskStatusInput): Promise<void> {
-    await this.http.updateTaskStatus(taskId, input);
-  }
-
-  private clearActiveClaim(message: Message): void {
-    const taskId = taskIdFromMessage(message);
-    this.claims.finishClaim("message", String(message.id));
-    if (!taskId) return;
-    this.activeTaskClaims.delete(message.id);
-    this.claims.finishClaim("task", String(taskId));
-  }
-}
-
-export function runnerMessageMatches(message: Pick<Message, "to" | "resolvedToAgent">, target: {
-  agentId: string;
-  label?: string;
-  provider: string;
-  tags: string[];
-  capabilities: string[];
-  defaultTags: string[];
-  defaultCapabilities: string[];
-  allowBroadTargets?: boolean;
-}): boolean {
-  if (message.resolvedToAgent === target.agentId) return true;
-  if (message.to === target.agentId) return true;
-  if (target.label && message.to === `label:${target.label}`) return true;
-  if (target.allowBroadTargets === false) return false;
-  if (message.to === "broadcast") return true;
-  if (message.to.startsWith("tag:")) {
-    const tag = message.to.slice("tag:".length);
-    return target.tags.includes(tag) || target.defaultTags.includes(tag) || tag === target.provider;
-  }
-  if (message.to.startsWith("cap:")) {
-    const cap = message.to.slice("cap:".length);
-    return target.capabilities.includes(cap) || target.defaultCapabilities.includes(cap);
-  }
-  return false;
-}
-
-export function taskIdFromMessage(message: Pick<Message, "payload">): number | undefined {
-  const taskId = message.payload?.taskId;
-  return Number.isSafeInteger(taskId) ? taskId as number : undefined;
-}
-
-// The server appends a self-claim/status instruction to task message bodies
-// (taskMessageBody in src/db.ts: "Claim this task before working it, then update
-// task status when finished."). For runner-managed agents the runner already owns
-// claim + status, so that line is not only redundant but actively harmful: the
-// agent tries to follow it, has no real claim command, and improvises a stray
-// `agent-relay /send-claimable claim <id>` that leaves an orphan claimable message.
-// Strip the trailing guidance from messages the runner has auto-claimed.
-const RUNNER_CLAIMED_GUIDANCE_RE = /\s*Claim this task before working it, then update task status when finished\.\s*$/;
-
-export function stripRunnerClaimedGuidance(body: string): string {
-  return body.replace(RUNNER_CLAIMED_GUIDANCE_RE, "");
-}
-
-function csvTags(raw: string | undefined): string[] {
-  return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
-}
-
-function relayBusUrl(relayUrl: string): string {
-  const url = new URL(relayUrl);
-  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-  url.pathname = `${url.pathname.replace(/\/+$/, "")}/bus`;
-  url.search = "";
-  return url.toString();
-}
-
-export function runnerAgentStatus(status: "idle" | "busy" | "offline" | "error"): "idle" | "busy" | "offline" {
-  return status === "error" ? "offline" : status;
-}
-
-export function runnerBusErrorAction(code: string, stopped: boolean): "ignore" | "log" | "stop" {
-  if (code === "STALE_SESSION") return stopped ? "ignore" : "stop";
-  return "log";
-}
-
-export function runnerShouldResolveProviderExit(status: SemanticStatus, exitCommandInProgress: boolean): boolean {
-  return !exitCommandInProgress && (status === "offline" || status === "error");
-}
-
-export function runnerShouldRestartUnexpectedProviderExit(
-  status: SemanticStatus,
-  input: {
-    exitCommandInProgress: boolean;
-    stopped: boolean;
-    restartInProgress: boolean;
-    provider?: string;
-    headless: boolean;
-    hasTerminalSession: boolean;
-  },
-): boolean {
-  return status === "offline"
-    && !input.exitCommandInProgress
-    && !input.stopped
-    && !input.restartInProgress
-    && input.headless
-    && input.hasTerminalSession;
-}
-
-export function latestClaudeResumeIdFromText(text: string): string | undefined {
-  let latest: string | undefined;
-  CLAUDE_RESUME_RE.lastIndex = 0;
-  for (let match = CLAUDE_RESUME_RE.exec(text); match; match = CLAUDE_RESUME_RE.exec(text)) {
-    latest = match[1];
-  }
-  return latest;
-}
-
-function latestClaudeResumeIdFromLogFile(path: string): string | undefined {
-  let fd: number | undefined;
-  try {
-    const stat = statSync(path);
-    const length = Math.min(stat.size, LOG_TAIL_BYTES);
-    const offset = Math.max(0, stat.size - length);
-    const buffer = Buffer.alloc(length);
-    fd = openSync(path, "r");
-    readSync(fd, buffer, 0, length, offset);
-    return latestClaudeResumeIdFromText(buffer.toString("utf8"));
-  } catch {
-    return undefined;
-  } finally {
-    if (fd !== undefined) closeSync(fd);
-  }
-}
-
-function commandTimeoutMs(params: Record<string, unknown>, fallback = 10_000): number {
-  const raw = params.timeoutMs;
-  if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return fallback;
-  return Math.min(raw, 60_000);
-}
-
-export function shouldLogDeliveryFailure(error: unknown): boolean {
-  const message = errMessage(error);
-  return message !== "no Claude monitor connected";
-}
-
-export function runtimeTokenRenewDelayMs(expiresAtSeconds: number, nowMs = Date.now()): number | undefined {
-  const expiresAtMs = expiresAtSeconds * 1000;
-  const ttlMs = expiresAtMs - nowMs;
-  if (!Number.isFinite(ttlMs) || ttlMs <= 0) return undefined;
-  const leadMs = Math.min(60 * 60 * 1000, Math.max(60_000, Math.floor(ttlMs * 0.2)));
-  const jitterMs = Math.floor(Math.random() * Math.min(30_000, Math.max(0, leadMs / 2)));
-  return Math.max(1_000, ttlMs - leadMs - jitterMs);
-}
-
-export function runtimeTokenRenewTimerSchedule(delayMs: number): { delayMs: number; renew: boolean } | undefined {
-  if (!Number.isFinite(delayMs) || delayMs <= 0) return undefined;
-  if (delayMs > MAX_TIMER_DELAY_MS) return { delayMs: MAX_TIMER_DELAY_MS, renew: false };
-  return { delayMs, renew: true };
-}
-
-function lifecycleCapabilities(): Record<string, true> {
-  return {
-    shutdownHard: true,
-    restartHard: true,
-    semanticStatus: true,
-    transportReconnect: true,
-  };
-}
-
-interface ProbeModelInfo {
-  model?: string;
-  effort?: string;
-}
-
-function runtimeProviderCapabilities(options: RunnerOptions, contextState?: ContextState, probeModel?: ProbeModelInfo): ProviderCapabilities {
-  const model = options.model ?? probeModel?.model;
-  const effort = options.effort ?? probeModel?.effort;
-  const modelSource = options.model ? "runtime" as const : probeModel?.model ? "provider" as const : "runtime" as const;
-  const shellMode = runtimeShellMode(options);
-  return {
-    lifecycle: {
-      managed: true,
-      shutdownHard: options.provider === "claude" ? options.headless : true,
-      restartHard: options.provider === "claude" ? options.headless : true,
-      semanticStatus: true,
-      reconnect: true,
-    },
-    model: {
-      provider: options.provider,
-      alias: model,
-      id: model,
-      effort,
-      source: modelSource,
-      confidence: options.model ? "reported" : probeModel?.model ? "reported" : "unknown",
-      lastUpdatedAt: options.startedAt,
-    },
-    session: {
-      approvalMode: options.approvalMode,
-      fileRead: true,
-      fileWrite: options.approvalMode !== "read-only",
-      shell: shellMode !== "none",
-      shellMode,
-      source: "runtime",
-      confidence: "reported",
-      lastUpdatedAt: options.startedAt,
-    },
-    ...runtimeProviderContextCapabilities(options, contextState),
-    ...runtimeProviderTerminalCapabilities(options),
-    liveSession: {
-      capture: true,
-      inject: Boolean(options.adapter.deliverInitialPrompt),
-      interrupt: Boolean(options.adapter.interrupt),
-      // Both providers mirror directly-typed prompts and stream reasoning/tool
-      // activity into chat (Claude via hooks + transcript tail, Codex via
-      // app-server item events).
-      promptEcho: true,
-      reasoning: true,
-      slashCommands: options.provider === "claude" || options.provider === "codex",
-    },
-    source: "runtime",
-    confidence: "reported",
-    lastUpdatedAt: options.startedAt,
-  };
-}
-
-function runtimeShellMode(options: RunnerOptions): NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]> {
-  if (options.approvalMode === "read-only") {
-    return options.provider === "claude" ? "read-only-guarded" : "none";
-  }
-  return options.approvalMode === "open" ? "unrestricted" : "guarded";
-}
-
-function runtimeProviderTerminalCapabilities(options: RunnerOptions): Pick<ProviderCapabilities, "terminal"> {
-  if (options.provider === "claude" && options.headless) {
-    return {
-      terminal: {
-        live: {
-          read: true,
-          write: true,
-        },
-      },
-    };
-  }
-  if (options.provider === "codex") {
-    return {
-      terminal: {
-        attach: {
-          create: true,
-          read: true,
-          write: true,
-          detach: true,
-        },
-      },
-    };
-  }
-  return {};
-}
-
-function appliedAgentProfileMetadata(provider: string, profile: AgentProfile): Record<string, unknown> {
-  const projection = provider === "claude" || provider === "codex"
-    ? agentProfileProjectionReport({ provider, profile })
-    : undefined;
-  return {
-    name: profile.name,
-    base: profile.base,
-    provider: profile.provider ?? "any",
-    relay: profile.relay,
-    instructions: {
-      repoInstructions: profile.instructions.repoInstructions,
-      globalInstructions: profile.instructions.globalInstructions,
-      appendCount: profile.instructions.append.length,
-      hasSystem: Boolean(profile.instructions.system),
-    },
-    skills: profile.skills.filter((item) => item.enabled).length,
-    plugins: profile.plugins.filter((item) => item.enabled).length,
-    mcp: { mode: profile.mcp.mode },
-    hooks: { mode: profile.hooks.mode },
-    permissions: profile.permissions,
-    projection,
-  };
-}
-
-function runtimeProviderContextCapabilities(options: RunnerOptions, contextState?: ContextState): Pick<ProviderCapabilities, "context"> {
-  const context: NonNullable<ProviderCapabilities["context"]> = { resume: "none" };
-  const supportsManagedContext = options.provider === "codex" || (options.provider === "claude" && options.headless);
-  if (contextState) {
-    context.stats = { source: contextState.source, confidence: contextState.confidence };
-    if (typeof contextState.tokensMax === "number" && Number.isFinite(contextState.tokensMax)) {
-      context.windowTokens = contextState.tokensMax;
-    }
-  }
-  if (supportsManagedContext) {
-    context.compact = true;
-    context.clear = true;
-  }
-  context.inject = true;
-  if (supportsManagedContext && options.adapter.compact && options.adapter.compactSupportsInstructions) context.resume = "native";
-  else if (supportsManagedContext && options.adapter.clearContext) context.resume = "clear-inject";
-  return Object.keys(context).length ? { context } : {};
-}
-
-function providerStateFromActiveWork(activeWork: Array<{ kind: string; metadata?: Record<string, unknown> }>): Record<string, unknown> | null {
-  const providerTurn = activeWork.find((item) => item.kind === "provider-turn");
-  const state = providerTurn?.metadata?.providerState;
-  return state && typeof state === "object" && !Array.isArray(state) ? state as Record<string, unknown> : null;
-}
-
-function isHttpAuthError(error: unknown): boolean {
-  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
-  return status === 401 || status === 403;
-}
-
-function isHttpStatusError(error: unknown, code: number): boolean {
-  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
-  return status === code;
-}
-
-function httpErrorKey(error: unknown): string {
-  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
-  if (typeof status === "number") return `status:${status}`;
-  return String(error);
-}
-
-function isContextState(value: unknown): value is ContextState {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const state = value as Record<string, unknown>;
-  return typeof state.utilization === "number" &&
-    typeof state.lifecycleState === "string" &&
-    typeof state.source === "string" &&
-    typeof state.confidence === "string";
-}
+export { AgentRunner } from "./runner-core";
+export {
+  latestClaudeResumeIdFromText,
+  runnerAgentStatus,
+  runnerBusErrorAction,
+  runnerMessageMatches,
+  runnerShouldResolveProviderExit,
+  runnerShouldRestartUnexpectedProviderExit,
+  runtimeTokenRenewDelayMs,
+  runtimeTokenRenewTimerSchedule,
+  shouldLogDeliveryFailure,
+  stripRunnerClaimedGuidance,
+  taskIdFromMessage,
+} from "./runner-helpers";