@desplega.ai/agent-swarm 1.113.0 → 1.115.0

package/src/be/mcp-proxy.ts

@@ -0,0 +1,132 @@
+import { getMcpServerById, getResolvedConfig } from "@/be/db";
+import { McpHttpClient, type McpTool, type McpToolCallEnvelope } from "@/mcp-client/http-client";
+import { ensureMcpToken } from "@/oauth/ensure-mcp-token";
+import type { McpServer } from "@/types";
+import { registerVolatileSecret } from "@/utils/secret-scrubber";
+
+const MCP_PROXY_TIMEOUT_MS = 30_000;
+
+function parseHeadersJson(value: string | null): Record<string, string> {
+  if (!value) return {};
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return Object.fromEntries(
+      Object.entries(parsed as Record<string, unknown>)
+        .filter((entry): entry is [string, string] => typeof entry[1] === "string")
+        .map(([key, headerValue]) => [key, headerValue]),
+    );
+  } catch {
+    return {};
+  }
+}
+
+function resolveHeaderConfigKeys(
+  headerConfigKeys: string | null,
+  context: { agentId?: string; repoId?: string },
+): Record<string, string> {
+  if (!headerConfigKeys) return {};
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(headerConfigKeys);
+  } catch {
+    return {};
+  }
+
+  const configs = getResolvedConfig(context.agentId, context.repoId);
+  const configMap = new Map(configs.map((config) => [config.key, config.value]));
+  const resolved: Record<string, string> = {};
+
+  if (Array.isArray(parsed)) {
+    for (const item of parsed) {
+      if (typeof item !== "string") continue;
+      const value = configMap.get(item);
+      if (value === undefined) continue;
+      registerVolatileSecret(value, `mcp-header:${item}`);
+      resolved[item] = value;
+    }
+    return resolved;
+  }
+
+  if (!parsed || typeof parsed !== "object") return resolved;
+  for (const [headerName, configKey] of Object.entries(parsed as Record<string, unknown>)) {
+    if (typeof configKey !== "string") continue;
+    const value = configMap.get(configKey);
+    if (value === undefined) continue;
+    registerVolatileSecret(value, `mcp-header:${configKey}`);
+    resolved[headerName] = value;
+  }
+  return resolved;
+}
+
+async function resolveMcpHeaders(
+  server: McpServer,
+  context: { agentId?: string; repoId?: string },
+): Promise<Record<string, string>> {
+  const headers = {
+    ...parseHeadersJson(server.headers),
+    ...resolveHeaderConfigKeys(server.headerConfigKeys, context),
+  };
+
+  if (server.authMethod !== "oauth") return headers;
+
+  delete headers.Authorization;
+  delete headers.authorization;
+  const token = await ensureMcpToken(server.id);
+  if (!token) throw new Error("No OAuth token for this MCP server");
+  if (token.status !== "connected") {
+    throw new Error(token.lastErrorMessage ?? `OAuth status: ${token.status}`);
+  }
+
+  registerVolatileSecret(token.accessToken, `mcp-oauth:${server.id}`);
+  const rawType = token.tokenType || "Bearer";
+  const prefix = rawType.toLowerCase() === "bearer" ? "Bearer" : rawType;
+  headers.Authorization = `${prefix} ${token.accessToken}`;
+  return headers;
+}
+
+async function createMcpServerClient(
+  serverId: string,
+  context: { agentId?: string; repoId?: string; timeoutMs?: number } = {},
+): Promise<McpHttpClient> {
+  const server = getMcpServerById(serverId);
+  if (!server) throw new Error("MCP server not found");
+  if (!server.isEnabled) throw new Error("MCP server is disabled");
+  if (server.transport === "sse") {
+    throw new Error("SSE MCP servers are not supported yet — use a streamable HTTP server");
+  }
+  if (server.transport !== "http") {
+    throw new Error("Only streamable HTTP MCP servers are supported by script connections");
+  }
+  if (!server.url) throw new Error("MCP server URL is required");
+
+  const client = new McpHttpClient(server.url, "", "", undefined, {
+    clientInfo: { name: "agent-swarm-script-mcp-proxy", version: "1.0.0" },
+    omitEmptyAuthHeaders: true,
+    timeoutMs: context.timeoutMs ?? MCP_PROXY_TIMEOUT_MS,
+  });
+  client.useRawUrl = true;
+  client.customHeaders = await resolveMcpHeaders(server, context);
+  return client;
+}
+
+export async function listMcpServerTools(
+  serverId: string,
+  context: { agentId?: string; repoId?: string; timeoutMs?: number } = {},
+): Promise<McpTool[]> {
+  const client = await createMcpServerClient(serverId, context);
+  await client.initialize();
+  return client.listTools();
+}
+
+export async function callMcpServerTool(
+  serverId: string,
+  tool: string,
+  args: Record<string, unknown>,
+  context: { agentId?: string; repoId?: string; timeoutMs?: number } = {},
+): Promise<McpToolCallEnvelope> {
+  const client = await createMcpServerClient(serverId, context);
+  await client.initialize();
+  return client.callToolRaw(tool, args);
+}

