agent-relay-runner 0.11.8 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.4"
+    "agent-relay-sdk": "0.2.6"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/hooks/relay-status.sh

@@ -53,6 +53,25 @@ relay_post_session_turn() {
     -d "$body" >/dev/null 2>&1 || true
 }
 
+relay_post_user_prompt() {
+  # Mirror a prompt the human typed directly into this Claude session (web
+  # terminal / TUI) into the dashboard chat, and hand over the transcript path so
+  # the runner can tail reasoning/tool steps for the turn. The runner dedups
+  # prompts it injected itself. Fire-and-forget; never blocks or fails the turn.
+  local payload="${1:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  [ -z "$payload" ] && return 0
+  command -v jq >/dev/null 2>&1 || return 0
+  local body
+  body="$(printf '%s' "$payload" | jq -c '{prompt: (.prompt // ""), transcriptPath: (.transcript_path // "")}' 2>/dev/null || true)"
+  [ -z "$body" ] && return 0
+  case "$body" in *'"prompt":""'*) return 0 ;; esac
+  curl -fsS --max-time 3 -X POST "http://127.0.0.1:${port}/user-prompt" \
+    -H 'Content-Type: application/json' \
+    -d "$body" >/dev/null 2>&1 || true
+}
+
 relay_pending_reply_stop_decision() {
   local port="${AGENT_RELAY_RUNNER_PORT:-}"
   [ -z "$port" ] && return 0
@@ -82,3 +101,42 @@ relay_json_bool_field() {
 relay_json_escape() {
   printf '%s' "${1:-}" | sed 's/\\/\\\\/g; s/"/\\"/g'
 }
+
+# Print a short "request-review when done" reminder to stdout IFF this agent owns
+# an isolated workspace whose branch has committed work not yet integrated into
+# base. Prints nothing otherwise — so plain chat, shared-mode, and no-change
+# sessions never pay context/token cost. Reads the workspace from
+# AGENT_RELAY_WORKSPACE_JSON (set by the orchestrator at spawn) and does a local,
+# network-free git count. Always returns 0 (never aborts its caller).
+relay_review_reminder_text() {
+  local ws="${AGENT_RELAY_WORKSPACE_JSON:-}"
+  [ -z "$ws" ] && return 0
+  local mode worktree base id branch ahead
+  mode="$(relay_json_string_field mode "$ws")"
+  [ "$mode" = "isolated" ] || return 0
+  worktree="$(relay_json_string_field worktreePath "$ws")"
+  base="$(relay_json_string_field baseSha "$ws")"
+  [ -z "$base" ] && base="$(relay_json_string_field baseRef "$ws")"
+  id="$(relay_json_string_field id "$ws")"
+  branch="$(relay_json_string_field branch "$ws")"
+  [ -n "$worktree" ] || return 0
+  [ -n "$base" ] || return 0
+  [ -n "$id" ] || return 0
+  ahead="$(git -C "$worktree" rev-list --count "${base}..HEAD" 2>/dev/null || echo 0)"
+  case "$ahead" in ''|*[!0-9]*) ahead=0 ;; esac
+  [ "$ahead" -gt 0 ] || return 0
+  printf '[agent-relay] You have %s committed change(s) on `%s` that are not yet integrated into base. If your task is complete, request review so Agent Relay can auto-land it: POST /api/workspaces/%s/actions with {"action":"request-review"}. If you are still working, ignore this — it only appears while there is unmerged committed work.' \
+    "$ahead" "${branch:-this branch}" "$id"
+  return 0
+}
+
+# Wrap reminder text in the Claude Code additionalContext envelope for a given
+# hook event. Emits nothing when the text is empty.
+relay_emit_additional_context() {
+  local event="${1:-}" text="${2:-}"
+  [ -z "$event" ] && return 0
+  [ -z "$text" ] && return 0
+  printf '{"hookSpecificOutput":{"hookEventName":"%s","additionalContext":"%s"}}' \
+    "$event" "$(relay_json_escape "$text")"
+  return 0
+}

package/plugins/claude/hooks/session-start.sh

@@ -12,3 +12,9 @@ case "$source_kind" in
   *)
     ;;
 esac
+
+# Re-prime the request-review reminder when a session (re)starts — crucially on
+# source=="compact", which is how it survives a context compaction (PreCompact
+# cannot inject post-compact context; SessionStart can). No-op on a fresh startup
+# with no committed work, and silent for non-isolated/no-change sessions.
+relay_emit_additional_context SessionStart "$(relay_review_reminder_text || true)"

package/plugins/claude/hooks/user-prompt-submit.sh

@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+payload="$(cat || true)"
 relay_post_status busy
+# Mirror a terminal/TUI-typed prompt into the dashboard chat and start reasoning
+# tailing for this turn. No-op for prompts the runner injected (chat box / relay).
+relay_post_user_prompt "$payload"
+# Re-surface the request-review reminder each turn while there is unmerged
+# committed work — so a long session can't "forget" to land it. Silent otherwise.
+relay_emit_additional_context UserPromptSubmit "$(relay_review_reminder_text || true)"

package/src/adapter.ts

@@ -12,6 +12,10 @@ export interface ProviderStatusEvent {
     status: string;
     id?: string;
     timestamp?: number;
+    title?: string;
+    body?: string;
+    icon?: string;
+    metadata?: Record<string, unknown>;
   };
   id?: string;
   label?: string;
