@desplega.ai/agent-swarm 1.135.2 → 1.136.0

package/src/be/db-retention.ts

@@ -0,0 +1,275 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { isEnvFlagEnabled } from "../utils/env-flag";
+import { getDbClient } from "./db";
+import { MAX_DB_RETENTION_DAYS } from "./swarm-config-guard";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const RETENTION_INTERVAL_MS = 60 * 60 * 1000;
+const BATCH_SIZE = 5_000;
+const PER_TABLE_BATCH_CAP = 40;
+const WALL_CLOCK_CAP_MS = 60_000;
+const YIELD_MS = 5;
+
+/**
+ * This is deliberately a closed list. Neither table nor column names may come
+ * from operator configuration: a retention policy must never target a table
+ * that code review has not explicitly approved as safe to delete from.
+ */
+export const DB_RETENTION_TABLES = [
+  {
+    table: "session_logs",
+    timeColumn: "createdAt",
+    envKey: "SESSION_LOG_RETENTION_DAYS",
+    metricsKey: "sessionLogs",
+  },
+  {
+    table: "agent_log",
+    timeColumn: "createdAt",
+    envKey: "AGENT_LOG_RETENTION_DAYS",
+    metricsKey: "agentLog",
+  },
+  {
+    table: "events",
+    timeColumn: "createdAt",
+    envKey: "EVENTS_RETENTION_DAYS",
+    metricsKey: "events",
+  },
+] as const;
+
+type RetentionTable = (typeof DB_RETENTION_TABLES)[number];
+type RetentionMetricsKey = RetentionTable["metricsKey"];
+
+export type DbRetentionTableStats = {
+  at: string;
+  /** Deleted rows, or rows that would be deleted when dryRun is true. */
+  rowsDeleted: number;
+  batches: number;
+  durationMs: number;
+  dryRun: boolean;
+  cumulativeRowsDeleted: number;
+};
+
+export type DbRetentionStats = Partial<Record<RetentionMetricsKey, DbRetentionTableStats>>;
+
+/** Test-only controls; production callers always use the bounded defaults above. */
+export type DbRetentionTickOptions = {
+  now?: Date;
+  batchSize?: number;
+  perTableBatchCap?: number;
+  wallClockCapMs?: number;
+};
+
+let retentionTimer: ReturnType<typeof setInterval> | null = null;
+let retentionTickPromise: Promise<void> | null = null;
+let retentionAbortController: AbortController | null = null;
+let retentionStats: DbRetentionStats = {};
+let cumulativeRowsDeleted: Partial<Record<RetentionMetricsKey, number>> = {};
+
+// Timers must not inherit an open database transaction from their caller.
+const scheduleContextFree = AsyncLocalStorage.snapshot();
+
+function readPositiveIntEnv(key: string, env: NodeJS.ProcessEnv = process.env): number | null {
+  const raw = env[key]?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return null;
+  const value = Number(raw);
+  return Number.isSafeInteger(value) && value >= 1 && value <= MAX_DB_RETENTION_DAYS ? value : null;
+}
+
+function yieldTick(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, YIELD_MS));
+}
+
+function retentionDays(table: RetentionTable): number | null {
+  return readPositiveIntEnv(table.envKey);
+}
+
+function dryRunEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const raw = env.DB_RETENTION_DRY_RUN;
+  if (raw === undefined || raw.trim() === "") return false;
+  return isEnvFlagEnabled("DB_RETENTION_DRY_RUN", true, env);
+}
+
+async function sweepTable(
+  table: RetentionTable,
+  cutoff: string,
+  dryRun: boolean,
+  deadline: number,
+  batchSize: number,
+  perTableBatchCap: number,
+  signal: AbortSignal,
+): Promise<{ rowsDeleted: number; batches: number; complete: boolean }> {
+  const client = getDbClient();
+  let rowsDeleted = 0;
+  let batches = 0;
+  let pagesFetched = 0;
+  let cursor: string | null = null;
+  let complete = true;
+  let exhausted = false;
+  // Bounded on pages fetched, not on delete batches: a sparse or no-match
+  // table would otherwise walk every primary-key page until the wall-clock
+  // deadline, since batches only increments when a page has expired rows.
+  const pageLimit = dryRun ? Number.POSITIVE_INFINITY : perTableBatchCap;
+  while (!signal.aborted && pagesFetched < pageLimit && Date.now() < deadline) {
+    // Page by the primary key, not by the retention predicate. A query that
+    // filters on createdAt while ordering by id can scan the whole PK index
+    // before finding LIMIT matches when eligible rows are sparse. This query
+    // visits at most batchSize rows per statement; cutoff filtering happens in
+    // memory and deletes are restricted to the IDs in that bounded page.
+    const page: Array<{ id: string; createdAt: string }> = await client.query<{
+      id: string;
+      createdAt: string;
+    }>(
+      `SELECT id, ${table.timeColumn} AS createdAt
+       FROM ${table.table}
+       ${cursor === null ? "" : "WHERE id > ?"}
+       ORDER BY id
+       LIMIT ?`,
+      cursor === null ? [batchSize] : [cursor, batchSize],
+    );
+    pagesFetched += 1;
+    if (Date.now() >= deadline || signal.aborted) {
+      complete = false;
+      break;
+    }
+    if (page.length === 0) {
+      exhausted = true;
+      break;
+    }
+
+    cursor = page[page.length - 1]?.id ?? null;
+    const expiredIds = page.filter((row) => row.createdAt < cutoff).map((row) => row.id);
+    if (expiredIds.length > 0) {
+      if (dryRun) {
+        rowsDeleted += expiredIds.length;
+      } else {
+        // IDs came directly from the bounded page and are placeholders, so
+        // this statement is bounded by the page size and remains retryable.
+        const placeholders = expiredIds.map(() => "?").join(", ");
+        const result = await client.run(
+          `DELETE FROM ${table.table} WHERE id IN (${placeholders})`,
+          expiredIds,
+        );
+        rowsDeleted += result.changes;
+      }
+      batches += 1;
+    }
+    if (page.length < batchSize) {
+      exhausted = true;
+      break;
+    }
+    await yieldTick();
+  }
+  // A dry-run count is only useful if the full table was scanned. Never
+  // publish a partial count when the wall-clock budget or shutdown interrupted
+  // the keyset scan.
+  return { rowsDeleted, batches, complete: !dryRun || (complete && exhausted) };
+}
+
+/** Run one bounded sweep over every enabled table. Failures are isolated per table. */
+export function runDbRetentionTick(options: DbRetentionTickOptions = {}): Promise<void> {
+  if (retentionTickPromise) return retentionTickPromise;
+
+  const abortController = new AbortController();
+  retentionAbortController = abortController;
+  const promise = Promise.resolve().then(async () => {
+    try {
+      const tickStartedAt = Date.now();
+      const cutoffBase = options.now ?? new Date(tickStartedAt);
+      const dryRun = dryRunEnabled();
+      const batchSize = options.batchSize ?? BATCH_SIZE;
+      const perTableBatchCap = options.perTableBatchCap ?? PER_TABLE_BATCH_CAP;
+      const deadline = tickStartedAt + (options.wallClockCapMs ?? WALL_CLOCK_CAP_MS);
+      let deletedAny = false;
+
+      for (const table of DB_RETENTION_TABLES) {
+        if (abortController.signal.aborted || Date.now() >= deadline) break;
+        const days = retentionDays(table);
+        if (days === null) continue;
+
+        const startedAt = Date.now();
+        try {
+          const cutoff = new Date(cutoffBase.getTime() - days * DAY_MS).toISOString();
+          const result = await sweepTable(
+            table,
+            cutoff,
+            dryRun,
+            deadline,
+            batchSize,
+            perTableBatchCap,
+            abortController.signal,
+          );
+          if (dryRun && !result.complete) {
+            throw new Error("dry-run count stopped before completion");
+          }
+          deletedAny ||= !dryRun && result.rowsDeleted > 0;
+          const cumulative =
+            (cumulativeRowsDeleted[table.metricsKey] ?? 0) + (dryRun ? 0 : result.rowsDeleted);
+          cumulativeRowsDeleted[table.metricsKey] = cumulative;
+          retentionStats[table.metricsKey] = {
+            at: new Date().toISOString(),
+            rowsDeleted: result.rowsDeleted,
+            batches: result.batches,
+            durationMs: Date.now() - startedAt,
+            dryRun,
+            cumulativeRowsDeleted: cumulative,
+          };
+          if (result.rowsDeleted > 0) {
+            console.log(
+              `[db-retention] ${table.table}: ${dryRun ? "would delete" : "deleted"} ${result.rowsDeleted} row(s) in ${result.batches} batch(es) after ${Date.now() - startedAt}ms`,
+            );
+          }
+        } catch (err) {
+          console.error(`[db-retention] ${table.table} sweep failed:`, (err as Error).message);
+        }
+      }
+
+      if (deletedAny && !abortController.signal.aborted) {
+        try {
+          // Harmless when auto_vacuum is not INCREMENTAL; never run a blocking VACUUM here.
+          await getDbClient().run("PRAGMA incremental_vacuum(2000)");
+        } catch (err) {
+          console.error("[db-retention] incremental vacuum failed:", (err as Error).message);
+        }
+      }
+    } finally {
+      if (retentionAbortController === abortController) retentionAbortController = null;
+      retentionTickPromise = null;
+    }
+  });
+  retentionTickPromise = promise;
+  return promise;
+}
+
+export function getDbRetentionStats(): DbRetentionStats {
+  return { ...retentionStats };
+}
+
+/** Start the hourly sweep. The first tick runs immediately. */
+export async function startDbRetention(intervalMs = RETENTION_INTERVAL_MS): Promise<void> {
+  if (retentionTimer) return;
+  const configured = DB_RETENTION_TABLES.map(
+    (table) => `${table.table}=${retentionDays(table) ?? "disabled"}`,
+  ).join(", ");
+  console.log(`[db-retention] starting (${configured}, dryRun=${dryRunEnabled()})`);
+  retentionTimer = scheduleContextFree(() =>
+    setInterval(() => void runDbRetentionTick(), intervalMs),
+  );
+  if (typeof retentionTimer.unref === "function") retentionTimer.unref();
+  await runDbRetentionTick();
+}
+
+export async function stopDbRetention(): Promise<void> {
+  if (retentionTimer) {
+    clearInterval(retentionTimer);
+    retentionTimer = null;
+  }
+  retentionAbortController?.abort();
+  await retentionTickPromise;
+}
+
+/** Test hook to prevent module state leaking between Bun test files. */
+export async function resetDbRetentionForTests(): Promise<void> {
+  await stopDbRetention();
+  retentionStats = {};
+  cumulativeRowsDeleted = {};
+}

