agent-relay-server 0.120.6 → 0.121.1

package/src/config.ts

@@ -64,6 +64,10 @@ export const STUCK_BUSY_PROVIDER_TURN_MS = envPositiveInt("AGENT_RELAY_STUCK_BUS
 export const STUCK_BUSY_STARTUP_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_STARTUP_MS", STUCK_BUSY_THRESHOLD_MS);
 export const STUCK_BUSY_RECONNECT_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_RECONNECT_MS", STUCK_BUSY_THRESHOLD_MS);
 export const STUCK_BUSY_SHUTDOWN_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_SHUTDOWN_MS", STUCK_BUSY_THRESHOLD_MS);
+export const EVENT_LOOP_LAG_SAMPLE_MS = envPositiveInt("AGENT_RELAY_EVENT_LOOP_LAG_SAMPLE_MS", 1_000);
+export const EVENT_LOOP_LAG_WINDOW_SAMPLES = envPositiveInt("AGENT_RELAY_EVENT_LOOP_LAG_WINDOW_SAMPLES", 60);
+export const EVENT_LOOP_LAG_WARN_MS = envNonNegativeNumber("AGENT_RELAY_EVENT_LOOP_LAG_WARN_MS", 250);
+export const EVENT_LOOP_LAG_LOG_MS = envNonNegativeNumber("AGENT_RELAY_EVENT_LOOP_LAG_LOG_MS", EVENT_LOOP_LAG_WARN_MS);
 // #713 — provider-token silence ALONE is not a wedge signal for Claude (long turns, extended
 // thinking, and native compaction all go token-silent while healthy). Before declaring stuck we
 // ALSO require the transport heartbeat to be genuinely dead: no server frame / heartbeat-ack within
@@ -112,6 +116,56 @@ export function relayAuthHeaders(base: Record<string, string> = {}): Record<stri
   return token ? { ...base, [RELAY_TOKEN_HEADER]: token } : base;
 }
 
+// #1024 — origins the orchestrator proxy may forward the relay MASTER token (relayToken()) to.
+// A dynamically-registered orchestrator can carry an attacker-controlled apiUrl; forwarding the
+// master token there leaks full relay admin. This is the defense-in-depth backstop behind the
+// registration lock: even if some path seeds an orchestrator row, the proxy refuses to talk to an
+// untrusted apiUrl at all (never sending the token OR the caller's query string). Explicit
+// operator overrides — comma-separated origins, e.g. "https://orch.example.com".
+export const TRUSTED_ORCHESTRATOR_ORIGINS = (process.env.AGENT_RELAY_TRUSTED_ORCHESTRATOR_ORIGINS || "")
+  .split(",")
+  .map((origin) => origin.trim())
+  .filter(Boolean);
+
+// A private/LAN/tailnet IP literal — never a public, attacker-reachable address.
+function isPrivateIpLiteral(host: string): boolean {
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (v4) {
+    const a = Number(v4[1]), b = Number(v4[2]);
+    if (a === 10 || a === 127) return true;              // 10.0.0.0/8, loopback
+    if (a === 172 && b >= 16 && b <= 31) return true;    // 172.16.0.0/12
+    if (a === 192 && b === 168) return true;             // 192.168.0.0/16
+    if (a === 169 && b === 254) return true;             // 169.254.0.0/16 link-local
+    if (a === 100 && b >= 64 && b <= 127) return true;   // 100.64.0.0/10 CGNAT (tailnet)
+    return false;
+  }
+  if (/^f[cd][0-9a-f]*:/.test(host)) return true;         // IPv6 ULA fc00::/7
+  if (/^fe[89ab][0-9a-f]*:/.test(host)) return true;      // IPv6 link-local fe80::/10
+  return false;
+}
+
+// Whether the relay master token may be forwarded to this orchestrator apiUrl (#1024). Trusts
+// loopback, bare single-label hostnames (LAN/MagicDNS — never a public FQDN), private DNS
+// suffixes, private/CGNAT/ULA IP literals, and any explicit AGENT_RELAY_TRUSTED_ORCHESTRATOR_ORIGINS
+// entry. A public IP or public FQDN (e.g. http://attacker.example) is refused unless allowlisted.
+export function isTrustedOrchestratorApiUrl(apiUrl: string | undefined): boolean {
+  if (!apiUrl) return false;
+  let url: URL;
+  try {
+    url = new URL(apiUrl);
+  } catch {
+    return false;
+  }
+  if (TRUSTED_ORCHESTRATOR_ORIGINS.includes(url.origin)) return true;
+  let host = url.hostname.toLowerCase();
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1); // unwrap IPv6 literal
+  if (host === "localhost" || host === "127.0.0.1" || host === "::1") return true;
+  // A bare single-label host (no dot, not an IPv6 literal) is a LAN/MagicDNS name, never public.
+  if (!host.includes(".") && !host.includes(":")) return true;
+  if (/\.(local|internal|lan|home|ts\.net|tailnet)$/.test(host)) return true;
+  return isPrivateIpLiteral(host);
+}
+
 export function allowUnauthenticated(): boolean {
   return process.env.AGENT_RELAY_ALLOW_UNAUTH === "1";
 }

