agent-relay-server 0.124.0 → 0.126.0

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,126 @@ 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);
+  const queue = deferredLineageReports.get(childId) ?? [];
+  queue.push(messageId);
+  while (queue.length > LINEAGE_FINAL_GROUP_CAP) queue.shift();
+  deferredLineageReports.set(childId, queue);
 }
 
-function clearDeferredLineageReport(childId: string): void {
-  deferredLineageReports.delete(childId);
-}
-
-/** 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[] = [];
+  const held: Array<{ original: Message; session: Record<string, unknown> }> = [];
+  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;
+    held.push({ original, session });
+  }
+  const selected = source === "edge-fallback" ? selectEdgeFallbackLineageReports(held) : held;
+  let groupOrder = 0;
+  for (const { original, session } of selected) {
+    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(original.id, finality);
+    if (finalizedOriginal) finalizedOriginals.push(finalizedOriginal);
+  }
+  return { forwarded, finalizedOriginals };
+}
+
+function selectEdgeFallbackLineageReports<T extends { original: Message }>(held: T[]): T[] {
+  if (held.length <= 1) return held;
+  let bestIndex = -1;
+  let bestScore = -Infinity;
+  for (let i = 0; i < held.length; i++) {
+    const score = edgeFallbackReportScore(held[i]!.original.body);
+    if (score > bestScore || (score === bestScore && i > bestIndex)) {
+      bestScore = score;
+      bestIndex = i;
+    }
+  }
+  return bestScore > 0 && bestIndex >= 0 ? [held[bestIndex]!] : [held.at(-1)!];
+}
+
+const EDGE_FALLBACK_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 EDGE_FALLBACK_REPORT_STRUCTURE = /(^|\n)\s*[-*]\s+\S|`[^`]+`|\b(typecheck|bun test|tests? pass(?:ed)?|gates? green|rca|verified|implemented)\b/i;
+const EDGE_FALLBACK_GENERIC_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;
+const EDGE_FALLBACK_NARRATION = /^(?:i(?:'|’)ll|i(?:'|’)m|let me|checking|running|reading|found\b|now\b)/i;
+
+function edgeFallbackReportScore(body: string): number {
+  const trimmed = body.trim();
+  if (!trimmed) return -10;
+  if (trimmed.length <= 180 && EDGE_FALLBACK_GENERIC_CODA.test(trimmed) && !EDGE_FALLBACK_REPORT_BOUNDARY.test(trimmed)) return -5;
+  let score = 0;
+  if (trimmed.length >= 120) score += 2;
+  if (EDGE_FALLBACK_REPORT_BOUNDARY.test(trimmed)) score += 6;
+  if (EDGE_FALLBACK_REPORT_STRUCTURE.test(trimmed)) score += 3;
+  if (EDGE_FALLBACK_NARRATION.test(trimmed)) score -= 3;
+  return score;
 }
 
 /**
- * #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 +602,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 +662,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 +687,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/agent-sessions.ts

@@ -2,7 +2,7 @@
 import { RELAY_TOKEN_HEADER, isRecord, isSpawnProvider } from "agent-relay-sdk";
 import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeAgentRoute, authorizeRoute, canViewAgentRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, requestUserAddress, requestUserId, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
 import { arbitrateDrive, currentDriver, drivingMessage, releaseDrive, type DriveArbitration } from "../agent-drive-arbiter";
-import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, readSpawnCallerSystemPromptAppend, resolveAgentOwnership, sendMessage, withResolvedProvisioning } from "../db";
+import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage, withResolvedProvisioning } from "../db";
 import { announcePresence, viewersForAgent } from "../dashboard-presence";
 import { buildManagedSpawnParams } from "../managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
@@ -19,8 +19,8 @@ import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "../servic
 import { type AgentCard, type SpawnApprovalMode } from "../types";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { getManifest } from "agent-relay-providers";
-import { composeProfileSpawnInstructions } from "../project-instructions";
 import { relayToken } from "../config";
+import { restartInstructionParamsForAgent } from "../services/restart-instructions";
 
 // 409 when a second human tries to drive an agent another user is already driving (#394). The
 // blocked driver learns who holds the wheel so the UI can show "X is driving" + offer "request".
@@ -133,6 +133,7 @@ export function restartSpawnParamsForAgent(
   const agentProfile = resolvedProfile ? applyDefaultSharedMcp(resolvedProfile) : undefined;
   const workspaceMode = metaString(agent.meta, "workspaceMode") ?? "inherit";
   const resolvedModel = resolveSpawnModelParams(provider, model, effort, { onError: "passthrough", skipDefaultWhenEmpty: true });
+  const projectedInstructions = restartInstructionParamsForAgent(agent, { spawnRequestId, cwd }) ?? {};
   // #1052-v2 — a dashboard-spawned agent has NO spawn policy, so its restart skips the
   // `buildManagedSpawnParams` policy branch above and lands here. Re-project the profile role
   // charter / project knowledge / scoped memory (the SAME projection a fresh spawn gets) so the
@@ -152,8 +153,6 @@ export function restartSpawnParamsForAgent(
   // params — the SAME field a fresh agent.spawn stashes it in, see spawn-agent.ts). The reader then
   // recovers it from either the original agent.spawn row OR a later agent.restart row, so each
   // generation has its own recoverable copy and the brief follows the agent across every rotation.
-  const callerAppend = readSpawnCallerSystemPromptAppend(spawnRequestId);
-  const composed = composeProfileSpawnInstructions({ cwd, operatorId: resolveAgentOwnership(agent.id).ownerUserId, ...(profileName ? { profileName } : {}), ...(agentProfile ? { profile: agentProfile } : {}), ...(callerAppend ? { callerSystemPromptAppend: callerAppend } : {}) });
   const params = buildSpawnCommand({
     provider,
     modelParams: resolvedModel,
@@ -168,12 +167,12 @@ export function restartSpawnParamsForAgent(
     approvalMode: approvalMode ?? "guarded",
     permissionMode: approvalMode ?? "guarded",
     providerArgs: providerArgs.length ? providerArgs : undefined,
-    ...(composed.systemPromptAppend ? { systemPromptAppend: composed.systemPromptAppend } : {}),
+    ...(typeof projectedInstructions.systemPromptAppend === "string" ? { systemPromptAppend: projectedInstructions.systemPromptAppend } : {}),
     // #1067 — re-persist the RAW brief (pre-composition) under this restart's fresh spawnRequestId so
     // the NEXT restart, whose predecessor id is this fresh id, can recover it. Without this the brief
     // survives only one restart (the original agent.spawn row is keyed on the very first id).
-    ...(callerAppend ? { callerSystemPromptAppend: callerAppend } : {}),
-    ...(composed.relayInjectionEvents.length ? { relayInjectionEvents: composed.relayInjectionEvents } : {}),
+    ...(typeof projectedInstructions.callerSystemPromptAppend === "string" ? { callerSystemPromptAppend: projectedInstructions.callerSystemPromptAppend } : {}),
+    ...(Array.isArray(projectedInstructions.relayInjectionEvents) ? { relayInjectionEvents: projectedInstructions.relayInjectionEvents } : {}),
     policyName: policyName || undefined,
     headless: true,
     spawnRequestId: requestId,
@@ -298,6 +297,9 @@ export const postAgentAction: Handler = async (req, params) => {
     const metaPolicyName = typeof agent.meta?.policyName === "string" ? agent.meta.policyName : undefined;
     const metaSpawnRequestId = typeof agent.meta?.spawnRequestId === "string" ? agent.meta.spawnRequestId : undefined;
     const resumeId = action === "resume" ? latestResumeIdForAgent(agent) : undefined;
+    const restartInstructions = action === "restart" || action === "resume"
+      ? restartInstructionParamsForAgent(agent, { spawnRequestId: metaSpawnRequestId, cwd: metaString(agent.meta, "cwd") ?? orchestrator?.baseDir })
+      : undefined;
     if (action === "resume" && !orchestrator) return error("no online orchestrator available to resume agent", 409);
     if (action === "resume" && !resumeId) return error("no resume id recorded for agent", 422);
     const denied = authorizeRoute(req, {
@@ -319,6 +321,7 @@ export const postAgentAction: Handler = async (req, params) => {
         ...(metaPolicyName ? { policyName: metaPolicyName } : {}),
         ...(metaSpawnRequestId ? { spawnRequestId: metaSpawnRequestId } : {}),
         ...(action === "restart" || action === "resume" ? { restartSpawn: restartSpawnParamsForAgent(agent, orchestrator, metaPolicyName, metaSpawnRequestId, { resumeId }) } : {}),
+        ...(restartInstructions ?? {}),
         ...(action === "compact" ? compactMemoryParams(agent) : {}),
         ...(resumeId ? { claudeResumeId: resumeId } : {}),
         requestedBy: "dashboard",

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;

package/src/routes/orchestrator.ts

@@ -4,7 +4,7 @@ import { CONTRACT_VERSIONS, parseRuntimeCapabilities, parseRuntimeContracts, par
 import { notifyAgentOffline } from "../agent-lifecycle-events";
 import { diagnoseAgentDeath } from "../agent-death-diagnosis";
 import { VERSION } from "../config";
-import { ValidationError, deleteOrchestrator, getOrchestrator, listOrchestrators, orchestratorHeartbeat, recordAgentExitDiagnostics, setOrchestratorUpgradeState, updateManagedAgents, upsertOrchestrator } from "../db";
+import { ValidationError, deleteOrchestrator, getAgent, getOrchestrator, listOrchestrators, orchestratorHeartbeat, recordAgentExitDiagnostics, setOrchestratorUpgradeState, updateManagedAgents, upsertOrchestrator } from "../db";
 import { auditEvent, authAuditMetadata, authorizeRoute, cleanJsonArray, cleanSafeNumber, dashboardAttribution, emitCommand, error, isRootCredentialRequest, json, parseBody, spawnRequestId, type Handler } from "./_shared";
 import { cleanMeta, cleanString, cleanStringArray, cleanWorkspaceMetadata, optionalEnum } from "../validation";
 import { createCommand, updateCommand } from "../commands-db";
@@ -13,6 +13,7 @@ import { getLifecycleManager } from "../lifecycle-manager";
 import { issueOrchestratorRuntimeToken } from "../runtime-tokens";
 import { isOrchestratorRegistrationAuthorized } from "../security";
 import { type ManagedAgent, type ManagedSessionExitDiagnostics, type OrchestratorRuntimeInput, type RegisterOrchestratorInput, type SpawnApprovalMode, type SpawnProvider } from "../types";
+import { restartSpawnParamsForAgent } from "./agent-sessions";
 
 function cleanProtocolVersion(value: unknown): number | undefined {
   if (value === undefined) return undefined;
@@ -533,13 +534,15 @@ export const postOrchestratorAction: Handler = async (req, params) => {
       resource: { orchestratorId: orch.id, agentId, policyName, spawnRequestId },
     });
     if (denied) return denied;
+    const agent = action === "restart" && agentId ? getAgent(agentId) : undefined;
+    const restartSpawn = agent ? restartSpawnParamsForAgent(agent, orch, policyName, spawnRequestId) : undefined;
 
     const command = createCommand({
       type: action === "restart" ? "agent.restart" : "agent.shutdown",
       source: "system",
       target: orch.agentId,
       correlationId: spawnRequestId,
-      params: { action, agentId, policyName, spawnRequestId, sessionName, tmuxSession, reason, requestedBy: "dashboard", requestedAt: Date.now(), orchestratorId: orch.id },
+      params: { action, agentId, policyName, spawnRequestId, sessionName, tmuxSession, reason, ...(restartSpawn ? { restartSpawn } : {}), requestedBy: "dashboard", requestedAt: Date.now(), orchestratorId: orch.id },
     });
     emitCommand(command);
     auditEvent({

package/src/routes/settings.ts

@@ -10,7 +10,7 @@ import { isRequestAuthorizedFor } from "../security";
 import { cleanString } from "../validation";
 import { emitConfigChanged } from "../sse";
 import { error, json, normalizeConfigPathParam, parseBody, requestUserId, type Handler } from "./_shared";
-import { DEFAULT_USER_ID, isRecord, type ConfigEntry, type SettingDescriptor, type SettingEntry } from "agent-relay-sdk";
+import { DEFAULT_USER_ID, isRecord, type ConfigEntry, type JSONSchema, type SettingDescriptor, type SettingEntry } from "agent-relay-sdk";
 
 type SettingEnvelope = SettingEntry;
 
@@ -91,7 +91,10 @@ async function putSetting(req: Request, namespaceRaw: string | undefined, keyRaw
     if (!validation.valid) return json({ error: "invalid setting value", details: validation.errors }, 400);
     if (descriptor.tier === "user") {
       const userId = requestUserId(req);
-      const userEntry = setUserSetting(userId, namespace, key, parsed.body.value, updatedBy);
+      const valueToStore = descriptor.mergeMapKeys && isRecord(parsed.body.value)
+        ? mergeMapKeysIntoExisting(getUserSetting(userId, namespace, key)?.value, parsed.body.value, descriptor.schema)
+        : parsed.body.value;
+      const userEntry = setUserSetting(userId, namespace, key, valueToStore, updatedBy);
       emitConfigChanged(userEntry.namespace, userEntry.key, userEntry.version);
       return json(settingEnvelope(req, descriptor, userEntry), userEntry.version === 1 ? 201 : 200);
     }
@@ -156,3 +159,29 @@ function mergeSettingDefaults(defaults: unknown, value: unknown): unknown {
   }
   return merged;
 }
+
+// A `mergeMapKeys` descriptor (#1124) is a dictionary keyed by caller-chosen ids (e.g. one row
+// per conversation). A PUT only ever knows its own device's changed keys, never every other
+// device's, so overwriting the whole stored value like a normal setting would erase them — this
+// merges just the incoming keys on top of whatever is already stored instead. The merged result
+// is then capped at the schema's `maxProperties` (when set) so per-key merges from unboundedly
+// many devices can't grow the row forever; the entry with the OLDEST `updatedAt` is evicted first
+// (missing/non-numeric `updatedAt`, e.g. a pre-#1124 row, sorts as oldest: 0).
+function mergeMapKeysIntoExisting(existing: unknown, incoming: Record<string, unknown>, schema: JSONSchema): Record<string, unknown> {
+  const merged: Record<string, unknown> = isRecord(existing) ? { ...existing } : {};
+  for (const [key, item] of Object.entries(incoming)) merged[key] = item;
+
+  const cap = typeof schema.maxProperties === "number" ? schema.maxProperties : undefined;
+  const entries = Object.entries(merged);
+  if (cap !== undefined && entries.length > cap) {
+    entries.sort((a, b) => entryUpdatedAt(a[1]) - entryUpdatedAt(b[1]));
+    const overflow = entries.length - cap;
+    for (let i = 0; i < overflow; i += 1) delete merged[entries[i]![0]];
+  }
+  return merged;
+}
+
+function entryUpdatedAt(value: unknown): number {
+  if (isRecord(value) && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt)) return value.updatedAt;
+  return 0;
+}

package/src/services/restart-instructions.ts

@@ -0,0 +1,36 @@
+import { isSpawnProvider } from "agent-relay-sdk";
+import { getAgentProfile } from "../config-store";
+import { readSpawnCallerSystemPromptAppend, resolveAgentOwnership, withResolvedProvisioning } from "../db";
+import { composeProfileSpawnInstructions } from "../project-instructions";
+import { applyDefaultSharedMcp } from "../shared-mcp";
+import type { AgentCard } from "../types";
+
+function metaString(meta: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = meta?.[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+export function restartInstructionParamsForAgent(
+  agent: AgentCard,
+  opts: { spawnRequestId?: string; cwd?: string } = {},
+): Record<string, unknown> | undefined {
+  const provider = metaString(agent.meta, "provider");
+  if (!isSpawnProvider(provider)) return undefined;
+  const cwd = opts.cwd ?? metaString(agent.meta, "cwd");
+  const profileName = metaString(agent.meta, "profile");
+  const resolvedProfile = withResolvedProvisioning(profileName ? getAgentProfile(profileName)?.value : undefined, provider);
+  const agentProfile = resolvedProfile ? applyDefaultSharedMcp(resolvedProfile) : undefined;
+  const callerAppend = readSpawnCallerSystemPromptAppend(opts.spawnRequestId);
+  const composed = composeProfileSpawnInstructions({
+    ...(cwd ? { cwd } : {}),
+    operatorId: resolveAgentOwnership(agent.id).ownerUserId,
+    ...(profileName ? { profileName } : {}),
+    ...(agentProfile ? { profile: agentProfile } : {}),
+    ...(callerAppend ? { callerSystemPromptAppend: callerAppend } : {}),
+  });
+  return {
+    ...(composed.systemPromptAppend ? { systemPromptAppend: composed.systemPromptAppend } : {}),
+    ...(callerAppend ? { callerSystemPromptAppend: callerAppend } : {}),
+    ...(composed.relayInjectionEvents.length ? { relayInjectionEvents: composed.relayInjectionEvents } : {}),
+  };
+}

package/src/services/send-message.ts

@@ -24,7 +24,6 @@
 import { canonicalHumanAgentId, isHumanAgentId, isMechanicalMessageKind, isRecord, isReservedAgentId, isTurnFinalSession } from "agent-relay-sdk";
 import {
   ValidationError,
-  flushDeferredLineageReport,
   getAgent,
   getMessage,
   latestInboundMessage,
@@ -228,28 +227,18 @@ function prepareSendMessage(input: SendMessageInput, ctx: AuthContext, opts: Sen
   return { receipt, suppressedParent: suppressResultsOnlyAck(input) };
 }
 
-/**
- * #1037 — the child transitioned out of busy (idle/awaiting-input). Deliver its deferred turn-final
- * report-up (a quiet child's last turn, held back so mid-work narration never reached the spawner)
- * and fan it out over SSE. No-op when nothing was deferred. Driven off the bus turn-end edge.
- */
-export function flushIdleLineageReport(childId: string): void {
-  const promoted = flushDeferredLineageReport(childId);
-  if (promoted?.created) emitNewMessages([promoted.message]);
-}
-
 /** How far back the startup sweep re-scans for held-but-lost turn-final captures (#1040). A report
- * is only ever deferred while its child is mid-turn, so any capture lost across a restart is recent;
+ * is only ever held while its work window is open, so any capture lost across a restart is recent;
  * a day is a generous ceiling that still bounds the scan. */
 const LINEAGE_STARTUP_SWEEP_WINDOW_MS = 24 * 60 * 60 * 1000;
 
 /**
- * #1040 — startup re-promotion sweep. `deferredLineageReports` is an in-memory Map, so a relay
- * restart drops every held turn-final report-up. The captures are persisted, though, so re-run
- * promotion for recent final response captures: an idle child whose report was lost gets it
- * delivered now, an already-delivered one is a no-op (idempotency key), and a still-busy child
- * re-defers (re-arming the in-memory hold so a later idle edge flushes it). Idempotent and safe to
- * run periodically.
+ * #1040/#1084 — startup re-promotion sweep. The held-turn-final group (db/messages.ts) is an
+ * in-memory Map, so a relay restart drops it. The captures are persisted, though, so re-run
+ * promotion for recent final response captures: this just REBUILDS the held group (an
+ * already-forwarded capture is a no-op via its idempotency key; a `verbose` child's capture is
+ * delivered immediately, as it always is). Delivery to the spawner still only ever happens via an
+ * explicit work-finality signal (markAgentWorkFinal) — this sweep never flushes on its own.
  */
 export function sweepDeferredLineageReportsOnStartup(now: number = Date.now()): { promoted: number; scanned: number } {
   const captures = listRecentFinalResponseCaptures(now - LINEAGE_STARTUP_SWEEP_WINDOW_MS);

package/src/services/shutdown-agent.ts

@@ -37,6 +37,7 @@ import { createCommand } from "../commands-db";
 import { emitCommandEvent } from "../command-events";
 import { listManagedOrchestratorsForAgent } from "../orchestrator-lookup";
 import { emitActivityEvent, emitAgentStatus } from "../sse";
+import { markAgentWorkFinal } from "./work-finality";
 import { stringValue } from "agent-relay-sdk";
 import type { AuthContext } from "./auth-context";
 import type { AgentCard, Command } from "../types";
@@ -211,6 +212,11 @@ export function shutdownAgent(input: ShutdownAgentInput, ctx: AuthContext): Shut
     },
   });
   emitCommandEvent(command, "command.requested");