package/src/be/db.ts

@@ -4782,13 +4782,19 @@ export async function createTaskExtended(
   let requestedByUserIdInherited = false;
   const id = crypto.randomUUID();
   const now = new Date().toISOString();
-  const status: AgentTaskStatus = options?.offeredTo
-    ? "offered"
-    : options?.agentId
-      ? "pending"
-      : options?.status === "backlog"
-        ? "backlog"
-        : "unassigned";
+  // `status: "draft"` wins over offeredTo/agentId — a draft task keeps its
+  // intended owner/offer for when it's promoted (#1240), but must not be
+  // dispatch-eligible while attachments are still uploading.
+  const status: AgentTaskStatus =
+    options?.status === "draft"
+      ? "draft"
+      : options?.offeredTo
+        ? "offered"
+        : options?.agentId
+          ? "pending"
+          : options?.status === "backlog"
+            ? "backlog"
+            : "unassigned";
 
   // Inherit Slack/AgentMail metadata from parent task (unless explicitly overridden)
   if (options?.parentTaskId) {
@@ -5355,6 +5361,75 @@ export async function moveTaskFromBacklog(taskId: string): Promise<AgentTask | n
   return row ? rowToAgentTask(row) : null;
 }
 
+/**
+ * Promote a task out of `draft` status into whichever status it should have
+ * had at creation time — `offered` if it was offered to an agent, `pending`
+ * if it has an owning agent (the common UI-composer case, which defaults to
+ * Lead), otherwise `unassigned`. `draft` exists solely to keep a task
+ * dispatch-ineligible while its UI-uploaded attachments are still in flight
+ * (#1240); this is the promote half of that window. Called once the upload
+ * batch settles — success, partial failure, or total failure all promote, a
+ * draft is never left stranded by upload errors — or by
+ * `promoteAbandonedDraftTasks` for drafts nobody ever promoted.
+ */
+export async function promoteDraftTask(taskId: string): Promise<AgentTask | null> {
+  const now = new Date().toISOString();
+  const row = await getDbClient().get<AgentTaskRow>(
+    `UPDATE agent_tasks
+       SET status = CASE
+           WHEN offeredTo IS NOT NULL THEN 'offered'
+           WHEN agentId IS NOT NULL THEN 'pending'
+           ELSE 'unassigned'
+         END,
+         lastUpdatedAt = ?
+       WHERE id = ? AND status = 'draft'
+       RETURNING *`,
+    [now, taskId],
+  );
+
+  if (row) {
+    try {
+      await createLogEntry({
+        eventType: "task_status_change",
+        taskId,
+        agentId: row.agentId ?? undefined,
+        oldValue: "draft",
+        newValue: row.status,
+      });
+    } catch {}
+  }
+
+  return row ? rowToAgentTask(row) : null;
+}
+
+/**
+ * Heartbeat sweep: promote drafts abandoned mid-upload (tab closed, network
+ * dropped) instead of leaving them permanently dispatch-ineligible — the
+ * composer's UI-driven promote (`promoteDraftTask`) never fires if the user
+ * never comes back. Same target-status logic, applied in bulk by elapsed
+ * time. Default 5 minutes is well above the tens-of-seconds worst-case
+ * upload-batch duration seen against slow storage (#1226) while still
+ * surfacing an abandoned session to its owner promptly.
+ */
+export async function promoteAbandonedDraftTasks(timeoutMinutes: number = 5): Promise<number> {
+  const cutoffTime = new Date(Date.now() - timeoutMinutes * 60 * 1000).toISOString();
+  const now = new Date().toISOString();
+
+  const result = await getDbClient().run(
+    `UPDATE agent_tasks
+       SET status = CASE
+           WHEN offeredTo IS NOT NULL THEN 'offered'
+           WHEN agentId IS NOT NULL THEN 'pending'
+           ELSE 'unassigned'
+         END,
+         lastUpdatedAt = ?
+       WHERE status = 'draft' AND lastUpdatedAt < ?`,
+    [now, cutoffTime],
+  );
+
+  return result.changes;
+}
+
 /**
  * Release tasks that have been in 'reviewing' status for too long.
  * Returns them to 'offered' status for retry.

package/src/be/swarm-config-guard.ts

@@ -39,6 +39,9 @@ type ConfigValidator = (value: unknown) => string | null;
 
 const BOOLEAN_LITERALS = ["true", "false", "1", "0"];
 
+/** A conservative window that remains representable by JavaScript Date arithmetic. */
+export const MAX_DB_RETENTION_DAYS = 1_000_000;
+
 /** Build `{ KEY: validator }` entries accepting only boolean literals. */
 function booleanValidators(keys: string[]): Record<string, ConfigValidator> {
   const message = (key: string) =>
@@ -81,6 +84,27 @@ function integerValidators(keys: string[], min: number): Record<string, ConfigVa
   );
 }
 