package/src/db/claim-sql.ts

@@ -26,3 +26,19 @@ type MessageIdRef = "m.id" | "messages.id";
 export function messageTaskClosed(messageRef: MessageIdRef): string {
   return `EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = ${messageRef} AND t.status IN (${CLOSED_TASK_STATUS_SQL}))`;
 }
+
+/**
+ * SQL predicate: a claimable message that has NO linked task has already been handled by its claim
+ * holder. A claimable with a linked task settles via `messageTaskClosed`; one WITHOUT a task had no
+ * completion state at all — after the 30-min lease expired `releaseExpiredClaims` nulled the claim
+ * and the poll re-offered the finished work to every matching agent, forever (#1022 F6). The runner
+ * only marks a claimable read AFTER winning the claim (losers `continue` without reading), so a
+ * read receipt from any non-sender uniquely means "the holder took and processed it" — the missing
+ * settle signal. Gate the expired/unclaimed poll branch with `AND NOT ${claimableHandledNoTask(...)}`.
+ * `messageRef` is a fixed internal column reference, not user input.
+ */
+export function claimableHandledNoTask(messageRef: MessageIdRef): string {
+  const fromAgentRef = messageRef === "m.id" ? "m.from_agent" : "messages.from_agent";
+  return `(NOT EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = ${messageRef}) ` +
+    `AND EXISTS (SELECT 1 FROM message_reads mr WHERE mr.message_id = ${messageRef} AND mr.agent_id <> ${fromAgentRef}))`;
+}

package/src/db/connection.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { DB_SLOW_QUERY_MS } from "../config";
 