package/src/be/migrations/109_rbac_roles.sql

@@ -0,0 +1,79 @@
+-- RBAC role engine storage (DES-445, increment 3).
+-- Defines durable role grants for authenticated user admission. See the design
+-- note at thoughts/taras/plans/2026-07-07-des-445-rbac-user-policy-admission-model.md.
+--
+-- Trigger fragility: trg_users_default_role depends on the users table. SQLite
+-- silently drops triggers when a table is rebuilt with the create/copy/drop/
+-- rename pattern, so any future users-table rebuild must recreate this trigger.
+-- Phase 2's ensureRbacSeedsSynced boot path intentionally self-heals it as a
+-- backstop, but migrations that rebuild users should still recreate it directly.
+-- Built-in seed conflicts are surfaced by ensureRbacSeedsSynced at boot; that
+-- is fatal when RBAC_ENABLED=true and logged/continued when the flag is off.
+
+CREATE TABLE IF NOT EXISTS roles (
+  id            TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  name          TEXT NOT NULL UNIQUE,
+  description   TEXT,
+  isBuiltin     INTEGER NOT NULL DEFAULT 0,
+  grantsAll     INTEGER NOT NULL DEFAULT 0,
+  createdAt     TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  lastUpdatedAt TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  -- Future role-management API populates audit users; system writers leave NULL.
+  created_by    TEXT REFERENCES users(id),
+  updated_by    TEXT REFERENCES users(id)
+);
+
+CREATE TABLE IF NOT EXISTS role_permissions (
+  roleId    TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
+  verb      TEXT NOT NULL,
+  createdAt TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  -- Future role-management API populates audit users; system writers leave NULL.
+  created_by TEXT REFERENCES users(id),
+  updated_by TEXT REFERENCES users(id),
+  PRIMARY KEY (roleId, verb)
+);
+
+CREATE TABLE IF NOT EXISTS principal_roles (
+  id            TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  principalType TEXT NOT NULL CHECK (principalType IN ('user','agent')),
+  principalId   TEXT NOT NULL,
+  roleId        TEXT NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
+  createdAt     TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  -- Future role-management API populates audit users; system writers leave NULL.
+  created_by    TEXT REFERENCES users(id),
+  updated_by    TEXT REFERENCES users(id),
+  UNIQUE (principalType, principalId, roleId)
+);
+CREATE INDEX IF NOT EXISTS idx_principal_roles_principal
+  ON principal_roles(principalType, principalId);
+
+-- Built-in roles: fixed ids so trigger/backfill SQL and code can reference them.
+INSERT OR IGNORE INTO roles (id, name, description, isBuiltin, grantsAll) VALUES
+  ('rbac-role-admin', 'admin',
+   'Full access including verb-less routes (legacy-equivalent default).', 1, 1),
+  ('rbac-role-requester', 'requester',
+   'Own-task lifecycle: what legacy policy grants user principals.', 1, 0);
+
+-- Initial snapshot of the requester verb-set; code (BUILTIN_ROLES in
+-- src/be/rbac-roles.ts) is authoritative and re-syncs at boot.
+INSERT OR IGNORE INTO role_permissions (roleId, verb) VALUES
+  ('rbac-role-requester', 'task.read.own'),
+  ('rbac-role-requester', 'task.cancel.own'),
+  ('rbac-role-requester', 'task.action.own'),
+  ('rbac-role-requester', 'task.fs.mutate');
+
+-- Backfill: every existing user holds the default role.
+INSERT OR IGNORE INTO principal_roles (principalType, principalId, roleId)
+  SELECT 'user', id, 'rbac-role-admin'
+  FROM users
+  WHERE EXISTS (SELECT 1 FROM roles WHERE id = 'rbac-role-admin');
+
+-- Every future user row (createUser, findOrCreateUserByEmail, raw test
+-- INSERTs) gets the default role atomically.
+CREATE TRIGGER IF NOT EXISTS trg_users_default_role
+AFTER INSERT ON users
+BEGIN
+  INSERT OR IGNORE INTO principal_roles (principalType, principalId, roleId)
+  SELECT 'user', NEW.id, 'rbac-role-admin'
+  WHERE EXISTS (SELECT 1 FROM roles WHERE id = 'rbac-role-admin');
+END;

