agent-relay-server 0.123.2 → 0.125.0

package/src/db/provisioning-registry.ts

@@ -10,7 +10,12 @@ import { errMessage, isRecord, SPAWN_PROVIDERS } from "agent-relay-sdk";
 import type {
   AgentProfileProvider,
   HookAssetDefinition,
+  McpApplicability,
   McpAssetDefinition,
+  McpEnvValue,
+  McpHealthProbe,
+  McpRunConfig,
+  McpSetupRecipe,
   PluginAssetDefinition,
   ProvisioningCapability,
   ProvisioningAsset,
@@ -41,6 +46,158 @@ const BUNDLED_SOURCE_TYPE = "bundled";
 // (src/db/provisioning-callmux.ts) when splitting literals from placeholders.
 export const SHARED_CALLMUX_CONFIG_ENV_ALLOWLIST: Readonly<Record<string, readonly string[]>> = { vent: ["VENT_REPO"] };
 
+// #1030 slice 1 (#1110) — MCP setup recipe / run config validation.
+const MCP_SETUP_KINDS = ["npm-global", "download", "bundled"] as const;
+const MCP_TRANSPORTS = ["stdio", "ws", "http"] as const;
+const MCP_HEALTH_PROBE_KINDS = ["tcp", "http", "none"] as const;
+const MCP_LISTENER_MODES = ["shared", "per-agent"] as const;
+// Exact pin only — no ranges ("^1.2.3"), tags ("latest", "next"), or partial versions
+// ("1.2"). The same recipe must reproduce byte-for-byte on every host.
+const EXACT_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const SHA256_HEX = /^[a-f0-9]{64}$/i;
+// callmux's own secret-ref grammar (`env:NAME`, `file:/path`), plus `secret:<name>` for
+// the relay-owned secret store a follow-on issue (#1111) resolves. A ref is stored and
+// validated for shape only in this slice — no resolution (env lookup / file read /
+// secret-store fetch) happens here.
+const MCP_ENV_REF_SCHEMES = ["secret", "env", "file"] as const;
+// Content-shaped credential detection for literal runConfig.env values (#1030 review
+// steer): a value that looks like a real token/key must be rejected in favor of a
+// `secret:<name>` reference — the registry never carries a resolved secret.
+const INLINE_SECRET_CONTENT_PATTERNS: RegExp[] = [
+  /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/i,
+  /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/,
+  /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/,
+  /\bsk-[A-Za-z0-9_-]{20,}\b/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /^Bearer\s+\S{16,}$/i,
+];
+
+function looksLikeInlineSecret(value: string): boolean {
+  if (INLINE_SECRET_CONTENT_PATTERNS.some((pattern) => pattern.test(value))) return true;
+  // Crude high-entropy heuristic: a long token-shaped string mixing upper/lower/digit.
+  return value.length >= 24 && /^[A-Za-z0-9_.-]+$/.test(value) && /[0-9]/.test(value) && /[A-Z]/.test(value) && /[a-z]/.test(value);
+}
+
+function assertMcpSetupRecipe(value: unknown): McpSetupRecipe {
+  if (!isRecord(value)) throw new ValidationError("mcp setup recipe must be an object");
+  const kind = value.kind;
+  if (kind === "npm-global") {
+    const pkg = value.pkg;
+    const version = value.version;
+    if (typeof pkg !== "string" || !pkg.trim()) throw new ValidationError("mcp setup npm-global requires pkg");
+    if (typeof version !== "string" || !EXACT_SEMVER.test(version)) {
+      throw new ValidationError("mcp setup npm-global requires an exact pinned version (e.g. 1.2.3), not a range or tag");
+    }
+    return { kind, pkg, version };
+  }
+  if (kind === "download") {
+    const url = value.url;
+    const sha256 = value.sha256;
+    const bin = value.bin;
+    if (typeof url !== "string" || !/^https:\/\//.test(url)) throw new ValidationError("mcp setup download requires an https url");
+    if (typeof sha256 !== "string" || !SHA256_HEX.test(sha256)) throw new ValidationError("mcp setup download requires a sha256 checksum (64 hex chars)");
+    if (typeof bin !== "string" || !bin.trim()) throw new ValidationError("mcp setup download requires bin");
+    return { kind, url, sha256: sha256.toLowerCase(), bin };
+  }
+  if (kind === "bundled") return { kind: "bundled" };
+  throw new ValidationError(`mcp setup recipe kind must be one of: ${MCP_SETUP_KINDS.join(", ")}`);
+}
+
+// Splits a leading `<scheme>:<ref>` off an env value when scheme is one of the
+// recognized MCP_ENV_REF_SCHEMES. Returns null for a bare literal (no colon, or a
+// colon-containing literal like a Windows path whose prefix isn't a known scheme).
+function parseMcpEnvRef(value: string): { scheme: (typeof MCP_ENV_REF_SCHEMES)[number]; ref: string } | null {
+  const colon = value.indexOf(":");
+  if (colon <= 0) return null;
+  const scheme = value.slice(0, colon);
+  if (!(MCP_ENV_REF_SCHEMES as readonly string[]).includes(scheme)) return null;
+  return { scheme: scheme as (typeof MCP_ENV_REF_SCHEMES)[number], ref: value.slice(colon + 1) };
+}
+
+function assertMcpRunConfigEnvValue(key: string, value: unknown): McpEnvValue {
+  if (!ENV_NAME.test(key)) throw new ValidationError(`mcp runConfig env key ${key} is not a valid env name`);
+  if (typeof value !== "string") throw new ValidationError(`mcp runConfig env ${key} must be a string (a literal, or a "secret:"/"env:"/"file:" reference)`);
+  const parsed = parseMcpEnvRef(value);
+  if (parsed) {
+    if (!parsed.ref.trim()) throw new ValidationError(`mcp runConfig env ${key} ${parsed.scheme}: reference must include a name/path`);
+    return value;
+  }
+  if (looksLikeInlineSecret(value) || (isSecretLikeEnvName(key) && !isEnvPlaceholder(value))) {
+    throw new ValidationError(`mcp runConfig env ${key} looks like an inline secret; use "secret:<name>" instead of a literal value`);
+  }
+  return value;
+}
+
+function assertMcpHealthProbe(value: unknown): McpHealthProbe {
+  if (!isRecord(value)) throw new ValidationError("mcp runConfig healthProbe must be an object");
+  const kind = value.kind;
+  if (kind !== "tcp" && kind !== "http" && kind !== "none") {
+    throw new ValidationError(`mcp runConfig healthProbe.kind must be one of: ${MCP_HEALTH_PROBE_KINDS.join(", ")}`);
+  }
+  const probe: McpHealthProbe = { kind };
+  if (value.path !== undefined) {
+    if (typeof value.path !== "string" || !value.path) throw new ValidationError("mcp runConfig healthProbe.path must be a non-empty string");
+    probe.path = value.path;
+  }
+  if (value.intervalMs !== undefined) {
+    if (typeof value.intervalMs !== "number" || !(value.intervalMs > 0)) throw new ValidationError("mcp runConfig healthProbe.intervalMs must be a positive number");
+    probe.intervalMs = value.intervalMs;
+  }
+  if (value.timeoutMs !== undefined) {
+    if (typeof value.timeoutMs !== "number" || !(value.timeoutMs > 0)) throw new ValidationError("mcp runConfig healthProbe.timeoutMs must be a positive number");
+    probe.timeoutMs = value.timeoutMs;
+  }
+  return probe;
+}
+
+function assertMcpRunConfig(value: unknown): McpRunConfig {
+  if (!isRecord(value)) throw new ValidationError("mcp runConfig must be an object");
+  const command = value.command;
+  if (typeof command !== "string" || !command.trim()) throw new ValidationError("mcp runConfig requires command");
+  const runConfig: McpRunConfig = { command, transport: "stdio", listenerMode: "shared" };
+  if (value.args !== undefined) {
+    if (!Array.isArray(value.args) || !value.args.every((arg) => typeof arg === "string")) throw new ValidationError("mcp runConfig args must be strings");
+    runConfig.args = value.args;
+  }
+  if (value.env !== undefined) {
+    if (!isRecord(value.env)) throw new ValidationError("mcp runConfig env must be an object");
+    const env: Record<string, McpEnvValue> = {};
+    for (const [key, raw] of Object.entries(value.env)) env[key] = assertMcpRunConfigEnvValue(key, raw);
+    runConfig.env = env;
+  }
+  const transport = value.transport;
+  if (transport !== "stdio" && transport !== "ws" && transport !== "http") {
+    throw new ValidationError(`mcp runConfig transport must be one of: ${MCP_TRANSPORTS.join(", ")}`);
+  }
+  runConfig.transport = transport;
+  if (value.healthProbe !== undefined) runConfig.healthProbe = assertMcpHealthProbe(value.healthProbe);
+  const listenerMode = value.listenerMode;
+  if (listenerMode !== "shared" && listenerMode !== "per-agent") {
+    throw new ValidationError(`mcp runConfig listenerMode must be one of: ${MCP_LISTENER_MODES.join(", ")}`);
+  }
+  runConfig.listenerMode = listenerMode;
+  return runConfig;
+}
+
+function assertMcpApplicability(value: unknown): McpApplicability {
+  if (!isRecord(value)) throw new ValidationError("mcp applicability must be an object");
+  const applicability: McpApplicability = {};
+  if (value.providers !== undefined) {
+    if (!Array.isArray(value.providers) || !value.providers.every((p) => typeof p === "string")) {
+      throw new ValidationError("mcp applicability.providers must be an array of strings");
+    }
+    for (const provider of value.providers) assertProvider(provider as AgentProfileProvider);
+    applicability.providers = value.providers as AgentProfileProvider[];
+  }
+  if (value.profiles !== undefined) {
+    if (!Array.isArray(value.profiles) || !value.profiles.every((p) => typeof p === "string" && p.trim())) {
+      throw new ValidationError("mcp applicability.profiles must be an array of non-empty strings");
+    }
+    applicability.profiles = value.profiles as string[];
+  }
+  return applicability;
+}
+
 interface ProvisioningAssetRow {
   id: string;
   capability_id?: string | null;
@@ -179,6 +336,9 @@ export interface PatchProvisioningAssetVariantInput {
 
 export interface CreateMcpProvisioningVariantInput {
   server: unknown;
+  setup?: unknown;
+  runConfig?: unknown;
+  applicability?: unknown;
   enabled?: boolean;
   approvalStatus?: "approved" | "pending";
   versionConstraint?: string;
@@ -213,6 +373,9 @@ function assertDefinition(kind: ProvisioningAssetKind, definition: ResolvedAsset
     assertMcpSecretPlaceholders(def.server, def.name);
     const metadata = isRecord(def.metadata) ? def.metadata : {};
     if (isRecord(metadata.callmuxServer)) assertCallmuxServerPlaceholders(metadata.callmuxServer as ProvisioningMcpServer, def.name);
+    if (def.setup !== undefined) assertMcpSetupRecipe(def.setup);
+    if (def.runConfig !== undefined) assertMcpRunConfig(def.runConfig);
+    if (def.applicability !== undefined) assertMcpApplicability(def.applicability);
   }
   if (kind === "hook") {
     const def = definition as HookAssetDefinition;
@@ -873,11 +1036,21 @@ export function createMcpProvisioningVariant(
   const capability = getProvisioningCapabilityRowById(capabilityId);
   if (capability.kind !== "mcp") throw new ValidationError("MCP variants require an mcp capability");
   const server = coerceMcpServer(input.server);
+  const setup = input.setup !== undefined ? assertMcpSetupRecipe(input.setup) : undefined;
+  const runConfig = input.runConfig !== undefined ? assertMcpRunConfig(input.runConfig) : undefined;
+  const applicability = input.applicability !== undefined ? assertMcpApplicability(input.applicability) : undefined;
   const asset = upsertProvisioningAsset({
     kind: "mcp",
     name: capability.slug,
     provider: "any",
-    definition: { kind: "mcp", name: capability.slug, server },
+    definition: {
+      kind: "mcp",
+      name: capability.slug,
+      server,
+      ...(setup ? { setup } : {}),
+      ...(runConfig ? { runConfig } : {}),
+      ...(applicability ? { applicability } : {}),
+    },
     enabled: input.enabled,
   });
   const approvalStatus = input.approvalStatus ?? "approved";

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;

package/src/routes/provisioning-registry.ts

@@ -134,6 +134,9 @@ export const postProvisioningVariantMcpRoute: Handler = async (req, params) => {
     const body = expectObject(parsed.body);
     const variant = createMcpProvisioningVariant(params.id!, {
       server: body.server ?? body,
+      setup: body.setup,
+      runConfig: body.runConfig,
+      applicability: body.applicability,
       enabled: typeof body.enabled === "boolean" ? body.enabled : undefined,
       approvalStatus: optionalEnum(body.approvalStatus, "approvalStatus", APPROVAL_STATUSES, "approved"),
       versionConstraint: cleanString(body.versionConstraint, "versionConstraint", { max: 120 }),

package/src/routing-policy-store.ts

@@ -25,6 +25,8 @@ import type {
   DispatchRule,
   ProviderQuotaRoutingConfig,
   QuotaBandThresholds,
+  QuotaPaceBandThresholds,
+  QuotaPacingConfig,
   RoutingPolicy,
   RoutingRule,
 } from "agent-relay-sdk";
@@ -107,6 +109,7 @@ export function normalizeRoutingPolicy(value: unknown): RoutingPolicy {
     rules: normalizeRules(input.rules),
     ...(input.quotaBands !== undefined ? { quotaBands: normalizeQuotaBands(input.quotaBands) } : {}),
     ...(input.providerQuota !== undefined ? { providerQuota: normalizeProviderQuota(input.providerQuota) } : {}),
+    ...(input.quotaPacing !== undefined ? { quotaPacing: normalizeQuotaPacing(input.quotaPacing) } : {}),
     ...(input.dispatch !== undefined ? { dispatch: normalizeDispatchPolicy(input.dispatch) } : {}),
   };
 }
@@ -264,6 +267,58 @@ function normalizeQuotaBands(raw: unknown): Partial<QuotaBandThresholds> {
   return result;
 }
 
+// #1098/#1105 — the budget-pacing controller's tunables. Same shape as normalizeQuotaBands: every
+// field optional, so a partial PUT only overrides what it names and everything else keeps falling
+// back to the provider-quota.ts defaults.
+function normalizeQuotaPacing(raw: unknown): QuotaPacingConfig {
+  if (!isRecord(raw)) throw new ValidationError("quotaPacing must be an object");
+  const result: QuotaPacingConfig = {};
+  if (raw.delta !== undefined) {
+    if (typeof raw.delta !== "number" || !Number.isFinite(raw.delta) || raw.delta <= 0) {
+      throw new ValidationError("quotaPacing.delta must be a positive finite number");
+    }
+    result.delta = raw.delta;
+  }
+  if (raw.thresholds !== undefined) result.thresholds = normalizeQuotaPaceThresholds(raw.thresholds);
+  if (raw.windowLengthMs !== undefined) result.windowLengthMs = normalizeQuotaPaceWindowLengths(raw.windowLengthMs);
+  return result;
+}
+
+function normalizeQuotaPaceThresholds(raw: unknown): Partial<QuotaPaceBandThresholds> {
+  if (!isRecord(raw)) throw new ValidationError("quotaPacing.thresholds must be an object");
+  const result: Partial<QuotaPaceBandThresholds> = {};
+  if (raw.preferAt !== undefined) result.preferAt = cleanFraction(raw.preferAt, "quotaPacing.thresholds.preferAt");
+  if (raw.normalAt !== undefined) result.normalAt = cleanFraction(raw.normalAt, "quotaPacing.thresholds.normalAt");
+  if (raw.cautionAt !== undefined) result.cautionAt = cleanFraction(raw.cautionAt, "quotaPacing.thresholds.cautionAt");
+  // Descending: preferAt > normalAt > cautionAt (weight 1 = best/promote, 0 = worst/avoid).
+  const orderedPairs: Array<[string, number]> = [];
+  if (result.preferAt !== undefined) orderedPairs.push(["preferAt", result.preferAt]);
+  if (result.normalAt !== undefined) orderedPairs.push(["normalAt", result.normalAt]);
+  if (result.cautionAt !== undefined) orderedPairs.push(["cautionAt", result.cautionAt]);
+  for (let i = 0; i < orderedPairs.length - 1; i++) {
+    const cur = orderedPairs[i]!;
+    const next = orderedPairs[i + 1]!;
+    if (cur[1] <= next[1]) {
+      throw new ValidationError(`quotaPacing.thresholds.${cur[0]} must be greater than quotaPacing.thresholds.${next[0]}`);
+    }
+  }
+  return result;
+}
+
+function normalizeQuotaPaceWindowLengths(raw: unknown): Partial<Record<"5h" | "7d", number>> {
+  if (!isRecord(raw)) throw new ValidationError("quotaPacing.windowLengthMs must be an object");
+  const result: Partial<Record<"5h" | "7d", number>> = {};
+  for (const role of ["5h", "7d"] as const) {
+    const value = raw[role];
+    if (value === undefined) continue;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+      throw new ValidationError(`quotaPacing.windowLengthMs.${role} must be a positive finite number`);
+    }
+    result[role] = value;
+  }
+  return result;
+}
+
 function normalizeProviderQuota(raw: unknown): Partial<Record<string, ProviderQuotaRoutingConfig>> {
   if (!isRecord(raw)) throw new ValidationError("providerQuota must be an object");
   const result: Partial<Record<string, ProviderQuotaRoutingConfig>> = {};

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

package/src/services/transient-agent-reaper.ts

@@ -8,6 +8,7 @@ import { relayToken } from "../config";
 import { workspaceOwnerOrchestrator } from "../workspace-host";
 import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
 import { finalizeEphemeralTasksOnReap } from "./task-entity";
+import { markAgentWorkFinal } from "./work-finality";
 import type { AgentCard, Command, WorkspaceGitState, WorkspaceRecord } from "../types";
 
 // The single home for "dispose a transient/one-shot agent" — the canonical `agent.shutdown`
@@ -38,6 +39,10 @@ export function requestTransientAgentShutdown(agent: AgentCard, opts: TransientS
   });
   emitRelayEvent({ type: "command.requested", source: command.source, subject: command.id, data: { command } });
   emitRelayEvent({ type: "agent.exited", source: "server", subject: agent.id, data: { agentId: agent.id, parent: agent.spawnedBy, reason: opts.reason, workspaceId: opts.workspaceId, workspaceStatus: opts.workspaceStatus } });
+  // #1084 — reaping a transient agent always follows a verified-complete land/idle-grace check
+  // (the caller only reaches here once `land.complete`/gates-passed holds), so it is a genuine
+  // teardown completion signal: close its work window, forwarding only the held final group.
+  markAgentWorkFinal(agent.id, "edge-fallback");
   // #645 — persist a clean terminal marker so the #634 heartbeat-gap watchdog reads this benign
   // completion as a terminus (not a silent death) once the reaped worker stops heartbeating.
   recordTerminalEvent({ agentId: agent.id, reason: opts.reason, kind: "agent.exited", epoch: agent.epoch, createdAt: now });
@@ -67,6 +72,20 @@ export function resetTransientTrackerForTests(): void {
   transientTracker.clear();
 }
 
+// #1084 HIGH crash-final-loss fix-forward — a persistent (or autonomous) worker never enters the
+// transient reap path above (it keeps running; land-and-continue). Its held work-final ring would
+// otherwise only ever flush on an eventual explicit teardown (shutdownAgent) — hours away, or never,
+// for a long-lived agent that simply idles after reporting in. This mirrors the SAME idle-grace
+// mechanics as the transient tracker (aligned on `transientGraceMs`, not trigger-happy: a coordinator
+// steer resets the clock the moment the agent goes busy again, exactly like `transientTracker`), but
+// only ever calls `markAgentWorkFinal` — it never shuts the agent down.
+const persistentIdleFinalityMs = () => envMsOrDefault("AGENT_RELAY_PERSISTENT_IDLE_FINALITY_MS", 2 * 60 * 1000);
+const persistentIdleTracker = new Map<string, { firstIdleAt: number; lastFlushedAt?: number }>();
+
+export function resetPersistentIdleTrackerForTests(): void {
+  persistentIdleTracker.clear();
+}
+
 // How many commits the agent's branch has ahead of its base. Returns null when
 // the check can't run (missing fields, host/probe failure) — callers treat null as
 // "unknown" and preserve the safe #614 hold-pending bias: only 0 is fast-reaped.
@@ -234,9 +253,28 @@ export async function reapTransientAgents(): Promise<Record<string, unknown>> {
   const now = Date.now();
   const grace = transientGraceMs();
   const maxLandWait = transientMaxLandWaitMs();
+  const persistentGrace = persistentIdleFinalityMs();
   const seen = new Set<string>();
+  const seenPersistent = new Set<string>();
+  const persistentFinalsFlushed: string[] = [];
   const reaped: string[] = [], held: string[] = [], waiting: string[] = [];
   for (const agent of listAgents()) {
+    if (agent.lifecycle === "persistent") {
+      // No parent means no held ring can ever be flushed to anyone (flushWorkFinalReports
+      // requires a spawner) — skip tracking it at all rather than churn the map every scan.
+      if (!agent.spawnedBy) continue;
+      seenPersistent.add(agent.id);
+      if (reapProtected(agent)) { persistentIdleTracker.delete(agent.id); continue; }
+      if (completedProviderTurns(agent) === 0) { persistentIdleTracker.delete(agent.id); continue; }
+      const persistentEntry = persistentIdleTracker.get(agent.id) ?? { firstIdleAt: now };
+      persistentIdleTracker.set(agent.id, persistentEntry);
+      const persistentIdleForMs = now - persistentEntry.firstIdleAt;
+      if (persistentIdleForMs < persistentGrace || persistentEntry.lastFlushedAt) continue;
+      persistentEntry.lastFlushedAt = now;
+      markAgentWorkFinal(agent.id, "edge-fallback");
+      persistentFinalsFlushed.push(agent.id);
+      continue;
+    }
     if (agent.lifecycle !== "transient") continue;
     seen.add(agent.id);
     // A held agent (rate-limit hold #286, or any provider-blocked state) reads as
@@ -282,5 +320,6 @@ export async function reapTransientAgents(): Promise<Record<string, unknown>> {
     reaped.push(agent.id);
   }
   for (const key of transientTracker.keys()) if (!seen.has(key)) transientTracker.delete(key);
-  return { scanned: seen.size, waiting, held, reaped, tracked: transientTracker.size };
+  for (const key of persistentIdleTracker.keys()) if (!seenPersistent.has(key)) persistentIdleTracker.delete(key);
+  return { scanned: seen.size, waiting, held, reaped, tracked: transientTracker.size, persistentFinalsFlushed };
 }

package/src/services/work-finality.ts

@@ -0,0 +1,25 @@
+// #1084 (Part D of #1079) — the work-window finality service. A "work-final" is a RELAY-LEVEL
+// mark anchored to explicit completion signals the platform already owns: `relay_workspace_ready`
+// (src/mcp/tools-workspace.ts), a task's execution status reaching `done` (src/services/task-entity.ts),
+// and agent teardown/reap (src/services/shutdown-agent.ts). It is deliberately NOT anchored to a
+// per-turn busy→idle bus edge — that heuristic is exactly what produced the false-final flood this
+// issue supersedes (#1078/#1058/#1032/#976): a child idling briefly between two subtasks is
+// indistinguishable, on the wire, from a child that just finished.
+//
+// markAgentWorkFinal is the single entry point every anchor calls. It closes the child's held
+// turn-final group (db/messages.ts flushWorkFinalReports) as ONE work-final unit and fans the
+// result out over SSE: newly-forwarded chat reports as `message.new` (the coordinator's inbox), and
+// the original already-rendered session captures as `message.finalized` (so a bubble the dashboard
+// showed as ordinary mid-turn narration can be retroactively upgraded once its window closes).
+import type { MessageWorkFinalitySource } from "agent-relay-sdk";
+import { flushWorkFinalReports, type WorkFinalFlushResult } from "../db/messages.ts";
+import { emitMessageFinalized, emitNewMessages } from "../sse.ts";
+
+export function markAgentWorkFinal(agentId: string | undefined | null, source: MessageWorkFinalitySource): WorkFinalFlushResult {
+  if (!agentId) return { forwarded: [], finalizedOriginals: [] };
+  const result = flushWorkFinalReports(agentId, source);
+  const created = result.forwarded.filter((entry) => entry.created).map((entry) => entry.message);
+  if (created.length > 0) emitNewMessages(created);
+  for (const original of result.finalizedOriginals) emitMessageFinalized(original);
+  return result;
+}