@@ -23,6 +27,20 @@ export interface ProviderStatusEvent {
 
 export type ProviderStatusUpdate = SemanticStatus | ProviderStatusEvent;
 
+/**
+ * A session-mirror event surfaced by an adapter that learns about session
+ * activity through provider events rather than hooks/transcripts (e.g. the Codex
+ * app-server). The runner turns these into `kind: "session"` chat messages, the
+ * same lane Claude's transcript capture uses. Provider-independent boundary.
+ */
+export interface ProviderSessionEvent {
+  type: "prompt" | "response" | "reasoning" | "tool";
+  body: string;
+  origin?: "chat" | "terminal" | "provider";
+  turnId?: string;
+  label?: string;
+}
+
 export interface ProviderConfig {
   command: string;
   defaultArgs: string[];
@@ -32,6 +50,9 @@ export interface ProviderConfig {
   defaultApprovalMode: string;
   defaultTags: string[];
   chatCaptureMode: "final" | "full";
+  // When false, the runner does not stream reasoning/tool steps into chat. Defaults
+  // to enabled (steps render discreetly, never as chat bubbles).
+  reasoningCapture?: boolean;
   headless: {
     tmuxPrefix: string;
     shutdownTimeoutMs: number;
@@ -106,11 +127,24 @@ export interface ProviderAdapter {
   shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void>;
   compact?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
   clearContext?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  // Interrupt the in-flight turn without ending the session (ESC for Claude's
+  // tmux pane, turn/interrupt for the Codex app-server). Provider-independent at
+  // the runner boundary; each adapter does what its provider actually supports.
+  interrupt?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  // Out-of-band activity probe for the busy-state reconciler: returns the real
+  // provider activity when the runner's claim state may have gone stale (e.g. the
+  // turn was interrupted from the web terminal so no Stop hook fired). "unknown"
+  // means the provider can't be cheaply probed and the reconciler should defer.
+  probeActivity?(process: ManagedProcess): Promise<"busy" | "idle" | "unknown">;
   terminalAttachSpec?(process: ManagedProcess): Promise<TerminalAttachSpec>;
   respondToPermissionDecision?(process: ManagedProcess, input: ProviderPermissionDecisionInput): Promise<Record<string, unknown> | void>;
   deliverInitialPrompt?(process: ManagedProcess, prompt: string): Promise<void>;
   deliver(process: ManagedProcess, messages: Message[]): Promise<void>;
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void;
+  // Subscribe to session-mirror events from providers that emit them directly
+  // (Codex app-server item events). Claude mirrors via hooks/transcript instead,
+  // so it leaves this unimplemented.
+  onSessionEvent?(cb: (event: ProviderSessionEvent) => void): void;
   // Headless providers with no tmux session (e.g. the Codex app-server) still
   // warrant an automatic restart on unexpected exit. Returning true opts the
   // provider into the runner's restart-with-backoff path.

package/src/adapters/claude-transcript.ts

@@ -13,6 +13,15 @@
 interface TranscriptBlock {
   type?: string;
   text?: string;
+  thinking?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+}
+
+export interface TurnStep {
+  type: "reasoning" | "tool";
+  text: string;
+  label?: string;
 }
 
 interface TranscriptMessage {
@@ -134,6 +143,49 @@ export function extractFinalAssistantMessage(jsonl: string): string {
  * string or an array of content blocks (same shape as transcript entries).
  * Thinking and tool_use blocks are dropped, matching extractLastAssistantTurn.
  */
+/**
+ * Extract the ordered reasoning and tool steps for the most recent turn (since
+ * the last real user prompt). Used by the reasoning tailer to stream discreet
+ * progress into chat while a turn is in flight. Returns steps in transcript order
+ * so the tailer can emit only the ones it hasn't seen yet by index.
+ */
+export function extractLatestTurnSteps(jsonl: string): TurnStep[] {
+  const lines = jsonl.split("\n");
+  let steps: TurnStep[] = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry: TranscriptEntry;
+    try {
+      entry = JSON.parse(trimmed) as TranscriptEntry;
+    } catch {
+      continue;
+    }
+    if (isRealUserPrompt(entry)) {
+      steps = [];
+      continue;
+    }
+    if (entry.type !== "assistant") continue;
+    for (const b of blocks(entry.message)) {
+      if (b.type === "thinking" && typeof b.thinking === "string" && b.thinking.trim()) {
+        steps.push({ type: "reasoning", text: b.thinking.trim() });
+      } else if (b.type === "tool_use" && typeof b.name === "string" && b.name) {
+        steps.push({ type: "tool", label: b.name, text: summarizeToolUse(b.name, b.input) });
+      }
+    }
+  }
+  return steps;
+}
+
+/** Compact one-line summary of a tool invocation for the discreet activity row. */
+export function summarizeToolUse(name: string, input: Record<string, unknown> | undefined): string {
+  const str = (key: string): string | undefined => (input && typeof input[key] === "string" ? (input[key] as string) : undefined);
+  const candidate = str("command") ?? str("file_path") ?? str("path") ?? str("pattern") ?? str("query") ?? str("url") ?? str("description") ?? str("prompt");
+  const summary = candidate ? candidate.replace(/\s+/g, " ").trim() : "";
+  if (!summary) return name;
+  return summary.length > 200 ? `${summary.slice(0, 197)}…` : summary;
+}
+
 export function extractHookAssistantMessage(content: unknown): string {
   if (typeof content === "string") return content.trim();
   if (!Array.isArray(content)) return "";

package/src/adapters/claude.ts

@@ -60,6 +60,33 @@ export class ClaudeAdapter implements ProviderAdapter {
     return { method: "tmux-inject", command: "/clear" };
   }
 
+  async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    if (!session || !tmuxHasSession(session, socket)) throw new Error("no active tmux session to interrupt");
+    // The same ESC the web terminal's aux key sends: cancels the in-flight turn
+    // and drops Claude back to its input box without ending the session.
+    const result = Bun.spawnSync(tmuxCommand(socket, "send-keys", "-t", session, "Escape"), {
+      stdin: "ignore", stdout: "ignore", stderr: "pipe",
+    });
+    if (result.exitCode !== 0) {
+      const stderr = result.stderr.toString().trim();
+      throw new Error(`tmux interrupt failed: ${stderr || `exit code ${result.exitCode}`}`);
+    }
+    return { method: "tmux-escape" };
+  }
+
+  async probeActivity(process: ManagedProcess): Promise<"busy" | "idle" | "unknown"> {
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    if (!session || !tmuxHasSession(session, socket)) return "unknown";
+    let pane: string;
+    try { pane = captureTmuxPane(session, socket); } catch { return "unknown"; }
+    if (claudePaneIsBusy(pane)) return "busy";
+    if (claudePaneLooksReady(pane)) return "idle";
+    return "unknown";
+  }
+
   async deliver(process: ManagedProcess, messages: Message[]): Promise<void> {
     const monitor = process.meta?.monitor as { deliver?(messages: Message[]): Promise<number[]> } | undefined;
     // A monitor object always exists for headless claude (it proxies to the runner

package/src/adapters/codex.ts

@@ -2,7 +2,7 @@ import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirS
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { ContextState, Message } from "agent-relay-sdk";
-import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
 import { workspaceDepsNoteFromEnv } from "../relay-instructions";
 
 /** Relay context prepended to a Codex agent's first turn: the standard relay
@@ -24,13 +24,42 @@ type PendingCodexApproval = {
 export class CodexAdapter implements ProviderAdapter {
   readonly provider = "codex";
   private statusCb: (status: ProviderStatusUpdate) => void = () => {};
+  private sessionEventCb: (event: ProviderSessionEvent) => void = () => {};
   private readonly subagentThreads = new Map<string, { label?: string; role?: string; parentId?: string }>();
   private readonly pendingApprovals = new Map<string, PendingCodexApproval>();
+  // Active turn id for the main thread, captured from turn/started so an interrupt
+  // can target the in-flight turn. Cleared on turn/completed.
+  private activeTurnId?: string;
+  // Assistant message text accumulated across the current turn's agentMessage items,
+  // flushed as one session response on turn/completed (mirrors Claude's chatCaptureMode).
+  private turnMessages: string[] = [];
+  private captureMode: "final" | "full" = "final";
 
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
     this.statusCb = cb;
   }
 
+  onSessionEvent(cb: (event: ProviderSessionEvent) => void): void {
+    this.sessionEventCb = cb;
+  }
+
+  async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client) throw new Error("Codex App Server client is unavailable");
+    const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    if (!threadId) throw new Error("Codex thread is not ready");
+    if (!this.activeTurnId) throw new Error("no active Codex turn to interrupt");
+    await client.turnInterrupt(threadId, this.activeTurnId);
+    return { method: "turn-interrupt", turnId: this.activeTurnId };
+  }
+
+  // Codex streams thread/status continuously, so the runner's claim state never
+  // goes stale the way Claude's can after an out-of-band interrupt. No cheap probe
+  // is needed — defer to the live status stream.
+  async probeActivity(): Promise<"busy" | "idle" | "unknown"> {
+    return "unknown";
+  }
+
   // The Codex app-server is headless and has no tmux session, but an unexpected
   // exit should still be restarted with backoff rather than resolved as a final exit.
   supportsUnexpectedExitRestart(): boolean {
@@ -38,6 +67,7 @@ export class CodexAdapter implements ProviderAdapter {
   }
 
   async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
+    this.captureMode = (config.providerConfig as ProviderConfig).chatCaptureMode ?? "final";
     const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
     const appServer = Bun.spawn([args.command, ...args.args], {
       cwd: args.cwd,
@@ -295,16 +325,25 @@ export class CodexAdapter implements ProviderAdapter {
       if (threadId && this.subagentThreads.has(threadId)) {
         this.statusCb({ status: "busy", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
-        this.statusCb({ status: "busy", reason: "provider-turn" });
+        const turn = isRecord(params?.turn) ? params.turn : undefined;
+        this.activeTurnId = stringValue(turn?.id);
+        this.turnMessages = [];
+        this.statusCb({ status: "busy", reason: "provider-turn", id: this.activeTurnId });
       }
     }
     if (method.includes("turn/completed") || method.includes("turn.completed")) {
       if (threadId && this.subagentThreads.has(threadId)) {
         this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
-        this.statusCb({ status: "idle", reason: "provider-turn" });
+        this.flushTurnResponse();
+        const completedTurnId = this.activeTurnId;
+        this.activeTurnId = undefined;
+        this.statusCb({ status: "idle", reason: "provider-turn", id: completedTurnId });
       }
     }
+    if ((method.includes("item/completed") || method.includes("item.completed")) && !isSubagent) {
+      this.handleCodexItem(isRecord(params?.item) ? params.item : undefined);
+    }
     if (method.includes("thread/status")) {
       const status = statusType(params?.status);
       if (threadId && this.subagentThreads.has(threadId)) {
@@ -317,6 +356,40 @@ export class CodexAdapter implements ProviderAdapter {
     }
   }
 
+  // Turn one completed Codex thread item into a session-mirror event. agentMessage
+  // text is accumulated and flushed as a single response on turn/completed; the rest
+  // (user prompt echo, reasoning, tool steps) is surfaced as it lands.
+  private handleCodexItem(item: Record<string, unknown> | undefined): void {
+    if (!item) return;
+    const type = stringValue(item.type);
+    const turnId = this.activeTurnId;
+    if (type === "agentMessage") {
+      const text = stringValue(item.text)?.trim();
+      if (text) this.turnMessages.push(text);
+      return;
+    }
+    if (type === "userMessage") {
+      const text = codexUserMessageText(item.content);
+      if (text) this.sessionEventCb({ type: "prompt", origin: "terminal", body: text, ...(turnId ? { turnId } : {}) });
+      return;
+    }
+    if (type === "reasoning") {
+      const text = codexReasoningText(item);
+      if (text) this.sessionEventCb({ type: "reasoning", origin: "provider", body: text, ...(turnId ? { turnId } : {}) });
+      return;
+    }
+    const tool = codexToolSummary(type, item);
+    if (tool) this.sessionEventCb({ type: "tool", origin: "provider", body: tool.body, label: tool.label, ...(turnId ? { turnId } : {}) });
+  }
+
+  private flushTurnResponse(): void {
+    if (!this.turnMessages.length) return;
+    const joined = this.captureMode === "full" ? this.turnMessages.join("\n\n") : this.turnMessages[this.turnMessages.length - 1]!;
+    this.turnMessages = [];
+    const text = joined.trim();
+    if (text) this.sessionEventCb({ type: "response", origin: "provider", body: text, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
+  }
+
   private providerStateFromThreadStatus(status: unknown, params?: Record<string, unknown>): Record<string, unknown> | undefined {
     const state = codexProviderStateFromThreadStatus(status, params);
     if (state?.state !== "blocked" || state.reason !== "waitingOnApproval" || state.pendingApproval) return state;
@@ -337,6 +410,52 @@ function codexApprovalFromServerRequest(message: { id: string | number; method:
   };
 }
 
+/** Extract the human text from a Codex userMessage item's content (UserInput[]). */
+export function codexUserMessageText(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(isRecord)
+    .filter((part) => part.type === "text" || part.type === "input_text" || part.type === "output_text")
+    .map((part) => (typeof part.text === "string" ? part.text : ""))
+    .filter(Boolean)
+    .join("")
+    .trim();
+}
+
+/** Extract reasoning text from a Codex reasoning item (content[] preferred, summary[] fallback). */
+export function codexReasoningText(item: Record<string, unknown>): string {
+  const stringsOf = (value: unknown): string[] =>
+    Array.isArray(value) ? value.filter((v): v is string => typeof v === "string" && v.trim().length > 0) : [];
+  const content = stringsOf(item.content);
+  const text = (content.length ? content : stringsOf(item.summary)).join("\n\n").trim();
+  return text;
+}
+
+/** Build a compact { label, body } activity summary for a Codex tool item. */
+export function codexToolSummary(type: string | undefined, item: Record<string, unknown>): { label: string; body: string } | null {
+  const oneLine = (value: unknown): string => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+  const clip = (text: string): string => (text.length > 200 ? `${text.slice(0, 197)}…` : text);
+  if (type === "commandExecution") {
+    const command = oneLine(item.command);
+    return { label: "Shell", body: clip(command || "command") };
+  }
+  if (type === "fileChange") {
+    const changes = Array.isArray(item.changes) ? item.changes.filter(isRecord) : [];
+    const files = changes.map((c) => stringValue(c.path) ?? stringValue(c.file) ?? "").filter(Boolean);
+    return { label: "Edit", body: clip(files.length ? files.join(", ") : "file changes") };
+  }
+  if (type === "mcpToolCall" || type === "dynamicToolCall") {
+    const tool = stringValue(item.tool) ?? "tool";
+    const server = stringValue(item.server) ?? stringValue(item.namespace);
+    return { label: server ? `${server}/${tool}` : tool, body: clip(oneLine(JSON.stringify(item.arguments ?? {})) || tool) };
+  }
+  if (type === "webSearch") {
+    return { label: "Search", body: clip(oneLine(item.query) || "web search") };
+  }
+  return null;
+}
+
 function codexApprovalMethod(method: string): boolean {
   return method === "execCommandApproval" ||
     method === "applyPatchApproval" ||

package/src/control-server.ts

@@ -24,6 +24,10 @@ interface ControlServerOptions {
   // path so the runner can capture the assistant turn and surface it in the
   // dashboard chat without the agent re-emitting it via /reply.
   onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown }): Promise<void>;
+  // A provider UserPromptSubmit hook hands over the prompt the human typed
+  // directly into the session (web terminal / TUI) so the runner can mirror it
+  // into the dashboard chat and start tailing the turn transcript for reasoning.
+  onUserPrompt?(input: { prompt: string; transcriptPath?: string }): Promise<void>;
 }
 
 export function startControlServer(options: ControlServerOptions): ControlServer {
@@ -66,6 +70,9 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       if (url.pathname === "/session-turn" && req.method === "POST") {
         return handleSessionTurn(req, options);
       }
+      if (url.pathname === "/user-prompt" && req.method === "POST") {
+        return handleUserPrompt(req, options);
+      }
       if (url.pathname === "/monitor") {
         const upgraded = srv.upgrade(req, { data: { kind: "monitor" } });
         return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
@@ -216,6 +223,27 @@ export function claudePermissionApprovalView(id: string, body: Record<string, un
       choices: [],
     };
   }
+  // ExitPlanMode arrives through the generic PermissionRequest hook (it doesn't
+  // match the AskUserQuestion matcher), which used to render the raw tool_input
+  // JSON with generic Approve/Deny buttons. Surface the plan as markdown with the
+  // real plan-mode choices instead. approve → allow (exit plan mode and proceed);
+  // deny → keep planning.
+  if (toolName === "ExitPlanMode") {
+    const plan = typeof toolInput.plan === "string" && toolInput.plan.trim()
+      ? toolInput.plan
+      : JSON.stringify(toolInput);
+    return {
+      id,
+      provider: "claude",
+      kind: "plan",
+      title: "Claude is ready to code",
+      body: plan,
+      choices: [
+        { id: "approve", label: "Approve plan" },
+        { id: "deny", label: "Keep planning" },
+      ],
+    };
+  }
   const command = typeof toolInput.command === "string" ? toolInput.command : "";
   const description = typeof toolInput.description === "string" ? toolInput.description : "";
   const bodyText = [
@@ -304,6 +332,17 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
   }
 }
 
+async function handleUserPrompt(req: Request, options: ControlServerOptions): Promise<Response> {
+  if (!options.onUserPrompt) return Response.json({ ok: false, reason: "prompt echo unavailable" });
+  const body = await req.json().catch(() => null);
+  const prompt = isRecord(body) && typeof body.prompt === "string" ? body.prompt : "";
+  if (!prompt.trim()) return Response.json({ ok: false, reason: "prompt required" }, { status: 400 });
+  const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : undefined;
+  // Fire-and-forget: the hook must not block Claude's turn on relay round-trips.
+  void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath })).catch(() => {});
+  return Response.json({ ok: true });
+}
+
 async function handleStatus(req: Request, options: ControlServerOptions): Promise<Response> {
   const body = await req.json().catch(() => null) as Partial<ProviderStatusEvent> | null;
   const status = body?.status;

package/src/runner.ts

@@ -1,15 +1,15 @@
 import { hostname } from "node:os";
-import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync, writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import type { AgentProfile, ContextState, Message, ProviderCapabilities, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
+import type { AgentProfile, ContextState, Message, MessageSessionMeta, ProviderCapabilities, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
 import { RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
 import { contextStateFromProbeMetrics, readContextProbeState } from "agent-relay-sdk/context-probe";
-import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } 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 { extractLastAssistantTurn, extractFinalAssistantMessage, extractHookAssistantMessage, transcriptLooksComplete } from "./adapters/claude-transcript";
+import { extractLastAssistantTurn, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, transcriptLooksComplete } from "./adapters/claude-transcript";
 import { agentProfileProjectionReport } from "./profile-projection";
 import { profileUsesHostProviderGlobals } from "./profile-home";
 import { runtimeMetadata } from "./version";
@@ -67,6 +67,32 @@ const UNEXPECTED_EXIT_WINDOW_MS = 2 * 60 * 1000;
 const RAPID_EXIT_MS = 30 * 1000;
 const MAX_RAPID_UNEXPECTED_EXITS = 3;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const LOG_TAIL_BYTES = 128 * 1024;
+// A UserPromptSubmit echo matching a runner-injected prompt within this window is
+// the same prompt arriving back from the provider — drop it to avoid a duplicate.
+const PROMPT_ECHO_DEDUP_MS = 30_000;
+// Busy reconciler: how often to probe real provider activity, and how many
+// consecutive idle probes confirm a stuck-busy state should be cleared.
+const BUSY_RECONCILE_POLL_MS = 4_000;
+const BUSY_RECONCILE_IDLE_CONFIRM = 3;
+// 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.
+const RELAY_INJECTION_MARKERS = ["[relay message #", "[agent-relay"];
+// Reasoning tailer poll cadence (item 5). Coarse on purpose — reasoning is a
+// discreet progress signal, not a token stream, so ~1.2s keeps it light.
+const REASONING_POLL_MS = 1_200;
+const CLAUDE_RESUME_RE = /\bclaude\s+--resume\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b/gi;
+
+interface RunnerTimelineEvent {
+  status: string;
+  id?: string;
+  timestamp: number;
+  title?: string;
+  body?: string;
+  icon?: string;
+  metadata?: Record<string, unknown>;
+}
 
 export class AgentRunner {
   private readonly agentId: string;
@@ -101,8 +127,24 @@ export class AgentRunner {
   private readonly unexpectedExitTimes: number[] = [];
   private readonly pendingMessages = new Map<number, Message>();
   private readonly activeTaskClaims = new Map<number, ActiveTaskClaim>();
-  private pendingTimelineEvent?: { status: string; id?: string; timestamp: number };
+  private pendingTimelineEvent?: RunnerTimelineEvent;
   private pendingPromptMessageId?: number;
+  // Session-mirror: a synthesized id grouping a turn's reasoning/tool steps and
+  // its final response. Set when a provider-turn starts, cleared when it ends.
+  private currentTurnId?: string;
+  // Prompt-echo dedup: the last prompt the runner itself injected (chat box or
+  // initial prompt). A UserPromptSubmit hook echo matching this within the window
+  // is the same prompt arriving back from the provider and must not double-post.
+  private lastInjectedPrompt?: { text: string; at: number };
+  // Busy reconciler: consecutive idle probes observed while claims still say busy.
+  private busyReconcileIdleStreak = 0;
+  private busyReconcileTimer?: ReturnType<typeof setInterval>;
+  // 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;
+  // Reasoning tailer (item 5): streams the in-flight turn's reasoning/tool steps
+  // from the Claude transcript into chat as discreet session events.
+  private reasoningTail?: { timer: ReturnType<typeof setInterval>; emitted: number };
   private scratch?: SessionScratchLayout;
 
   constructor(private readonly options: RunnerOptions) {
@@ -183,6 +225,7 @@ export class AgentRunner {
       onTerminalAttachSpec: () => this.terminalAttachSpec(),
       onReplyObligations: () => this.http.listReplyObligations(this.agentId),
       onSessionTurn: (input) => this.publishSessionTurn(input),
+      onUserPrompt: (input) => this.handleUserPrompt(input),
     });
     this.writeRunnerInfoFile();
     this.options.adapter.onStatusChange((status) => {
@@ -195,6 +238,7 @@ export class AgentRunner {
       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) => this.enqueueMessage(message as Message));
     this.bus.on("command", (type, params, commandId, command) => {
       void this.handleCommand(type, params, commandId, command);
@@ -238,6 +282,8 @@ export class AgentRunner {
     this.httpLivenessTimer = undefined;
     if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
     this.tokenRenewTimer = undefined;
+    this.disarmBusyReconciler();
+    this.stopReasoningTail();
     this.control?.stop();
     await this.bus.close();
   }
@@ -416,7 +462,7 @@ export class AgentRunner {
   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 !== "prompt.inject") 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) {
@@ -439,6 +485,9 @@ export class AgentRunner {
       } 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");
+        providerResult = await this.options.adapter.interrupt(this.process);
       } else if (type === "agent.injectContext") {
         if (!this.process) throw new Error("provider process is unavailable");
         providerResult = await this.injectContext(params);
@@ -534,6 +583,9 @@ export class AgentRunner {
     if (!this.options.adapter.deliverInitialPrompt) throw new Error("provider does not support prompt injection");
     const messageId = typeof params.messageId === "number" ? params.messageId : undefined;
     if (messageId) this.pendingPromptMessageId = messageId;
+    // 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.lastInjectedPrompt = { text: body.trim(), at: Date.now() };
     await this.options.adapter.deliverInitialPrompt(this.process, body);
     return { injected: true, messageId };
   }
@@ -579,9 +631,69 @@ export class AgentRunner {
       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;
+        console.warn(`[runner] ${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) {
         console.error(`[runner] 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;
@@ -589,6 +701,23 @@ export class AgentRunner {
 
       const delayMs = Math.min(10_000, Math.max(500, 500 * recent.length));
       console.warn(`[runner] 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 {
@@ -605,6 +734,10 @@ export class AgentRunner {
     }
   }
 
+  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();
@@ -620,6 +753,46 @@ export class AgentRunner {
     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 } : {}) });
   }
@@ -646,8 +819,26 @@ export class AgentRunner {
         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 state = (update.providerState as { state?: unknown }).state;
+      this.providerBlocked = state === "blocked";
+    } else if (status === "idle") {
+      this.providerBlocked = false;
+    }
+    if (status === "busy" && reason === "provider-turn") {
+      if (!this.currentTurnId) this.currentTurnId = typeof update !== "string" && update.id ? update.id : crypto.randomUUID();
+      this.armBusyReconciler();
+    } else if (status === "idle" && reason === "provider-turn") {
+      this.currentTurnId = undefined;
+      this.disarmBusyReconciler();
+      this.stopReasoningTail();
+    }
     if (status === "busy") {
       this.claims.clearTerminalStatus();
       this.claims.startWork(reason, id, typeof update === "string" ? {} : {
@@ -674,14 +865,16 @@ export class AgentRunner {
     this.publishStatus();
   }
 
-  // Phase 1 live-session lane: capture the assistant turn from the Claude
-  // transcript and post it as an observed "session" message so it shows in the
-  // dashboard chat with zero agent tokens. Posting it as a reply to the
-  // triggering message also clears the reply obligation, so the Stop hook no
-  // longer nags the agent to /reply — which is what made it re-emit before.
+  // 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.
   private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown }): Promise<void> {
-    // Find the triggering message to reply to: either a pending prompt injection
-    // (Phase 2 direct lane) or a reply obligation from the dashboard human.
+    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) {
@@ -693,52 +886,216 @@ export class AgentRunner {
         const obligation = [...obligations].reverse().find((o) => o.from === "user");
         replyToMessageId = obligation?.messageId;
       } catch {
-        return;
+        // fall through and capture without correlation
       }
     }
-    if (!replyToMessageId) return;
 
-    let jsonl: string;
-    try {
-      jsonl = await readFile(input.transcriptPath, "utf8");
-    } catch {
-      return;
-    }
-    // The Stop hook can fire before the final assistant entry is flushed to
-    // disk. Claude Code 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 the
-    // extraction yields non-empty text.
+    // 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 = "";
-    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 { return; }
+    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;
+        const extract = this.options.providerConfig.chatCaptureMode === "full" ? extractLastAssistantTurn : extractFinalAssistantMessage;
+        body = extract(jsonl);
+        if (body) break;
       }
-      if (!transcriptLooksComplete(jsonl)) continue;
-      const extract = this.options.providerConfig.chatCaptureMode === "full" ? extractLastAssistantTurn : extractFinalAssistantMessage;
-      body = extract(jsonl);
-      if (body) break;
     }
-    // Fallback: use last_assistant_message from the Stop hook payload directly.
-    // This bypasses the transcript file race entirely — Claude Code provides the
-    // content in-memory before the hook even fires.
+    // 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) return;
 
+    await this.publishSessionEvent({
+      from: this.agentId,
+      to: "user",
+      body,
+      ...(replyToMessageId ? { replyTo: replyToMessageId } : {}),
+      session: { type: "response", origin: "provider", ...(turnId ? { turnId } : {}) },
+    });
+  }
+
+  // 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 async publishSessionEvent(input: {
+    from: string;
+    to: string;
+    body: string;
+    session: MessageSessionMeta;
+    replyTo?: number;
+  }): Promise<void> {
     try {
       await this.http.sendMessage({
+        from: input.from,
+        to: input.to,
+        ...(input.replyTo ? { replyTo: input.replyTo } : {}),
+        kind: "session",
+        body: input.body,
+        payload: { session: { provider: this.options.provider, ...input.session } },
+      });
+    } catch (error) {
+      this.logRunnerDiagnostic(`session ${input.session.type} capture failed: ${error instanceof Error ? error.message : String(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 (!this.currentTurnId) this.currentTurnId = crypto.randomUUID();
+    const text = input.prompt.trim();
+    if (text && !this.isRunnerInjectedPrompt(text)) {
+      await this.publishSessionEvent({
+        from: "user",
+        to: this.agentId,
+        body: text,
+        session: { type: "prompt", origin: "terminal", turnId: this.currentTurnId },
+      });
+    }
+    if (input.transcriptPath) this.startReasoningTail(input.transcriptPath);
+  }
+
+  // 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") {
+      // If a relay message is awaiting the agent's own reply, let the agent answer
+      // it (Codex agents reply via their relay skills) instead of double-posting.
+      let replyToMessageId: number | undefined;
+      const pendingPrompt = this.pendingPromptMessageId;
+      if (pendingPrompt) {
+        replyToMessageId = pendingPrompt;
+        this.pendingPromptMessageId = undefined;
+      } else {
+        try {
+          const obligations = await this.http.listReplyObligations(this.agentId);
+          if (obligations.some((o) => o.from === "user")) return;
+        } catch {
+          // capture anyway on lookup failure
+        }
+      }
+      await this.publishSessionEvent({
         from: this.agentId,
         to: "user",
-        replyTo: replyToMessageId,
-        kind: "session",
         body,
+        ...(replyToMessageId ? { replyTo: replyToMessageId } : {}),
+        session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}) },
       });
-    } catch (error) {
-      this.logRunnerDiagnostic(`session turn capture failed: ${error instanceof Error ? error.message : String(error)}`);
+      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 } : {}) },
+    });
+  }
+
+  private isRunnerInjectedPrompt(text: string): boolean {
+    if (RELAY_INJECTION_MARKERS.some((marker) => text.startsWith(marker))) return true;
+    const recent = this.lastInjectedPrompt;
+    if (recent && recent.text === text && Date.now() - recent.at < PROMPT_ECHO_DEDUP_MS) {
+      this.lastInjectedPrompt = undefined;
+      return true;
+    }
+    return false;
+  }
+
+  // --- Busy-state reconciler (item 2) -------------------------------------------------
+  // A safety net for turns that end out of band (interrupted from the web terminal,
+  // a hook that never fired) where the runner would otherwise stay stuck "busy".
+  private armBusyReconciler(): void {
+    if (this.busyReconcileTimer || !this.options.adapter.probeActivity) return;
+    this.busyReconcileIdleStreak = 0;
+    this.busyReconcileTimer = setInterval(() => { void this.runBusyReconcile(); }, BUSY_RECONCILE_POLL_MS);
+  }
+
+  private disarmBusyReconciler(): void {
+    if (this.busyReconcileTimer) clearInterval(this.busyReconcileTimer);
+    this.busyReconcileTimer = undefined;
+    this.busyReconcileIdleStreak = 0;
+  }
+
+  private async runBusyReconcile(): Promise<void> {
+    if (this.stopped || !this.process || !this.options.adapter.probeActivity) { this.disarmBusyReconciler(); return; }
+    // Only act while the runner still believes a provider turn is in flight, and
+    // never override a legitimate approval/blocked state.
+    if (this.claims.currentStatus() !== "busy" || this.providerBlocked) { this.busyReconcileIdleStreak = 0; return; }
+    if (!this.claims.activeWork().some((w) => w.kind === "provider-turn")) { this.disarmBusyReconciler(); return; }
+    let activity: "busy" | "idle" | "unknown";
+    try { activity = await this.options.adapter.probeActivity(this.process); } catch { return; }
+    if (activity !== "idle") { this.busyReconcileIdleStreak = 0; return; }
+    this.busyReconcileIdleStreak += 1;
+    if (this.busyReconcileIdleStreak < BUSY_RECONCILE_IDLE_CONFIRM) return;
+    this.logRunnerDiagnostic(`busy reconciler cleared a stuck provider-turn (idle confirmed ${this.busyReconcileIdleStreak}x)`);
+    const turnId = this.currentTurnId;
+    this.disarmBusyReconciler();
+    this.setProviderStatus({ status: "idle", reason: "provider-turn", id: turnId ?? "provider-turn" });
+  }
+
+  // --- Reasoning tailer (item 5) ------------------------------------------------------
+  // Tail the in-flight turn's Claude transcript and surface new reasoning/tool steps
+  // as discreet session events. Coalesced and coarse; the final response still comes
+  // through publishSessionTurn.
+  private startReasoningTail(transcriptPath: string): void {
+    if (this.options.providerConfig.reasoningCapture === false) return;
+    this.stopReasoningTail();
+    const state = { emitted: 0, timer: undefined as unknown as ReturnType<typeof setInterval> };
+    const poll = async (): Promise<void> => {
+      let jsonl: string;
+      try { jsonl = await readFile(transcriptPath, "utf8"); } catch { return; }
+      const steps = extractLatestTurnSteps(jsonl);
+      const turnId = this.currentTurnId;
+      for (let i = state.emitted; i < steps.length; i++) {
+        const step = steps[i]!;
+        void this.publishSessionEvent({
+          from: this.agentId,
+          to: "user",
+          body: step.text,
+          session: { type: step.type, origin: "provider", ...(turnId ? { turnId } : {}), ...(step.label ? { label: step.label } : {}) },
+        });
+      }
+      if (steps.length > state.emitted) state.emitted = steps.length;
+    };
+    state.timer = setInterval(() => { void poll(); }, REASONING_POLL_MS);
+    this.reasoningTail = state;
+    void poll();
+  }
+
+  private stopReasoningTail(): void {
+    if (this.reasoningTail) clearInterval(this.reasoningTail.timer);
+    this.reasoningTail = undefined;
   }
 
   private publishStatus(): void {
@@ -874,9 +1231,20 @@ export class AgentRunner {
   private scheduleRuntimeTokenRenewal(delayMs?: number): void {
     if (this.tokenRenewTimer) clearTimeout(this.tokenRenewTimer);
     this.tokenRenewTimer = undefined;
-    if (!this.isRuntimeTokenRenewable()) return;
-    const computedDelay = delayMs ?? runtimeTokenRenewDelayMs(this.currentTokenExpiresAt!, Date.now());
-    if (computedDelay === undefined) return;
+    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(() => {
@@ -889,6 +1257,8 @@ export class AgentRunner {
     }, 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 &&
@@ -898,32 +1268,36 @@ export class AgentRunner {
     );
   }
 
+  // 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.isRuntimeTokenRenewable()) return;
+    if (this.stopped || this.tokenRenewInFlight || !this.currentToken) return;
     this.tokenRenewInFlight = true;
     try {
-      const renewed = await this.http.renewRuntimeToken();
-      this.currentToken = renewed.token;
-      this.currentTokenJti = renewed.record.jti;
-      this.currentTokenProfileId = renewed.record.profileId ?? this.currentTokenProfileId;
-      this.currentTokenExpiresAt = renewed.record.expiresAt;
-      this.options.token = renewed.token;
-      this.options.tokenJti = renewed.record.jti;
-      this.options.tokenProfileId = this.currentTokenProfileId;
-      this.options.tokenExpiresAt = this.currentTokenExpiresAt;
-      this.http.setToken(renewed.token);
-      this.bus.setToken(renewed.token);
-      this.httpLivenessAuthFailed = false;
-      this.pendingTimelineEvent = {
-        status: "runtime-token-renewed",
-        id: renewed.record.jti,
-        timestamp: Date.now(),
-      };
-      this.bus.reconnectTransport("runtime token renewed");
-      this.publishStatus();
-      this.scheduleRuntimeTokenRenewal();
-    } catch (error) {
-      this.logRuntimeTokenRenewalFailure(error);
+      // 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(),
@@ -935,6 +1309,56 @@ export class AgentRunner {
     }
   }
 
+  // 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);
+    this.httpLivenessAuthFailed = false;
+    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();
@@ -1146,6 +1570,32 @@ export function runnerShouldRestartUnexpectedProviderExit(
     && input.hasTerminalSession;
 }
 
+export function latestClaudeResumeIdFromText(text: string): string | undefined {
+  let latest: string | undefined;
+  CLAUDE_RESUME_RE.lastIndex = 0;
+  for (let match = CLAUDE_RESUME_RE.exec(text); match; match = CLAUDE_RESUME_RE.exec(text)) {
+    latest = match[1];
+  }
+  return latest;
+}
+
+export function latestClaudeResumeIdFromLogFile(path: string): string | undefined {
+  let fd: number | undefined;
+  try {
+    const stat = statSync(path);
+    const length = Math.min(stat.size, LOG_TAIL_BYTES);
+    const offset = Math.max(0, stat.size - length);
+    const buffer = Buffer.alloc(length);
+    fd = openSync(path, "r");
+    readSync(fd, buffer, 0, length, offset);
+    return latestClaudeResumeIdFromText(buffer.toString("utf8"));
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
 function commandTimeoutMs(params: Record<string, unknown>, fallback = 10_000): number {
   const raw = params.timeoutMs;
   if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return fallback;
@@ -1221,6 +1671,13 @@ function runtimeProviderCapabilities(options: RunnerOptions, contextStats?: { so
     liveSession: {
       capture: true,
       inject: Boolean(options.adapter.deliverInitialPrompt),
+      interrupt: Boolean(options.adapter.interrupt),
+      // Both providers mirror directly-typed prompts and stream reasoning/tool
+      // activity into chat (Claude via hooks + transcript tail, Codex via
+      // app-server item events).
+      promptEcho: true,
+      reasoning: true,
+      slashCommands: options.provider === "claude" || options.provider === "codex",
     },
     source: "runtime",
     confidence: "reported",