package/src/be/migrations/111_oauth_credential_bindings.sql

@@ -0,0 +1,6 @@
+ALTER TABLE script_credential_bindings
+  ADD COLUMN auth_kind TEXT NOT NULL DEFAULT 'config'
+  CHECK(auth_kind IN ('config', 'oauth'));
+
+ALTER TABLE script_credential_bindings
+  ADD COLUMN oauth_provider TEXT;

package/src/be/migrations/112_script_connections_graphql.sql

@@ -0,0 +1,96 @@
+DROP TABLE IF EXISTS script_connections_new;
+
+CREATE TABLE script_connections_new (
+  id TEXT PRIMARY KEY,
+  slug TEXT NOT NULL,
+  display_name TEXT,
+  kind TEXT NOT NULL CHECK(kind IN ('raw', 'openapi', 'mcp', 'graphql')),
+  scope TEXT NOT NULL DEFAULT 'global' CHECK(scope IN ('global', 'agent', 'repo')),
+  scope_id TEXT,
+  base_url TEXT,
+  allowed_hosts_json TEXT NOT NULL DEFAULT '[]',
+  credential_binding_id TEXT REFERENCES script_credential_bindings(id) ON DELETE SET NULL,
+  openapi_spec_source_kind TEXT CHECK(openapi_spec_source_kind IN ('url', 'inline', 'agent_fs')),
+  openapi_spec_source TEXT,
+  openapi_spec_json TEXT,
+  openapi_spec_etag TEXT,
+  openapi_spec_fetched_at TEXT,
+  mcp_server_id TEXT REFERENCES mcp_servers(id) ON DELETE SET NULL,
+  generated_types TEXT,
+  generated_runtime_json TEXT,
+  generated_at TEXT,
+  generation_error TEXT,
+  enabled INTEGER NOT NULL DEFAULT 1,
+  version INTEGER NOT NULL DEFAULT 1,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  created_by TEXT REFERENCES users(id),
+  updated_by TEXT REFERENCES users(id),
+  CHECK(scope = 'global' OR scope_id IS NOT NULL),
+  CHECK(kind != 'openapi' OR openapi_spec_json IS NOT NULL),
+  CHECK(kind != 'mcp' OR mcp_server_id IS NOT NULL)
+);
+
+INSERT INTO script_connections_new (
+  id,
+  slug,
+  display_name,
+  kind,
+  scope,
+  scope_id,
+  base_url,
+  allowed_hosts_json,
+  credential_binding_id,
+  openapi_spec_source_kind,
+  openapi_spec_source,
+  openapi_spec_json,
+  openapi_spec_etag,
+  openapi_spec_fetched_at,
+  mcp_server_id,
+  generated_types,
+  generated_runtime_json,
+  generated_at,
+  generation_error,
+  enabled,
+  version,
+  created_at,
+  updated_at,
+  created_by,
+  updated_by
+)
+SELECT
+  id,
+  slug,
+  display_name,
+  kind,
+  scope,
+  scope_id,
+  base_url,
+  allowed_hosts_json,
+  credential_binding_id,
+  openapi_spec_source_kind,
+  openapi_spec_source,
+  openapi_spec_json,
+  openapi_spec_etag,
+  openapi_spec_fetched_at,
+  mcp_server_id,
+  generated_types,
+  generated_runtime_json,
+  generated_at,
+  generation_error,
+  enabled,
+  version,
+  created_at,
+  updated_at,
+  created_by,
+  updated_by
+FROM script_connections;
+
+DROP TABLE script_connections;
+ALTER TABLE script_connections_new RENAME TO script_connections;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_script_connections_slug_scope
+  ON script_connections(slug, scope, COALESCE(scope_id, ''));
+
+CREATE INDEX IF NOT EXISTS idx_script_connections_kind_enabled
+  ON script_connections(kind, enabled);

