agent-relay-server 0.124.0 → 0.126.0

package/runner/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/runner/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

package/src/agent-lifecycle-events.ts

@@ -4,6 +4,7 @@ import { LIFECYCLE_STATE_WORKING, childSignalKey, stampLifecycleSignal, taskSign
 import { deliverableTaskIdsBySpawnRequestId, getAgent, markAgentReadyNotified, recordCrashReport, recordTerminalEvent } from "./db";
 import { crashReportFor } from "./agent-death-diagnosis";
 import { renderTemplate } from "./prompt-resolver";
+import { markAgentWorkFinal } from "./services/work-finality";
 import type { AgentCard, AgentDeathDiagnosis } from "./types";
 
 /** One-line cause tag appended to a death notification body, e.g. " · why: Clean exit (exit code 0)". */
@@ -187,6 +188,13 @@ export function notifyAgentOffline(childId: string, reason: string, diagnosis?:
   const child = getAgent(childId);
   const parent = child?.spawnedBy;
   if (!child || !parent) return;
+  // #1084 crash-final-loss fix-forward — this is the platform confirming the child is gone for
+  // good (past the reconnect/stale grace, or an explicit exit-diagnostics report). A genuine final
+  // report captured+held in the ring before the crash must go out now or it is lost forever: no
+  // later signal (relay_workspace_ready, task→done) is coming from a process that no longer exists.
+  // Idempotent (flushWorkFinalReports no-ops once the ring is empty), so a redundant call from a
+  // second offline classification of the same agent is harmless.
+  markAgentWorkFinal(childId, "edge-fallback");
   // Classify from the live set OR the durable readiness stamp. The `delete` always runs (cleanup of
   // the in-memory set); the persisted stamp covers a child that became ready before a relay restart.
   const wasReady = readyFired.delete(childId) || everReady(child);

package/src/bus.ts

@@ -15,7 +15,6 @@ import { agentProviderTimelineEvent, auditRunnerTimelineEvent } from "./provider
 import { ServiceAuthError } from "./services/errors";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent, shutdownInputFromBusFrame } from "./services/shutdown-agent";
 import { flushQueuedDirectMessages } from "./services/managed-running";
-import { flushIdleLineageReport } from "./services/send-message";
 import { isAgentUnavailable } from "./db/agent-predicates";
 import { applyCommandToRecipe } from "./recipe-runner";
 import { enqueueContinuationInjectionAfterSelfResume } from "./self-resume";
@@ -106,10 +105,6 @@ export function busHandleClose(ws: BusWebSocket): void {
     if (!conn.transportReconnect) {
       setStatus(conn.agentId, "stale", { instanceId: conn.instanceId, epoch: conn.epoch });
       emitAgentStatusEvent(conn.agentId);
-      // #1040 — a WS close is a busy→exit edge (the runner crashed/dropped before its stop-hook
-      // status frame). Flush any held turn-final report-up so it still reaches the spawner instead
-      // of dying with the socket. No-op when nothing was deferred.
-      flushIdleLineageReport(conn.agentId);
     }
   }
 }
@@ -134,9 +129,6 @@ export function expireStaleBusAgents(graceMs = busStaleGraceMs(), lagGraceMs = 0
     // (a fresh instanceId → epoch bump), never on a heartbeat lapse.
     setStatus(row.id, "offline");
     emitAgentStatusEvent(row.id);
-    // #1040 — the stale sweep is the terminal busy→offline edge for a runner that dropped without a
-    // clean idle transition. Flush any held turn-final report-up before the agent ages out.
-    flushIdleLineageReport(row.id);
     const tasks = orphanTasksForAgent(row.id);
     for (const task of tasks) {
       orphanedTasks.push(task);
@@ -172,16 +164,6 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
             heartbeat(conn.agentId, { instanceId: conn.instanceId, epoch: conn.epoch }, runtime);
             if (frame.payload.status) {
               setStatus(conn.agentId, frame.payload.status, { instanceId: conn.instanceId, epoch: conn.epoch });
-              // #1040 — a heartbeat frame can carry the busy→idle transition instead of a `status`
-              // frame. Flush the held report-up on THIS edge too, else `before.status` is already
-              // non-busy at the next status frame → the flush never fires → the child deadlocks idle
-              // with its verdict held and the coordinator waits forever.
-              // #1037 (re-regression) — gate on a genuine at-rest `idle`, NOT merely "not busy". A
-              // real turn-end always reports `idle`; a transient non-idle status (a stray `online`,
-              // a malformed frame) is NOT the end of the child's work and must not flush its held
-              // mid-work capture upstream. Terminal exit edges (WS-close/stale sweep) keep their
-              // unconditional flush for the #1040 delivery guarantee — this only tightens the LIVE edge.
-              if (current?.status === "busy" && frame.payload.status === "idle") flushIdleLineageReport(conn.agentId);
             }
             emitAgentStatusEvent(conn.agentId);
             // #416 — flush queued messages if the agent transitioned from unavailable to available.
@@ -226,12 +208,6 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         emitAgentStatusEvent(conn.agentId);
         // #237 stop-hook → instant ⚪↔🟡 changes detection on the turn-end edge.
         probeWorkspaceOnTurnEnd(before, after);
-        // #1037 — the same busy→idle turn-end edge flushes a quiet child's deferred turn-final
-        // report-up to its spawner (held back while the child was mid-work). Gate on a genuine
-        // at-rest `idle`: a real turn-end reports `idle`, whereas a transient non-idle status
-        // (stray `online`, reconnect) is not the child going to rest and must not flush its held
-        // mid-work capture. Terminal exit edges keep the #1040 unconditional flush.
-        if (before?.status === "busy" && after && after.status === "idle") flushIdleLineageReport(conn.agentId);
         // #633 — silent clean-exit: a runner that stays alive after its provider terminally exited
         // marks the offline edge with `terminalProviderExit`; the owning service turns that into a
         // terminal event + #636 diagnosis (and clears the hold on a genuine resume).

package/src/db/agents.ts

@@ -566,7 +566,20 @@ export function reapStaleAgents(ttlMs: number = STALE_TTL_MS, lagGraceMs = 0): s
 
 export { settleSingleTargetOnDemandTasks } from "./task-maintenance.ts";
 
-export function pruneOfflineAgents(maxOfflineMs: number = DAY_MS): string[] {
+export function pruneOfflineAgents(
+  maxOfflineMs: number = DAY_MS,
+  opts?: {
+    /**
+     * #1084 crash-final-loss fix-forward — defense-in-depth for a held work-final ring that
+     * somehow survived to prune time (the primary flush is `notifyAgentOffline`, fired when the
+     * agent first goes offline). Called per pruned agent id BEFORE its row is deleted, so a
+     * caller can flush any still-held final report while `getAgent(id)` can still resolve it —
+     * kept a plain callback (not a direct import) so this db-layer module stays free of
+     * service/SSE-layer dependencies.
+     */
+    beforeDelete?: (agentId: string) => void;
+  },
+): string[] {
   const cutoff = Date.now() - maxOfflineMs;
   return getDb().transaction(() => {
     const rows = getDb()
@@ -597,6 +610,7 @@ export function pruneOfflineAgents(maxOfflineMs: number = DAY_MS): string[] {
 
     for (const row of rows) {
       // Offline past the prune horizon and being deleted — a hard kill, not recoverable.
+      opts?.beforeDelete?.(row.id);
       revokeRuntimeTokensForAgent(row.id, now, "pruned");
       closeOpenPairsForAgent(row.id, now);
       removeSubscriptionsForAgent(row.id);