+/** Build `{ KEY: validator }` entries accepting integers inside a closed range. */
+function boundedIntegerValidators(
+  keys: string[],
+  min: number,
+  max: number,
+): Record<string, ConfigValidator> {
+  return Object.fromEntries(
+    keys.map((key) => [
+      key,
+      (value: unknown) => {
+        const str = String(value).trim();
+        const parsed = Number(str);
+        if (!/^\d+$/.test(str) || !Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+          return `Invalid ${key} (must be an integer between ${min} and ${max})`;
+        }
+        return null;
+      },
+    ]),
+  );
+}
+
 function validateFloatRange(
   key: string,
   value: unknown,
@@ -163,6 +187,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "ANONYMIZED_TELEMETRY",
     "SWARM_HIDE_CLOUD_PROMO",
     "DB_QUERY_BOUNDED_ENABLED",
+    "DB_RETENTION_DRY_RUN",
   ]),
   ...enumValidator("SLACK_THREAD_STEERING", ["lead", "all"]),
   ...enumValidator("SLACK_THREAD_STEERING_MODE", ["steer", "queue"]),
@@ -191,6 +216,11 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     ],
     1,
   ),
+  ...boundedIntegerValidators(
+    ["SESSION_LOG_RETENTION_DAYS", "AGENT_LOG_RETENTION_DAYS", "EVENTS_RETENTION_DAYS"],
+    1,
+    MAX_DB_RETENTION_DAYS,
+  ),
   // 0 is meaningful here: "auto-assign nothing this sweep".
   ...integerValidators(["HEARTBEAT_MAX_AUTO_ASSIGN"], 0),
   MEMORY_MIN_SIMILARITY: (value) =>

