agent-relay-server 0.120.6 → 0.121.0

package/src/event-loop-lag.ts

@@ -0,0 +1,90 @@
+import {
+  EVENT_LOOP_LAG_LOG_MS,
+  EVENT_LOOP_LAG_SAMPLE_MS,
+  EVENT_LOOP_LAG_WARN_MS,
+  EVENT_LOOP_LAG_WINDOW_SAMPLES,
+} from "./config";
+
+export interface EventLoopLagSnapshot {
+  currentMs: number;
+  maxMs: number;
+  maxSinceLastReadMs: number;
+  sampleCount: number;
+  windowSamples: number;
+  sampleIntervalMs: number;
+  warnThresholdMs: number;
+  lastSampleAt?: number;
+}
+
+const samples = new Array<number>(EVENT_LOOP_LAG_WINDOW_SAMPLES).fill(0);
+let sampleIndex = 0;
+let sampleCount = 0;
+let currentMs = 0;
+let maxSinceLastReadMs = 0;
+let lastSampleAt: number | undefined;
+let timer: ReturnType<typeof setInterval> | undefined;
+let lastTickAt = 0;
+
+export function computeEventLoopLagMs(elapsedMs: number, expectedMs: number): number {
+  if (!Number.isFinite(elapsedMs) || !Number.isFinite(expectedMs)) return 0;
+  return Math.max(0, elapsedMs - expectedMs);
+}
+
+export function recordEventLoopLagSample(lagMs: number, sampledAt: number = Date.now(), logSpike = false): void {
+  const normalized = Number.isFinite(lagMs) ? Math.max(0, lagMs) : 0;
+  currentMs = normalized;
+  maxSinceLastReadMs = Math.max(maxSinceLastReadMs, normalized);
+  lastSampleAt = sampledAt;
+  samples[sampleIndex] = normalized;
+  sampleIndex = (sampleIndex + 1) % samples.length;
+  sampleCount = Math.min(sampleCount + 1, samples.length);
+  if (logSpike && EVENT_LOOP_LAG_LOG_MS > 0 && normalized >= EVENT_LOOP_LAG_LOG_MS) {
+    console.warn(`[health] event-loop lag ${Math.round(normalized)}ms`);
+  }
+}
+
+export function getEventLoopLagSnapshot(): EventLoopLagSnapshot {
+  let maxMs = 0;
+  for (let i = 0; i < sampleCount; i += 1) maxMs = Math.max(maxMs, samples[i] ?? 0);
+  const maxSinceLastRead = maxSinceLastReadMs;
+  maxSinceLastReadMs = 0;
+  return {
+    currentMs,
+    maxMs,
+    maxSinceLastReadMs: maxSinceLastRead,
+    sampleCount,
+    windowSamples: EVENT_LOOP_LAG_WINDOW_SAMPLES,
+    sampleIntervalMs: EVENT_LOOP_LAG_SAMPLE_MS,
+    warnThresholdMs: EVENT_LOOP_LAG_WARN_MS,
+    lastSampleAt,
+  };
+}
+
+export function startEventLoopLagSampler(): void {
+  if (timer) return;
+  lastTickAt = performance.now();
+  timer = setInterval(() => {
+    const now = performance.now();
+    const lagMs = computeEventLoopLagMs(now - lastTickAt, EVENT_LOOP_LAG_SAMPLE_MS);
+    lastTickAt = now;
+    recordEventLoopLagSample(lagMs, Date.now(), true);
+  }, EVENT_LOOP_LAG_SAMPLE_MS);
+  timer.unref?.();
+}
+
+export function stopEventLoopLagSampler(): void {
+  if (!timer) return;
+  clearInterval(timer);
+  timer = undefined;
+}
+
+export function resetEventLoopLagForTests(): void {
+  stopEventLoopLagSampler();
+  samples.fill(0);
+  sampleIndex = 0;
+  sampleCount = 0;
+  currentMs = 0;
+  maxSinceLastReadMs = 0;
+  lastSampleAt = undefined;
+  lastTickAt = 0;
+}

package/src/maintenance/jobs.ts

