@desplega.ai/agent-swarm 2.7.4 → 2.7.6

package/src/be/db.ts

@@ -313,7 +313,11 @@ export {
   getContextVersionHistory,
   getLatestContextVersion,
 } from "./db/context-versions";
-export { getScriptRunExecutionArgs } from "./db/script-runs";
+export {
+  getScriptRunExecutionArgs,
+  getScriptRunFollowUpGuard,
+  setScriptRunFollowUpGuard,
+} from "./db/script-runs";
 export {
   AssetKeyMovesBlockedError,
   assertAssetKeyMovesAllowed,
@@ -336,12 +340,14 @@ export {
 } from "./db/runtime";
 
 export {
+  countAgentDispatchesInThread,
   type ExistingTrackerContextWork,
   type ExistingTrackerContextWorkReason,
   findActiveTasksByVcs,
-  findCompletedTaskInThread,
+  findCompletedTasksInThread,
   findExistingLinearTrackerContextWork,
   findRecentCancelledTaskInThread,
+  findRecentFailedTaskInThread,
   findTaskByGitHub,
   findTaskByVcs,
   getAgentCurrentTask,
@@ -6283,7 +6289,7 @@ export interface UpdateScheduledTaskData {
   description?: string;
   cronExpression?: string | null;
   intervalMs?: number | null;
-  taskTemplate?: string;
+  taskTemplate?: string | null;
   taskType?: string;
   tags?: string[];
   priority?: number;
@@ -13073,6 +13079,9 @@ export async function listRecentSessions(
 ): Promise<SessionListItem[] | SessionListItemSummary[]> {
   const query = sessionSummaryQuery(opts);
   const threadRoots = threadRootsSql();
+  const order = (a: string) =>
+    `${opts.triage === "later" ? `${a}.snoozeUntil ASC,` : ""}
+    ${a}.lastActivityAt DESC, ${a}.rootCreatedAt DESC, ${a}.root_id DESC`;
   const rootRows = await getDbClient().query<
     AgentTaskRow & {
       __chainCount: number;
@@ -13084,13 +13093,14 @@ export async function listRecentSessions(
       __threadRoots: number;
     }
   >(
+    // Page first on the summaries, then read agent_tasks for the page roots only.
     `SELECT r.*, a.chainCount AS __chainCount, a.lastActivityAt AS __lastActivityAt,
       a.latestStatus AS __latestStatus, a.readState AS __readState,
       a.snoozeUntil AS __snoozeUntil, a.needsYou AS __needsYou,
       ${threadRoots.sql} AS __threadRoots
-    FROM (${query.sql}) a CROSS JOIN agent_tasks r ON r.id = a.root_id
-    ORDER BY ${opts.triage === "later" ? "a.snoozeUntil ASC," : ""}
-      a.lastActivityAt DESC, r.createdAt DESC, r.id DESC LIMIT ? OFFSET ?`,
+    FROM (SELECT * FROM (${query.sql}) page ORDER BY ${order("page")} LIMIT ? OFFSET ?) a
+    CROSS JOIN agent_tasks r ON r.id = a.root_id
+    ORDER BY ${order("a")}`,
     [...threadRoots.params, ...query.params, opts.limit ?? 25, opts.offset ?? 0],
   );
   const fields = await sessionPageFields(
@@ -14112,6 +14122,7 @@ type ScriptRunRow = {
   last_heartbeat_at: string | null;
   idempotencyKey: string | null;
   requestedByUserId: string | null;
+  sourceTaskId: string | null;
   created_by: string | null;
   updated_by: string | null;
 };
@@ -14156,6 +14167,7 @@ function rowToScriptRun(row: ScriptRunRow): ScriptRun {
     lastHeartbeatAt: row.last_heartbeat_at ?? undefined,
     idempotencyKey: row.idempotencyKey ?? undefined,
     requestedByUserId: row.requestedByUserId ?? undefined,
+    sourceTaskId: row.sourceTaskId ?? undefined,
   };
 }
 
@@ -14184,6 +14196,7 @@ export async function createScriptRun(data: {
   scriptName?: string;
   idempotencyKey?: string;
   requestedByUserId?: string;
+  sourceTaskId?: string;
   createdBy?: string;
   updatedBy?: string;
 }): Promise<{ run: ScriptRun; existing: boolean }> {
@@ -14198,8 +14211,9 @@ export async function createScriptRun(data: {
 
   const row = await client.get<ScriptRunRow>(
     `INSERT INTO script_runs
-        (id, agentId, scriptName, source, args, idempotencyKey, requestedByUserId, created_by, updated_by)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        (id, agentId, scriptName, source, args, idempotencyKey, requestedByUserId, sourceTaskId,
+         created_by, updated_by)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
        RETURNING *`,
     [
       data.id,
@@ -14212,6 +14226,7 @@ export async function createScriptRun(data: {
       sealJson(data.args ?? null),
       data.idempotencyKey ?? null,
       data.requestedByUserId ?? null,
+      data.sourceTaskId ?? null,
       data.createdBy ?? null,
       data.updatedBy ?? data.createdBy ?? null,
     ],

package/src/be/memory/providers/sqlite-store.ts

@@ -45,14 +45,18 @@ function armFetchLimit(limit: number): number {
 // lookup against it is a full table scan per outer row. The old backfill used
 // `WHERE NOT EXISTS (SELECT 1 FROM memory_fts f WHERE f.memory_id = m.id)`,
 // which is N x N: at ~18k memories it held the main connection for minutes at
-// boot. Both statements below use a non-correlated `NOT IN (subquery)`, which
-// SQLite evaluates once into an ephemeral index, so each is one pass over each
-// table. `memory_id IS NOT NULL` keeps a stray NULL row from turning every
-// NOT IN into NULL (which would insert nothing).
-export const FTS_DELETE_EXTRA_SQL = `DELETE FROM memory_fts
-  WHERE memory_id NOT IN (SELECT id FROM agent_memory)`;
-export const FTS_MISSING_IDS_SQL = `SELECT m.id FROM agent_memory m
-  WHERE m.id NOT IN (SELECT memory_id FROM memory_fts WHERE memory_id IS NOT NULL)`;
+// boot. The diff below reads each table once, in rowid batches (FTS5 seeks a
+// rowid range), and yields the event loop between batches: one whole-table
+// statement held the loop for seconds on a large DB. A memory_fts row is an
+// orphan when its memory is gone; that check is a lookup on the agent_memory
+// primary key. A NULL memory_id is never an orphan, as with the old NOT IN.
+export const FTS_SCAN_BATCH_SQL = `SELECT rowid AS rowid, memory_id AS memoryId,
+  memory_id IS NOT NULL
+    AND NOT EXISTS (SELECT 1 FROM agent_memory m WHERE m.id = memory_fts.memory_id) AS orphan
+  FROM memory_fts WHERE rowid > ? ORDER BY rowid LIMIT ?`;
+export const MEMORY_ID_BATCH_SQL = `SELECT rowid AS rowid, id FROM agent_memory
+  WHERE rowid > ? ORDER BY rowid LIMIT ?`;
+const FTS_SCAN_BATCH_SIZE = 1000;
 const FTS_POPULATE_BATCH_SIZE = 500;
 
 export type AgentMemoryRow = {
@@ -251,12 +255,45 @@ export class SqliteMemoryStore implements MemoryStore {
   private async populateFtsTable(): Promise<void> {
     const client = getDbClient();
     const startedAt = performance.now();
-    const deletedExtra = await client.run(FTS_DELETE_EXTRA_SQL);
-    if (deletedExtra.changes > 0) {
-      console.warn(`[memory-fts] removed_extra_rows count=${deletedExtra.changes}`);
+    const yieldLoop = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+    // Drop orphan rows and collect the memory ids the index holds.
+    const indexed = new Set<string>();
+    let removed = 0;
+    for (let after = 0; ; ) {
+      const rows = await client.query<{ rowid: number; memoryId: string | null; orphan: number }>(
+        FTS_SCAN_BATCH_SQL,
+        [after, FTS_SCAN_BATCH_SIZE],
+      );
+      if (rows.length === 0) break;
+      after = rows[rows.length - 1]!.rowid;
+      const orphans = rows.filter((row) => row.orphan).map((row) => row.rowid);
+      if (orphans.length > 0) {
+        await client.run(
+          `DELETE FROM memory_fts WHERE rowid IN (${orphans.map(() => "?").join(",")})`,
+          orphans,
+        );
+        removed += orphans.length;
+      }
+      for (const row of rows) if (!row.orphan && row.memoryId) indexed.add(row.memoryId);
+      await yieldLoop();
+    }
+    if (removed > 0) {
+      console.warn(`[memory-fts] removed_extra_rows count=${removed}`);
+    }
+
+    const missing: { id: string }[] = [];
+    for (let after = 0; ; ) {
+      const rows = await client.query<{ rowid: number; id: string }>(MEMORY_ID_BATCH_SQL, [
+        after,
+        FTS_SCAN_BATCH_SIZE,
+      ]);
+      if (rows.length === 0) break;
+      after = rows[rows.length - 1]!.rowid;
+      for (const row of rows) if (!indexed.has(row.id)) missing.push(row);
+      await yieldLoop();
     }
 
-    const missing = await client.query<{ id: string }>(FTS_MISSING_IDS_SQL);
     for (let i = 0; i < missing.length; i += FTS_POPULATE_BATCH_SIZE) {
       const ids = missing.slice(i, i + FTS_POPULATE_BATCH_SIZE).map((row) => row.id);
       const placeholders = ids.map(() => "?").join(",");

package/src/be/migrations/259_session_summaries_open_tasks.sql

@@ -0,0 +1,111 @@
+-- What the session read path needs from session_summaries (migration 253):
+-- the key and source indexes its filters use, and openTaskCount, the number
+-- of chain tasks that are not finished (status outside completed, failed,
+-- cancelled, superseded).
+--
+-- Auto-Done (src/be/db/session-tree.ts) moves a quiet Inbox session to Done
+-- only when every chain task is finished. The session read path now reads
+-- session_summaries instead of walking the chain, so the summary carries the
+-- count. Same consistency rules as migration 253:
+-- - Inserts add the new task's count incrementally.
+-- - A status change applies its +1 or -1 in a BEFORE trigger. An AFTER
+--   trigger of the same statement that recomputes the chain (a rewound
+--   lastUpdatedAt, a requester or source edit) then overwrites it with the
+--   exact count, so the delta is never applied on top of a recompute.
+-- - session_summary_recompute_apply recomputes it with the other aggregates.
+
+ALTER TABLE session_summaries ADD COLUMN openTaskCount INTEGER NOT NULL DEFAULT 0;
+
+-- The group (key range) and source filters of the list and count. Activity
+-- writes do not touch either column, so neither index costs the hot path.
+CREATE INDEX idx_session_summaries_key ON session_summaries("key");
+CREATE INDEX idx_session_summaries_source ON session_summaries(source);
+
+DROP TRIGGER session_summary_recompute_apply;
+CREATE TRIGGER session_summary_recompute_apply
+INSTEAD OF INSERT ON session_summary_recompute
+BEGIN
+  UPDATE session_summaries SET
+    chainCount = (SELECT COUNT(*) FROM session_members m WHERE m.rootId = NEW.rootId),
+    lastActivityAt = (SELECT MAX(t.lastUpdatedAt) FROM session_members m
+      JOIN agent_tasks t ON t.id = m.taskId WHERE m.rootId = NEW.rootId),
+    latestStatus = (SELECT t.status FROM session_members m
+      JOIN agent_tasks t ON t.id = m.taskId WHERE m.rootId = NEW.rootId
+      ORDER BY t.lastUpdatedAt DESC LIMIT 1),
+    pendingApprovalCount = (SELECT COUNT(*) FROM session_members m
+      JOIN approval_requests ar ON ar.sourceTaskId = m.taskId
+      WHERE m.rootId = NEW.rootId AND ar.status = 'pending'),
+    openTaskCount = (SELECT COUNT(*) FROM session_members m
+      JOIN agent_tasks t ON t.id = m.taskId WHERE m.rootId = NEW.rootId
+      AND t.status NOT IN ('completed', 'failed', 'cancelled', 'superseded')),
+    lastHumanAt = (SELECT MAX(at) FROM (
+      SELECT t.createdAt AS at FROM session_members m JOIN agent_tasks t ON t.id = m.taskId
+      WHERE m.rootId = NEW.rootId AND t.requestedByUserId IS NOT NULL
+        AND t.requestedByUserIdInherited = 0
+        AND COALESCE(t.source, '') NOT IN ('mcp', 'system', 'schedule', 'workflow')
+      UNION ALL
+      SELECT sm.created_at FROM session_members m
+      JOIN task_steering_messages sm ON sm.task_id = m.taskId
+      WHERE m.rootId = NEW.rootId AND sm.created_by_kind = 'user' AND sm.status != 'cancelled'
+      UNION ALL
+      SELECT ar.createdAt FROM session_members m
+      JOIN approval_requests ar ON ar.sourceTaskId = m.taskId
+      WHERE m.rootId = NEW.rootId AND ar.status = 'pending'))
+  WHERE rootId = NEW.rootId
+    AND EXISTS (SELECT 1 FROM agent_tasks WHERE id = NEW.rootId);
+END;
+
+DROP TRIGGER session_task_insert;
+CREATE TRIGGER session_task_insert
+AFTER INSERT ON agent_tasks
+BEGIN
+  INSERT OR REPLACE INTO session_members (taskId, rootId)
+  SELECT NEW.id, NEW.id WHERE NEW.parentTaskId IS NULL
+  UNION ALL
+  SELECT NEW.id, m.rootId FROM session_members m WHERE m.taskId = NEW.parentTaskId;
+
+  INSERT OR REPLACE INTO session_summaries (rootId, createdAt, source, "key", requestedByUserId,
+    scheduleId, taskType, slackChannelId, contextKey, chainCount, lastActivityAt, latestStatus,
+    pendingApprovalCount, openTaskCount, lastHumanAt)
+  SELECT NEW.id, NEW.createdAt, NEW.source, NEW."key", NEW.requestedByUserId, NEW.scheduleId,
+    NEW.taskType, NEW.slackChannelId, NEW.contextKey, 1, NEW.lastUpdatedAt, NEW.status, 0,
+    NEW.status NOT IN ('completed', 'failed', 'cancelled', 'superseded'),
+    CASE WHEN NEW.requestedByUserId IS NOT NULL AND NEW.requestedByUserIdInherited = 0
+      AND COALESCE(NEW.source, '') NOT IN ('mcp', 'system', 'schedule', 'workflow')
+      THEN NEW.createdAt END
+  WHERE NEW.parentTaskId IS NULL;
+
+  UPDATE session_summaries SET
+    chainCount = chainCount + 1,
+    openTaskCount = openTaskCount
+      + (NEW.status NOT IN ('completed', 'failed', 'cancelled', 'superseded')),
+    latestStatus = CASE WHEN NEW.lastUpdatedAt >= lastActivityAt THEN NEW.status ELSE latestStatus END,
+    lastActivityAt = MAX(lastActivityAt, NEW.lastUpdatedAt),
+    lastHumanAt = CASE WHEN NEW.requestedByUserId IS NOT NULL AND NEW.requestedByUserIdInherited = 0
+      AND COALESCE(NEW.source, '') NOT IN ('mcp', 'system', 'schedule', 'workflow')
+      AND (lastHumanAt IS NULL OR NEW.createdAt > lastHumanAt)
+      THEN NEW.createdAt ELSE lastHumanAt END
+  WHERE NEW.parentTaskId IS NOT NULL
+    AND rootId = (SELECT rootId FROM session_members WHERE taskId = NEW.id);
+END;
+
+-- BEFORE, so an AFTER recompute in the same statement has the last word.
+CREATE TRIGGER session_task_open
+BEFORE UPDATE OF status ON agent_tasks
+WHEN (OLD.status NOT IN ('completed', 'failed', 'cancelled', 'superseded'))
+  IS NOT (NEW.status NOT IN ('completed', 'failed', 'cancelled', 'superseded'))
+BEGIN
+  UPDATE session_summaries SET
+    openTaskCount = openTaskCount
+      + CASE WHEN NEW.status NOT IN ('completed', 'failed', 'cancelled', 'superseded') THEN 1 ELSE -1 END
+  WHERE rootId = (SELECT rootId FROM session_members WHERE taskId = NEW.id);
+END;
+
+-- Backfill: one pass over the unfinished tasks.
+UPDATE session_summaries SET openTaskCount = unfinished.n
+FROM (
+  SELECT m.rootId, COUNT(*) AS n FROM agent_tasks t JOIN session_members m ON m.taskId = t.id
+  WHERE t.status NOT IN ('completed', 'failed', 'cancelled', 'superseded')
+  GROUP BY m.rootId
+) AS unfinished
+WHERE unfinished.rootId = session_summaries.rootId;

package/src/be/migrations/260_runtime_pool_cache.sql

@@ -0,0 +1,20 @@
+-- NULL preserves the ephemeral-only behavior of existing pools.
+ALTER TABLE runtime_pools ADD COLUMN cache TEXT
+  CHECK (cache IS NULL OR json_valid(cache));
+
+-- Retain release intent across API restarts and pool deletion.
+CREATE TABLE runtime_cache_releases (
+  id TEXT PRIMARY KEY,
+  pool_id TEXT NOT NULL,
+  controller_id TEXT NOT NULL REFERENCES runtime_controllers(id) ON DELETE RESTRICT,
+  owner_id TEXT NOT NULL,
+  cache_key TEXT NOT NULL,
+  runtime_ids TEXT NOT NULL CHECK (json_valid(runtime_ids) AND json_type(runtime_ids) = 'array'),
+  state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'deleting')),
+  last_error TEXT,
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  created_by TEXT REFERENCES users(id) ON DELETE SET NULL,
+  updated_by TEXT REFERENCES users(id) ON DELETE SET NULL,
+  UNIQUE(controller_id, owner_id, cache_key)
+);

package/src/be/migrations/262_session_visibility_indexes.sql

@@ -0,0 +1,18 @@
+-- Covering indexes for the session visibility walk (readableSessionCondition
+-- in src/be/db/tasks/read.ts). Every task list and count a dashboard user
+-- loads computes the set of tasks in sessions the user cannot read: roots
+-- owned by someone else, plus all their descendants.
+--
+-- agent_tasks rows carry large `task` text, and parentTaskId, scheduleId and
+-- requestedByUserId sit after it, in the overflow pages. Without these
+-- indexes the root step read every unscheduled task row and the recursive
+-- step read the row of every descendant. With them, both steps stay in the
+-- index. Production has no sqlite_stat1; the planner picks both without it.
+
+-- Root step: `scheduleId IS NULL` plus the root, owner and id columns.
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_session_owner
+  ON agent_tasks(scheduleId, parentTaskId, requestedByUserId, id);
+
+-- Recursive step: the children of a hidden task, by id.
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_parentTaskId_id
+  ON agent_tasks(parentTaskId, id);

package/src/be/migrations/263_task_list_filter_index.sql

@@ -0,0 +1,11 @@
+-- Covering index for the default task list count (getTasksCount in
+-- src/be/db/tasks/read.ts). The task list hides heartbeat tasks by default:
+--
+--   IFNULL(taskType, '') NOT IN (...) AND tags NOT LIKE '%"heartbeat"%'
+--
+-- A NOT IN and a NOT LIKE cannot seek, so the count scans. taskType and tags
+-- sit after the large `task` text, in the overflow pages, so the scan read
+-- every task body. This index holds the two filter columns and `id` (the
+-- session visibility filter), so the count scans the index only.
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_list_filter
+  ON agent_tasks(taskType, tags, id);

package/src/be/migrations/264_slack_thread_cover_index.sql

@@ -0,0 +1,9 @@
+-- Covering index for the Slack render-v2 watcher sweep (getSlackTreeMessages
+-- in src/be/db.ts), which runs on every watcher tick, even when idle. For
+-- each stored tree it tests the thread's tasks by createdAt, status, source
+-- and lastUpdatedAt. Those columns sit after the large `task` text, in the
+-- overflow pages, so each test read whole task rows. This index holds them,
+-- so the tests stay in the index. Partial: only Slack tasks carry a channel.
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_slack_thread_cover
+  ON agent_tasks(slackChannelId, slackThreadTs, createdAt, status, source, lastUpdatedAt, id)
+  WHERE slackChannelId IS NOT NULL;

package/src/be/migrations/266_script_runs_source_task.sql

@@ -0,0 +1,11 @@
+-- The task whose session launched a durable script run (the caller's
+-- X-Source-Task-Id, kept only when that task belongs to the launching agent).
+-- The follow-up re-delegation guard reads it when the run's ctx.step.agentTask
+-- dispatches, the same way send-task reads the caller's source task.
+ALTER TABLE script_runs ADD COLUMN sourceTaskId TEXT;
+
+-- The run's follow-up re-delegation guard decision, taken once for the whole
+-- run at its first new step: NULL (not decided yet), 'passed', or the rule that
+-- blocked it ('same-work' or 'loop-cap'). Every later step follows it, so
+-- parallel steps of one run are dispatched all or none.
+ALTER TABLE script_runs ADD COLUMN followUpGuard TEXT;

package/src/be/model-validation.ts

@@ -7,7 +7,8 @@
  *   - a `latest:<provider>/<family>` alias that is valid grammar and resolves to a catalog model;
  *   - a catalog id, bare (`claude-opus-5-5`, `gpt-5.6-sol`) or provider-qualified
  *     (`openrouter/deepseek/deepseek-v4.1-flash`, `amazon-bedrock/...`);
- *   - a Claude CLI shortname (`opus`, `sonnet`, ...), which the CLI resolves itself.
+ *   - a Claude CLI shortname (`opus`, `sonnet`, ...), which the CLI resolves itself;
+ *   - a ChatGPT subscription id `openai-codex/<id>` whose `<id>` is in the `openai` section.
  *
  * Escape hatch: `allowCustomModel: true` on the call (tools, REST bodies, workflow node
  * config, the agent runtime PATCH). Custom ids skip the check and are stored as given, for
@@ -23,6 +24,7 @@
  */
 import {
   buildClaudeShortnameMap,
+  chatgptSubscriptionModelId,
   type HarnessCatalogSections,
   harnessModelMismatch,
   isAlias,
@@ -55,6 +57,8 @@ function hasModel(catalog: CatalogSections, provider: string, modelId: string):
 export function isKnownCatalogModel(model: string, catalog: CatalogSections): boolean {
   const id = model.trim().replace(CONTEXT_SUFFIX_RE, "");
   if (!id) return false;
+  const subscriptionId = chatgptSubscriptionModelId(id);
+  if (subscriptionId) return hasModel(catalog, "openai", subscriptionId);
   const slash = id.indexOf("/");
   if (slash > 0) {
     const provider = id.slice(0, slash);

package/src/be/pricing-normalize.ts

@@ -40,8 +40,9 @@ const ROUTING_PREFIXES_BY_PROVIDER: Record<PricingProvider, readonly string[]> =
   // openai, … — strip whichever proxy prefix the user picked.
   opencode: ["openrouter/", "github-copilot/"],
   // pi-mono can hit openrouter mirrors, the github-copilot proxy, or native
-  // anthropic/openai/google providers.
-  pi: ["openrouter/", "github-copilot/"],
+  // anthropic/openai/google providers. `openai-codex/<id>` is an OpenAI id
+  // served by the ChatGPT subscription pool, priced like codex on that pool.
+  pi: ["openrouter/", "github-copilot/", "openai-codex/"],
   // codex normally reports a bare id, but a user may set MODEL_OVERRIDE to a
   // prefixed form. Be forgiving on the lookup side.
   codex: ["openai/", "github-copilot/"],
@@ -69,6 +70,10 @@ const ROUTING_PREFIXES_BY_PROVIDER: Record<PricingProvider, readonly string[]> =
   // The Grok CLI reports a bare xAI id (`grok-4.6`) or `openrouter/<vendor>/<id>`
   // for an OpenRouter model; stripping the prefix lands it on the openrouter rows.
   grok: ["openrouter/", "xai/"],
+  // fx reports the swarm model string: `openrouter/<vendor>/<id>` (OpenRouter
+  // connection), `vercel/<vendor>/<id>` (AI Gateway) or a bare OpenAI id.
+  // Stripping the route prefix lands the first two on `<vendor>/<id>` rows.
+  fx: ["openrouter/", "vercel/"],
 };
 
 /** `gpt-5-nano-2025-08-07` -> `gpt-5-nano`. Anthropic's 8-digit dates (`-20251001`) are real catalog ids and are left alone. */

package/src/be/runtime-pools/cache-cleanup.ts

@@ -0,0 +1,109 @@
+import type { ControllerCommands } from "../../runtime-providers/controller";
+import { poolCacheKey, type RuntimeCacheReference } from "../../runtime-providers/types";
+import type { RuntimePool } from "../../types";
+import { scrubSecrets } from "../../utils/secret-scrubber";
+import { getDbClient, getSwarmConfigs } from "../db";
+
+/** The stored key is private API metadata; legacy caches retain their original name. */
+export async function getPoolCache(poolId: string): Promise<{
+  key: string;
+  mountPath: string;
+  controllerId: string;
+} | null> {
+  const row = await getDbClient().get<{ cache: string | null; controllerId: string }>(
+    "SELECT cache, json_extract(placements, '$[0]') AS controllerId FROM runtime_pools WHERE id = ?",
+    [poolId],
+  );
+  if (!row?.cache) return null;
+  const cache = JSON.parse(row.cache);
+  return {
+    key: cache.key ?? poolCacheKey(poolId),
+    mountPath: cache.mountPath,
+    controllerId: row.controllerId,
+  };
+}
+
+/** Call in the pool write transaction; no infrastructure calls occur here. */
+export async function queuePoolCacheRelease(
+  pool: RuntimePool,
+  actor: string | null,
+): Promise<void> {
+  if (!pool.cache) return;
+  const owner = (await getSwarmConfigs({ scope: "global", key: "runtime_owner_id" }))[0];
+  // No runtime could have created an owned cache before the owner was allocated.
+  if (!owner) return;
+  const cache = (await getPoolCache(pool.id))!;
+  const runtimes = await getDbClient().query<{ id: string }>(
+    `SELECT id FROM runtime_instances WHERE pool_id = ?
+     AND (controller_id = ? OR controller_id IS NULL) AND status != 'offline'`,
+    [pool.id, pool.placements[0]!],
+  );
+  await getDbClient().run(
+    `INSERT INTO runtime_cache_releases
+      (id, pool_id, controller_id, owner_id, cache_key, runtime_ids, created_by, updated_by)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(controller_id, owner_id, cache_key) DO NOTHING`,
+    [
+      crypto.randomUUID(),
+      pool.id,
+      pool.placements[0]!,
+      owner.value,
+      cache.key,
+      JSON.stringify(runtimes.map((r) => r.id)),
+      actor,
+      actor,
+    ],
+  );
+}
+
+interface CacheRelease extends RuntimeCacheReference {
+  id: string;
+  controllerId: string;
+}
+
+const RELEASE_LEASE_MS = 5 * 60_000;
+
+/** Claims are atomic across reconcilers; all network calls are outside DB transactions. */
+export async function reconcileCacheReleases(
+  commands: (id: string) => Promise<ControllerCommands>,
+  signal: AbortSignal,
+  now?: Date,
+): Promise<void> {
+  const jobs = await getDbClient().query<CacheRelease>(
+    `SELECT id, pool_id AS poolId, controller_id AS controllerId, owner_id AS ownerId,
+     cache_key AS key FROM runtime_cache_releases ORDER BY created_at`,
+  );
+  for (const job of jobs) {
+    if (signal.aborted) return;
+    const claimed = now ?? new Date();
+    const claimedAt = claimed.toISOString();
+    // Reclaim abandoned work after five minutes; generation keys fence late provider calls.
+    const reserved = await getDbClient().run(
+      `UPDATE runtime_cache_releases SET state = 'deleting', updated_at = ?
+       WHERE id = ? AND (state = 'pending' OR updated_at < ?) AND NOT EXISTS (
+         SELECT 1 FROM runtime_instances WHERE status != 'offline'
+         AND id IN (SELECT value FROM json_each(runtime_cache_releases.runtime_ids))
+       )`,
+      [claimedAt, job.id, new Date(claimed.getTime() - RELEASE_LEASE_MS).toISOString()],
+    );
+    if (!reserved.changes) continue;
+    try {
+      signal.throwIfAborted();
+      const controller = await commands(job.controllerId);
+      if (!controller.releaseCache)
+        throw new Error("Controller cannot release caches; upgrade it before cleanup");
+      await controller.releaseCache({ key: job.key, poolId: job.poolId, ownerId: job.ownerId });
+      await getDbClient().run(
+        "DELETE FROM runtime_cache_releases WHERE id = ? AND state = 'deleting' AND updated_at = ?",
+        [job.id, claimedAt],
+      );
+    } catch (error) {
+      const message = scrubSecrets(String(error));
+      await getDbClient().run(
+        `UPDATE runtime_cache_releases SET state = 'pending', last_error = ?, updated_at = ?
+         WHERE id = ? AND state = 'deleting' AND updated_at = ?`,
+        [message, new Date().toISOString(), job.id, claimedAt],
+      );
+      if (!signal.aborted) console.error("[runtime-pools] Cache cleanup deferred:", message);
+    }
+  }
+}