@@ -79,7 +80,8 @@ export async function runDbMaintenanceWorker<T>(operation: string, args: string[
     throw new Error("database worker requires a file-backed database");
   }
   if (signal?.aborted) throw new Error("database worker aborted");
-  const proc = Bun.spawn([process.execPath, join(import.meta.dir, "maintenance-worker.ts"), operation, dbPath, ...args], {
+  const bunPath = existsSync(process.execPath) ? process.execPath : (Bun.which("bun") ?? process.execPath);
+  const proc = Bun.spawn([bunPath, join(import.meta.dir, "maintenance-worker.ts"), operation, dbPath, ...args], {
     stdin: "ignore",
     stdout: "pipe",
     stderr: "pipe",

package/src/db/continuations.ts

@@ -55,6 +55,16 @@ export function seedContinuationObjectiveFromSpawnPrompt(agentId: string, spawnR
   return ensureContinuationEnvelope({ agentId, objective: params.prompt, config, now });
 }
 
+// #1023 — the ruledOut ledger was append-only with no cap: cumulative resends
+// duplicated entries verbatim, and nothing bounded total size, so one long-running
+// agent could render a multi-megabyte continuation straight into its own fresh
+// context. MAX_LEDGER_TOTAL_BYTES/MAX_LEDGER_ENTRIES bound what stays in the
+// envelope; dedupe drops literal resends. Entries pushed out by the bound are
+// returned as droppedLedgerEntries so the caller can archive them (still
+// recallable via relay_recall) instead of silently destroying them.
+const MAX_LEDGER_TOTAL_BYTES = 256 * 1024;
+const MAX_LEDGER_ENTRIES = 500;
+
 export function updateContinuationAfterCompact(input: {
   agentId: string;
   generation: number;
@@ -63,7 +73,7 @@ export function updateContinuationAfterCompact(input: {
   archiveRefs?: string[];
   spentTokens: number;
   now?: number;
-}): ContinuationEnvelope {
+}): { envelope: ContinuationEnvelope; droppedLedgerEntries: ContinuationLedgerEntry[] } {
   const existing = getContinuationEnvelope(input.agentId);
   if (!existing) throw new ValidationError("continuation envelope not found");
   const now = input.now ?? Date.now();
@@ -76,20 +86,51 @@ export function updateContinuationAfterCompact(input: {
       tokens: existing.budget.spent.tokens + Math.max(0, input.spentTokens),
     },
   };
+  const { ledger, dropped } = mergeLedger(existing.ledger, input.ledgerEntries);
   getDb().query(`
     UPDATE agent_continuations
     SET generation = ?, ledger = ?, working_state = ?, archive_refs = ?, budget = ?, updated_at = ?
     WHERE agent_id = ?
   `).run(
     input.generation,
-    JSON.stringify([...existing.ledger, ...input.ledgerEntries]),
+    JSON.stringify(ledger),
     input.workingState,
     JSON.stringify([...existing.archiveRefs, ...(input.archiveRefs ?? [])]),
     JSON.stringify(nextBudget),
     now,
     input.agentId,
   );
-  return getContinuationEnvelope(input.agentId)!;
+  return { envelope: getContinuationEnvelope(input.agentId)!, droppedLedgerEntries: dropped };
+}
+
+function ledgerEntryKey(entry: ContinuationLedgerEntry): string {
+  return `${entry.ruledOut.trim().toLowerCase()} ${entry.why.trim().toLowerCase()}`;
+}
+
+function ledgerEntryBytes(entry: ContinuationLedgerEntry): number {
+  return new TextEncoder().encode(entry.ruledOut).byteLength + new TextEncoder().encode(entry.why).byteLength + 48;
+}
+
+function mergeLedger(
+  existing: ContinuationLedgerEntry[],
+  incoming: ContinuationLedgerEntry[],
+): { ledger: ContinuationLedgerEntry[]; dropped: ContinuationLedgerEntry[] } {
+  const seen = new Set(existing.map(ledgerEntryKey));
+  const merged = [...existing];
+  for (const entry of incoming) {
+    const key = ledgerEntryKey(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(entry);
+  }
+  let start = merged.length > MAX_LEDGER_ENTRIES ? merged.length - MAX_LEDGER_ENTRIES : 0;
+  let totalBytes = 0;
+  for (let i = merged.length - 1; i >= start; i -= 1) totalBytes += ledgerEntryBytes(merged[i]!);
+  while (totalBytes > MAX_LEDGER_TOTAL_BYTES && start < merged.length - 1) {
+    totalBytes -= ledgerEntryBytes(merged[start]!);
+    start += 1;
+  }
+  return { ledger: merged.slice(start), dropped: merged.slice(0, start) };
 }
 
 export function appendContinuationArchiveRefs(agentId: string, archiveRefs: string[]): ContinuationEnvelope | null {

package/src/db/index.ts

@@ -33,6 +33,7 @@ export * from "./continuations.ts";
 export * from "./continuation-archives.ts";
 export * from "./crash-reports.ts";
 export * from "./terminal-events.ts";
+export * from "./retention.ts";
 export * from "./plans.ts";
 export * from "./teams.ts";
 export * from "./blackboard.ts";

package/src/db/maintenance-worker.ts

@@ -29,6 +29,97 @@ try {
       return db.query("DELETE FROM messages WHERE created_at < ?").run(cutoff).changes;
     })();
     console.log(JSON.stringify({ prunedMessages }));
+  } else if (operation === "retention-prune") {
+    if (!arg) throw new Error("retention-prune requires options JSON");
+    const opts = JSON.parse(arg) as {
+      messageCutoff: number;
+      activityCutoff: number;
+      activityMaxRows: number;
+      spawnCommandCutoff: number;
+      batchSize: number;
+    };
+    const batchSize = Math.min(Math.max(Math.trunc(opts.batchSize), 1), 50_000);
+    const result = db.transaction(() => {
+      db.query(`
+        UPDATE messages
+        SET reply_to = NULL
+        WHERE reply_to IN (
+          SELECT id FROM messages
+          WHERE created_at < ?
+          ORDER BY created_at ASC, id ASC
+          LIMIT ?
+        )
+      `).run(opts.messageCutoff, batchSize);
+      const prunedMessages = db.query(`
+        DELETE FROM messages
+        WHERE id IN (
+          SELECT id FROM messages
+          WHERE created_at < ?
+          ORDER BY created_at ASC, id ASC
+          LIMIT ?
+        )
+      `).run(opts.messageCutoff, batchSize).changes;
+      const prunedActivityEvents = db.query(`
+        DELETE FROM activity_events
+        WHERE id IN (
+          SELECT ae.id
+          FROM activity_events ae
+          WHERE (
+              ae.created_at < ?
+              OR ae.id NOT IN (
+                SELECT id
+                FROM activity_events
+                ORDER BY created_at DESC, id DESC
+                LIMIT ?
+              )
+            )
+            AND NOT (
+              ae.kind = 'state'
+              AND ae.title = 'Agent registered'
+              AND EXISTS (
+                SELECT 1
+                FROM commands c
+                WHERE c.type = 'agent.spawn'
+                  AND c.status = 'succeeded'
+                  AND coalesce(json_extract(c.params, '$.registrationConfirmed'), 0) != 1
+                  AND (
+                    c.correlation_id = json_extract(ae.metadata, '$.spawnRequestId')
+                    OR json_extract(c.params, '$.spawnRequestId') = json_extract(ae.metadata, '$.spawnRequestId')
+                  )
+              )
+            )
+          ORDER BY ae.created_at ASC, ae.id ASC
+          LIMIT ?
+        )
+      `).run(opts.activityCutoff, opts.activityMaxRows, batchSize).changes;
+      const prunedSpawnCommands = db.query(`
+        DELETE FROM commands
+        WHERE id IN (
+          SELECT c.id
+          FROM commands c
+          WHERE c.type = 'agent.spawn'
+            AND c.status IN ('succeeded', 'failed', 'canceled', 'timed_out')
+            AND c.updated_at < ?
+            AND NOT (
+              c.status = 'succeeded'
+              AND coalesce(json_extract(c.params, '$.registrationConfirmed'), 0) != 1
+            )
+            AND NOT EXISTS (
+              SELECT 1
+              FROM managed_agent_state mas
+              WHERE mas.spawn_request_id IS NOT NULL
+                AND (
+                  mas.spawn_request_id = c.correlation_id
+                  OR mas.spawn_request_id = json_extract(c.params, '$.spawnRequestId')
+                )
+            )
+          ORDER BY c.updated_at ASC, c.created_at ASC
+          LIMIT ?
+        )
+      `).run(opts.spawnCommandCutoff, batchSize).changes;
+      return { prunedMessages, prunedActivityEvents, prunedSpawnCommands };
+    })();
+    console.log(JSON.stringify(result));
   } else {
     throw new Error(`unknown maintenance operation: ${operation}`);
   }

package/src/db/message-reads.ts

@@ -1,6 +1,6 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
+import { isRecord, stringValue, isMechanicalMessageKind, isReportVerbosity, type ReportVerbosity } from "agent-relay-sdk";
 import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
 import { parseJson } from "../utils";
 import { isLiveIsolatedWorkspace } from "../workspace-phase";
@@ -19,7 +19,7 @@ import { sendMessageWithResult } from "./messages.ts";
 import { deleteArtifactLinksForEntity } from "./artifacts.ts";
 import { getDb, getDbPath, runDbMaintenanceWorker, timedQuery } from "./connection.ts";
 import { legacyChannelTargets, isChannelAgentId } from "./delivery.ts";
-import { messageTaskClosed } from "./claim-sql.ts";
+import { claimableHandledNoTask, messageTaskClosed } from "./claim-sql.ts";
 import { MSG_SELECT, rowToMessage } from "./mappers.ts";
 import type {
   AgentCard,
@@ -306,7 +306,11 @@ export function pollMessages(query: PollQuery): Message[] {
     targetClauses.push(freshFanoutTargetClause(`tag:${tag}`, agent, params));
   }
   for (const cap of agentCaps) {
+    // A capability fan-out is accepted at send time under both `cap:` and its `capability:` alias
+    // (planSend/FANOUT_PREFIXES + the SDK matcher). Poll for BOTH stored forms, or a message sent
+    // to `capability:X` gets a delivered receipt yet is invisible to every poll (#1022 F3).
     targetClauses.push(freshFanoutTargetClause(`cap:${cap}`, agent, params));
+    targetClauses.push(freshFanoutTargetClause(`capability:${cap}`, agent, params));
   }
   if (agentLabel) {
     targetClauses.push(freshFanoutTargetClause(`label:${agentLabel}`, agent, params));
@@ -338,7 +342,9 @@ export function pollMessages(query: PollQuery): Message[] {
   // pruned/deleted its message claims are released to NULL (see pruneOfflineAgents/deleteAgent),
   // so without it a finished task's message resurrects as fresh work on the next restart (which
   // mints a new agent id, so message_reads no longer dedups it) — the automation re-delivery bug.
-  conditions.push(`(claimable = 0 OR claimed_by = ? OR ((claimed_by IS NULL OR claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT ${messageTaskClosed("m.id")}))`);
+  // `claimableHandledNoTask` closes the same gap for claimables with NO linked task: once the
+  // holder handled one, its lease expired and it got re-offered to everyone forever (#1022 F6).
+  conditions.push(`(claimable = 0 OR claimed_by = ? OR ((claimed_by IS NULL OR claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT ${messageTaskClosed("m.id")} AND NOT ${claimableHandledNoTask("m.id")}))`);
   params.push(query.for, Date.now());
 
   if (query.sinceId !== undefined) {
@@ -594,6 +600,30 @@ export function seedSpawnPromptMirror(
   }
 }
 
+/**
+ * #1037 — the per-spawn report-up verbosity a spawner chose, read from the persisted `agent.spawn`
+ * command params by spawnRequestId. Mirrors seedSpawnPromptMirror: at first registration the relay
+ * has both the resolved child id and the spawn command, so registration stamps this onto child meta
+ * where the lineage report-up delivery gate reads it. Returns undefined when absent/unparseable
+ * (the gate then defaults to `quiet`).
+ */
+export function readSpawnReportVerbosity(spawnRequestId: string | undefined): ReportVerbosity | undefined {
+  if (!spawnRequestId) return undefined;
+  try {
+    const row = getDb().query(`
+      SELECT params FROM commands
+      WHERE type = 'agent.spawn' AND correlation_id = ?
+      ORDER BY created_at DESC
+      LIMIT 1
+    `).get(spawnRequestId) as { params: string } | undefined;
+    const params = row ? parseJson<unknown>(row.params, {}) : {};
+    if (!isRecord(params)) return undefined;
+    return isReportVerbosity(params.reportVerbosity) ? params.reportVerbosity : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function markRead(messageId: number, agentId: string): boolean {
   const exists = getDb().query("SELECT 1 FROM messages WHERE id = ?").get(messageId);
   if (!exists) return false;
@@ -607,7 +637,7 @@ export function markRead(messageId: number, agentId: string): boolean {
         delivery_next_retry_at = NULL,
         delivery_poison_reason = NULL,
         delivery_updated_at = ?
-    WHERE id = ? AND (to_target = ? OR resolved_to_agent = ? OR to_target = 'broadcast' OR to_target LIKE 'tag:%' OR to_target LIKE 'cap:%' OR to_target LIKE 'label:%' OR to_target LIKE 'team:%')
+    WHERE id = ? AND (to_target = ? OR resolved_to_agent = ? OR to_target = 'broadcast' OR to_target LIKE 'tag:%' OR to_target LIKE 'cap:%' OR to_target LIKE 'capability:%' OR to_target LIKE 'label:%' OR to_target LIKE 'team:%')
   `).run(Date.now(), messageId, agentId, agentId);
   return true;
 }

package/src/db/messages.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
+import { isRecord, stringValue, isMechanicalMessageKind, isReportVerbosity, type ReportVerbosity } from "agent-relay-sdk";
+import { LIFECYCLE_STATE_WORKING, childSignalKey, stampLifecycleSignal, taskSignalKey } from "../lifecycle-signal-registry";
 import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
 import { parseJson } from "../utils";
 import { isLiveIsolatedWorkspace } from "../workspace-phase";
@@ -13,7 +14,7 @@ import {
   type RuntimeContracts,
 } from "../contracts";
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS, DEFAULT_FANOUT_TTL_SECONDS } from "../config";
-import { matchAgents } from "../agent-ref";
+import { matchAgents, messageMatchesAgent } from "../agent-ref";
 import { isFanoutTarget } from "../channel-target";
 import { getAgent, validateAgentSession } from "./agents.ts";
 import { cleanAttachmentRefs, linkAttachmentRefs, validateAttachmentRefs } from "./artifacts.ts";
@@ -26,6 +27,7 @@ import { getMessage } from "./message-queries.ts";
 import { childStreamSubscribed, type ChildStream } from "./notification-subscriptions.ts";
 import { runningAgentForPolicy } from "./policy-runtime.ts";
 import { getTask, releaseExpiredClaims } from "./tasks.ts";
+import { deliverableTaskIdsBySpawnRequestId } from "./task-entity.ts";
 import { insertTaskEvent, claimTaskWhere, CLAIM_TASK_KIND } from "./task-core.ts";
 import type {
   AgentCard,
@@ -334,6 +336,105 @@ function findRecentExplicitLineageDuplicate(input: {
   return row ? rowToMessage(row) : null;
 }
 
+/** Per-spawn report-up verbosity (#1037), read from the child's meta; defaults to `quiet`. */
+function reportVerbosityOf(child: AgentCard): ReportVerbosity {
+  const value = child.meta?.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 — 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>();
+
+function deferLineageReport(childId: string, messageId: number): void {
+  deferredLineageReports.set(childId, messageId);
+}
+
+function clearDeferredLineageReport(childId: string): void {
+  deferredLineageReports.delete(childId);
+}
+
+/** Test seam: clear the #1037 deferred report-up hold between tests. */
+export function __resetDeferredLineageReports(): void {
+  deferredLineageReports.clear();
+}
+
+/**
+ * #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.
+ */
+export function flushDeferredLineageReport(childId: string): { message: Message; created: boolean } | null {
+  const messageId = deferredLineageReports.get(childId);
+  if (messageId === undefined) return null;
+  deferredLineageReports.delete(childId);
+  const message = getMessage(messageId);
+  if (!message) return null;
+  return promoteLineageCapturedResponse(message);
+}
+
+/**
+ * #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).
+ */
+export function listRecentFinalResponseCaptures(sinceMs: number, limit = 1000): Message[] {
+  const rows = getDb().query(`
+    ${MSG_SELECT}
+    INNER JOIN (
+      SELECT from_agent, MAX(id) AS latest_id
+      FROM messages
+      WHERE kind = 'session'
+        AND created_at >= ?
+        AND json_extract(payload, '$.session.type') = 'response'
+        AND json_extract(payload, '$.session.final') = 1
+      GROUP BY from_agent
+    ) latest ON latest.latest_id = m.id
+    ORDER BY m.id DESC
+    LIMIT ?
+  `).all(sinceMs, limit) as any[];
+  return rows
+    .map(rowToMessage)
+    .filter((message) => {
+      const session = sessionMeta(message);
+      return session ? isFinalSessionResponse(session) : false;
+    });
+}
+
+/** Deliverable task ids this child is executing, from its direct meta.taskId + spawnRequestId link. */
+function childTaskIds(child: AgentCard): number[] {
+  const ids = new Set<number>();
+  const direct = child.meta?.taskId;
+  const directNum = typeof direct === "string" ? Number(direct) : direct;
+  if (typeof directNum === "number" && Number.isSafeInteger(directNum) && directNum > 0) ids.add(directNum);
+  const spawnRequestId = stringValue(child.meta?.spawnRequestId);
+  if (spawnRequestId) for (const id of deliverableTaskIdsBySpawnRequestId(spawnRequestId)) ids.add(id);
+  return [...ids];
+}
+
+// #1032b — a delivered report-up is a first-class lifecycle signal to the spawner. Stamp it so a
+// redundant "Task status pulse" for the same child/task is suppressed rather than double-waking.
+// #1038 — a report-up conveys "the child is progressing", so it is state-keyed to `working`: it
+// supersedes only a redundant `working` pulse, never a later distinct milestone (committed/landed/done).
+function stampReportUpLifecycleSignal(parent: string, child: AgentCard): void {
+  stampLifecycleSignal(parent, childSignalKey(child.id));
+  for (const taskId of childTaskIds(child)) stampLifecycleSignal(parent, taskSignalKey(taskId, LIFECYCLE_STATE_WORKING));
+}
+
 export function promoteLineageCapturedResponse(message: Message): { message: Message; created: boolean } | null {
   if (message.kind !== "session") return null;
   const session = sessionMeta(message);
@@ -344,7 +445,17 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
   const child = getAgent(message.from);
   const parent = child?.spawnedBy;
   if (!parent) return null;
-  if (stream !== "responses" && !childStreamSubscribed({ parentId: parent, child, stream })) return null;
+  const verbosity = reportVerbosityOf(child);
+  // #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)) {
+    deferLineageReport(child.id, message.id);
+    return null;
+  }
 
   const idempotencyKey = lineageStreamReportKey(message, session, stream);
   const existing = findMessageByIdempotencyKey(message.from, idempotencyKey);
@@ -378,7 +489,7 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
     }
   }
 
-  return sendMessageWithResult({
+  const result = sendMessageWithResult({
     from: message.from,
     to: parent,
     kind: "chat",
@@ -390,6 +501,11 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
       : { childStreamCapture: { stream, ...session } },
     occurredAt: message.occurredAt ?? message.createdAt,
   });
+  if (stream === "responses" && result.created) {
+    clearDeferredLineageReport(child.id);
+    stampReportUpLifecycleSignal(parent, child);
+  }
+  return result;
 }
 
 // Event time may be queued-then-backfilled, so it can legitimately be older than the
@@ -402,7 +518,21 @@ function sanitizeOccurredAt(occurredAt: number | undefined, receivedAt: number):
   return Math.floor(occurredAt);
 }
 
-export function sendMessageWithResult(input: SendMessageInput): { message: Message; created: boolean; updated?: boolean } {
+export interface SendMessageResult {
+  message: Message;
+  created: boolean;
+  updated?: boolean;
+}
+
+export function sendMessageWithResult(input: SendMessageInput): SendMessageResult {
+  return sendMessageWithResultInternal(input, true);
+}
+
+export function sendMessagesBatchWithResult(inputs: SendMessageInput[]): SendMessageResult[] {
+  return getDb().transaction(() => inputs.map((input) => sendMessageWithResultInternal(input, false)))();
+}
+
+function sendMessageWithResultInternal(input: SendMessageInput, wrapTransaction: boolean): SendMessageResult {
   const now = Date.now();
   const payload = input.payload ?? {};
   const attachmentRefs = cleanAttachmentRefs(payload);
@@ -495,7 +625,7 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
     maxAgeSeconds = DEFAULT_FANOUT_TTL_SECONDS;
   }
 
-  const id = getDb().transaction(() => {
+  const insertMessage = () => {
     const result = insert.run({
       $from: input.from,
       $to: input.to,
@@ -528,7 +658,8 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
       else enforceQueueLimit(input.to);
     }
     return newId;
-  })();
+  };
+  const id = wrapTransaction ? getDb().transaction(insertMessage)() : insertMessage();
 
   return { message: getMessage(id)!, created: true };
 }
@@ -543,7 +674,7 @@ export function getThread(messageId: number): Message[] {
   const threadId = msg.threadId ?? msg.id;
   return (
     getDb()
-      .query(`${MSG_SELECT} WHERE m.thread_id = ? ORDER BY m.created_at ASC`)
+      .query(`${MSG_SELECT} WHERE m.thread_id = ? ORDER BY m.created_at ASC, m.id ASC`)
       .all(threadId) as any[]
   ).map(rowToMessage);
 }
@@ -606,6 +737,14 @@ export function claimMessage(messageId: number, agentId: string, guard?: AgentSe
   // A same-agent re-claim is allowed (idempotent lease refresh, see claimMessageRow); only a
   // claim held by a *different* agent blocks (#261).
   if (msg.claimedBy && msg.claimedBy !== agentId) return { ok: false, error: `already claimed by ${msg.claimedBy}` };
+  // The claimer must actually be a recipient — the same predicate that gates live delivery (bus/sse
+  // push) and poll. Without it an unrelated agent could claim a claimable addressed directly to
+  // someone else, and `pollMessages`/`messageMatchesAgent` then hid it from the rightful recipient,
+  // so the message vanished for its intended owner (#1022 F7). Checked AFTER the claimedBy guard so
+  // a genuine "already claimed" contention still reports that precise reason; a fan-out claimable
+  // (tag:/cap:/broadcast/…) still matches every eligible pool member, and the holder's own re-claim
+  // still matches (claimedBy is null or itself here, so the ownership short-circuit never fires).
+  if (!messageMatchesAgent(msg, agentId, agent)) return { ok: false, error: "message is not addressed to this agent" };
 
   try {
     return getDb().transaction(() => {

package/src/db/migrations.ts

@@ -706,6 +706,7 @@ export function applyMigrations(): void {
     getDb().run("ALTER TABLE agents ADD COLUMN team_id TEXT");
   }
   getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_team ON agents(team_id)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_spawn_request ON agents(json_extract(meta, '$.spawnRequestId'))");
   getDb().run(`
     CREATE TABLE IF NOT EXISTS notification_subscriptions (
       id TEXT PRIMARY KEY,
@@ -913,6 +914,12 @@ export function applyMigrations(): void {
   getDb().run("CREATE INDEX IF NOT EXISTS idx_agent_active_memories_agent ON agent_active_memories(agent_id)");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_label ON agents(label)");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_kind ON agents(kind)");
+  getDb().run(`
+    CREATE INDEX IF NOT EXISTS idx_activity_registered_spawn_request
+    ON activity_events(json_extract(metadata, '$.spawnRequestId'))
+    WHERE kind = 'state' AND title = 'Agent registered'
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_commands_spawn_watchdog ON commands(type, status, updated_at)");
 
   getDb().run(`
     CREATE TABLE IF NOT EXISTS integration_registry (

package/src/db/pairs.ts

@@ -205,6 +205,7 @@ export function createPair(input: CreatePairInput): {
 
   const resolved = resolvePairTarget(input.target, input.from);
   if (!resolved.ok) return resolved;
+  if (resolved.agent.id === input.from) return { ok: false, code: "invalid", error: "cannot pair with yourself" };
 
   const now = Date.now();
   const ttlMs = Math.min(Math.max(input.ttlMs ?? DEFAULT_PAIR_TTL_MS, 10_000), MAX_PAIR_TTL_MS);