@@ -3,6 +3,7 @@ import { deriveAgentBusyHealth } from "../agent-busy-health";
 import { expireStaleBusAgents } from "../bus";
 import { pruneOutbox } from "../bus-outbox";
 import { expireCommands } from "../commands-db";
+import { getRetentionConfig } from "../retention-config-store";
 import { OFFLINE_PRUNE_MS, REAP_INTERVAL_MS, STALE_TTL_MS } from "../config";
 import {
   createActivityEvent,
@@ -13,7 +14,7 @@ import {
   listStaleQueuedDirectTargets,
   pruneOrphanedSharedWorkspaces,
   pruneOfflineAgents,
-  pruneOldMessagesAsync,
+  pruneRetentionBatchAsync,
   pruneProviderQuotaHistory,
   reapStaleAgents,
   reapStaleOrchestrators,
@@ -375,13 +376,26 @@ export const definitions: MaintenanceJobDefinition[] = [
   },
   {
     id: "old-message-prune",
-    title: "Old message prune",
-    description: "Delete messages outside the configured retention window.",
+    title: "Data retention prune",
+    description: "Delete old messages, activity events, and terminal spawn commands in bounded batches.",
     intervalMs: DAY_MS,
     runOnStart: false,
-    handler(context) {
-      const retentionDays = Number(process.env.RETENTION_DAYS) || 30;
-      return pruneOldMessagesAsync(retentionDays * DAY_MS, { signal: context?.signal });
+    async handler(context) {
+      const retention = getRetentionConfig();
+      const now = Date.now();
+      const result = await pruneRetentionBatchAsync({
+        messageCutoff: now - retention.messageRetentionDays * DAY_MS,
+        activityCutoff: now - retention.activityEventRetentionDays * DAY_MS,
+        activityMaxRows: retention.activityEventMaxRows,
+        spawnCommandCutoff: now - retention.spawnCommandTerminalRetentionDays * DAY_MS,
+        batchSize: retention.pruneBatchSize,
+      }, { signal: context?.signal });
+      return {
+        prunedMessages: result.prunedMessages,
+        prunedActivityEvents: result.prunedActivityEvents,
+        prunedSpawnCommands: result.prunedSpawnCommands,
+        offThread: result.offThread,
+      };
     },
   },
   {

package/src/retention-config-store.ts

@@ -0,0 +1,32 @@
+import { getConfig, setConfig } from "./config-store";
+import {
+  RETENTION_CONFIG_DEFAULTS,
+  RETENTION_KEY,
+  RETENTION_NAMESPACE,
+  validateRetentionConfig,
+  type RetentionConfig,
+} from "./retention-config";
+import type { ConfigEntry } from "./types";
+
+/** Instance-wide retention config, merged over defaults (always returns a usable value). */
+export function getRetentionConfig(): RetentionConfig {
+  const entry = getConfig<Partial<RetentionConfig>>(RETENTION_NAMESPACE, RETENTION_KEY);
+  if (!entry) return { ...RETENTION_CONFIG_DEFAULTS };
+  return validateRetentionConfig({ ...RETENTION_CONFIG_DEFAULTS, ...entry.value });
+}
+
+export function getRetentionConfigEntry(): ConfigEntry<RetentionConfig> {
+  const entry = getConfig<RetentionConfig>(RETENTION_NAMESPACE, RETENTION_KEY);
+  return entry ?? {
+    namespace: RETENTION_NAMESPACE,
+    key: RETENTION_KEY,
+    value: { ...RETENTION_CONFIG_DEFAULTS },
+    version: 0,
+    updatedAt: "default",
+    updatedBy: "system",
+  };
+}
+
+export function setRetentionConfig(value: unknown, updatedBy?: string): ConfigEntry<RetentionConfig> {
+  return setConfig(RETENTION_NAMESPACE, RETENTION_KEY, value as RetentionConfig, updatedBy);
+}

package/src/retention-config.ts

@@ -0,0 +1,58 @@
+import { isRecord } from "agent-relay-sdk";
+import { ValidationError } from "./db/connection.ts";
+
+export const RETENTION_NAMESPACE = "retention";
+export const RETENTION_KEY = "default";
+
+export interface RetentionConfig {
+  messageRetentionDays: number;
+  activityEventRetentionDays: number;
+  activityEventMaxRows: number;
+  spawnCommandTerminalRetentionDays: number;
+  pruneBatchSize: number;
+}
+
+export const RETENTION_CONFIG_DEFAULTS: RetentionConfig = {
+  messageRetentionDays: 30,
+  activityEventRetentionDays: 14,
+  activityEventMaxRows: 100_000,
+  spawnCommandTerminalRetentionDays: 14,
+  pruneBatchSize: 10_000,
+};
+
+export const RETENTION_CONFIG_SCHEMA = {
+  type: "object",
+  properties: {
+    messageRetentionDays: { type: "integer", minimum: 1, maximum: 3650 },
+    activityEventRetentionDays: { type: "integer", minimum: 1, maximum: 3650 },
+    activityEventMaxRows: { type: "integer", minimum: 1, maximum: 10_000_000 },
+    spawnCommandTerminalRetentionDays: { type: "integer", minimum: 1, maximum: 3650 },
+    pruneBatchSize: { type: "integer", minimum: 1, maximum: 50_000 },
+  },
+  additionalProperties: false,
+} as const;
+
+function cleanInteger(value: unknown, field: string, fallback: number, min: number, max: number): number {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+    throw new ValidationError(`${field} must be an integer between ${min} and ${max}`);
+  }
+  return value;
+}
+
+export function validateRetentionConfig(value: unknown): RetentionConfig {
+  if (!isRecord(value)) throw new ValidationError("retention config value must be an object");
+  return {
+    messageRetentionDays: cleanInteger(value.messageRetentionDays, "messageRetentionDays", RETENTION_CONFIG_DEFAULTS.messageRetentionDays, 1, 3650),
+    activityEventRetentionDays: cleanInteger(value.activityEventRetentionDays, "activityEventRetentionDays", RETENTION_CONFIG_DEFAULTS.activityEventRetentionDays, 1, 3650),
+    activityEventMaxRows: cleanInteger(value.activityEventMaxRows, "activityEventMaxRows", RETENTION_CONFIG_DEFAULTS.activityEventMaxRows, 1, 10_000_000),
+    spawnCommandTerminalRetentionDays: cleanInteger(
+      value.spawnCommandTerminalRetentionDays,
+      "spawnCommandTerminalRetentionDays",
+      RETENTION_CONFIG_DEFAULTS.spawnCommandTerminalRetentionDays,
+      1,
+      3650,
+    ),
+    pruneBatchSize: cleanInteger(value.pruneBatchSize, "pruneBatchSize", RETENTION_CONFIG_DEFAULTS.pruneBatchSize, 1, 50_000),
+  };
+}

package/src/routes/messages.ts

@@ -7,7 +7,7 @@ import { emitMessageClaimed, emitMessageDeleted, emitMessageDeliveryUpdated, emi
 import { errMessage, isMechanicalMessageKind, isRecord } from "agent-relay-sdk";
 import { injectMemoryForMessageDelivery } from "../memory-service";
 import { authContextFromRequest } from "../services/auth-context";
-import { sendMessageService } from "../services/send-message";
+import { sendMessagesBatchService, sendMessageService } from "../services/send-message";
 import { AmbiguousTargetError, ServiceAuthError } from "../services/errors";
 import { type AgentSessionGuard, type Message, type SendMessageInput } from "../types";
 
@@ -73,6 +73,7 @@ function isDirectTarget(to: string): boolean {
 }
 
 const VALID_MSG_KINDS = ["chat", "channel.event", "task", "pair", "control", "system", "session"];
+const MAX_MESSAGE_BATCH = 100;
 
 export const getQueuedMessagesRoute: Handler = (req) => {
   const url = new URL(req.url);
@@ -149,6 +150,17 @@ export const postMessage: Handler = async (req) => {
   const parsed = await parseBody<unknown>(req);
   if (!parsed.ok) return error(parsed.error, parsed.status);
   try {
+    if (isRecord(parsed.body) && Array.isArray(parsed.body.messages)) {
+      if (parsed.body.messages.length === 0 || parsed.body.messages.length > MAX_MESSAGE_BATCH) {
+        throw new ValidationError(`messages must contain 1-${MAX_MESSAGE_BATCH} items`);
+      }
+      const inputs = parsed.body.messages.map((message) => normalizeMessageInput(message));
+      if (inputs.some((input) => input.kind !== "session")) {
+        throw new ValidationError("batch messages only supports kind=session");
+      }
+      const results = sendMessagesBatchService(inputs, authContextFromRequest(req));
+      return json({ messages: results.map((result) => result.message) }, 201);
+    }
     const input = normalizeMessageInput(parsed.body);
     if (!input.idempotencyKey) {
       input.idempotencyKey = cleanString(req.headers.get("Idempotency-Key") ?? undefined, "idempotencyKey", { max: 240 });

package/src/routing-policy-store.ts

@@ -278,7 +278,7 @@ function normalizeProviderQuotaConfig(raw: unknown, provider: string): ProviderQ
   if (!isRecord(raw)) throw new ValidationError(`providerQuota.${provider} must be an object`);
   const cfg: ProviderQuotaRoutingConfig = {};
   if (raw.hardBackstopUtilization !== undefined) {
-    cfg.hardBackstopUtilization = cleanFraction(raw.hardBackstopUtilization, `providerQuota.${provider}.hardBackstopUtilization`);
+    cfg.hardBackstopUtilization = cleanHardBackstopFraction(raw.hardBackstopUtilization);
   }
   if (raw.burnPenaltyUtilizationFloor !== undefined) {
     cfg.burnPenaltyUtilizationFloor = cleanFraction(raw.burnPenaltyUtilizationFloor, `providerQuota.${provider}.burnPenaltyUtilizationFloor`);
@@ -293,6 +293,16 @@ function cleanQuotaFraction(value: unknown, field: string): number {
   return value;
 }
 
+function cleanHardBackstopFraction(value: unknown): number {
+  // hardBackstopUtilization=0 is an intentional contract: disable the hard backstop
+  // for that provider. Other invalid values normalize to the default instead.
+  if (value === 0) return 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    return 0.99;
+  }
+  return value;
+}
+
 function cleanFraction(value: unknown, field: string): number {
   if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
     throw new ValidationError(`${field} must be a number between 0 and 1`);

package/src/server.ts

@@ -13,6 +13,7 @@ import { installNotificationSubscriptionRule } from "./notification-subscription
 import { installQuotaAdvisoryHandler } from "./quota-advisory";
 import { startPlanLiveBindings } from "./services/plan-live-bindings";
 import { startRelayScheduler } from "./services/scheduler";
+import { startEventLoopLagSampler } from "./event-loop-lag";
 import { recordWorkspaceIssueActivity } from "./services/spawn-issue-activity";
 import { onWorkspaceCreate } from "./db";
 import { isTerminalSessionRequestAuthorized } from "./terminal-authz";
@@ -80,6 +81,7 @@ export function startServer(): void {
   getCompactionWatch().start();
   reconcileRelayVersion();
   startConnectorStatusPoller();
+  startEventLoopLagSampler();
   startMaintenanceScheduler();
   startRelayScheduler();
 

package/src/services/send-message.ts

@@ -28,11 +28,13 @@ import {
   getMessage,
   listAgents,
   promoteLineageCapturedResponse,
+  sendMessagesBatchWithResult,
   sendMessageWithResult,
   channelObligationAnsweredBy,
+  type SendMessageResult as DbSendMessageResult,
 } from "../db";
 import { planSend, type DeliveryReceipt } from "../agent-ref";
-import { emitMessageQueued, emitNewMessage } from "../sse";
+import { emitMessageQueued, emitNewMessages } from "../sse";
 import { getLifecycleManager } from "../lifecycle-manager";
 import { isComponentAuthorizedFor, isIntegrationAllowed } from "../security";
 import { AmbiguousTargetError, ServiceAuthError } from "./errors";
@@ -175,6 +177,42 @@ export function sendMessageService(
   ctx: AuthContext,
   opts: SendMessageOptions = {},
 ): SendMessageResult {
+  const { receipt, suppressedParent } = prepareSendMessage(input, ctx, opts);
+  if (suppressedParent) return { message: suppressedParent, created: false, receipt };
+  const result = sendMessageWithResult(input);
+  emitSendResults([result]);
+  return { message: result.message, created: result.created, receipt };
+}
+
+export function sendMessagesBatchService(
+  inputs: SendMessageInput[],
+  ctx: AuthContext,
+  opts: SendMessageOptions = {},
+): SendMessageResult[] {
+  const prepared = inputs.map((input) => ({ input, ...prepareSendMessage(input, ctx, opts) }));
+  const results: SendMessageResult[] = [];
+  const storeInputs: SendMessageInput[] = [];
+  const storeIndexes: number[] = [];
+  for (const item of prepared) {
+    if (item.suppressedParent) {
+      results.push({ message: item.suppressedParent, created: false, receipt: item.receipt });
+      continue;
+    }
+    results.push(null as unknown as SendMessageResult);
+    storeIndexes.push(results.length - 1);
+    storeInputs.push(item.input);
+  }
+  const stored = sendMessagesBatchWithResult(storeInputs);
+  for (let i = 0; i < stored.length; i++) {
+    const result = stored[i]!;
+    const outputIndex = storeIndexes[i]!;
+    results[outputIndex] = { message: result.message, created: result.created, receipt: prepared[outputIndex]!.receipt };
+  }
+  emitSendResults(stored);
+  return results;
+}
+
+function prepareSendMessage(input: SendMessageInput, ctx: AuthContext, opts: SendMessageOptions): { receipt: DeliveryReceipt; suppressedParent: Message | null } {
   const receipt = validateSendMessageAuthorization(input, ctx, opts);
   // Reply-obligation linking: some real answers are ordinary sends without replyTo/thread linkage.
   // Channel bridge replies have a single unambiguous open obligation case;
@@ -184,29 +222,33 @@ export function sendMessageService(
     const answered = channelObligationAnsweredBy(input.from, input.to);
     if (answered !== null) input.replyTo = answered;
   }
-  const suppressedParent = suppressResultsOnlyAck(input);
-  if (suppressedParent) return { message: suppressedParent, created: false, receipt };
-  const result = sendMessageWithResult(input);
-  if (result.created) {
-    if (result.message.deliveryStatus === "queued") {
-      emitMessageQueued(result.message);
-      // Wake an on-demand managed policy that has no live agent attached yet.
-      if (result.message.to?.startsWith("policy:")) {
-        getLifecycleManager().onMessageForPolicy(result.message.to.slice("policy:".length));
+  return { receipt, suppressedParent: suppressResultsOnlyAck(input) };
+}
+
+function emitSendResults(results: DbSendMessageResult[]): void {
+  const liveMessages: Message[] = [];
+  for (const result of results) {
+    if (result.created) {
+      if (result.message.deliveryStatus === "queued") {
+        emitMessageQueued(result.message);
+        // Wake an on-demand managed policy that has no live agent attached yet.
+        if (result.message.to?.startsWith("policy:")) {
+          getLifecycleManager().onMessageForPolicy(result.message.to.slice("policy:".length));
+        }
+      } else {
+        liveMessages.push(result.message);
       }
-    } else {
-      emitNewMessage(result.message);
+      const promoted = promoteLineageCapturedResponse(result.message);
+      if (promoted?.created) liveMessages.push(promoted.message);
+    } else if (result.updated) {
+      // Session-step upsert (#parity): the row changed in place (same DB id). Re-emit so the
+      // dashboard's id-keyed merge replaces the existing step live — no duplicate row.
+      liveMessages.push(result.message);
+      const promoted = promoteLineageCapturedResponse(result.message);
+      if (promoted?.created) liveMessages.push(promoted.message);
     }
-    const promoted = promoteLineageCapturedResponse(result.message);
-    if (promoted?.created) emitNewMessage(promoted.message);
-  } else if (result.updated) {
-    // Session-step upsert (#parity): the row changed in place (same DB id). Re-emit so the
-    // dashboard's id-keyed merge replaces the existing step live — no duplicate row.
-    emitNewMessage(result.message);
-    const promoted = promoteLineageCapturedResponse(result.message);
-    if (promoted?.created) emitNewMessage(promoted.message);
   }
-  return { message: result.message, created: result.created, receipt };
+  emitNewMessages(liveMessages);
 }
 
 function suppressResultsOnlyAck(input: SendMessageInput): Message | null {

package/src/services/spawn-registration-watchdog.ts

@@ -20,12 +20,21 @@ interface SpawnCommandGroup {
   rows: SpawnCommandRow[];
 }
 
+interface SpawnCandidateRow {
+  spawn_request_id: string;
+  latest_updated_at: number;
+}
+
 interface SpawnRegistrationWatchdogResult extends Record<string, unknown> {
   failedSpawnCommandIds: string[];
   notifiedSpawnCommandIds: string[];
   silencedSpawnCommandIds: string[];
+  confirmedSpawnCommandIds: string[];
+  checkedSpawnGroups: number;
 }
 
+const MAX_SPAWN_GROUPS_PER_RUN = 25;
+
 export function reapUnregisteredSpawnCommands(
   now = Date.now(),
   deadlineMs = SPAWN_REGISTRATION_DEADLINE_MS,
@@ -33,20 +42,40 @@ export function reapUnregisteredSpawnCommands(
 ): SpawnRegistrationWatchdogResult {
   const cutoff = now - deadlineMs;
   const notifyCutoff = now - notifyMaxAgeMs;
-  const rows = getDb().query(`
-    SELECT id, params, correlation_id, updated_at
-    FROM commands
-    WHERE type = 'agent.spawn'
-      AND status = 'succeeded'
-    ORDER BY updated_at ASC
-  `).all() as SpawnCommandRow[];
+  const candidateRows = getDb().query(`
+    WITH spawn_groups AS (
+      SELECT
+        coalesce(nullif(json_extract(params, '$.spawnRequestId'), ''), correlation_id) AS spawn_request_id,
+        max(updated_at) AS latest_updated_at
+      FROM commands
+      WHERE type = 'agent.spawn'
+        AND status = 'succeeded'
+        AND json_valid(params)
+        AND coalesce(json_extract(params, '$.registrationConfirmed'), 0) != 1
+        AND coalesce(nullif(json_extract(params, '$.spawnedBy'), ''), '') != ''
+      GROUP BY coalesce(nullif(json_extract(params, '$.spawnRequestId'), ''), correlation_id)
+    )
+    SELECT spawn_request_id, latest_updated_at
+    FROM spawn_groups
+    WHERE spawn_request_id IS NOT NULL
+      AND latest_updated_at <= ?
+    ORDER BY latest_updated_at DESC
+    LIMIT ?
+  `).all(cutoff, MAX_SPAWN_GROUPS_PER_RUN) as SpawnCandidateRow[];
+  const rows = loadSpawnCommandRows(candidateRows.map((row) => row.spawn_request_id));
 
   const failedSpawnCommandIds: string[] = [];
   const notifiedSpawnCommandIds: string[] = [];
   const silencedSpawnCommandIds: string[] = [];
+  const confirmedSpawnCommandIds: string[] = [];
+  let checkedSpawnGroups = 0;
   for (const group of groupSpawnCommands(rows)) {
     if (group.latestUpdatedAt > cutoff) continue;
-    if (hasEverRegisteredAgent(group.spawnRequestId)) continue;
+    checkedSpawnGroups++;
+    if (hasEverRegisteredAgent(group.spawnRequestId)) {
+      confirmedSpawnCommandIds.push(...markSpawnGroupRegistrationConfirmed(group, now));
+      continue;
+    }
 
     const reason = `spawned agent did not register within ${deadlineMs}ms`;
     const failedCommands = group.rows
@@ -70,7 +99,25 @@ export function reapUnregisteredSpawnCommands(
     }
   }
 
-  return { failedSpawnCommandIds, notifiedSpawnCommandIds, silencedSpawnCommandIds };
+  return { failedSpawnCommandIds, notifiedSpawnCommandIds, silencedSpawnCommandIds, confirmedSpawnCommandIds, checkedSpawnGroups };
+}
+
+function loadSpawnCommandRows(spawnRequestIds: string[]): SpawnCommandRow[] {
+  if (spawnRequestIds.length === 0) return [];
+  const placeholders = spawnRequestIds.map(() => "?").join(",");
+  return getDb().query(`
+    SELECT id, params, correlation_id, updated_at
+    FROM commands
+    WHERE type = 'agent.spawn'
+      AND status = 'succeeded'
+      AND json_valid(params)
+      AND coalesce(json_extract(params, '$.registrationConfirmed'), 0) != 1
+      AND (
+        correlation_id IN (${placeholders})
+        OR json_extract(params, '$.spawnRequestId') IN (${placeholders})
+      )
+    ORDER BY updated_at ASC
+  `).all(...spawnRequestIds, ...spawnRequestIds) as SpawnCommandRow[];
 }
 
 function groupSpawnCommands(rows: SpawnCommandRow[]): SpawnCommandGroup[] {
@@ -121,6 +168,24 @@ function hasEverRegisteredAgent(spawnRequestId: string): boolean {
   return Boolean(registration);
 }
 
+function markSpawnGroupRegistrationConfirmed(group: SpawnCommandGroup, now: number): string[] {
+  const confirmed: string[] = [];
+  const stmt = getDb().query(`
+    UPDATE commands
+    SET params = ?
+    WHERE id = ?
+      AND status = 'succeeded'
+  `);
+  for (const row of group.rows) {
+    const params = parseParams(row.params);
+    if (params.registrationConfirmed === true) continue;
+    params.registrationConfirmed = true;
+    params.registrationConfirmedAt = now;
+    if (stmt.run(JSON.stringify(params), row.id).changes > 0) confirmed.push(row.id);
+  }
+  return confirmed;
+}
+
 function parseParams(raw: string): Record<string, unknown> {
   try {
     const parsed = JSON.parse(raw);

package/src/settings/registry.ts

@@ -35,6 +35,7 @@ import {
   NOTIFICATIONS_SETTINGS_SCHEMA,
   parseNotificationSettingsKey,
 } from "../notification-settings";
+import { RETENTION_CONFIG_DEFAULTS, RETENTION_CONFIG_SCHEMA, RETENTION_KEY, RETENTION_NAMESPACE } from "../retention-config";
 
 /** Fail-closed default scope — a descriptor that omits scope requires admin to
  *  read and write (#385 owns the scope grammar; this layer only declares it). */
@@ -400,6 +401,16 @@ function seedBuiltInSettings(): void {
     display: { group: "Teams", label: "Team idle watchdog", description: "Coordinator nudge when a team has no busy members.", order: 45 },
   });
 
+  registerSetting({
+    namespace: RETENTION_NAMESPACE,
+    key: RETENTION_KEY,
+    schema: RETENTION_CONFIG_SCHEMA,
+    defaults: RETENTION_CONFIG_DEFAULTS,
+    scope: { read: "settings:read:system", write: "settings:write:system" },
+    tier: "server-runtime",
+    display: { group: "System", label: "Data retention", description: "Retention windows and batch size for high-churn Relay tables.", order: 46 },
+  });
+
   registerSetting({
     namespace: "provider",
     key: "chatCaptureMode",

package/src/sse.ts

@@ -161,6 +161,10 @@ function fanout(event: RelayEvent): void {
     sendNewMessage(event.data as unknown as Message, event.seq);
     return;
   }
+  if (event.type === "message.batch") {
+    sendNewMessages(batchMessages(event.data), event.seq);
+    return;
+  }
   if (event.type === "task.updated" || event.type === "task.created" || event.type === "task.claimed" || event.type === "task.status") {
     sendTaskChanged(event.data as unknown as Task, event.type, event.seq);
     return;
@@ -172,28 +176,62 @@ function fanout(event: RelayEvent): void {
 }
 
 function sendNewMessage(msg: Message, seq?: number): void {
-  const scopedBroadcastAgentIds = msg.to === "broadcast"
-    ? new Set(matchingDeliveryAgents("broadcast", { from: msg.from, channel: msg.channel }).map((agent) => agent.id))
-    : null;
-  const chunk = sseFrame("message.new", msg, seq);
+  sendNewMessages([msg], seq);
+}
+
+function sendNewMessages(messages: Message[], seq?: number): void {
+  if (messages.length === 0) return;
+  const chunks = messages.map((msg, index) => [msg, sseFrame("message.new", msg, seq === undefined ? undefined : seq + index)] as const);
+  const broadcastScopes = new Map<number, Set<string>>();
+  for (const msg of messages) {
+    if (msg.to === "broadcast") {
+      broadcastScopes.set(msg.id, new Set(matchingDeliveryAgents("broadcast", { from: msg.from, channel: msg.channel }).map((agent) => agent.id)));
+    }
+  }
   const agentCache = new Map<string, AgentCard | null>();
   for (const conn of connections.values()) {
-    if (!conn.agentId) {
+    for (const [msg, chunk] of chunks) {
+      if (!conn.agentId) {
+        sendEncoded(conn, chunk);
+        continue;
+      }
+      const scopedBroadcastAgentIds = broadcastScopes.get(msg.id) ?? null;
+      if (scopedBroadcastAgentIds && !scopedBroadcastAgentIds.has(conn.agentId)) continue;
+      if (!messageMatchesAgent(msg, conn.agentId, fanoutAgent(conn.agentId, agentCache))) continue;
       sendEncoded(conn, chunk);
-      continue;
     }
-    if (scopedBroadcastAgentIds && !scopedBroadcastAgentIds.has(conn.agentId)) continue;
-    if (!messageMatchesAgent(msg, conn.agentId, fanoutAgent(conn.agentId, agentCache))) continue;
-    sendEncoded(conn, chunk);
   }
 }
 
+function batchMessages(data: Record<string, unknown>): Message[] {
+  const messages = (data as { messages?: unknown }).messages;
+  return Array.isArray(messages) ? messages as Message[] : [];
+}
+
 export function emitNewMessage(msg: Message) {
   emitRelayEvent({ type: "message.new", source: msg.from, subject: String(msg.id), data: msg as unknown as Record<string, unknown> });
   const notification = notificationForMessage(msg);
   if (notification) emitNotificationCreated(notification);
 }
 
+export function emitNewMessages(messages: Message[]) {
+  if (messages.length === 0) return;
+  if (messages.length === 1) {
+    emitNewMessage(messages[0]!);
+    return;
+  }
+  emitRelayEvent({
+    type: "message.batch",
+    source: messages[0]!.from,
+    subject: `${messages[0]!.id}:${messages.at(-1)!.id}`,
+    data: { messages } as unknown as Record<string, unknown>,
+  });
+  for (const msg of messages) {
+    const notification = notificationForMessage(msg);
+    if (notification) emitNotificationCreated(notification);
+  }
+}
+
 interface RelayInjectionTimelineInput {
   agentId: string;
   category: RelayInjectionCategory;
@@ -328,6 +366,13 @@ function replayEventsToConnection(conn: Connection | undefined, plan: ReplayPlan
 }
 
 function sendReplayEvent(conn: Connection, event: RelayEvent, agentCache: Map<string, AgentCard | null>): void {
+  if (event.type === "message.batch") {
+    for (const [index, msg] of batchMessages(event.data).entries()) {
+      if (conn.agentId && !messageMatchesAgent(msg, conn.agentId, fanoutAgent(conn.agentId, agentCache))) continue;
+      send(conn, "message.new", msg, event.seq + index);
+    }
+    return;
+  }
   if (event.type === "message.new" && conn.agentId) {
     const msg = event.data as unknown as Message;
     if (!messageMatchesAgent(msg, conn.agentId, fanoutAgent(conn.agentId, agentCache))) return;