@vellumai/assistant 0.12.5 → 0.12.6-dev.202609292019.a6f6d85

package/src/usage/attribution.ts

@@ -10,11 +10,15 @@ import { safeStringSlice } from "../util/unicode.js";
 
 const MAX_METADATA_VALUE_LENGTH = 128;
 
+/** `profileSource` reported for a turn whose profile the Auto router chose. */
+export const AUTO_PROFILE_SOURCE = "auto";
+
 export type UsageAttributionProfileSource =
   | "call_site"
   | "conversation"
   | "active"
   | "default"
+  | typeof AUTO_PROFILE_SOURCE
   | "unknown";
 
 export interface UsageAttributionInput {
@@ -27,6 +31,12 @@ export interface UsageAttributionInput {
    */
   profileResolutionCallSite?: LLMCallSite | null;
   overrideProfile?: string | null;
+  /**
+   * Who chose `overrideProfile`. `"auto"` marks a profile the Auto profile's
+   * router picked for the turn, so usage rows can tell an Auto pick from a
+   * user pin that landed on the same profile. Absent for a user pin.
+   */
+  overrideProfileOrigin?: "auto" | null;
   /**
    * Mirrors `ResolveCallSiteOpts.forceOverrideProfile`: the override profile
    * was floated above the call-site layers for this request, so attribution
@@ -227,9 +237,16 @@ function appliedProfileFromWinnerSelection(
     call_site: "call_site",
     default: "default",
   } as const;
+  // An override the Auto router chose is reported as its own source: the
+  // applied profile is the routed arm, so without this a routed turn would
+  // be indistinguishable from a user who pinned that arm.
+  const profileSource =
+    selection.source === "override" && input.overrideProfileOrigin === "auto"
+      ? AUTO_PROFILE_SOURCE
+      : sourceBySelection[selection.source];
   return {
     appliedProfile: selection.profileName,
-    profileSource: sourceBySelection[selection.source],
+    profileSource,
   };
 }
 

package/src/util/__tests__/oom-priority.test.ts

@@ -0,0 +1,55 @@
+import { mkdirSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import { setOomScoreAdj, withOomScoreAdj } from "../oom-priority.js";
+
+function fakeProc(pid: number): string {
+  const procRoot = mkdtempSync(join(tmpdir(), "oom-priority-"));
+  mkdirSync(join(procRoot, String(pid)));
+  return procRoot;
+}
+
+describe("setOomScoreAdj", () => {
+  test("writes the value for a pid on Linux", () => {
+    const procRoot = fakeProc(42);
+    expect(setOomScoreAdj(1000, 42, { procRoot, platform: "linux" })).toBe(
+      true,
+    );
+    expect(readFileSync(join(procRoot, "42", "oom_score_adj"), "utf-8")).toBe(
+      "1000",
+    );
+  });
+
+  test("is a no-op off Linux", () => {
+    const procRoot = fakeProc(42);
+    expect(setOomScoreAdj(1000, 42, { procRoot, platform: "darwin" })).toBe(
+      false,
+    );
+  });
+
+  test("reports failure for a pid that is gone", () => {
+    const procRoot = fakeProc(42);
+    expect(setOomScoreAdj(0, 43, { procRoot, platform: "linux" })).toBe(false);
+  });
+});
+
+describe("withOomScoreAdj", () => {
+  test("execs the command through a shell that raises its own score on Linux", () => {
+    expect(withOomScoreAdj(["chrome", "--flag"], 1000, "linux")).toEqual([
+      "sh",
+      "-c",
+      'echo 1000 2>/dev/null >/proc/self/oom_score_adj; exec "$0" "$@"',
+      "chrome",
+      "--flag",
+    ]);
+  });
+
+  test("returns the command unchanged off Linux", () => {
+    expect(withOomScoreAdj(["chrome", "--flag"], 1000, "darwin")).toEqual([
+      "chrome",
+      "--flag",
+    ]);
+  });
+});

package/src/util/__tests__/worker-memory.test.ts

@@ -38,6 +38,7 @@ describe("computeWorkerForceRamSizeBytes", () => {
 
 describe("workerMemoryEnv", () => {
   const savedForceRamSize = process.env.BUN_JSC_forceRAMSize;
+  const savedGcTimerDisable = process.env.BUN_GC_TIMER_DISABLE;
 
   afterEach(() => {
     if (savedForceRamSize === undefined) {
@@ -45,6 +46,11 @@ describe("workerMemoryEnv", () => {
     } else {
       process.env.BUN_JSC_forceRAMSize = savedForceRamSize;
     }
+    if (savedGcTimerDisable === undefined) {
+      delete process.env.BUN_GC_TIMER_DISABLE;
+    } else {
+      process.env.BUN_GC_TIMER_DISABLE = savedGcTimerDisable;
+    }
   });
 
   test("adds a clamped BUN_JSC_forceRAMSize on top of the parent environment", () => {
@@ -61,4 +67,14 @@ describe("workerMemoryEnv", () => {
     const env = workerMemoryEnv();
     expect(env.BUN_JSC_forceRAMSize).toBe("12345");
   });
+
+  test("disables the worker GC timer unless the operator set it", () => {
+    delete process.env.BUN_GC_TIMER_DISABLE;
+    expect(workerMemoryEnv().BUN_GC_TIMER_DISABLE).toBe("1");
+  });
+
+  test("keeps an operator-provided BUN_GC_TIMER_DISABLE", () => {
+    process.env.BUN_GC_TIMER_DISABLE = "0";
+    expect(workerMemoryEnv().BUN_GC_TIMER_DISABLE).toBe("0");
+  });
 });

package/src/util/debounce.ts

@@ -1,7 +1,3 @@
-/**
- * Single-key debouncer. Delays execution until no new calls arrive
- * within the specified delay period.
- */
 /**
  * Multi-key debouncer. Each key gets its own independent timer.
  * Includes an optional entry limit with eviction of oldest non-protected entries.

package/src/util/oom-priority.ts

@@ -0,0 +1,79 @@
+/**
+ * Linux OOM-killer priority for the daemon and everything it spawns.
+ *
+ * When the container hits its memory limit the kernel kills the process with
+ * the highest oom_score: its share of memory plus `oom_score_adj`. The daemon
+ * is usually the largest process in the container, so by default it is the
+ * victim and the assistant goes down with the runaway tool. Setting the daemon
+ * strongly negative and every child non-negative makes the kernel take a tool,
+ * desktop, or worker process first and leave the assistant running.
+ *
+ * Children inherit the parent's value at fork, so every spawn path must reset
+ * its child: shell children through `buildShellInvocation`, desktop children
+ * through the desktop session's spawn wrapper, workers and Qdrant through a
+ * parent-side write right after spawn. Raising a value never needs a
+ * capability; lowering one below the inherited value needs CAP_SYS_RESOURCE,
+ * which the platform grants and self-hosted Docker (non-root) does not. There
+ * the daemon stays at 0, which children at +1000 still lose to.
+ */
+
+import { writeFileSync } from "node:fs";
+
+import { CHILD_OOM_SCORE_ADJ } from "@vellumai/environments/shell";
+
+export { CHILD_OOM_SCORE_ADJ };
+
+/** Strongly avoided but still killable as a last resort, unlike -1000. */
+export const DAEMON_OOM_SCORE_ADJ = -700;
+/** The monitor records the kill, so it outlives everything but the daemon. */
+export const MONITOR_OOM_SCORE_ADJ = -500;
+/** Workers and Qdrant: kernel default, picked by memory share alone. */
+export const WORKER_OOM_SCORE_ADJ = 0;
+
+/**
+ * Wrap a command so the child raises its own `oom_score_adj` before it execs.
+ * `exec` keeps the pid and process group, so callers that track or kill the
+ * child see no difference. Deterministic where a parent-side write after
+ * spawn is not: the child may already have forked (Chrome's zygote, a coding
+ * agent's tools) before the parent's write lands, and those grandchildren
+ * would keep the inherited value. Identity on non-Linux hosts.
+ */
+export function withOomScoreAdj(
+  cmd: readonly string[],
+  value: number,
+  platform: NodeJS.Platform = process.platform,
+): string[] {
+  if (platform !== "linux") {
+    return [...cmd];
+  }
+  return [
+    "sh",
+    "-c",
+    `echo ${value} 2>/dev/null >/proc/self/oom_score_adj; exec "$0" "$@"`,
+    ...cmd,
+  ];
+}
+
+/**
+ * Write `oom_score_adj` for `pid` (or this process). Returns false where it
+ * cannot apply: non-Linux hosts, a process that already exited, or lowering
+ * without CAP_SYS_RESOURCE.
+ */
+export function setOomScoreAdj(
+  value: number,
+  pid: number | "self" = "self",
+  options: { procRoot?: string; platform?: NodeJS.Platform } = {},
+): boolean {
+  if ((options.platform ?? process.platform) !== "linux") {
+    return false;
+  }
+  try {
+    writeFileSync(
+      `${options.procRoot ?? "/proc"}/${pid}/oom_score_adj`,
+      String(value),
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/util/platform.ts

@@ -297,7 +297,6 @@ export function getSignalsDir(): string {
   return join(getWorkspaceDir(), "signals");
 }
 
-// --- Root-level runtime path helpers ---
 // These expose specific root-level file paths so callers don't need to
 // import getRootDir() directly. getRootDir() is intentionally unexported.
 
@@ -567,7 +566,6 @@ export function getWorkspaceSystemPromptDir(): string {
   return join(getWorkspaceDir(), "prompts", "system");
 }
 
-// ── Profiler filesystem layout ──────────────────────────────────────────
 // Managed profiler runs live under <workspace>/data/profiler/. These
 // helpers enforce a single canonical layout so every runtime caller
 // resolves the same paths.

package/src/util/plugin-manifest.ts

@@ -37,6 +37,10 @@ const LegacyPluginManifestSchema = z
   })
   .passthrough();
 
+const StandardPluginManifestDiscriminatorSchema = z.object({
+  $schema: z.literal(AGENT_PLUGINS_MANIFEST_SCHEMA_URL),
+});
+
 const StandardPluginManifestSchema = z
   .object({
     $schema: z.literal(AGENT_PLUGINS_MANIFEST_SCHEMA_URL),
@@ -129,13 +133,7 @@ export function getPluginManifestInstallAction(
     return "synthesize-legacy";
   }
 
-  if (
-    typeof json !== "object" ||
-    json === null ||
-    Array.isArray(json) ||
-    (json as Record<string, unknown>).$schema !==
-      AGENT_PLUGINS_MANIFEST_SCHEMA_URL
-  ) {
+  if (!StandardPluginManifestDiscriminatorSchema.safeParse(json).success) {
     return "synthesize-legacy";
   }
 

package/src/util/pricing.ts

@@ -63,6 +63,31 @@ const LEGACY_PRICING_FALLBACK: Record<string, Record<string, ModelPricing>> = {
   gemini: {
     "gemini-2.0-flash": { inputPer1M: 0.1, outputPer1M: 0.4 },
   },
+  // Models Fireworks no longer serves serverless. The catalog does not list
+  // them, but stored usage keeps their IDs, so request-log cost estimates
+  // still need their rates.
+  fireworks: {
+    "accounts/fireworks/models/glm-5p2": {
+      inputPer1M: 1.4,
+      outputPer1M: 4.4,
+      cacheReadPer1M: 0.26,
+    },
+    "accounts/fireworks/models/kimi-k2p6": {
+      inputPer1M: 0.95,
+      outputPer1M: 4.0,
+      cacheReadPer1M: 0.16,
+    },
+    "accounts/fireworks/models/deepseek-v4-pro-0813": {
+      inputPer1M: 1.32,
+      outputPer1M: 3.96,
+      cacheReadPer1M: 0.044,
+    },
+    "accounts/fireworks/models/deepseek-v4-flash-0731": {
+      inputPer1M: 0.14,
+      outputPer1M: 0.28,
+      cacheReadPer1M: 0.028,
+    },
+  },
 };
 
 /** Convert a catalog pricing entry to the internal pricing shape. */

package/src/util/worker-memory.ts

@@ -60,9 +60,14 @@ export function computeWorkerForceRamSizeBytes(
 
 /**
  * Environment for spawning a background worker `bun` process: the parent
- * environment plus `BUN_JSC_forceRAMSize`. An operator-provided
- * `BUN_JSC_forceRAMSize` in the parent environment wins over the computed
- * value.
+ * environment plus `BUN_JSC_forceRAMSize` and `BUN_GC_TIMER_DISABLE`. An
+ * operator-provided value for either in the parent environment wins.
+ *
+ * `BUN_GC_TIMER_DISABLE=1` turns off Bun's repeating GC timer in the worker.
+ * Under a `forceRAMSize` heap that timer, together with the per-tick
+ * collection request, keeps a long-lived worker collecting continuously at
+ * roughly one full core; the workers' own allocation still triggers
+ * collection normally.
  *
  * Bun.spawn replaces (rather than merges) the child environment when `env` is
  * passed, so this spreads the full parent environment.
@@ -73,5 +78,6 @@ export function workerMemoryEnv(): Record<string, string | undefined> {
     BUN_JSC_forceRAMSize:
       process.env.BUN_JSC_forceRAMSize ??
       String(computeWorkerForceRamSizeBytes(getContainerMemoryLimitBytes())),
+    BUN_GC_TIMER_DISABLE: process.env.BUN_GC_TIMER_DISABLE ?? "1",
   };
 }

package/src/util/worker-process.ts

@@ -20,6 +20,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { getCurrentLogFilePath, getLogger } from "./logger.js";
+import { setOomScoreAdj, WORKER_OOM_SCORE_ADJ } from "./oom-priority.js";
 import { isProcessAlive } from "./process-liveness.js";
 import {
   listProcessTable,
@@ -128,6 +129,11 @@ const PID_FILE_WAIT_TIMEOUT_MS = 15_000;
 const PID_FILE_POLL_INTERVAL_MS = 100;
 
 export interface SpawnWorkerProcessOptions {
+  /**
+   * `oom_score_adj` for the worker. Defaults to {@link WORKER_OOM_SCORE_ADJ};
+   * the child would otherwise inherit the daemon's protected value.
+   */
+  oomScoreAdj?: number;
   /**
    * Override how long to wait for the worker's PID file, in ms. Defaults to
    * {@link PID_FILE_WAIT_TIMEOUT_MS}. Primarily a testing seam.
@@ -626,6 +632,8 @@ export async function spawnWorkerProcess(args: {
     windowsHide: true,
   });
 
+  setOomScoreAdj(opts.oomScoreAdj ?? WORKER_OOM_SCORE_ADJ, child.pid);
+
   // Close our copy of the log fd — the child has its own.
   if (typeof stderrFd === "number") {
     closeSync(stderrFd);

package/src/workspace/byok-default-profile-ensure.ts

@@ -187,6 +187,8 @@ const HISTORICAL_INTENT_MODELS: Record<
       "accounts/fireworks/models/deepseek-v4-flash",
       // the ID migration 146 writes over stale deepseek-v4-flash pins.
       "accounts/fireworks/models/deepseek-v4-flash-0731",
+      // the ID migration 160 writes over stale deepseek-v4-flash-0731 pins.
+      "accounts/fireworks/models/deepseek-v4p1-flash",
     ],
   },
   "quality-optimized": {
@@ -209,10 +211,15 @@ const HISTORICAL_INTENT_MODELS: Record<
     fireworks: [
       // quality intent 2026-05-05 (#29755) to 2026-05-19 (#31068).
       "accounts/fireworks/models/kimi-k2p5",
+      // quality intent 2026-05-19 (#31068) to the 2026-09-28 kimi-k3
+      // repoint.
+      "accounts/fireworks/models/kimi-k2p6",
       // migration 136's in-place rewrite of a kimi-k2p5 pin.
       "accounts/fireworks/models/deepseek-v4-flash",
       // the ID migration 146 writes over stale deepseek-v4-flash pins.
       "accounts/fireworks/models/deepseek-v4-flash-0731",
+      // the ID migration 160 writes over stale deepseek-v4-flash-0731 pins.
+      "accounts/fireworks/models/deepseek-v4p1-flash",
     ],
   },
   "cost-optimized": {
@@ -234,6 +241,10 @@ const HISTORICAL_INTENT_MODELS: Record<
       // 146 rewrites it to the dated ID, so this survives only in pre-146
       // backups.
       "accounts/fireworks/models/deepseek-v4-flash",
+      // latency intent 2026-08-17 to the 2026-09-28 deepseek-v4p1-flash
+      // repoint. On live configs migration 160 rewrites it, so this
+      // survives only in pre-160 backups.
+      "accounts/fireworks/models/deepseek-v4-flash-0731",
     ],
   },
 };

package/src/workspace/hatched-date.ts

@@ -1,9 +1,14 @@
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { z } from "zod";
+
 import { getDataDir } from "../util/platform.js";
 
 const HATCHED_SIDECAR_FILENAME = "hatched.json";
+const HatchedSidecarSchema = z.object({
+  hatchedAt: z.unknown().optional(),
+});
 
 export function getHatchedSidecarPath(): string {
   return join(getDataDir(), HATCHED_SIDECAR_FILENAME);
@@ -24,10 +29,12 @@ function normalizeHatchedAt(value: unknown): string | undefined {
 
 export function readHatchedAtSidecar(): string | undefined {
   try {
-    const parsed = JSON.parse(
-      readFileSync(getHatchedSidecarPath(), "utf-8"),
-    ) as { hatchedAt?: unknown };
-    return normalizeHatchedAt(parsed.hatchedAt);
+    const parsed = HatchedSidecarSchema.safeParse(
+      JSON.parse(readFileSync(getHatchedSidecarPath(), "utf-8")),
+    );
+    return parsed.success
+      ? normalizeHatchedAt(parsed.data.hatchedAt)
+      : undefined;
   } catch {
     return undefined;
   }

package/src/workspace/migrations/160-repair-retired-fireworks-model-ids.ts

@@ -0,0 +1,209 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Database } from "bun:sqlite";
+
+import type { WorkspaceMigration } from "./types.js";
+
+/**
+ * Repair the retired Fireworks model IDs in workspace LLM config.
+ *
+ * Fireworks has no serverless deployment of DeepSeek V4 Flash 0731,
+ * DeepSeek V4 Pro 0813 or Kimi K2.6: chat/completions calls fail with a
+ * 404 "Model not found, inaccessible, and/or not deployed". Existing
+ * configs can pin any of these IDs in `llm.default`, `llm.callSites.*`, and `llm.profiles.*`.
+ *
+ * Repair those leaves only on an exact stale match, replacing with the
+ * successor Fireworks names (see `REPLACEMENT_BY_STALE_MODEL_ID`). Kimi
+ * K2.6 has two named successors; Kimi K3 is the one that accepts image
+ * input, which Kimi K2.6 does.
+ *
+ * A replacement can also be an intent template's model, so a repaired
+ * hand-edited `custom-*` profile can read as unedited to
+ * `ensureByokDefaultProfiles` and collapse into that default. That is
+ * acceptable: the collapsed copy routes to the same model this migration
+ * writes.
+ *
+ * Provider guard: the stale IDs belong to the `fireworks` provider and also
+ * appear in managed profiles stamped `provider: "vellum"` (which route
+ * Fireworks-account model IDs through the managed proxy). Under the entries
+ * model (migration 145) `provider` can also hold a `provider_connections`
+ * entry name whose row kind drives dispatch. A fragment is repaired when
+ * its `provider` is `"fireworks"`, `"vellum"`, absent, or an entry name
+ * whose row kind is one of those. Any other provider is left untouched: an
+ * `openai-compatible` endpoint may legitimately serve a model by the stale
+ * name.
+ */
+export const repairRetiredFireworksModelIdsMigration: WorkspaceMigration = {
+  id: "160-repair-retired-fireworks-model-ids",
+  description: "Repair retired Fireworks model IDs in workspace LLM config",
+  run(workspaceDir: string): void {
+    const configPath = join(workspaceDir, "config.json");
+    if (!existsSync(configPath)) {
+      return;
+    }
+
+    // Read outside the parse catch: a transient filesystem error (EIO,
+    // EACCES) must reach the runner so the migration retries, while
+    // malformed JSON is a permanent state this migration cannot repair.
+    const rawText = readFileSync(configPath, "utf-8");
+
+    let config: Record<string, unknown>;
+    try {
+      const raw = JSON.parse(rawText);
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return;
+      }
+      config = raw as Record<string, unknown>;
+    } catch {
+      return;
+    }
+
+    const llm = readObject(config.llm);
+    if (llm === null) {
+      return;
+    }
+
+    // Entry rows load lazily: only a stale fragment whose provider is
+    // neither a repairable vendor nor absent needs them. An unreadable DB
+    // then fails the run (retried next boot) rather than checkpointing a
+    // pass that skips entry-bound profiles.
+    let rows: Map<string, string> | null | undefined;
+    const isRepairableProvider = (provider: unknown): boolean => {
+      if (provider === undefined) {
+        return true;
+      }
+      if (typeof provider !== "string") {
+        return false;
+      }
+      if (REPAIRABLE_PROVIDERS.has(provider)) {
+        return true;
+      }
+      if (rows === undefined) {
+        rows = readConnectionRows(workspaceDir);
+      }
+      if (rows === null) {
+        throw new Error(
+          "provider_connections is not readable; retrying the model-ID repair on the next run",
+        );
+      }
+      const kind = rows.get(provider);
+      return kind !== undefined && REPAIRABLE_PROVIDERS.has(kind);
+    };
+
+    let changed = false;
+
+    changed =
+      repairFragment(readObject(llm.default), isRepairableProvider) || changed;
+
+    const callSites = readObject(llm.callSites);
+    if (callSites !== null) {
+      for (const rawConfig of Object.values(callSites)) {
+        changed =
+          repairFragment(readObject(rawConfig), isRepairableProvider) ||
+          changed;
+      }
+    }
+
+    const profiles = readObject(llm.profiles);
+    if (profiles !== null) {
+      for (const rawProfile of Object.values(profiles)) {
+        changed =
+          repairFragment(readObject(rawProfile), isRepairableProvider) ||
+          changed;
+      }
+    }
+
+    if (!changed) {
+      return;
+    }
+
+    // Write-then-rename so an interrupted write cannot leave config.json
+    // truncated: a torn in-place write would parse as invalid JSON on the
+    // retry, which the catch above treats as "nothing to do", letting the
+    // runner checkpoint the migration as completed against a corrupt file.
+    const tmpPath = `${configPath}.migration-160.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(config, null, 2) + "\n");
+    renameSync(tmpPath, configPath);
+  },
+  // The exact-match rewrite is idempotent, so a transient failure (full
+  // disk, I/O error) is safe to retry on later startups.
+  retryFailedCheckpoint: true,
+  down(_workspaceDir: string): void {
+    // Forward-only: reintroducing a retired model ID would break
+    // Fireworks calls.
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Helpers: self-contained per workspace migrations AGENTS.md
+// ---------------------------------------------------------------------------
+
+const REPLACEMENT_BY_STALE_MODEL_ID = new Map([
+  [
+    "accounts/fireworks/models/deepseek-v4-flash-0731",
+    "accounts/fireworks/models/deepseek-v4p1-flash",
+  ],
+  [
+    "accounts/fireworks/models/deepseek-v4-pro-0813",
+    "accounts/fireworks/models/deepseek-v4p1-flash",
+  ],
+  ["accounts/fireworks/models/kimi-k2p6", "accounts/fireworks/models/kimi-k3"],
+]);
+const REPAIRABLE_PROVIDERS = new Set(["fireworks", "vellum"]);
+
+function repairFragment(
+  fragment: Record<string, unknown> | null,
+  isRepairableProvider: (provider: unknown) => boolean,
+): boolean {
+  if (fragment === null) {
+    return false;
+  }
+  if (typeof fragment.model !== "string") {
+    return false;
+  }
+  const replacement = REPLACEMENT_BY_STALE_MODEL_ID.get(fragment.model);
+  if (replacement === undefined) {
+    return false;
+  }
+  if (!isRepairableProvider(fragment.provider)) {
+    return false;
+  }
+  fragment.model = replacement;
+  return true;
+}
+
+/**
+ * Connection name -> provider kind, or null when the DB or table is not
+ * readable. The caller fails the run on null: entry-name providers must be
+ * judged against real rows, never guessed. An absent DB file is a real
+ * state (no rows, so every entry name is dangling and stays untouched).
+ */
+function readConnectionRows(workspaceDir: string): Map<string, string> | null {
+  const dbPath = join(workspaceDir, "data", "db", "assistant.db");
+  if (!existsSync(dbPath)) {
+    return new Map();
+  }
+  let db: Database;
+  try {
+    db = new Database(dbPath);
+  } catch {
+    return null;
+  }
+  try {
+    const rows = db
+      .query(`SELECT name, provider FROM provider_connections`)
+      .all() as Array<{ name: string; provider: string }>;
+    return new Map(rows.map((r) => [r.name, r.provider]));
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
+function readObject(value: unknown): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}