agent-relay-server 0.124.0 → 0.125.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";
@@ -1291,6 +1291,10 @@ 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;
@@ -1423,7 +1427,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 +1447,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 +1474,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 +1518,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 +1639,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 +1774,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 +1789,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;
     }

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);

package/src/db/messages.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
 import {
+  hasWorkFinality,
   isRecord,
   isTurnFinalSession,
   stringValue,
@@ -8,6 +9,7 @@ import {
   isReportVerbosity,
   type MessagePayload,
   type MessageWorkFinality,
+  type MessageWorkFinalitySource,
   type ReportVerbosity,
 } from "agent-relay-sdk";
 import { LIFECYCLE_STATE_WORKING, childSignalKey, stampLifecycleSignal, taskSignalKey } from "../lifecycle-signal-registry";
@@ -364,11 +366,6 @@ function reportVerbosityOf(child: AgentCard): ReportVerbosity {
   return isReportVerbosity(value) ? value : "quiet";
 }
 
-/** The child is mid-turn (not yet idle/awaiting-input). The authoritative "still working" signal. */
-function childIsBusy(child: AgentCard): boolean {
-  return child.status === "busy";
-}
-
 // #1037 (re-regression) — the report-up must reach the spawner as a CONCISE result, not the full
 // turn transcript. In `chatCaptureMode: "full"` (and for rambling multi-block recaps) the captured
 // turn-final body is the ENTIRE turn's narration — every "Let me read X… now Y… now Z…" segment
@@ -424,50 +421,90 @@ function distillLineageReportBody(body: string, messageId: number): string {
   return `${reportUpElision(messageId)}\n\n${tail}`;
 }
 
-// #1037 — a quiet child's turn-final response that arrives while the child is still busy is a
-// mid-task yield, not the end of its work. Instead of shipping it upstream (mid-work narration) or
-// dropping it (a genuine last turn whose idle status simply hasn't landed yet), we HOLD the latest
-// one per child and flush it when the child transitions to idle (see flushDeferredLineageReport,
-// driven off the bus turn-end edge). Coalescing on childId means only the final turn's report lands.
-const deferredLineageReports = new Map<string, number>();
+// #1084 — a turn-final response is TURN-final (this provider turn ended), not WORK-final (the
+// agent's work is done). Forwarding every one upstream is the false-final flood (#1078/#1058/#1032/
+// #976): a child idling briefly between two subtasks looks identical, on the wire, to a child that
+// just finished. So a `responses`-stream turn-final is never delivered on capture — it is HELD per
+// child in a small ring (the last few closing turns; see LINEAGE_FINAL_GROUP_CAP) until an explicit
+// work-finality signal closes the window (see flushWorkFinalReports in ../services/work-finality.ts,
+// anchored to relay_workspace_ready / task→done / agent teardown-reap — never a busy→idle bus edge).
+const LINEAGE_FINAL_GROUP_CAP = 3;
+// #1084 MEDIUM fix-forward — the ring above is capped by COUNT, not recency: after 5 steer cycles
+// a 3-slot ring holds whatever is still sitting there regardless of age, so a close could flush up
+// to 2 stale mid-work narrations from earlier cycles alongside (or instead of) the real closing
+// message(s). `flushWorkFinalReports` gates each held entry on its age *relative to the close*, so
+// only captures from the completing sequence — not leftover narration from a much earlier cycle —
+// ride along in the delivered group. Generous relative to LINEAGE_REPORT_DUPLICATE_WINDOW_MS (2min)
+// so a genuinely multi-turn closing sequence is never mistaken for stale narration.
+const LINEAGE_FINAL_GROUP_RECENCY_MS = 10 * 60 * 1000;
+const deferredLineageReports = new Map<string, number[]>();
 
 function deferLineageReport(childId: string, messageId: number): void {
-  deferredLineageReports.set(childId, messageId);
-}
-
-function clearDeferredLineageReport(childId: string): void {
-  deferredLineageReports.delete(childId);
+  const queue = deferredLineageReports.get(childId) ?? [];
+  queue.push(messageId);
+  while (queue.length > LINEAGE_FINAL_GROUP_CAP) queue.shift();
+  deferredLineageReports.set(childId, queue);
 }
 
-/** Test seam: clear the #1037 deferred report-up hold between tests. */
+/** Test seam: clear the held work-final group between tests. */
 export function __resetDeferredLineageReports(): void {
   deferredLineageReports.clear();
 }
 
+export interface WorkFinalFlushResult {
+  /** The chat report(s) forwarded (or found already-forwarded) to the spawner, oldest first. */
+  forwarded: Array<{ message: Message; created: boolean }>;
+  /** The original session-mirror captures retroactively tagged `payload.finality` (for the
+   * `message.finalized` SSE upgrade of already-rendered bubbles). */
+  finalizedOriginals: Message[];
+}
+
 /**
- * #1037 — flush a child's deferred turn-final report to its spawner. Called when the child
- * transitions out of busy (idle/awaiting-input): re-runs the promotion, which now passes the idle
- * gate and delivers. No-op when nothing was deferred. Returns the promoted message, or null.
+ * #1084 — close a child's work window: flush its held turn-final group to its spawner as ONE
+ * work-final unit sharing a fresh `windowId`, tagged with `source` (the explicit signal that closed
+ * the window) and an incrementing `groupOrder`. No-op when nothing was held. This is the ONLY path
+ * that delivers a `responses`-stream capture to the spawner (besides the `verbose` bypass in
+ * promoteLineageCapturedResponse) — call it from the finality service, never from a bus status edge.
  */
-export function flushDeferredLineageReport(childId: string): { message: Message; created: boolean } | null {
-  const messageId = deferredLineageReports.get(childId);
-  if (messageId === undefined) return null;
+export function flushWorkFinalReports(childId: string, source: MessageWorkFinalitySource): WorkFinalFlushResult {
+  const queue = deferredLineageReports.get(childId);
+  if (!queue || queue.length === 0) return { forwarded: [], finalizedOriginals: [] };
   deferredLineageReports.delete(childId);
-  const message = getMessage(messageId);
-  if (!message) return null;
-  return promoteLineageCapturedResponse(message);
+  const child = getAgent(childId);
+  const parent = child?.spawnedBy;
+  if (!child || !parent) return { forwarded: [], finalizedOriginals: [] };
+
+  const windowId = randomUUID();
+  const markedAt = Date.now();
+  const recencyCutoff = markedAt - LINEAGE_FINAL_GROUP_RECENCY_MS;
+  const forwarded: Array<{ message: Message; created: boolean }> = [];
+  const finalizedOriginals: Message[] = [];
+  let groupOrder = 0;
+  for (const messageId of queue) {
+    const original = getMessage(messageId);
+    if (!original) continue;
+    // #1084 MEDIUM — drop stale mid-work narration the count-capped ring is still holding from an
+    // earlier steer cycle; only captures from the completing sequence ride along in this group.
+    if ((original.occurredAt ?? original.createdAt) < recencyCutoff) continue;
+    const session = sessionMeta(original);
+    if (!session) continue;
+    const finality: MessageWorkFinality = { windowId, source, groupOrder, markedAt };
+    const result = forwardLineageStreamCapture(original, session, "responses", child, parent, finality);
+    if (!result) continue;
+    groupOrder++;
+    forwarded.push(result);
+    const finalizedOriginal = setMessageWorkFinality(messageId, finality);
+    if (finalizedOriginal) finalizedOriginals.push(finalizedOriginal);
+  }
+  return { forwarded, finalizedOriginals };
 }
 
 /**
- * #1040/#1041 — the persisted turn-final response captures needed to rebuild the in-memory
- * deferred-report hold after a relay restart. Bounded by a recency window (a report is only ever
- * held while its child was mid-turn, so it is inherently recent). Grouped to the single newest
- * (highest-id) final capture per from_agent child *before* the row cap is applied, so that: (a) an
- * older mid-task final that #1037 coalesced away — persisted but never given an idempotency key —
- * is never resurrected alongside the real verdict, and (b) a chatty child's own history can't push
- * another child's final out of the cap. The caller re-runs promotion, which is idempotent: an
- * already-delivered capture is a no-op, an idle child's lost report is delivered, and a still-busy
- * child simply re-defers (holding the newest one, matching the live #1037 coalescing contract).
+ * #1040/#1041 — the persisted turn-final response captures needed to rebuild the in-memory held
+ * group after a relay restart. Bounded by a recency window (a report is only ever held while its
+ * work window is open, so it is inherently recent). The caller re-runs promotion per capture, which
+ * is idempotent: an already-forwarded capture is a no-op (idempotency key), and everything else
+ * re-enters the held ring exactly as it stood pre-restart, awaiting the next work-finality signal.
  */
 export function listRecentFinalResponseCaptures(sinceMs: number, limit = 1000): Message[] {
   const rows = getDb().query(`
@@ -529,17 +566,47 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
   // #1037 verbose: forward every child stream without an explicit per-stream subscription.
   if (stream !== "responses" && verbosity !== "verbose" && !childStreamSubscribed({ parentId: parent, child, stream })) return null;
 
-  // #1037 — the report-up delivery gate. In `quiet` (default), a turn-final response that arrives
-  // while the child is still busy is mid-task narration: defer it (flushed on the idle transition)
-  // rather than waking the spawner mid-work. `normal`/`verbose` forward every turn-final at once.
-  if (stream === "responses" && verbosity === "quiet" && childIsBusy(child)) {
+  // #1084 — a `responses`-stream turn-final is TURN-final, not WORK-final: hold it (see
+  // deferLineageReport above) rather than forwarding, regardless of the child's busy/idle state —
+  // only an explicit work-finality signal (flushWorkFinalReports) delivers it upstream. `verbose` is
+  // an explicit opt-in firehose (a caller that asked for every turn) and bypasses the hold, matching
+  // its pre-#1084 behavior.
+  if (stream === "responses" && verbosity !== "verbose") {
     deferLineageReport(child.id, message.id);
     return null;
   }
 
+  return forwardLineageStreamCapture(message, session, stream, child, parent);
+}
+
+/**
+ * Forward one captured child-stream event to its spawner as a `chat` report-up. Shared by the
+ * `verbose` immediate bypass (no `finality`) and `flushWorkFinalReports` (tags the forwarded report
+ * — and, via the caller, the original capture — with the closing work window's `finality`).
+ */
+function forwardLineageStreamCapture(
+  message: Message,
+  session: Record<string, unknown>,
+  stream: ChildStream,
+  child: AgentCard,
+  parent: string,
+  finality?: MessageWorkFinality,
+): { message: Message; created: boolean } | null {
   const idempotencyKey = lineageStreamReportKey(message, session, stream);
   const existing = findMessageByIdempotencyKey(message.from, idempotencyKey);
-  if (existing) return { message: existing, created: false };
+  if (existing) {
+    // #1084 MEDIUM (Lens-3 retroactive-finality) fix-forward — an already-forwarded report (e.g. a
+    // `verbose` bypass, or a duplicate suppressed on an earlier attempt) must still pick up the
+    // finality tag when its window later closes, or its dashboard bubble never upgrades from
+    // ordinary mid-turn narration to a closing message. Only patch when it isn't already tagged —
+    // an existing tag reflects an earlier, equally-valid window close and must not be overwritten.
+    if (finality && !hasWorkFinality(existing.payload)) {
+      const updatedPayload: MessagePayload = { ...(existing.payload ?? {}), finality };
+      getDb().query("UPDATE messages SET payload = ? WHERE id = ?").run(JSON.stringify(updatedPayload), existing.id);
+      return { message: getMessage(existing.id) ?? existing, created: false };
+    }
+    return { message: existing, created: false };
+  }
   if (stream === "responses") {
     const turnId = captureTurnId(session);
     if (turnId) {
@@ -559,12 +626,17 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
       since: message.createdAt - LINEAGE_REPORT_DUPLICATE_WINDOW_MS,
     });
     if (duplicate && !responseCaptureMeta(duplicate)) {
+      const updatedPayload: MessagePayload = {
+        ...(duplicate.payload ?? {}),
+        responseCapture: { ...session },
+        ...(finality ? { finality } : {}),
+      };
       getDb().query(`
         UPDATE messages
         SET idempotency_key = coalesce(idempotency_key, ?),
             payload = ?
         WHERE id = ?
-      `).run(idempotencyKey, JSON.stringify({ ...(duplicate.payload ?? {}), responseCapture: { ...session } }), duplicate.id);
+      `).run(idempotencyKey, JSON.stringify(updatedPayload), duplicate.id);
       return { message: getMessage(duplicate.id) ?? duplicate, created: false };
     }
   }
@@ -579,12 +651,11 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
     replyExpected: false,
     idempotencyKey,
     payload: stream === "responses"
-      ? { responseCapture: { ...session } }
+      ? { responseCapture: { ...session }, ...(finality ? { finality } : {}) }
       : { childStreamCapture: { stream, ...session } },
     occurredAt: message.occurredAt ?? message.createdAt,
   });
   if (stream === "responses" && result.created) {
-    clearDeferredLineageReport(child.id);
     stampReportUpLifecycleSignal(parent, child);
   }
   return result;