package/src/be/migrations/113_task_routing_affinity.sql

@@ -0,0 +1,9 @@
+-- 113_task_routing_affinity.sql
+-- Routing-affinity snapshot for interrupted/pooled tasks (routing-affinity
+-- follow-up to DES-523). Nullable JSON blob: { sourceAgentId, role,
+-- harnessProvider, capabilities }, always written/read whole. NULL = the
+-- task is untagged and pool behavior is unchanged. See
+-- `isAgentEligibleForTask` in src/be/db.ts and `RoutingAffinitySchema` in
+-- src/types.ts.
+
+ALTER TABLE agent_tasks ADD COLUMN routingAffinity TEXT;

package/src/be/migrations/114_backfill_gpt_5_6_pricing.sql

@@ -0,0 +1,15 @@
+-- 114_backfill_gpt_5_6_pricing.sql
+-- Add GPT-5.6 Codex Sol/Terra/Luna pricing rows for existing deployments.
+-- Fresh installs also run this after 046, so CODEX_MODEL_PRICING remains fully
+-- represented at effective_from=0 without mutating already-applied migrations.
+
+INSERT OR IGNORE INTO pricing (provider, model, token_class, effective_from, price_per_million_usd, createdAt, lastUpdatedAt) VALUES
+  ('codex', 'gpt-5.6-sol',     'input',        0, 5.0,    0, 0),
+  ('codex', 'gpt-5.6-sol',     'cached_input', 0, 0.5,    0, 0),
+  ('codex', 'gpt-5.6-sol',     'output',       0, 30.0,   0, 0),
+  ('codex', 'gpt-5.6-terra',   'input',        0, 2.5,    0, 0),
+  ('codex', 'gpt-5.6-terra',   'cached_input', 0, 0.25,   0, 0),
+  ('codex', 'gpt-5.6-terra',   'output',       0, 15.0,   0, 0),
+  ('codex', 'gpt-5.6-luna',    'input',        0, 1.0,    0, 0),
+  ('codex', 'gpt-5.6-luna',    'cached_input', 0, 0.1,    0, 0),
+  ('codex', 'gpt-5.6-luna',    'output',       0, 6.0,    0, 0);

package/src/be/modelsdev-cache.json

@@ -50967,6 +50967,141 @@
             "cache_read": 1
           }
         }
+      },
+      "gpt-5.6-sol": {
+        "id": "gpt-5.6-sol",
+        "name": "GPT-5.6 Sol",
+        "family": "gpt",
+        "attachment": true,
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "tool_call": true,
+        "structured_output": true,
+        "temperature": false,
+        "knowledge": "2026-02-16",
+        "release_date": "2026-07-09",
+        "last_updated": "2026-07-09",
+        "modalities": {
+          "input": [
+            "text",
+            "image"
+          ],
+          "output": [
+            "text"
+          ]
+        },
+        "open_weights": false,
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "cost": {
+          "input": 5,
+          "output": 30,
+          "cache_read": 0.5
+        }
+      },
+      "gpt-5.6-terra": {
+        "id": "gpt-5.6-terra",
+        "name": "GPT-5.6 Terra",
+        "family": "gpt",
+        "attachment": true,
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "tool_call": true,
+        "structured_output": true,
+        "temperature": false,
+        "knowledge": "2026-02-16",
+        "release_date": "2026-07-09",
+        "last_updated": "2026-07-09",
+        "modalities": {
+          "input": [
+            "text",
+            "image"
+          ],
+          "output": [
+            "text"
+          ]
+        },
+        "open_weights": false,
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "cost": {
+          "input": 2.5,
+          "output": 15,
+          "cache_read": 0.25
+        }
+      },
+      "gpt-5.6-luna": {
+        "id": "gpt-5.6-luna",
+        "name": "GPT-5.6 Luna",
+        "family": "gpt",
+        "attachment": true,
+        "reasoning": true,
+        "reasoning_options": [
+          {
+            "type": "effort",
+            "values": [
+              "none",
+              "low",
+              "medium",
+              "high",
+              "xhigh",
+              "max"
+            ]
+          }
+        ],
+        "tool_call": true,
+        "structured_output": true,
+        "temperature": false,
+        "knowledge": "2026-02-16",
+        "release_date": "2026-07-09",
+        "last_updated": "2026-07-09",
+        "modalities": {
+          "input": [
+            "text",
+            "image"
+          ],
+          "output": [
+            "text"
+          ]
+        },
+        "open_weights": false,
+        "limit": {
+          "context": 1050000,
+          "output": 128000
+        },
+        "cost": {
+          "input": 1,
+          "output": 6,
+          "cache_read": 0.1
+        }
       }
     }
   },

