agent-relay-runner 0.62.3 → 0.63.0

package/src/runner-core.ts

@@ -0,0 +1,2224 @@
+import { hostname } from "node:os";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { AgentLifecycle, AgentProfile, ContextState, Message, MessageSessionMeta, 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 { 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 { 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 { deliverBufferedMcpCall as deliverBufferedMcpOutboxCall, deliverRunnerOutboxEvent } from "./mcp-outbox";
+import { RunnerInsights } from "./runner-insights";
+import { BusyReconciler } from "./busy-reconciler";
+import {
+  appliedAgentProfileMetadata,
+  commandTimeoutMs,
+  csvTags,
+  httpErrorKey,
+  isContextState,
+  isHttpAuthError,
+  isHttpStatusError,
+  latestClaudeResumeIdFromLogFile,
+  lifecycleCapabilities,
+  providerStateFromActiveWork,
+  relayBusUrl,
+  runnerAgentStatus,
+  runnerBusErrorAction,
+  runnerMessageMatches,
+  runnerShouldResolveProviderExit,
+  runnerShouldRestartUnexpectedProviderExit,
+  runtimeProviderCapabilities,
+  runtimeTokenRenewDelayMs,
+  runtimeTokenRenewTimerSchedule,
+  shouldLogDeliveryFailure,
+  stripRunnerClaimedGuidance,
+  taskIdFromMessage,
+  type ProbeModelInfo,
+} from "./runner-helpers";
+
+// 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;
+// A UserPromptSubmit echo matching a runner-injected prompt within this window is
+// the same prompt arriving back from the provider — drop it to avoid a duplicate.
+const PROMPT_ECHO_DEDUP_MS = 30_000;
+// Relay-injected content (delivered messages, memory context) is wrapped with
+// these markers; a UserPromptSubmit echo starting with one is a runner injection,
+// not a human typing into the terminal, so it must not be mirrored as a prompt.
+// `<task-notification>` is the harness wrapper for async monitor/task wake-ups
+// (which embed a `[relay message #…]` deeper inside, defeating a plain prefix
+// match) — it is emitted only by the harness, never typed by a human, so any
+// echo starting with it is a system injection, not a user prompt (#289).
+const RELAY_INJECTION_MARKERS = ["[relay message #", "[agent-relay", "<task-notification>"];
+// #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;
+interface RunnerTimelineEvent {
+  status: string;
+  id?: string;
+  timestamp: number;
+  title?: string;
+  body?: string;
+  icon?: string;
+  metadata?: Record<string, unknown>;
+}
+
+interface ReasoningTailState {
+  timer: ReturnType<typeof setInterval>;
+  seen: Set<string>;
+  emittedNarrationKeys: Set<string>;
+  poll(): Promise<void>;
+}
+
+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 readonly insights: RunnerInsights;
+  private readonly busyReconciler: BusyReconciler;
+  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;
+  // 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 }> = [];
+  // 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?: ReasoningTailState;
+  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.insights = new RunnerInsights({
+      agentId: this.agentId,
+      cwd: options.cwd,
+      workspace: options.workspace,
+      getOutbox: () => this.outbox,
+      getProviderSessionId: () => this.providerSessionId,
+      getProcess: () => this.process,
+      getAdapter: () => this.options.adapter,
+      getLastTranscriptPath: () => this.lastTranscriptPath,
+      sessionLog: (message) => this.sessionLog(message),
+    });
+    this.busyReconciler = new BusyReconciler({
+      isStopped: () => this.stopped,
+      hasProcess: () => Boolean(this.process),
+      currentStatus: () => this.claims.currentStatus(),
+      isProviderBlocked: () => this.providerBlocked,
+      hasProviderTurn: () => this.claims.activeWork().some((w) => w.kind === "provider-turn"),
+      canProbeActivity: () => Boolean(this.options.adapter.probeActivity),
+      probeActivity: () => this.process && this.options.adapter.probeActivity
+        ? this.options.adapter.probeActivity(this.process)
+        : undefined,
+      clearProviderTurn: (reason) => this.forceClearProviderTurn(reason),
+      sessionDebug: (message) => this.sessionDebug(message),
+    });
+    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.busyReconciler.disarm();
+    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.busyReconciler.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.busyReconciler.arm();
+    } 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.busyReconciler.disarm();
+      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);
+      await this.drainReasoningTail();
+      this.narrativeFlushEntryCount = countTranscriptEntries(jsonl);
+      if (!body || this.preFlushBodyAlreadyMirroredByReasoningTail(jsonl, 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> {
+    await deliverRunnerOutboxEvent({
+      record,
+      http: this.http,
+      relayUrl: this.options.relayUrl,
+      token: this.currentToken,
+      updatePayload: (seq, payload) => this.outbox.updatePayload(seq, payload),
+      sessionLog: (message) => this.sessionLog(message),
+      recoverRuntimeTokenAfterAuthFailure: (source) => this.recoverRuntimeTokenAfterAuthFailure(source),
+    });
+  }
+
+  // Replay a buffered MCP tool call (Stage 2, #215) that the proxy queued while the relay was
+  // unreachable. Kept as a method wrapper for tests; the concern lives in mcp-outbox.ts.
+  private async deliverBufferedMcpCall(record: OutboxRecord): Promise<void> {
+    await deliverBufferedMcpOutboxCall({
+      record,
+      relayUrl: this.options.relayUrl,
+      token: this.currentToken,
+      recoverRuntimeTokenAfterAuthFailure: (source) => this.recoverRuntimeTokenAfterAuthFailure(source),
+    });
+  }
+
+  // A hook reported an unhandled failure (#198 seam). Already logged FATAL by the control
+  // server; here we additionally surface it durably to the server as a generic insight so
+  // it shows up in observability rather than only in the per-agent log (#196).
+  private reportHookFatal(report: { hook: string; error: string }): void {
+    try {
+      this.insights.queueHookFatal(report);
+    } catch (error) {
+      logger.error("outbox", `failed to queue hook-fatal report: ${errMessage(error)}`);
+    }
+  }
+
+  // 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() } });
+  }
+
+  // Repo-name project id for insight observations, resolved once by the insights collaborator.
+  private insightProject(): string {
+    return this.insights.project();
+  }
+
+  private async captureContinuationArchive(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    await this.insights.captureContinuationArchive(reason, opts);
+  }
+
+  private async captureContextRatio(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    await this.insights.captureContextRatio(reason, opts);
+  }
+
+  // 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;
+  }
+
+  // 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();
+  }
+
+  // --- 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 emittedNarrationKeys = 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;
+    let pendingPoll = Promise.resolve();
+    const pollBody = 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;
+        this.publishSessionEvent({
+          from: this.agentId,
+          to: "user",
+          body: step.text,
+          session: { type: step.type, origin: "provider", ...(turnId ? { turnId } : {}), ...(step.label ? { label: step.label } : {}) },
+        });
+        if (step.type === "narration") emittedNarrationKeys.add(sig);
+      }
+      if (emitted) this.sessionDebug(`reasoning tail emitted ${emitted} step(s) (turn ${turnId ?? "?"}, ${seen.size} total)`);
+    };
+    const poll = (): Promise<void> => {
+      const next = pendingPoll.then(pollBody, pollBody);
+      pendingPoll = next.catch(() => {});
+      return next;
+    };
+    this.reasoningTail = { seen, emittedNarrationKeys, poll, timer: setInterval(() => { void poll(); }, REASONING_POLL_MS) };
+    this.sessionLog(`reasoning tail started (turn ${turnIdAtStart ?? "?"})`);
+    void poll();
+  }
+
+  private async drainReasoningTail(): Promise<void> {
+    if (this.options.providerConfig.reasoningCapture === false) return;
+    await this.reasoningTail?.poll();
+  }
+
+  private preFlushBodyAlreadyMirroredByReasoningTail(jsonl: string, body: string): boolean {
+    const tail = this.reasoningTail;
+    if (!tail || !tail.emittedNarrationKeys.size) return false;
+    const steps = extractLatestTurnSteps(jsonl);
+    const keys = stepDedupKeys(steps);
+    const mirrored = steps
+      .map((step, index) => ({ step, key: keys[index]! }))
+      .filter(({ step, key }) => step.type === "narration" && tail.emittedNarrationKeys.has(key))
+      .map(({ step }) => step.text)
+      .join("\n\n")
+      .trim();
+    const trimmed = body.trim();
+    return mirrored === trimmed || mirrored.endsWith(`\n\n${trimmed}`);
+  }
+
+  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));
+  }
+}