agent-relay-runner 0.124.0 → 0.126.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.124.0",
+  "version": "0.126.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "agent-relay-providers": "0.104.4",
-    "agent-relay-sdk": "0.2.116",
+    "agent-relay-sdk": "0.2.117",
     "callmux": "0.23.0"
   },
   "devDependencies": {

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.124.0",
+  "version": "0.126.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

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

@@ -115,6 +115,7 @@ relay_post_session_turn() {
   # below, so the agent is not nagged to /reply (and does not re-emit).
   local transcript_path="${1:-}"
   local last_assistant_message="${2:-}"
+  local prompt_id="${3:-}"
   local port="${AGENT_RELAY_RUNNER_PORT:-}"
   [ -z "$port" ] && return 0
   # transcript_path is the primary capture source, but the Stop payload can omit it
@@ -127,6 +128,13 @@ relay_post_session_turn() {
     [ "$body" != "{" ] && body="${body},"
     body="${body}\"lastAssistantMessage\":${last_assistant_message}"
   fi
+  # prompt_id (#1086): Claude's native turn identifier — the stable id the runner
+  # uses instead of a minted random UUID, and the deterministic key it slices the
+  # transcript by for full-mode enrichment.
+  if [ -n "$prompt_id" ]; then
+    [ "$body" != "{" ] && body="${body},"
+    body="${body}\"promptId\":\"$(relay_json_escape "$prompt_id")\""
+  fi
   body="${body}}"
   curl -fsS -X POST "http://127.0.0.1:${port}/session-turn" \
     -H 'Content-Type: application/json' \
@@ -144,7 +152,9 @@ relay_post_user_prompt() {
   [ -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)"
+  # promptId (#1086): Claude's native prompt_id for the turn this prompt starts —
+  # the stable turn identifier the runner uses instead of minting a random UUID.
+  body="$(printf '%s' "$payload" | jq -c '{prompt: (.prompt // ""), transcriptPath: (.transcript_path // ""), promptId: (.prompt_id // "")}' 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" \

package/plugins/claude/hooks/stop.sh

@@ -23,7 +23,12 @@ bg_count="$(relay_background_task_count "$payload")"
 # (stop_hook_active=true) must NOT suppress capturing this turn's response, or the live mirror
 # silently drops frames. Always post the turn; only the reply-obligation decision is gated below.
 last_assistant_msg="$(echo "$payload" | jq -c '.last_assistant_message // empty' 2>/dev/null || true)"
-relay_post_session_turn "$(relay_json_string_field transcript_path "$payload")" "$last_assistant_msg"
+# prompt_id (#1086): Claude's own native turn identifier, correlating this Stop with
+# the same UUID stamped on every transcript entry of the turn (and the id the
+# UserPromptSubmit hook reported at turn start) — the stable replacement for a
+# runner-minted random UUID.
+prompt_id="$(relay_json_string_field prompt_id "$payload")"
+relay_post_session_turn "$(relay_json_string_field transcript_path "$payload")" "$last_assistant_msg" "$prompt_id"
 
 if [ "$stop_hook_active" != "true" ]; then
   # `|| true`: under `set -e`, a non-zero from the obligation check must never abort

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

@@ -3,7 +3,12 @@ set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
 relay_install_hook_guard user-prompt-submit
 payload="$(cat || true)"
-relay_post_status busy
+# prompt_id (#1086): Claude's own native turn identifier for the prompt starting
+# now — the same UUID the Stop hook reports and the transcript stamps on every
+# entry of this turn. Passed as the busy report's `id` so the runner adopts it as
+# currentTurnId instead of minting a random UUID (runner-core.ts setProviderStatus).
+prompt_id="$(relay_json_string_field prompt_id "$payload")"
+relay_post_status busy "" "$prompt_id"
 # 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"

package/src/adapter.ts

@@ -1,4 +1,4 @@
-import type { AgentProfile, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
+import type { AgentProfile, LivenessSignal, Message, MessageFinalityConfidence, MessageTurnEndReason, ProviderState } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk/types/guards";
 import type { LivenessInputs } from "./liveness";
 import type { SessionEvent } from "./session-insights";
@@ -50,6 +50,10 @@ export interface ProviderSessionEvent {
   turnId?: string;
   /** True only when this response is the completed provider turn, not an intermediate flush. */
   final?: boolean;
+  /** Whether the turn-final edge was provider-native or reconstructed. Set only alongside `final`. */
+  confidence?: MessageFinalityConfidence;
+  /** Why the provider turn ended. Set only alongside `final`. */
+  endedBy?: MessageTurnEndReason;
   label?: string;
   status?: "running" | "completed" | "failed";
   streaming?: boolean;

package/src/adapters/claude-transcript.ts

@@ -46,6 +46,16 @@ interface TranscriptEntry {
   // Events/countSubstantiveTurns) intentionally do NOT filter — changing them
   // would shift the #184/#185 baselines, a separate concern.
   isSidechain?: boolean;
+  // Every entry carries its own `uuid` and its `parentUuid` (the entry it was
+  // appended after), forming a causal chain for the whole session. A `user`-type
+  // entry — whether the real prompt or a synthetic tool_result — is stamped with
+  // `promptId`: the same UUID Claude's Stop-hook payload reports as `prompt_id`,
+  // shared by every entry from that prompt until the next one. Assistant entries
+  // don't carry `promptId` directly; their turn is resolved by walking `parentUuid`
+  // back to the nearest ancestor that has one (see resolveEntryPromptId).
+  uuid?: string;
+  parentUuid?: string;
+  promptId?: string;
 }
 
 function blocks(message: TranscriptMessage | undefined): TranscriptBlock[] {
@@ -147,59 +157,39 @@ export function extractLastAssistantTurnAfterEntry(jsonl: string, afterEntry: nu
 }
 
 /**
- * Count valid JSON entries in a JSONL string. Used to record the high-water-mark
- * after a pre-flush so the Stop hook knows where to resume in full-capture mode.
+ * Resolve the `promptId` (Stop hook's `prompt_id`) a transcript entry belongs to.
+ * A `user`-type entry (the real prompt, or a synthetic tool_result) carries its own
+ * `promptId`; an assistant entry doesn't, so its turn is resolved by walking
+ * `parentUuid` back through the causal chain until an ancestor with one is found.
+ * Returns undefined for an entry with no resolvable ancestor (e.g. the very first
+ * turn of a process, before any `promptId` has ever been stamped).
  */
-export function countTranscriptEntries(jsonl: string): number {
-  let count = 0;
-  for (const line of jsonl.split("\n")) {
-    if (!line.trim()) continue;
-    try { JSON.parse(line); count++; } catch {}
-  }
-  return count;
-}
-
-/**
- * Returns only the text from the LAST assistant entry in the current turn.
- * Unlike extractLastAssistantTurn which collects all intermediate text between
- * tool calls, this returns just the final response — what the user sees as the
- * concluding message.
- */
-export function extractFinalAssistantMessage(jsonl: string): string {
-  const lines = jsonl.split("\n");
-  let lastText = "";
-  let pastLastUserPrompt = false;
-  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 (isSidechainEntry(entry)) continue;
-    if (isRealUserPrompt(entry)) {
-      pastLastUserPrompt = true;
-      lastText = "";
-      continue;
-    }
-    if (!pastLastUserPrompt) continue;
-    const text = assistantText(entry);
-    if (text) lastText = text;
+function resolveEntryPromptId(entry: TranscriptEntry, byUuid: ReadonlyMap<string, TranscriptEntry>): string | undefined {
+  let current: TranscriptEntry | undefined = entry;
+  const visited = new Set<string>();
+  while (current) {
+    if (typeof current.promptId === "string" && current.promptId) return current.promptId;
+    const parentUuid = current.parentUuid;
+    if (!parentUuid || visited.has(parentUuid)) return undefined;
+    visited.add(parentUuid);
+    current = byUuid.get(parentUuid);
   }
-  return lastText.trim();
+  return undefined;
 }
 
 /**
- * Like extractFinalAssistantMessage but skips the first `afterEntry` valid JSON
- * entries. Used when a PreToolUse pre-flush already emitted the text before a
- * blocking control, so final-mode Stop capture only sees later assistant text.
+ * Deterministic replacement for extractLastAssistantTurnAfterEntry's "walk back to
+ * the last real user prompt" heuristic: collects assistant `text` blocks for entries
+ * whose resolved promptId (see resolveEntryPromptId) equals the Claude-native
+ * `promptId` the Stop hook reported for this turn. Skips the first `afterEntry`
+ * entries the same way, for pre-flush resume. Since entries never move once
+ * written, a turn's promptId membership is exact — no text-shape guessing about
+ * what counts as a "real" prompt.
  */
-export function extractFinalAssistantMessageAfterEntry(jsonl: string, afterEntry: number): string {
+export function extractAssistantTurnForPrompt(jsonl: string, promptId: string, afterEntry = 0): string {
   const lines = jsonl.split("\n");
-  let lastText = "";
-  let pastLastUserPrompt = afterEntry > 0;
+  const byUuid = new Map<string, TranscriptEntry>();
+  const collected: string[] = [];
   let entryIndex = 0;
   for (const line of lines) {
     const trimmed = line.trim();
@@ -211,26 +201,30 @@ export function extractFinalAssistantMessageAfterEntry(jsonl: string, afterEntry
       continue;
     }
     entryIndex++;
+    if (typeof entry.uuid === "string" && entry.uuid) byUuid.set(entry.uuid, entry);
     if (isSidechainEntry(entry)) continue;
     if (entryIndex <= afterEntry) continue;
-    if (isRealUserPrompt(entry)) {
-      pastLastUserPrompt = true;
-      lastText = "";
-      continue;
-    }
-    if (!pastLastUserPrompt) continue;
+    if (entry.type !== "assistant") continue;
+    if (resolveEntryPromptId(entry, byUuid) !== promptId) continue;
     const text = assistantText(entry);
-    if (text) lastText = text;
+    if (text) collected.push(text);
   }
-  return lastText.trim();
+  return collected.join("\n\n").trim();
 }
 
 /**
- * Extract text from the `last_assistant_message` field in the Stop hook
- * payload. This is the content of the final assistant message — either a plain
- * string or an array of content blocks (same shape as transcript entries).
- * Thinking and tool_use blocks are dropped, matching extractLastAssistantTurn.
+ * Count valid JSON entries in a JSONL string. Used to record the high-water-mark
+ * after a pre-flush so the Stop hook knows where to resume in full-capture mode.
  */
+export function countTranscriptEntries(jsonl: string): number {
+  let count = 0;
+  for (const line of jsonl.split("\n")) {
+    if (!line.trim()) continue;
+    try { JSON.parse(line); count++; } catch {}
+  }
+  return count;
+}
+
 /**
  * Extract the ordered narration, reasoning, and tool steps for the most recent
  * turn (since the last real user prompt). Used by the reasoning tailer to stream

package/src/adapters/codex-agent-message-capture.ts

@@ -4,7 +4,6 @@ type CompleteItemOptions = { includeInResponse?: boolean; phase?: unknown };
 
 const MAX_CAPTURED_RESPONSE_CHARS = 16_000;
 const TRUNCATION_MARKER_PREFIX = "[truncated:";
-const TERSE_FINAL_MAX_CHARS = 280;
 
 export class CodexAgentMessageCapture {
   private segments: ResponseEntry[][] = [];
@@ -46,11 +45,16 @@ export class CodexAgentMessageCapture {
     this.currentSegment = [];
   }
 
+  // Deterministic turn-final response: prefer the trailing structured report span, not a generic
+  // post-handoff coda. The original #1079/#1086 trailing-run rule correctly kept early narration
+  // out, but it over-trimmed Codex turns shaped "summary -> workspace ready -> Landed..." and made
+  // report-up deliver only the coda (#1136). We still drop leading narration; we just let structured
+  // report markers beat a terse final status line.
   finish(emit: EmitAgentMessage): string | undefined {
     this.closeSegment(emit);
-    const selectedSegments = selectResponseSegments(this.segments);
+    const trailingSegment = selectFinalResponseSegments(this.segments);
     this.segments = [];
-    const text = selectedSegments.length ? selectedSegments.map(segmentBody).join("\n\n").trim() : undefined;
+    const text = trailingSegment ? trailingSegment.map(segmentBody).join("\n\n").trim() : undefined;
     return truncateCapturedResponse(text);
   }
 
@@ -96,41 +100,39 @@ export class CodexAgentMessageCapture {
   }
 }
 
-function selectResponseSegments(segments: ResponseEntry[][]): ResponseEntry[][] {
-  const nonEmptySegments = segments.filter((segment) => segment.length > 0);
-  const finalSegment = nonEmptySegments.at(-1);
-  if (!finalSegment) return [];
-  const finalBody = segmentBody(finalSegment);
-  if (!isTerseTerminalStatus(finalBody)) return [finalSegment];
-
-  // Codex often posts the real wrap-up across multiple assistant segments before a
-  // final workspace-ready/status line. Keep contiguous substantive segments after
-  // the last procedural assistant segment, then append the terminal status.
-  const selectedSegments: ResponseEntry[][] = [];
-  for (let index = nonEmptySegments.length - 2; index >= 0; index -= 1) {
-    const candidate = nonEmptySegments[index];
-    if (!candidate || !isSubstantiveResponseSegment(segmentBody(candidate))) break;
-    selectedSegments.unshift(candidate);
+function segmentBody(segment: ResponseEntry[]): string {
+  return segment.map((entry) => entry.body).join("\n\n").trim();
+}
+
+function selectFinalResponseSegments(segments: ResponseEntry[][]): ResponseEntry[][] | undefined {
+  const bodies = segments.map(segmentBody).filter(Boolean);
+  if (!bodies.length) return undefined;
+  let end = bodies.length - 1;
+  while (end > 0 && isGenericFinalCoda(bodies[end]!) && bodies.slice(0, end).some(isSubstantiveReportSegment)) end--;
+  const firstReport = bodies.slice(0, end + 1).findIndex(isReportBoundarySegment);
+  if (firstReport >= 0) return segments.slice(firstReport, end + 1);
+  for (let i = end; i >= 0; i--) {
+    if (isSubstantiveReportSegment(bodies[i]!)) return [segments[i]!];
   }
-  return [...selectedSegments, finalSegment];
+  return [segments[end]!];
 }
 
-function segmentBody(segment: ResponseEntry[]): string {
-  return segment.map((entry) => entry.body).join("\n\n").trim();
+const REPORT_BOUNDARY = /(^|\n)(#{1,6}\s|\*\*(summary|what changed|rca|fix|tests?|gates?|verification|risk)\b|(?:summary|what changed|rca|fix|tests?|gates?|verification|risk):)/i;
+const REPORT_STRUCTURE = /(^|\n)\s*[-*]\s+\S|`[^`]+`|\b(typecheck|bun test|tests? pass(?:ed)?|gates? green|rca|verified|implemented)\b/i;
+const GENERIC_FINAL_CODA = /^(?:done|landed(?: on main)?|committed|merged|ready|no further action|nothing further|all set)\b|(?:\bno further action needed\b|\bnothing further needed\b)$/i;
+
+function isReportBoundarySegment(body: string): boolean {
+  return REPORT_BOUNDARY.test(body.trim());
 }
 
-function isTerseTerminalStatus(body: string): boolean {
-  if (body.length > TERSE_FINAL_MAX_CHARS) return false;
-  if (/\n\s*(?:[-*]|\d+\.)\s+/.test(body)) return false;
-  return /\b(?:landed|ready for review|handed off|no further action|done|complete|completed|committed|merged)\b/i.test(body);
+function isSubstantiveReportSegment(body: string): boolean {
+  const trimmed = body.trim();
+  return !isGenericFinalCoda(trimmed) && (trimmed.length >= 120 || isReportBoundarySegment(trimmed) || REPORT_STRUCTURE.test(trimmed));
 }
 
-function isSubstantiveResponseSegment(body: string): boolean {
-  if (body.length >= 120) return true;
-  if (/\n\s*(?:[-*]|\d+\.)\s+/.test(body)) return true;
-  if (/\*\*(?:what changed|changes?|tests?|gates?|verification|risks?|residual risk|summary)\b/i.test(body)) return true;
-  if (/^#{1,3}\s+\S/m.test(body)) return true;
-  return body.split(/\n{2,}/).length >= 2;
+function isGenericFinalCoda(body: string): boolean {
+  const trimmed = body.trim();
+  return trimmed.length <= 180 && GENERIC_FINAL_CODA.test(trimmed) && !isReportBoundarySegment(trimmed);
 }
 
 function truncateCapturedResponse(text: string | undefined): string | undefined {

package/src/adapters/codex.ts

@@ -1,7 +1,7 @@
 import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import type { ContextState, InteractivePrompt, LivenessSignal, Message, ProviderState } from "agent-relay-sdk";
+import type { ContextState, InteractivePrompt, LivenessSignal, Message, MessageTurnEndReason, ProviderState } from "agent-relay-sdk";
 import { isRecord, stringValue } from "agent-relay-sdk";
 import { isPidAlive, killPid, processTreePids, processTreePidsFromTable, waitForPidsExit } from "agent-relay-sdk/process-utils";
 import { profileAllowsRelayFeature, providerMessageText, relayContext, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
@@ -144,13 +144,13 @@ export class CodexAdapter implements ProviderAdapter {
       const turnStatus = isRecord(activeTurn) ? stringValue(activeTurn.status) : undefined;
       if (turnStatus === "inProgress") return "busy";
       if (turnStatus === "completed" || turnStatus === "interrupted" || turnStatus === "failed") {
-        this.finishMainTurn();
+        this.finishMainTurn(codexEndedByFrom(turnStatus));
         return "idle";
       }
       const threadStatus = statusType(thread?.status);
       if (threadStatus === "active") return "busy";
       if (threadStatus === "idle" || threadStatus === "notLoaded" || threadStatus === "systemError") {
-        this.finishMainTurn();
+        this.finishMainTurn(codexEndedByFrom(threadStatus));
         return "idle";
       }
     } catch {
@@ -508,7 +508,7 @@ export class CodexAdapter implements ProviderAdapter {
       if (threadId && this.subagentThreads.has(threadId)) {
         this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
-        this.finishMainTurn();
+        this.finishMainTurn(codexEndedByFrom(method));
       }
     }
     if ((method.includes("thread/compacted") || method.includes("thread.compacted")) && threadId) {
@@ -527,15 +527,16 @@ export class CodexAdapter implements ProviderAdapter {
         if (status === "idle" || status === "notLoaded") this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
       } else {
         if (status === "active") this.statusCb({ status: "busy", reason: "provider-turn", providerState: this.providerStateFromThreadStatus(params?.status, params) });
-        if (status === "idle" || status === "notLoaded" || status === "systemError") this.finishMainTurn();
+        if (status === "idle" || status === "notLoaded" || status === "systemError") this.finishMainTurn(codexEndedByFrom(status));
       }
     }
   }
 
   // Turn one completed Codex thread item into a session-mirror event. agentMessage text is
-  // mirrored as narration as it lands; the captured turn-final response repeats the substantive
-  // assistant answer, including a substantive wrap-up segment before a terse terminal status.
-  // The rest (user prompt echo, reasoning, tool steps) is surfaced as it lands.
+  // mirrored as narration as it lands; the captured turn-final response repeats only the
+  // TRAILING agentMessage run — the segment after the last tool/file-change/reasoning
+  // boundary (design #1079 §3.2) — never earlier mid-work narration, which was already
+  // mirrored live. 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);
@@ -676,14 +677,23 @@ export class CodexAdapter implements ProviderAdapter {
     if (method.includes("outputDelta") || method.includes("output_delta") || method.includes("progress")) return;
   }
 
-  private flushTurnResponse(): void {
+  // A turn-final capture is emitted ONLY for a genuine `completed` turn (design #1079 §3.2):
+  // failed/interrupted turns must never produce a turn-final. Every "response"-type
+  // ProviderSessionEvent is unconditionally dual-stamped turnFinal/final downstream
+  // (publishCapturedResponse's provider-agnostic stamp), so the only way to keep a
+  // failed/interrupted partial OUT of D's work-final ring is to never emit it as a
+  // "response" event at all (#1083 Finding 1). The partial text was already mirrored live
+  // as narration by the `emit` callback inside agentMessageCapture.finish(), so it's still
+  // visible in the dashboard.
+  private flushTurnResponse(endedBy: MessageTurnEndReason): void {
     const text = this.agentMessageCapture.finish((body) => this.emitAgentNarration(body));
-    if (text) this.sessionEventCb({ type: "response", origin: "provider", body: text, final: true, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
+    if (!text || endedBy !== "completed") return;
+    this.sessionEventCb({ type: "response", origin: "provider", body: text, final: true, confidence: "definitive", endedBy, ...(this.activeTurnId ? { turnId: this.activeTurnId } : {}) });
   }
 
-  private finishMainTurn(): void {
+  private finishMainTurn(endedBy: MessageTurnEndReason): void {
     this.flushBufferedReasoning(); // surface any trailing reasoning before the closing response
-    this.flushTurnResponse();
+    this.flushTurnResponse(endedBy);
     const turnId = this.activeTurnId;
     this.activeTurnId = undefined;
     this.pendingApprovals.clear();
@@ -1151,6 +1161,14 @@ function statusType(value: unknown): string | undefined {
   return isRecord(value) ? stringValue(value.type) : undefined;
 }
 
+// Maps any Codex turn-ending signal — a turn/failed|interrupted (dot-notation too) app-server
+// method name, a turn status ("completed"/"interrupted"/"failed"), or a thread status
+// ("idle"/"notLoaded"/"systemError") — to the Part A (#1082) turn-end reason. "completed" is
+// the default for every signal that isn't explicitly a failure or an interruption.
+function codexEndedByFrom(value: string | undefined): MessageTurnEndReason {
+  return value === "systemError" || value?.includes("failed") ? "failed" : value?.includes("interrupted") ? "interrupted" : "completed";
+}
+
 function activeFlags(value: unknown): string[] {
   if (!isRecord(value) || !Array.isArray(value.activeFlags)) return [];
   return value.activeFlags.filter((flag): flag is string => typeof flag === "string" && flag.length > 0);

package/src/control-server.ts

@@ -49,12 +49,15 @@ interface ControlServerOptions {
   // dashboard chat without the agent re-emitting it via /reply.
   // isPreFlush: true signals a mid-turn call from a PreToolUse hook — flush any
   // un-mirrored narrative before the interactive form appears in chat (#435).
-  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; isPreFlush?: boolean }): Promise<void>;
+  // promptId (#1086): Claude's native `prompt_id` from the Stop hook payload — the
+  // stable, provider-native turn identifier used instead of a minted random UUID.
+  onSessionTurn?(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean }): Promise<void>;
   onPermissionResolved?(input: ResolvedPermissionPrompt): Promise<void> | 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>;
+  // promptId (#1086): Claude's native `prompt_id` for the turn this prompt starts.
+  onUserPrompt?(input: { prompt: string; transcriptPath?: string; promptId?: string }): Promise<void>;
   // A provider session-boundary hook (Claude PreCompact / SessionEnd) signals an imminent
   // context reset or termination so the runner can run end-of-session work (#183 pre-destroy
   // seam: #184 context-ratio capture) before the invasive operation. `reason` is the raw
@@ -501,6 +504,7 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
   const body = await req.json().catch(() => null);
   const transcriptPath = isRecord(body) && typeof body.transcriptPath === "string" ? body.transcriptPath : "";
   const lastAssistantMessage = isRecord(body) ? body.lastAssistantMessage : undefined;
+  const promptId = isRecord(body) && typeof body.promptId === "string" && body.promptId ? body.promptId : undefined;
   // transcriptPath is the primary source, but it can be absent (known CC Stop edge case).
   // lastAssistantMessage is the fallback for exactly that — accept either; reject only when
   // both are missing so the turn still reaches the dashboard chat (#264).
@@ -511,7 +515,7 @@ async function handleSessionTurn(req: Request, options: ControlServerOptions): P
   // reply-obligation check, so the captured turn must be persisted (and the
   // obligation cleared) before this response returns.
   try {
-    await options.onSessionTurn({ transcriptPath, lastAssistantMessage });
+    await options.onSessionTurn({ transcriptPath, lastAssistantMessage, ...(promptId ? { promptId } : {}) });
     return Response.json({ ok: true });
   } catch (error) {
     return Response.json({ ok: false, reason: errMessage(error) }, { status: 500 });
@@ -524,8 +528,9 @@ async function handleUserPrompt(req: Request, options: ControlServerOptions): Pr
   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;
+  const promptId = isRecord(body) && typeof body.promptId === "string" && body.promptId ? body.promptId : undefined;
   // Fire-and-forget: the hook must not block Claude's turn on relay round-trips.
-  void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath })).catch(() => {});
+  void Promise.resolve(options.onUserPrompt({ prompt, transcriptPath, ...(promptId ? { promptId } : {}) })).catch(() => {});
   return Response.json({ ok: true });
 }
 

package/src/response-capture-report.ts

@@ -12,8 +12,11 @@ type SessionPublisher = (input: {
   replyTo?: number;
 }) => void | Promise<void>;
 
+// #1086: dual-stamp the Part A (#1082) turn-finality field alongside the legacy
+// `final` alias so old consumers keep working while new ones can key off the
+// typed `turnFinal` flag directly instead of every writer's own `final: true`.
 function finalSession(session: MessageSessionMeta): MessageSessionMeta {
-  return { ...session, final: true };
+  return { ...session, turnFinal: true, final: true };
 }
 
 export async function publishCapturedResponse(input: {

package/src/runner-core.ts

@@ -16,7 +16,7 @@ import { readRunnerContextProbeState } from "./context-probe-state";
 import { startControlServer, type ControlServer, type ResolvedPermissionPrompt } from "./control-server";
 import { ReplyObligationCache, obligationRequiresExplicitReply, responseCaptureReplyRoute } from "./reply-obligation-cache";
 import { Outbox, type OutboxRecord } from "./outbox";
-import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, countTranscriptEntries, extractFinalAssistantMessage, extractFinalAssistantMessageAfterEntry, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
+import { extractLastAssistantTurn, extractLastAssistantTurnAfterEntry, extractAssistantTurnForPrompt, countTranscriptEntries, extractHookAssistantMessage, extractLatestTurnSteps, stepDedupKeys, transcriptLooksComplete } from "./adapters/claude-transcript";
 import { IncrementalClaudeTranscriptTail } from "./adapters/claude-transcript-tail";
 import { getManifest } from "agent-relay-providers";
 import { profileUsesProviderHostGlobals } from "./profile-home";
@@ -51,7 +51,7 @@ import {
   runnerAgentStatus,
   runnerBusErrorAction,
   runnerMessageMatches,
-  runnerMessageShouldDirtyObligations,
+  runnerMessageShouldDirtyObligations, restartOptionsFromCommand,
   runnerShouldResolveProviderExit,
   runnerShouldRestartUnexpectedProviderExit,
   runtimeProviderCapabilities,
@@ -60,7 +60,7 @@ import {
   shouldLogDeliveryFailure,
   stripRunnerClaimedGuidance,
   taskIdFromMessage,
-  type ProbeModelInfo,
+  type ProbeModelInfo, type RestartProviderOptions,
 } from "./runner-helpers";
 
 // Pre-destroy work is best-effort and must never hang teardown. Capping it keeps a slow
@@ -69,6 +69,7 @@ import {
 // 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;
+const STALE_PROVIDER_TURN_BUSY_MS = 10 * 60_000;
 
 interface RunnerOptions {
   provider: string;
@@ -535,7 +536,7 @@ export class AgentRunner {
     return mode === "isolated";
   }
 
-  private async spawnProvider(opts: { resumeId?: string; suppressPrompt?: boolean } = {}): Promise<ManagedProcess> {
+  private async spawnProvider(opts: RestartProviderOptions = {}): Promise<ManagedProcess> {
     this.providerSessionId = crypto.randomUUID();
     this.lastTranscriptPath = undefined;
     const includeProviderGlobals = profileUsesProviderHostGlobals(this.options);
@@ -586,7 +587,7 @@ export class AgentRunner {
       ...(this.options.profile ? { profile: this.options.profile } : {}),
       ...(this.options.agentProfile ? { agentProfile: this.options.agentProfile } : {}),
       ...(this.options.prompt && !opts.resumeId && !opts.suppressPrompt ? { prompt: this.options.prompt } : {}),
-      ...(this.options.systemPromptAppend ? { systemPromptAppend: this.options.systemPromptAppend } : {}),
+      ...((opts.systemPromptAppend ?? this.options.systemPromptAppend) ? { systemPromptAppend: opts.systemPromptAppend ?? this.options.systemPromptAppend } : {}),
       ...(this.options.tmuxSession ? { tmuxSession: this.options.tmuxSession } : {}),
       providerArgs: opts.resumeId ? [...this.options.providerArgs, "--resume", opts.resumeId] : this.options.providerArgs,
       providerConfig: this.options.providerConfig,
@@ -604,7 +605,7 @@ export class AgentRunner {
     };
     const launchSeededPrompt = this.options.adapter.seedsInitialPromptAtLaunch && !opts.resumeId && !opts.suppressPrompt ? this.options.prompt?.trim() : ""; if (launchSeededPrompt) this.recordInjectedPrompt(launchSeededPrompt);
     const managedProcess = await this.options.adapter.spawn(config);
-    const injectionEvents = runnerLaunchInjectionSessionEvents({ carried: this.options.relayInjectionEvents, provider: this.options.provider, config, providerConfig: this.options.providerConfig, agentId: this.agentId, providerSessionId: this.providerSessionId });
+    const injectionEvents = runnerLaunchInjectionSessionEvents({ carried: opts.relayInjectionEvents ?? this.options.relayInjectionEvents, provider: this.options.provider, config, providerConfig: this.options.providerConfig, agentId: this.agentId, providerSessionId: this.providerSessionId });
     for (const event of injectionEvents) {
       this.publishSessionEvent(event);
     }
@@ -777,7 +778,7 @@ export class AgentRunner {
       else this.lifecycleAction = undefined;
       this.publishStatus();
       let providerResult: Record<string, unknown> | void = undefined;
-      if (type === "agent.restart") await this.restartProvider();
+      if (type === "agent.restart") await this.restartProvider(restartOptionsFromCommand(params));
       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");
@@ -927,7 +928,7 @@ export class AgentRunner {
     return attachmentText ? `${body}\n\n${attachmentText}` : body;
   }
 
-  private async restartProvider(opts: { resumeId?: string; suppressPrompt?: boolean } = {}): Promise<void> {
+  private async restartProvider(opts: RestartProviderOptions = {}): Promise<void> {
     this.restartInProgress = true;
     try {
       if (this.process) {
@@ -1204,7 +1205,7 @@ export class AgentRunner {
     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;
+    let id = typeof update === "string" ? reason : update.id ?? reason;
     if (typeof update !== "string" && update.timeline) {
       this.pendingTimelineEvent = {
         status: update.timeline.status,
@@ -1291,13 +1292,19 @@ export class AgentRunner {
     }
     if (status === "busy" && reason === "provider-turn") {
       if (!this.currentTurnId) {
+        // For Claude, `update.id` carries the native prompt_id the UserPromptSubmit
+        // hook reported (relay-status.sh → /status) — the same id the Stop hook and
+        // transcript use for this turn. Falls back to a random mint only when no
+        // native id was supplied (e.g. a provider/path that doesn't report one).
         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})`);
       }
+      id = this.currentTurnId;
       this.busyReconciler.arm();
     } else if (status === "idle" && reason === "provider-turn") {
+      id = typeof update !== "string" && update.id ? update.id : this.currentTurnId ?? reason;
       if (this.currentTurnId) { this.completedProviderTurns += 1; this.sessionLog(`turn ended via provider idle (turn ${this.currentTurnId})`); }
       this.currentTurnId = undefined;
       this.currentTurnStartedAt = undefined;
@@ -1342,7 +1349,8 @@ export class AgentRunner {
       }
     } else if (status === "idle") {
       this.claims.clearTerminalStatus();
-      this.claims.finishWork(reason, id);
+      if (reason === "provider-turn") this.claims.clearWorkKind("provider-turn");
+      else this.claims.finishWork(reason, id);
       if (reason === "provider-turn") void this.completeObservedTaskClaims();
     }
     else if (status === "offline" || status === "error") this.claims.setTerminalStatus(status);
@@ -1423,7 +1431,7 @@ export class AgentRunner {
   // isPreFlush: true (#435/#499) — mid-turn PreToolUse boundary. Drain the live
   // tail and force-flush session messages before showing the blocking control;
   // the entry cursor lets Stop capture skip already-emitted text.
-  private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown; isPreFlush?: boolean }): Promise<void> {
+  private async publishSessionTurn(input: { transcriptPath: string; lastAssistantMessage?: unknown; promptId?: string; isPreFlush?: boolean }): Promise<void> {
     if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
 
     if (input.isPreFlush) {
@@ -1443,7 +1451,13 @@ export class AgentRunner {
       return;
     }
 
-    const turnId = this.currentTurnId;
+    // Claude's Stop hook reports its own native `prompt_id` — the same UUID the
+    // transcript stamps on every entry of this turn (extractAssistantTurnForPrompt /
+    // resolveEntryPromptId in claude-transcript.ts). It's the authoritative turn
+    // identifier; currentTurnId should already equal it (seeded from the same
+    // prompt_id at turn start — see setProviderStatus / handleUserPrompt), but this
+    // prefers the freshest source so finalization is correct even if the two drift.
+    const turnId = input.promptId ?? this.currentTurnId;
     this.stopReasoningTail();
     // Optional correlation for threading + obligation clearing — never a capture gate.
     let replyToMessageId: number | undefined, replyTarget = "user";
@@ -1464,32 +1478,41 @@ export class AgentRunner {
     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;
-        // If a pre-flush already emitted entries 1..flushCount, resume after that mark to avoid double-emit (#435/#499).
-        const extract = this.options.providerConfig.chatCaptureMode === "full"
-          ? (j: string) => (flushCount > 0 ? extractLastAssistantTurnAfterEntry(j, flushCount) : extractLastAssistantTurn(j))
-          : (j: string) => (flushCount > 0 ? extractFinalAssistantMessageAfterEntry(j, flushCount) : extractFinalAssistantMessage(j));
-        body = extract(jsonl);
-        if (body) break;
+    // PRIMARY capture source: the Stop hook's own last_assistant_message. Claude
+    // reports it synchronously in the hook payload itself, so there is no
+    // transcript file-read race to retry against — this text is authoritative and
+    // complete the moment the hook fires. The transcript is read at most ONCE
+    // (never retried/looped) and only to enrich "full" mode with the turn's
+    // intermediate narration; if that single read comes up empty (the file simply
+    // hasn't caught up yet) the hook payload text still carries the turn.
+    let body = extractHookAssistantMessage(input.lastAssistantMessage);
+    if (this.options.providerConfig.chatCaptureMode === "full" && input.transcriptPath) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (jsonl !== undefined && transcriptLooksComplete(jsonl)) {
+        // Deterministic slicing via prompt_id→parentUuid chaining when the native id is
+        // known; only fall back to the legacy "last real user prompt" heuristic when that
+        // deterministic slice comes up EMPTY, not merely when turnId is falsy — an old
+        // Claude (<2.1.196) mints a truthy random turnId that never resolves via promptId
+        // chaining, so branching on truthiness alone left this fallback unreachable and
+        // silently dropped intermediate narration in full mode (#1086 review, Finding F1).
+        let full = turnId ? extractAssistantTurnForPrompt(jsonl, turnId, flushCount) : "";
+        if (!full) full = flushCount > 0 ? extractLastAssistantTurnAfterEntry(jsonl, flushCount) : extractLastAssistantTurn(jsonl);
+        if (full) body = full;
       }
     }
-    // Fallback: last_assistant_message from the Stop hook payload, which bypasses
-    // the transcript file race entirely.
-    if (!body && input.lastAssistantMessage) {
-      body = extractHookAssistantMessage(input.lastAssistantMessage);
+    // Last-resort safety net for the default "final" mode (#1086 review, Finding F2):
+    // last_assistant_message is an undocumented Claude hook field. If a future Claude
+    // version renames or drops it, do ONE (never retried — same one-shot discipline as the
+    // "full" mode enrichment above) transcript read rather than silently losing every
+    // capture in the mode nearly every provider config runs in.
+    if (!body && this.options.providerConfig.chatCaptureMode === "final" && input.transcriptPath) {
+      let jsonl: string | undefined;
+      try { jsonl = await readFile(input.transcriptPath, "utf8"); } catch { jsonl = undefined; }
+      if (jsonl !== undefined) {
+        const fallback = turnId ? extractAssistantTurnForPrompt(jsonl, turnId, flushCount) : "";
+        body = fallback || (flushCount > 0 ? extractLastAssistantTurnAfterEntry(jsonl, flushCount) : extractLastAssistantTurn(jsonl));
+      }
     }
     // A pure tool-use turn with no closing text is fine to skip — its reasoning and
     // tool steps already carried the visibility into chat.
@@ -1499,7 +1522,18 @@ export class AgentRunner {
     }
 
     this.sessionLog(`response captured for turn ${turnId ?? "?"} (${body.length} chars${replyToMessageId ? `, replyTo #${replyToMessageId}` : ", no replyTo"})`);
-    await publishCapturedResponse({ publishSessionEvent: (event) => this.publishSessionEvent(event), outbox: this.sessionOutbox, provider: this.options.provider, from: this.agentId, to: replyTarget, body, replyTo: replyToMessageId, session: { type: "response", origin: "provider", final: true, ...(turnId ? { turnId } : {}) } });
+    await publishCapturedResponse({
+      publishSessionEvent: (event) => this.publishSessionEvent(event),
+      outbox: this.sessionOutbox,
+      provider: this.options.provider,
+      from: this.agentId,
+      to: replyTarget,
+      body,
+      replyTo: replyToMessageId,
+      // A Stop-hook-driven capture is by construction a definitive, provider-native
+      // turn completion — Claude's own lifecycle hook fired, not a reconstructed guess.
+      session: { type: "response", origin: "provider", final: true, confidence: "definitive", endedBy: "completed", ...(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();
@@ -1609,10 +1643,15 @@ export class AgentRunner {
   // 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> {
+  private async handleUserPrompt(input: { prompt: string; transcriptPath?: string; promptId?: string }): Promise<void> {
     if (input.transcriptPath) this.lastTranscriptPath = input.transcriptPath;
     if (!this.currentTurnId) {
-      this.currentTurnId = crypto.randomUUID();
+      // Claude's own prompt_id (from the UserPromptSubmit hook payload) is the
+      // native, stable turn identifier — the same id the Stop hook reports and the
+      // transcript stamps on every entry of this turn. Falls back to a random mint
+      // only for the rare case prompt_id wasn't available (see the ZS base schema
+      // note: absent until the very first user input of the process lifetime).
+      this.currentTurnId = input.promptId ?? crypto.randomUUID();
       this.currentTurnStartedAt = Date.now();
     }
     const text = input.prompt.trim();
@@ -1739,6 +1778,14 @@ export class AgentRunner {
       // Dashboard prompt injection is already answered by this captured App Server
       // response. User obligations still belong to the session mirror; spawner
       // obligations (#413) route to the spawn-parent with replyTo to clear the debt.
+      // #1083: a turn-final capture is ALWAYS mirrored, regardless of reply route — an
+      // autonomous Codex turn with no pending prompt and no eligible obligation used to
+      // hit `if (!route) return` here and vanish before ever reaching publishCapturedResponse,
+      // so it was neither shown in the dashboard nor eligible for report-up. The route only
+      // decides whether an explicit reply/obligation-clear also happens; when there's none,
+      // replyToMessageId stays undefined and the capture still lands as a plain session-mirror
+      // response (enqueueCapturedResponseReport's own `!replyTo` gate then correctly skips
+      // report-up — there's no spawner obligation to report up against).
       let replyToMessageId: number | undefined, replyTarget = "user";
       const pendingPrompt = this.pendingPromptMessageId;
       if (pendingPrompt) {
@@ -1746,10 +1793,9 @@ export class AgentRunner {
         this.pendingPromptMessageId = undefined;
       } else {
         const route = responseCaptureReplyRoute(this.obligationCache.get(), this.currentTurnStartedAt, { suppressUser: true });
-        if (!route) return; // The session mirror will satisfy the user obligation; don't double-post (#196).
-        replyToMessageId = route.replyToMessageId; replyTarget = route.to;
+        if (route) { replyToMessageId = route.replyToMessageId; replyTarget = route.to; }
       }
-      await publishCapturedResponse({ publishSessionEvent: (sessionEvent) => this.publishSessionEvent(sessionEvent), outbox: this.sessionOutbox, provider: this.options.provider, from: this.agentId, to: replyTarget, body, replyTo: replyToMessageId, session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}) } });
+      await publishCapturedResponse({ publishSessionEvent: (sessionEvent) => this.publishSessionEvent(sessionEvent), outbox: this.sessionOutbox, provider: this.options.provider, from: this.agentId, to: replyTarget, body, replyTo: replyToMessageId, session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}), ...(event.confidence ? { confidence: event.confidence } : {}), ...(event.endedBy ? { endedBy: event.endedBy } : {}) } });
       if (replyToMessageId) this.obligationCache.markDirty();
       return;
     }
@@ -1965,15 +2011,25 @@ export class AgentRunner {
     });
   }
 
+  private isStaleProviderTurnOnlyBusy(
+    status: SemanticStatus,
+    activeWork: Array<{ kind: string }>,
+    busyReasons: string[],
+    liveness: { hasLiveWork: boolean; lastProgressAt: number },
+  ): boolean {
+    if (status !== "busy") return false;
+    if (activeWork.length === 0 || activeWork.some((work) => work.kind !== "provider-turn")) return false;
+    if (busyReasons.some((reason) => reason !== "provider-turn")) return false;
+    if (liveness.hasLiveWork || !liveness.lastProgressAt) return false;
+    return Date.now() - liveness.lastProgressAt >= STALE_PROVIDER_TURN_BUSY_MS;
+  }
+
   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;
     // §4.1 Runner↔provider liveness contract (#725 / #746): fold the raw transport/timeline/
@@ -1989,6 +2045,12 @@ export class AgentRunner {
     const liveness = this.options.adapter.liveness
       ? this.options.adapter.liveness(livenessInputs)
       : computeLivenessSignal(livenessInputs);
+    const busyReasons = this.claims.reasons();
+    const staleProviderTurnBusy = this.isStaleProviderTurnOnlyBusy(status, activeWork, busyReasons, liveness);
+    const effectiveStatus = staleProviderTurnBusy ? "idle" : status;
+    const agentStatus = runnerAgentStatus(effectiveStatus);
+    const providerState = terminalFailure?.providerState ?? this.rateLimitHold ?? (staleProviderTurnBusy ? null : providerStateFromActiveWork(activeWork));
+    this.bus.setSemanticStatus(effectiveStatus === "offline" || effectiveStatus === "error" ? "idle" : effectiveStatus);
     this.bus.status({
       agentStatus,
       ready: agentStatus !== "offline" && !this.stopped,
@@ -2020,7 +2082,7 @@ export class AgentRunner {
             ? { lastError: `Claude provider exited; resume id ${this.terminalProviderExit.claudeResumeId} captured for manual recovery` }
             : { lastError: "Claude provider exited; manual intervention required" }),
         } : {}),
-        busyReasons: this.claims.reasons(),
+        busyReasons: staleProviderTurnBusy ? busyReasons.filter((reason) => reason !== "provider-turn") : busyReasons,
         completedProviderTurns: this.completedProviderTurns,
         activeWork,
         activeSubagents,

package/src/runner-helpers.ts

@@ -5,6 +5,7 @@ import { getManifest } from "agent-relay-providers";
 import type { BooleanCapabilityDefault, ProviderCapabilityCondition } from "agent-relay-providers";
 import { targetMatchesAgentIdentity } from "agent-relay-sdk/agent-target";
 import type { ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus } from "./adapter";
+import type { RunnerRelayInjectionEvent } from "./relay-injection-events";
 import { agentProfileProjectionReport } from "./profile-projection";
 import { assembleLaunch } from "./launch-assembly";
 
@@ -27,6 +28,13 @@ export interface ProbeModelInfo {
   effort?: string;
 }
 
+export interface RestartProviderOptions {
+  resumeId?: string;
+  suppressPrompt?: boolean;
+  systemPromptAppend?: string;
+  relayInjectionEvents?: RunnerRelayInjectionEvent[];
+}
+
 export function runnerMessageMatches(message: Pick<Message, "to" | "resolvedToAgent">, target: {
   agentId: string;
   label?: string;
@@ -62,6 +70,29 @@ export function stripRunnerClaimedGuidance(body: string): string {
   return body.replace(RUNNER_CLAIMED_GUIDANCE_RE, "");
 }
 
+const RELAY_INJECTION_CATEGORIES = new Set(["memory", "instructions", "tools", "comms", "knowledge", "context"]);
+
+function relayInjectionEventsFromParam(value: unknown): RunnerRelayInjectionEvent[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const events = value.flatMap((item): RunnerRelayInjectionEvent[] => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return [];
+    const record = item as Record<string, unknown>;
+    const detail = record.detail;
+    if (typeof record.category !== "string" || !RELAY_INJECTION_CATEGORIES.has(record.category)) return [];
+    if (typeof record.summary !== "string" || !record.summary.trim()) return [];
+    if (!detail || typeof detail !== "object" || Array.isArray(detail)) return [];
+    return [{ category: record.category as RunnerRelayInjectionEvent["category"], summary: record.summary, detail: detail as Record<string, unknown> }];
+  });
+  return events.length ? events : undefined;
+}
+
+export function restartOptionsFromCommand(params: Record<string, unknown>): RestartProviderOptions {
+  return {
+    systemPromptAppend: typeof params.systemPromptAppend === "string" ? params.systemPromptAppend : undefined,
+    relayInjectionEvents: relayInjectionEventsFromParam(params.relayInjectionEvents),
+  };
+}
+
 // Bound a runner's INITIAL relay registration. `connect` resolves on the first `registered`
 // frame and otherwise loops forever, so a token the relay rejects (401 at the WS upgrade)
 // hangs here silently. Race it against `timeoutMs`; on timeout, surface a fatal reason, tear