package/src/be/oauth-credential-bindings.ts

@@ -0,0 +1,35 @@
+import { ensureTokenOrThrow, oauthAppRowToProviderConfig } from "@/oauth/ensure-token";
+import type { OAuthProviderConfig } from "@/oauth/wrapper";
+import type { OAuthApp } from "@/tracker/types";
+import { getOAuthApp, getOAuthTokens, isTokenExpiringSoon } from "./db-queries/oauth";
+
+export type OAuthBindingTokenStatus = "ok" | "expiring" | "missing";
+
+const OAUTH_BINDING_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+
+export function oauthAppToProviderConfig(app: OAuthApp): OAuthProviderConfig {
+  return oauthAppRowToProviderConfig(app);
+}
+
+export function getOAuthProviderConfig(provider: string): OAuthProviderConfig | null {
+  const app = getOAuthApp(provider);
+  return app ? oauthAppRowToProviderConfig(app) : null;
+}
+
+export function getOAuthBindingTokenStatus(provider: string): OAuthBindingTokenStatus {
+  if (!getOAuthApp(provider)) return "missing";
+  if (!getOAuthTokens(provider)) return "missing";
+  return isTokenExpiringSoon(provider, OAUTH_BINDING_REFRESH_BUFFER_MS) ? "expiring" : "ok";
+}
+
+export async function resolveOAuthBindingToken(provider: string): Promise<string | undefined> {
+  if (!getOAuthApp(provider)) return undefined;
+  const initialTokens = getOAuthTokens(provider);
+  if (!initialTokens) return undefined;
+
+  if (isTokenExpiringSoon(provider, OAUTH_BINDING_REFRESH_BUFFER_MS)) {
+    await ensureTokenOrThrow(provider, OAUTH_BINDING_REFRESH_BUFFER_MS);
+  }
+
+  return getOAuthTokens(provider)?.accessToken;
+}

package/src/be/oauth-refresh-sweep.ts

