@desplega.ai/agent-swarm 2.7.5 → 2.7.7

package/src/commands/profile-sync.ts

@@ -27,6 +27,7 @@
  * but it must be VISIBLE.
  */
 
+import { rename } from "node:fs/promises";
 import { resolveTemplateAsync } from "../prompts/resolver.ts";
 import type { Agent, ProfileExpectedHashes, SwarmEvent } from "../types.ts";
 import { MAX_PROFILE_FILE_LENGTH } from "../utils/constants.ts";
@@ -52,10 +53,13 @@ export const SETUP_SCRIPT_PATH = "/workspace/start-up.sh";
 // Flow:
 //   1. Runner writes DB content → /workspace/*.md at session start.
 //   2. Runner records SHA-256 hashes of the written content (the "baselines").
-//   3. At session end, sync compares current file hash against its baseline.
+//   3. Every sync (session end AND on-edit) compares each file's hash against
+//      its baseline.
 //      - Hash matches → file untouched by the agent → skip sync (preserves
 //        any DB-side edits Lead made during the session).
 //      - Hash differs → agent modified the file → sync it back to DB.
+//   4. After the API accepts a file, its baseline advances to the synced hash,
+//      so a file edited once is not re-sent over a later DB-side edit.
 // ──────────────────────────────────────────────────────────────────────────
 export const IDENTITY_BASELINES_PATH = "/tmp/identity-baselines.json";
 
@@ -337,8 +341,71 @@ export async function prependProfileSyncRejectionBanner(
     : { prompt, injected: false };
 }
 
+/**
+ * Serializes every read-modify-write of IDENTITY_BASELINES_PATH across
+ * processes: the runner, the Claude hook and the pi extension each advance it,
+ * and two unserialized advances drop one another's hashes.
+ */
+export const IDENTITY_BASELINES_LOCK_PATH = `${IDENTITY_BASELINES_PATH}.lock`;
+/** The baselines critical section is one small read and write; wait this long for it. */
+const BASELINES_LOCK_WAIT_MS = 5_000;
+
+/** Profile-file IO, injectable so tests never touch the real workspace. */
+export interface ProfileFileIO {
+  readFile: FileReader;
+  writeFile: FileWriter;
+  /** Lock for baseline updates; defaults to IDENTITY_BASELINES_LOCK_PATH. */
+  baselinesLockPath?: string;
+}
+
+export const PROFILE_FILE_IO: ProfileFileIO = {
+  readFile: readFileIfExists,
+  writeFile: writeFileAtomic,
+};
+
+/**
+ * Replace the baselines at boot. Taken under the baselines lock so an advance
+ * still in flight from an earlier session cannot reapply its pre-boot read; if
+ * the lock is unavailable the boot baselines are written anyway.
+ */
 export async function writeIdentityBaselines(baselines: IdentityBaselines): Promise<void> {
-  await Bun.write(IDENTITY_BASELINES_PATH, JSON.stringify(baselines));
+  const write = () => writeFileAtomic(IDENTITY_BASELINES_PATH, JSON.stringify(baselines));
+  const locked = await withFileLock(IDENTITY_BASELINES_LOCK_PATH, write, {
+    waitMs: BASELINES_LOCK_WAIT_MS,
+  });
+  if (!locked.acquired) await write();
+}
+
+/**
+ * The baselines the runner records at boot: the hash of each DB value the
+ * workspace file now derives from. An empty HEARTBEAT.md is a valid DB value
+ * and is never rewritten at boot, so it is baselined too; otherwise the empty
+ * file that survives a restart would count as an edit and be sent over a later
+ * DB edit. The setup script is baselined from the entrypoint-composed file.
+ */
+export function bootIdentityBaselines(
+  profile: {
+    soulMd?: string;
+    identityMd?: string;
+    toolsMd?: string;
+    heartbeatMd?: string | null;
+    claudeMd?: string;
+  },
+  setupScriptFile: string | undefined,
+  agentId = "unknown",
+): IdentityBaselines {
+  const baselines: IdentityBaselines = {};
+  if (profile.soulMd) baselines.soulMd = contentSha256(profile.soulMd);
+  if (profile.identityMd) baselines.identityMd = contentSha256(profile.identityMd);
+  if (profile.toolsMd) baselines.toolsMd = contentSha256(profile.toolsMd);
+  if (typeof profile.heartbeatMd === "string") {
+    baselines.heartbeatMd = contentSha256(profile.heartbeatMd);
+  }
+  if (profile.claudeMd) baselines.claudeMd = contentSha256(profile.claudeMd);
+  const setupContent =
+    setupScriptFile === undefined ? null : extractSetupScriptContent(setupScriptFile, agentId);
+  if (setupContent) baselines.setupScript = contentSha256(setupContent);
+  return baselines;
 }
 
 export async function readIdentityBaselines(
@@ -353,6 +420,42 @@ export async function readIdentityBaselines(
   }
 }
 