package/src/maintenance/jobs.ts

@@ -48,6 +48,7 @@ import {
 import { routeNotification } from "../notification-router";
 import { pruneExpiredTokenRecords } from "../token-db";
 import { reapTransientAgents } from "../services/transient-agent-reaper";
+import { markAgentWorkFinal } from "../services/work-finality";
 import { reapUnregisteredSpawnCommands } from "../services/spawn-registration-watchdog";
 import { resumeRateLimitedAgents } from "../services/rate-limit-resume";
 import { collectCodexWhamQuota } from "../codex-wham-quota";
@@ -334,7 +335,12 @@ export const definitions: MaintenanceJobDefinition[] = [
     intervalMs: REAP_INTERVAL_MS,
     runOnStart: false,
     handler() {
-      const prunedAgentIds = pruneOfflineAgents(OFFLINE_PRUNE_MS);
+      // #1084 crash-final-loss fix-forward — defense-in-depth: `notifyAgentOffline` is the primary
+      // flush point when an agent first goes offline, so this is normally a no-op by the time an
+      // agent reaches prune horizon; kept here in case any offline transition ever bypasses it.
+      const prunedAgentIds = pruneOfflineAgents(OFFLINE_PRUNE_MS, {
+        beforeDelete: (id) => markAgentWorkFinal(id, "edge-fallback"),
+      });
       for (const id of prunedAgentIds) emitAgentRemoved(id);
       return { prunedAgentIds };
     },
@@ -361,7 +367,7 @@ export const definitions: MaintenanceJobDefinition[] = [
     runOnStart: false,
     handler: () => reapOrphanedSessions(),
   },
-  { id: "transient-agent-reaper", title: "Transient agent reaper", description: "Cleanly shut down transient spawned agents once they are idle and any isolated branch work has landed.", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: () => reapTransientAgents() },
+  { id: "transient-agent-reaper", title: "Transient agent reaper", description: "Cleanly shut down transient spawned agents once they are idle and any isolated branch work has landed; also flushes a persistent agent's held work-final report once it has settled idle (#1084 HIGH fix-forward).", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: () => reapTransientAgents() },
   {
     id: "lineage-report-startup-sweep",
     title: "Lineage report startup sweep",

package/src/mcp/tools-workspace.ts

@@ -5,6 +5,7 @@ import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import { describeWorkspacePhase, landReceipt, readyContract } from "../workspace-phase";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "../workspace-actions";
 import { refreshWorkspaceGitState } from "../workspace-probe";
+import { markAgentWorkFinal } from "../services/work-finality";
 import { optionalEnum } from "../validation";
 import type { Command, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceRecord } from "../types";
 import type { McpAuthContext, ToolDefinition } from "./types";
@@ -218,6 +219,9 @@ export async function relayWorkspaceMutation(auth: McpAuthContext, action: Works
   if (action === "ready") {
     payload.contract = readyContract(result.workspace);
     payload.guidance = describeWorkspacePhase(result.workspace);
+    // #1084 — relay_workspace_ready is an explicit, platform-owned completion signal: the caller
+    // is declaring its work window closed. Close it, forwarding only the held final group.
+    markAgentWorkFinal(result.workspace.ownerAgentId ?? callerAgentId(auth), "workspace-ready");
   }
   return payload;
 }

package/src/routes/agents.ts

@@ -10,7 +10,6 @@ import { emitAgentRemoved, emitAgentStatus } from "../sse";
 import { notifyAgentReady } from "../agent-lifecycle-events";
 import { bindSpawnedTaskToReadyAgent } from "../services/register-agent";
 import { flushQueuedDirectMessages } from "../services/managed-running";
-import { flushIdleLineageReport } from "../services/send-message";
 import { isAgentUnavailable } from "../db/agent-predicates";
 import { getCompactionWatch } from "../compaction-watch";
 import { isRecord } from "agent-relay-sdk";
@@ -200,9 +199,6 @@ export const patchAgentStatus: Handler = async (req, params) => {
     const before = getAgent(params.id!);
     if (!setStatus(params.id!, body.status as (typeof VALID_AGENT_STATUSES)[number], guard)) return error("agent not found", 404);
     auditAgentStateTransition(params.id!, before, getAgent(params.id!));
-    // #1040 — the HTTP status PATCH is also a busy→idle edge (a runner without a live bus socket).
-    // Flush any held turn-final report-up so it reaches the spawner on this path too.
-    if (before?.status === "busy" && body.status !== "busy") flushIdleLineageReport(params.id!);
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;