package/src/heartbeat/heartbeat.ts

@@ -29,6 +29,7 @@ import {
   isAgentEligibleForTask,
   isPoolAffinityEnforcementEnabled,
   MAX_EMPTY_POLLS,
+  promoteAbandonedDraftTasks,
   releaseStaleMentionProcessing,
   releaseStaleOfferedTasksForOfflineAgents,
   releaseStaleProcessingInbox,
@@ -116,6 +117,16 @@ export const STEERING_STALL_GRACE_MIN = Number(process.env.HEARTBEAT_STEERING_GR
 /** Stale resource cleanup threshold (minutes) */
 const STALE_CLEANUP_THRESHOLD_MINUTES = Number(process.env.HEARTBEAT_STALE_CLEANUP_MIN) || 30;
 
+/**
+ * Abandoned-draft promotion threshold (minutes, #1240). Deliberately much
+ * shorter than STALE_CLEANUP_THRESHOLD_MINUTES: a draft only exists while a
+ * UI-composer attachment batch uploads, which even against slow storage
+ * (#1226) took tens of seconds — 5 minutes is generous headroom above that
+ * worst case while still surfacing an abandoned session (tab closed
+ * mid-upload) to its owner within one coffee break, not half an hour.
+ */
+const DRAFT_TASK_TIMEOUT_MINUTES = Number(process.env.HEARTBEAT_DRAFT_TASK_TIMEOUT_MIN) || 5;
+
 /** Max pool tasks to auto-assign per sweep */
 function maxAutoAssignPerSweep(): number {
   const raw = process.env.HEARTBEAT_MAX_AUTO_ASSIGN?.trim();
@@ -221,6 +232,7 @@ export interface HeartbeatFindings {
     workflowRuns: number;
     staleRuntimes: number;
     staleOfferedTasks: number;
+    abandonedDraftTasks: number;
   };
 }
 
@@ -296,6 +308,7 @@ export async function codeLevelTriage(): Promise<HeartbeatFindings> {
       workflowRuns: 0,
       staleRuntimes: 0,
       staleOfferedTasks: 0,
+      abandonedDraftTasks: 0,
     },
   };
 
@@ -1026,6 +1039,9 @@ async function cleanupStaleResources(findings: HeartbeatFindings): Promise<void>
   findings.staleCleanup.inboxProcessing = await releaseStaleProcessingInbox(
     STALE_CLEANUP_THRESHOLD_MINUTES,
   );
+  findings.staleCleanup.abandonedDraftTasks = await promoteAbandonedDraftTasks(
+    DRAFT_TASK_TIMEOUT_MINUTES,
+  );
   // DES-523 Phase 3: escalate pinned crash-recovery resumes that were never
   // reclaimed within the grace window to a Lead re-delegation decision.
   await escalateUnreclaimedResumes(findings);
@@ -1331,6 +1347,7 @@ export async function runHeartbeatSweep(): Promise<void> {
           workflowRuns: 0,
           staleRuntimes: 0,
           staleOfferedTasks: 0,
+          abandonedDraftTasks: 0,
         },
       };
       // Expiry runs even on a cleanup-only tick: an idle agent whose runtime