@@ -0,0 +1,159 @@
+/**
+ * Background OAuth token refresh sweep.
+ *
+ * The reactive path (src/oauth/ensure-token.ts) only refreshes tokens when a
+ * binding is about to be USED, so rotation / inactivity-TTL refresh tokens can
+ * die while a connection sits idle. This sweep walks every oauth_tokens row on
+ * a 15-minute tick and refreshes when either:
+ *
+ *  (a) the access token expires within 30 minutes, or
+ *  (b) the row hasn't been touched in > 7 days (keep-alive for providers that
+ *      expire refresh tokens after an inactivity window, e.g. Atlassian ~90d).
+ *
+ * Relationship to src/oauth/keepalive.ts: that job is a 12-hour alerting
+ * keepalive hardcoded to the tracker providers (linear/jira). This sweep is
+ * the generic counterpart covering every provider registered in oauth_apps
+ * (script-connection credential bindings included). Both funnel through the
+ * same per-provider locks in ensure-token, so overlap is safe.
+ */
+import { forceRefreshTokenOrThrow } from "../oauth/ensure-token";
+import { scrubSecrets } from "../utils/secret-scrubber";
+import { getOAuthTokens, listOAuthTokenSweepRows } from "./db-queries/oauth";
+
+const EXPIRY_BUFFER_MS = 30 * 60 * 1000; // (a) refresh when expiring within 30 min
+const STALE_ROW_MS = 7 * 24 * 60 * 60 * 1000; // (b) keep-alive when untouched > 7 days
+const SWEEP_INTERVAL_MS = 15 * 60 * 1000;
+const SWEEP_STARTUP_DELAY_MS = 60 * 1000;
+
+export type OAuthRefreshSweepResult = {
+  checked: number;
+  refreshed: number;
+  skipped: number;
+  failed: string[];
+};
+
+/**
+ * Run one sweep over all stored OAuth tokens. Never throws — per-provider
+ * failures are collected in `failed` (and logged, scrubbed) so one dead
+ * provider can't starve the rest.
+ */
+export async function sweepOAuthTokenRefresh(): Promise<OAuthRefreshSweepResult> {
+  let checked = 0;
+  let refreshed = 0;
+  let skipped = 0;
+  const failed: string[] = [];
+
+  for (const row of listOAuthTokenSweepRows()) {
+    checked++;
+
+    if (!row.hasApp || !row.hasRefreshToken) {
+      skipped++;
+      continue;
+    }
+
+    const now = Date.now();
+    const expiringSoon = new Date(row.expiresAt).getTime() - now < EXPIRY_BUFFER_MS;
+    const stale = now - new Date(row.updatedAt).getTime() > STALE_ROW_MS;
+    if (!expiringSoon && !stale) {
+      skipped++;
+      continue;
+    }
+
+    const before = getOAuthTokens(row.provider);
+    try {
+      await forceRefreshTokenOrThrow(row.provider);
+      const after = getOAuthTokens(row.provider);
+      // forceRefreshTokenOrThrow stays silent on some no-op paths (row changed
+      // concurrently, config vanished mid-flight) — only count real refreshes.
+      const changed =
+        after !== null &&
+        (before === null ||
+          before.accessToken !== after.accessToken ||
+          before.expiresAt !== after.expiresAt ||
+          before.updatedAt !== after.updatedAt);
+      if (changed) {
+        refreshed++;
+      } else {
+        skipped++;
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      failed.push(`${row.provider}: ${message}`);
+      console.warn(
+        scrubSecrets(`[oauth-refresh-sweep] ${row.provider} refresh failed: ${message}`),
+      );
+    }
+  }
+
+  return { checked, refreshed, skipped, failed };
+}
+
+// ─── Periodic runner ─────────────────────────────────────────────────────────
+
+let sweepInterval: ReturnType<typeof setInterval> | null = null;
+let startupTimeout: ReturnType<typeof setTimeout> | null = null;
+let inflightSweep: Promise<void> | null = null;
+
+async function runSweepTick(trigger: "startup" | "interval"): Promise<void> {
+  if (inflightSweep) return inflightSweep;
+  inflightSweep = (async () => {
+    try {
+      const result = await sweepOAuthTokenRefresh();
+      // Stay quiet on no-op ticks; one concise line when something happened.
+      if (result.refreshed > 0 || result.failed.length > 0) {
+        console.log(
+          scrubSecrets(
+            `[oauth-refresh-sweep] ${trigger}: checked=${result.checked} refreshed=${result.refreshed} skipped=${result.skipped} failed=${result.failed.length}${result.failed.length > 0 ? ` (${result.failed.join("; ")})` : ""}`,
+          ),
+        );
+      }
+    } catch (err) {
+      // sweepOAuthTokenRefresh never throws by contract; belt and braces.
+      console.error("[oauth-refresh-sweep] sweep tick failed:", err);
+    } finally {
+      inflightSweep = null;
+    }
+  })();
+  return inflightSweep;
+}
+
+/**
+ * Start the periodic OAuth refresh sweep: first run ~1 minute after boot,
+ * then every 15 minutes. No-op when OAUTH_REFRESH_SWEEP_DISABLE=true or when
+ * already running.
+ */
+export function startOAuthRefreshSweep(): void {
+  if (process.env.OAUTH_REFRESH_SWEEP_DISABLE === "true") {
+    console.log("[oauth-refresh-sweep] Disabled via OAUTH_REFRESH_SWEEP_DISABLE");
+    return;
+  }
+  if (sweepInterval || startupTimeout) return;
+
+  console.log(
+    `[oauth-refresh-sweep] Starting (interval ${Math.round(SWEEP_INTERVAL_MS / 60_000)}min, first run in ${Math.round(SWEEP_STARTUP_DELAY_MS / 1000)}s)`,
+  );
+
+  startupTimeout = setTimeout(() => {
+    startupTimeout = null;
+    void runSweepTick("startup");
+  }, SWEEP_STARTUP_DELAY_MS);
+  startupTimeout.unref?.();
+
+  sweepInterval = setInterval(() => {
+    void runSweepTick("interval");
+  }, SWEEP_INTERVAL_MS);
+  sweepInterval.unref?.();
+}
+
+/** Stop the periodic sweep and wait for any in-flight run to finish. */
+export async function stopOAuthRefreshSweep(): Promise<void> {
+  if (startupTimeout) {
+    clearTimeout(startupTimeout);
+    startupTimeout = null;
+  }
+  if (sweepInterval) {
+    clearInterval(sweepInterval);
+    sweepInterval = null;
+  }
+  if (inflightSweep) await inflightSweep;
+}