+  // #1084 — an explicit shutdown is a platform-owned teardown signal: close the target's work
+  // window now rather than let a held final group die silently with the process. `edge-fallback`
+  // is the closest fit in the closed source enum — there is no cleaner workspace-ready/task-done
+  // signal backing an arbitrary teardown (which may target an agent with neither).
+  if (targetAgentId) markAgentWorkFinal(targetAgentId, "edge-fallback");
 
   // Lifecycle indicator — uniform across transports. The MCP path previously skipped
   // this, so an MCP-initiated shutdown left the agent with no "shutting down" signal in

package/src/services/task-entity.ts

@@ -44,6 +44,7 @@ import { emitRelayEvent } from "../events";
 import { routeNotification } from "../notification-router";
 import { isAgentExitDoneWhen, stageSatisfiesDoneWhen } from "./task-done-when";
 import { autoSubscribeTaskCoordinator, emitTaskSemanticNotification, taskTransitionForStage, taskTransitionForStatus } from "./task-semantic-events";
+import { markAgentWorkFinal } from "./work-finality";
 
 type CreateTaskEntityInput = CreateDeliverableTaskInput & {
   issueRefs?: string[];
@@ -140,6 +141,9 @@ export function setTaskEntityStatus(id: number, input: SetTaskStatusInput): Task
     });
   }
   if (isTerminalTaskStatus(detail.status)) removeSubscriptionsForTask(detail.id);
+  // #1084 — a task reaching `done` is an explicit, platform-owned completion signal for its
+  // owning agent's work window: close it, forwarding only the held final group.
+  if (before?.status !== "done" && detail.status === "done") markAgentWorkFinal(detail.ownerAgentId, "task-done");
   return detail;
 }