@@ -1396,6 +1413,7 @@ function logFindings(findings: HeartbeatFindings): void {
     inboxProcessing,
     workflowRuns,
     staleOfferedTasks,
+    abandonedDraftTasks,
   } = findings.staleCleanup;
   const totalCleanup =
     sessions + reviewingTasks + mentionProcessing + inboxProcessing + workflowRuns;
@@ -1405,6 +1423,9 @@ function logFindings(findings: HeartbeatFindings): void {
   if (staleOfferedTasks > 0) {
     parts.push(`stale_offers_released=${staleOfferedTasks}`);
   }
+  if (abandonedDraftTasks > 0) {
+    parts.push(`abandoned_drafts_promoted=${abandonedDraftTasks}`);
+  }
 
   if (parts.length > 0) {
     console.log(`[Heartbeat] Sweep complete: ${parts.join(", ")}`);

package/src/http/index.ts

@@ -9,6 +9,7 @@ import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/se
 import { getEnabledCapabilities, hasCapability } from "@/server";
 import { initAgentMail } from "../agentmail";
 import { closeDb, getSwarmConfigs, upsertSwarmConfig } from "../be/db";
+import { startDbRetention, stopDbRetention } from "../be/db-retention";
 import {
   enqueueAuditRow,
   flushAuditBuffer,
@@ -107,6 +108,7 @@ import {
   parseQueryParams,
   safeRequestUrlForLog,
   setCorsHeaders,
+  wireHttpSpanLifecycle,
 } from "./utils";
 import { handleWebhooks } from "./webhooks";
 import { handleWorkflowEvents } from "./workflow-events";
@@ -213,7 +215,6 @@ const transportActivityUser: McpTransportActivity = globalState.__transportActiv
 const httpServer = createHttpServer(async (req, res) => {
   const startTime = performance.now();
   let statusCode = 200;
-  let spanEnded = false;
 
   // Wrap writeHead to capture status code
   const originalWriteHead = res.writeHead.bind(res);
@@ -245,51 +246,43 @@ const httpServer = createHttpServer(async (req, res) => {
   await withRemoteContext(req.headers as Record<string, unknown>, async () => {
     const reqPath = req.url?.split("?")[0] ?? "";
     const pathSegments = getPathSegments(req.url || "");
+    const hasQueryString = (req.url ?? "").includes("?");
+    const hasTrailingSlash = reqPath.length > 1 && reqPath.endsWith("/");
     const skipSpan = reqPath === "/api/poll" && !isPollTracingEnabled();
     // Per OTel HTTP semantic conventions: span name is `{METHOD} {route-template}`
     // and `http.route` carries the bounded-cardinality template so SigNoz can
     // group/filter/aggregate by endpoint as a first-class field. `http.route` is
     // omitted (not fabricated) for unmatched core/MCP/404 paths. Raw path stays
     // on `url.path`.
-    const { spanName, httpRoute } = describeRequestRoute(req.method, pathSegments);
+    const { spanName, httpRoute } = describeRequestRoute(
+      req.method,
+      pathSegments,
+      hasQueryString,
+      hasTrailingSlash,
+    );
     // Standard OTel HTTP server semconv attributes — host, scheme, protocol
     // version, user-agent (the method/path/route/status are set inline below).
     const semconv = httpServerSemconvAttributes(req);
     const span = skipSpan
       ? null
-      : startSpan(spanName, {
-          "http.request.method": req.method ?? "",
-          "url.path": reqPath,
-          "url.scheme": semconv["url.scheme"],
-          "http.route": httpRoute,
-          "server.address": semconv["server.address"],
-          "network.protocol.version": semconv["network.protocol.version"],
-          "user_agent.original": semconv["user_agent.original"],
-          "agent.id": req.headers["x-agent-id"] as string | undefined,
-          "agentswarm.component": "api",
-        });
+      : startSpan(
+          spanName,
+          {
+            "http.request.method": req.method ?? "",
+            "url.path": reqPath,
+            "url.scheme": semconv["url.scheme"],
+            "http.route": httpRoute,
+            "server.address": semconv["server.address"],
+            "network.protocol.version": semconv["network.protocol.version"],
+            "user_agent.original": semconv["user_agent.original"],
+            "agent.id": req.headers["x-agent-id"] as string | undefined,
+            "agentswarm.component": "api",
+          },
+          { kind: "server" },
+        );
 
     if (span) {
-      res.on("finish", () => {
-        if (spanEnded) return;
-        spanEnded = true;
-        span.setAttributes({
-          "http.response.status_code": statusCode,
-          "agentswarm.http.duration_ms": Math.round((performance.now() - startTime) * 10) / 10,
-        });
-        if (statusCode >= 500) {
-          span.setStatus({ code: 2, message: `HTTP ${statusCode}` });
-        }
-        span.end();
-      });
-
-      res.on("error", (err) => {
-        if (spanEnded) return;
-        spanEnded = true;
-        span.recordException(err);
-        span.setStatus({ code: 2, message: err.message });
-        span.end();
-      });
+      wireHttpSpanLifecycle(res, span, () => statusCode, startTime);
     }
 
     // Run request handling inside the HTTP span's active context so any spans
@@ -449,6 +442,9 @@ async function shutdown() {
   // Stop memory expired-row garbage collector
   stopMemoryGc();
 
+  // Stop opt-in session, agent-log, and event retention before closing SQLite.
+  await stopDbRetention();
+
   // Stop scratch-script retention garbage collector
   stopScratchScriptGc();
 
@@ -693,6 +689,10 @@ httpServer
     // Start expired-memory garbage collector (1-hour tick, immediate first run)
     await startMemoryGc();
 
+    // Start the opt-in DB retention sweep after config hydration. Every key is
+    // read on each tick, so config reloads take effect without a restart.
+    await startDbRetention();
+
     // (RBAC audit sink is wired pre-listen — see above httpServer.listen.)
 
     // Background backfill: re-embed any agent_memory rows with wrong-dimension