+/**
+ * Record the hashes of profile files the API just accepted: the DB now holds
+ * that content, so the same bytes on disk are no longer an edit. The update
+ * runs under IDENTITY_BASELINES_LOCK_PATH so concurrent syncs never drop each
+ * other's hashes. Best effort: on failure the older baselines stay (logged).
+ */
+export async function advanceIdentityBaselines(
+  synced: Record<string, string>,
+  io: ProfileFileIO = PROFILE_FILE_IO,
+): Promise<void> {
+  if (Object.keys(synced).length === 0) return;
+  const update = async () => {
+    const baselines = (await readIdentityBaselines(io.readFile)) ?? {};
+    for (const [field, content] of Object.entries(synced)) {
+      baselines[field] = contentSha256(content);
+    }
+    await io.writeFile(IDENTITY_BASELINES_PATH, JSON.stringify(baselines));
+  };
+  try {
+    const locked = await withFileLock(
+      io.baselinesLockPath ?? IDENTITY_BASELINES_LOCK_PATH,
+      update,
+      {
+        waitMs: BASELINES_LOCK_WAIT_MS,
+      },
+    );
+    if (locked.acquired) return;
+    // No flock on this platform: nothing else can serialize it, so update anyway.
+    if (locked.reason === "unsupported") return await update();
+    console.warn(`[profile-sync] identity baselines not advanced: lock ${locked.reason}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(scrubSecrets(`[profile-sync] identity baselines not advanced: ${msg}`));
+  }
+}
+
 /**
  * Claude Code's personal-file CLAUDE.md path. This is what the Claude plugin
  * Stop hook reads and owns — the runner only uses it as a backstop for an
@@ -581,6 +684,8 @@ export interface ProfileSyncOptions {
   claudeMdLock?: { path?: string; waitMs?: number };
   /** Injectable fetch for tests. Defaults to the global `fetch`. */
   fetchImpl?: typeof fetch;
+  /** Injectable profile-file IO for tests. Defaults to the worker's FS. */
+  io?: ProfileFileIO;
 }
 
 /**
@@ -658,7 +763,7 @@ export function extractSetupScriptContent(raw: string, agentId = "unknown"): str
  *
  * When `baselines` is provided, skips any field whose content hash matches the
  * baseline (i.e. the file was not modified during the session). This prevents
- * session-end sync from clobbering DB-side edits made by Lead.
+ * a sync from clobbering DB-side edits made by Lead.
  */
 export function buildIdentityPayload(
   files: {
@@ -729,7 +834,7 @@ export function buildIdentityPayload(
 export type FileReader = (path: string) => Promise<string | undefined>;
 
 /** Default file reader — reads from the worker's local FS via Bun. */
-async function readFileIfExists(path: string): Promise<string | undefined> {
+export async function readFileIfExists(path: string): Promise<string | undefined> {
   try {
     const file = Bun.file(path);
     if (!(await file.exists())) return undefined;
@@ -739,6 +844,16 @@ async function readFileIfExists(path: string): Promise<string | undefined> {
   }
 }
 
+/** Writes a file's text. */
+export type FileWriter = (path: string, content: string) => Promise<void>;
+
+/** Write via a temp file and rename, so a concurrent reader never sees a partial file. */
+async function writeFileAtomic(path: string, content: string): Promise<void> {
+  const tmp = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  await Bun.write(tmp, content);
+  await rename(tmp, path);
+}
+
 /**
  * Compare the five local profile markdown files with the authenticated agent's
  * stored DB values. This must run inside the agent's local environment; a
@@ -788,11 +903,11 @@ export async function auditProfileDivergences(
  * `fields` selects which groups to include. The file reader is injectable so
  * the field-selection / guard logic can be unit-tested without touching the FS.
  *
- * When `changeSource` is `"session_sync"`, loads baseline hashes written at
- * session start and skips identity fields whose content hasn't changed — this
- * prevents blind-overwriting DB-side edits made by Lead during the session.
- * On-edit syncs (`"self_edit"`) bypass baselines entirely since the agent
- * explicitly changed the file and the new content should propagate.
+ * Loads the baseline hashes and skips identity fields and the setup script
+ * whose content hasn't changed — this prevents blind-overwriting DB-side edits
+ * made by Lead during the session. That holds for on-edit syncs
+ * (`"self_edit"`) too: an edit to one file triggers a sync of every identity
+ * file, and the untouched ones still hold the boot-time copy.
  */
 export async function collectProfilePayloads(
   fields: ProfileSyncField[],
@@ -803,7 +918,7 @@ export async function collectProfilePayloads(
 ): Promise<ProfilePayload[]> {
   const payloads: ProfilePayload[] = [];
 
-  const baselines = changeSource === "session_sync" ? await readIdentityBaselines(readFile) : null;
+  const baselines = await readIdentityBaselines(readFile);
 
   if (fields.includes("identity")) {
     const updates = buildIdentityPayload(
@@ -843,7 +958,7 @@ export async function collectProfilePayloads(
     const raw = await readFile(SETUP_SCRIPT_PATH);
     if (raw !== undefined) {
       const content = extractSetupScriptContent(raw, agentId);
-      if (content !== null) {
+      if (content !== null && baselines?.setupScript !== contentSha256(content)) {
         payloads.push({ label: "setup", body: { setupScript: content, changeSource } });
       }
     }
@@ -855,12 +970,13 @@ export async function collectProfilePayloads(
 /**
  * POST a single profile update. NON-FATAL but VISIBLE: a non-2xx response or a
  * thrown error is logged (scrubbed) and swallowed so it never fails the task,
- * but — unlike the original copies — it is never silently ignored.
+ * but — unlike the original copies — it is never silently ignored. Resolves to
+ * whether the API accepted it.
  */
 export async function postProfileUpdate(
   opts: Pick<ProfileSyncOptions, "agentId" | "apiUrl" | "apiKey" | "fetchImpl">,
   payload: ProfilePayload,
-): Promise<void> {
+): Promise<boolean> {
   const doFetch = opts.fetchImpl ?? fetch;
   try {
     const resp = await doFetch(`${opts.apiUrl}/api/agents/${opts.agentId}/profile`, {
@@ -885,10 +1001,26 @@ export async function postProfileUpdate(
         ),
       );
     }
+    return resp.ok;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.warn(scrubSecrets(`[profile-sync] ${payload.label} sync errored: ${msg}`));
+    return false;
+  }
+}
+
+/**
+ * The baseline-tracked profile fields a payload carried. Only for payloads sent
+ * outside the CLAUDE.md lock: the hook-owned personal CLAUDE.md keeps its own
+ * lineage record, but an unconditional CLAUDE.md sync (the workspace copy, or a
+ * self_edit) is tracked by its baseline like every other file.
+ */
+function baselineFieldsOf(payload: ProfilePayload): Record<string, string> {
+  const fields: Record<string, string> = {};
+  for (const [field, value] of Object.entries(payload.body)) {
+    if (field !== "changeSource" && typeof value === "string") fields[field] = value;
   }
+  return fields;
 }
 
 /**
@@ -912,16 +1044,19 @@ export async function syncProfileFilesToServer(opts: ProfileSyncOptions): Promis
     fields.includes("claude") && syncsHookOwnedClaudeMd(claudeMdPath, changeSource);
   const unlockedFields = claudeUnderLock ? fields.filter((f) => f !== "claude") : fields;
 
+  const io = opts.io ?? PROFILE_FILE_IO;
   const payloads = await collectProfilePayloads(
     unlockedFields,
     changeSource,
-    readFileIfExists,
+    io.readFile,
     claudeMdPath,
     opts.agentId,
   );
+  const synced: Record<string, string> = {};
   for (const payload of payloads) {
-    await postProfileUpdate(opts, payload);
+    if (await postProfileUpdate(opts, payload)) Object.assign(synced, baselineFieldsOf(payload));
   }
+  await advanceIdentityBaselines(synced, io);
 
   if (claudeUnderLock) {
     const { path: lockPath = CLAUDE_MD_LOCK_PATH, waitMs = RUNNER_LOCK_WAIT_MS } =
@@ -933,7 +1068,7 @@ export async function syncProfileFilesToServer(opts: ProfileSyncOptions): Promis
         const claude = await collectProfilePayloads(
           ["claude"],
           changeSource,
-          readFileIfExists,
+          io.readFile,
           claudeMdPath,
           opts.agentId,
         );

package/src/commands/runner.ts

@@ -135,7 +135,7 @@ import {
 } from "./credential-wait.ts";
 import { refreshIdentityIfChanged } from "./identity-refresh.ts";
 import {
-  contentSha256,
+  bootIdentityBaselines,
   prependProfileSyncRejectionBanner,
   resolveClaudeMdPath,
   syncProfileFilesToServer,
@@ -6779,12 +6779,20 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   // are skipped, which prevents clobbering DB-side edits made by Lead via
   // update-profile during the running session.
   try {
-    const baselines: Record<string, string> = {};
-    if (agentSoulMd) baselines.soulMd = contentSha256(agentSoulMd);
-    if (agentIdentityMd) baselines.identityMd = contentSha256(agentIdentityMd);
-    if (agentToolsMd) baselines.toolsMd = contentSha256(agentToolsMd);
-    if (agentHeartbeatMd) baselines.heartbeatMd = contentSha256(agentHeartbeatMd);
-    if (agentClaudeMd) baselines.claudeMd = contentSha256(agentClaudeMd);
+    // start-up.sh is not rewritten here when it exists: the entrypoint composed
+    // it from the DB at container start, so its agent-managed section is the base.
+    const setupFile = Bun.file("/workspace/start-up.sh");
+    const baselines = bootIdentityBaselines(
+      {
+        soulMd: agentSoulMd,
+        identityMd: agentIdentityMd,
+        toolsMd: agentToolsMd,
+        heartbeatMd: agentHeartbeatMd,
+        claudeMd: agentClaudeMd,
+      },
+      (await setupFile.exists()) ? await setupFile.text() : undefined,
+      agentId,
+    );
     await writeIdentityBaselines(baselines);
     console.log(`[${role}] Recorded identity file baselines for session-end sync`);
   } catch {

package/src/hooks/hook.ts

@@ -11,6 +11,7 @@ import {
 } from "../be/memory/raters/llm";
 import { materializeClaudeMd, stopClaudeMd } from "../commands/claude-md-session";
 import {
+  advanceIdentityBaselines,
   buildIndependentIdentityPayloads,
   contentSha256,
   fetchWithSyncTimeout,
@@ -148,7 +149,7 @@ export async function postHookProfileUpdate({
   body: ProfilePayload["body"];
   label: string;
   fetchImpl?: typeof fetch;
-}): Promise<void> {
+}): Promise<boolean> {
   try {
     const response = await fetchImpl(url, {
       method: "PUT",
@@ -166,9 +167,11 @@ export async function postHookProfileUpdate({
         ),
       );
     }
+    return response.ok;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(scrubSecrets(`[hook] ${label} profile sync errored: ${message}`));
+    return false;
   }
 }
 
@@ -676,10 +679,10 @@ export async function handleHook(): Promise<void> {
   /**
    * Sync SOUL.md and IDENTITY.md content back to the server.
    *
-   * When `changeSource` is `"session_sync"` (the Stop-hook default), loads
-   * baseline hashes written at session start and skips any file whose content
-   * hasn't changed. This prevents the session-end sync from clobbering DB-side
-   * edits that Lead made via `update-profile` during the running session.
+   * Loads the baseline hashes and skips any file whose content hasn't changed.
+   * This prevents clobbering DB-side edits that Lead made via `update-profile`
+   * during the running session: at Stop, and on a `"self_edit"` too, where an
+   * edit to one file re-reads all four.
    */
   const syncIdentityFilesToServer = async (
     agentId: string,
@@ -687,7 +690,7 @@ export async function handleHook(): Promise<void> {
   ): Promise<void> => {
     if (!mcpConfig) return;
 
-    const baselines = changeSource === "session_sync" ? await readIdentityBaselines() : null;
+    const baselines = await readIdentityBaselines();
 
     const updates: Record<string, string> = {};
 
@@ -747,14 +750,19 @@ export async function handleHook(): Promise<void> {
 
     if (Object.keys(updates).length === 0) return;
 
-    for (const payload of buildIndependentIdentityPayloads(updates, changeSource)) {
-      await postHookProfileUpdate({
+    const synced: Record<string, string> = {};
+    for (const [field, value] of Object.entries(updates)) {
+      const [payload] = buildIndependentIdentityPayloads({ [field]: value }, changeSource);
+      if (!payload) continue;
+      const ok = await postHookProfileUpdate({
         url: `${getBaseUrl()}/api/agents/${agentId}/profile`,
         headers: mcpConfig.headers,
         body: payload.body,
         label: payload.label,
       });
+      if (ok) synced[field] = value;
     }
+    await advanceIdentityBaselines(synced);
   };
 
   /**
@@ -792,9 +800,11 @@ export async function handleHook(): Promise<void> {
       warnProfileFileTooLarge(agentId, "setupScript", content.length, "hook");
       return;
     }
+    // Unchanged since it last matched the DB: not an edit, so don't send it.
+    if ((await readIdentityBaselines())?.setupScript === contentSha256(content)) return;
 
     try {
-      await fetch(`${getBaseUrl()}/api/agents/${agentId}/profile`, {
+      const resp = await fetch(`${getBaseUrl()}/api/agents/${agentId}/profile`, {
         method: "PUT",
         headers: {
           ...mcpConfig.headers,
@@ -802,6 +812,7 @@ export async function handleHook(): Promise<void> {
         },
         body: JSON.stringify({ setupScript: content, changeSource }),
       });
+      if (resp.ok) await advanceIdentityBaselines({ setupScript: content });
     } catch {
       /* silently fail */
     }

package/src/http/index.ts

@@ -33,6 +33,7 @@ import { startRuntimeSupervisor, stopRuntimeSupervisor } from "../be/runtime-poo
 import { startScratchScriptGc, stopScratchScriptGc } from "../be/scripts/retention";
 import { loadSecretRegistry } from "../be/secret-registry";
 import { seedLegacyCapabilitiesConfig } from "../be/seed-capabilities";
+import { startTaskAutoTitleListener } from "../be/task-auto-title-listener";
 import { initApiTelemetry } from "../be/telemetry-enable";
 import { startWorkerNudgeListener } from "../be/worker-nudge-listener";
 import { initBitbucket } from "../bitbucket";
@@ -465,6 +466,7 @@ const detachRealtime = attachRealtimeTransport(httpServer);
 const { attachControllerTransport } = await import("./controllers-connect");
 const detachControllers = attachControllerTransport(httpServer);
 const stopWorkerNudges = startWorkerNudgeListener();
+const taskAutoTitles = startTaskAutoTitleListener();
 const stopRoomDeletion = realtimeBus.subscribe("room:namespace-deleted", (namespace) => {
   void Promise.resolve(removeNamespaceRooms(String(namespace))).catch((error) =>
     console.error("[rooms] Deletion failed:", scrubSecrets(String(error))),
@@ -474,6 +476,7 @@ globalState.__closeRealtime = () => {
   detachRealtime();
   detachControllers();
   stopWorkerNudges();
+  taskAutoTitles.stop();
   stopRoomDeletion();
 };
 globalState.__httpServer = httpServer;
@@ -877,7 +880,7 @@ httpServer
     // Delete expired MCP overflow values (10-min tick, off the spill path)
     startMcpOverflowSweep();
 
-    // Start expired-memory garbage collector (1-hour tick, immediate first run)
+    // Start expired-memory garbage collector (1-hour tick, first run 2 min after boot)
     await startMemoryGc();
 
     // Start the opt-in DB retention sweep after config hydration. Every key is

package/src/http/list-total-cache.ts

@@ -3,8 +3,11 @@
  *
  * A list total is a COUNT over the same filters as the page, and on the large
  * tables behind the sessions and task lists it costs as much as the page
- * itself. Page 1 (offset 0) always counts, so a write (a new session, a
- * triage move) shows at once where the user looks first. Later pages reuse
+ * itself. By default page 1 (offset 0) always counts, so a write (a new
+ * session, a triage move) shows at once where the user looks first. A list
+ * whose count is expensive and whose total may lag can pass
+ * `firstPageTtlMs`: page 1 then reuses a count younger than that, so
+ * dashboard tabs that poll the same list share one count. Later pages reuse
  * that count for 30 s. A cold later page (deep link, expired entry) counts
  * too, so `total` is always set.
  */
@@ -13,7 +16,7 @@ export const LIST_TOTAL_TTL_MS = 30_000;
 const MAX_ENTRIES = 500;
 
 interface Entry {
-  expiresAt: number;
+  countedAt: number;
   total: Promise<number>;
 }
 
@@ -34,19 +37,23 @@ function filterKey(value: unknown): string {
   );
 }
 
-export function createListTotalCache(ttlMs = LIST_TOTAL_TTL_MS): ListTotalCache {
+export function createListTotalCache(
+  ttlMs = LIST_TOTAL_TTL_MS,
+  firstPageTtlMs = 0,
+): ListTotalCache {
   const entries = new Map<string, Entry>();
   return {
     get(filters, offset, compute) {
       const key = filterKey(filters);
       const now = Date.now();
       const hit = entries.get(key);
-      if (hit && hit.expiresAt > now && (offset ?? 0) > 0) return hit.total;
+      const maxAge = (offset ?? 0) > 0 ? ttlMs : Math.min(ttlMs, firstPageTtlMs);
+      if (hit && hit.countedAt + maxAge > now) return hit.total;
       if (hit) entries.delete(key);
 
-      // Cache the promise, so a later page that arrives mid-count shares it.
+      // Cache the promise, so a request that arrives mid-count shares it.
       const total = compute();
-      entries.set(key, { expiresAt: now + ttlMs, total });
+      entries.set(key, { countedAt: now, total });
       total.catch(() => {
         if (entries.get(key)?.total === total) entries.delete(key);
       });

package/src/http/memory.ts

@@ -1568,17 +1568,31 @@ const MEMORY_GC_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 let memoryGcTimer: ReturnType<typeof setInterval> | null = null;
 
 const SEARCH_RETRIEVAL_TTL_DAYS = 90;
+/** Rows per purge statement. The purge yields the event loop between batches. */
+const SEARCH_RETRIEVAL_PURGE_BATCH = 2000;
 
-async function purgeStaleSearchRetrievals(): Promise<number> {
+export async function purgeStaleSearchRetrievals(
+  batchSize = SEARCH_RETRIEVAL_PURGE_BATCH,
+): Promise<number> {
   try {
     const cutoff = new Date(
       Date.now() - SEARCH_RETRIEVAL_TTL_DAYS * 24 * 60 * 60 * 1000,
     ).toISOString();
-    const result = await getDbClient().run(
-      "DELETE FROM memory_retrieval WHERE eventType = 'search' AND retrievedAt < ?",
-      [cutoff],
-    );
-    return result.changes;
+    let purged = 0;
+    for (;;) {
+      // `+eventType` keeps the planner on the retrievedAt range. Without
+      // sqlite_stat1 it prefers the eventType equality, which reads every
+      // search row to test its date, even when nothing is stale.
+      const result = await getDbClient().run(
+        `DELETE FROM memory_retrieval WHERE rowid IN (
+          SELECT rowid FROM memory_retrieval
+          WHERE +eventType = 'search' AND retrievedAt < ? LIMIT ?)`,
+        [cutoff, batchSize],
+      );
+      purged += result.changes;
+      if (result.changes < batchSize) return purged;
+      await new Promise<void>((resolve) => setImmediate(resolve));
+    }
   } catch (err) {
     console.error("[memory-gc] Search retrieval purge failed:", (err as Error).message);
     return 0;
@@ -1602,11 +1616,22 @@ async function runMemoryGcTick(label: "Initial" | "Periodic"): Promise<void> {
   }
 }
 
-export async function startMemoryGc(intervalMs = MEMORY_GC_INTERVAL_MS): Promise<void> {
+/** The first purge waits this long, so it does not compete with boot work. */
+const MEMORY_GC_INITIAL_DELAY_MS = 2 * 60 * 1000;
+let memoryGcInitialTimer: ReturnType<typeof setTimeout> | null = null;
+
+export async function startMemoryGc(
+  intervalMs = MEMORY_GC_INTERVAL_MS,
+  initialDelayMs = MEMORY_GC_INITIAL_DELAY_MS,
+): Promise<void> {
   if (memoryGcTimer) return;
 
-  // Run immediately on startup to clear any backlog
-  await runMemoryGcTick("Initial");
+  // Clear any backlog soon after startup, but off the boot path.
+  memoryGcInitialTimer = setTimeout(() => {
+    memoryGcInitialTimer = null;
+    void runMemoryGcTick("Initial");
+  }, initialDelayMs);
+  if (typeof memoryGcInitialTimer?.unref === "function") memoryGcInitialTimer.unref();
 
   memoryGcTimer = setInterval(() => {
     void runMemoryGcTick("Periodic");
@@ -1615,6 +1640,10 @@ export async function startMemoryGc(intervalMs = MEMORY_GC_INTERVAL_MS): Promise
 }
 
 export function stopMemoryGc(): void {
+  if (memoryGcInitialTimer) {
+    clearTimeout(memoryGcInitialTimer);
+    memoryGcInitialTimer = null;
+  }
   if (memoryGcTimer) {
     clearInterval(memoryGcTimer);
     memoryGcTimer = null;