@taicho-ai/framework 0.1.0

package/src/store/files.ts

@@ -0,0 +1,51 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Workspace file canon. Files are the source of truth; the DB is a cache. */
+export const paths = {
+  agentDir: (ws: string, id: string) => join(ws, "agents", id),
+  agentFile: (ws: string, id: string) => join(ws, "agents", id, "agent.md"),
+  teamsDir: (ws: string) => join(ws, "teams"),
+  teamDir: (ws: string, id: string) => join(ws, "teams", id),
+  teamFile: (ws: string, id: string) => join(ws, "teams", id, "team.md"),
+  teamWorkflowFile: (ws: string, id: string) => join(ws, "teams", id, "workflow.md"),
+  policyDir: (ws: string, id: string) => join(ws, "agents", id, "policies"),
+  exemplarDir: (ws: string, id: string) => join(ws, "agents", id, "exemplars"),
+  artifactDir: (ws: string) => join(ws, "artifacts"),
+  plansDir: (ws: string) => join(ws, "plans"),
+  runDir: (ws: string, id: string) => join(ws, "runs", id),
+  runRecordDir: (ws: string, runId: string) => {
+    const i = runId.indexOf("/");
+    if (i < 0) throw new Error("bad run id: " + runId);
+    return join(ws, "runs", runId.slice(0, i), runId.slice(i + 1));
+  },
+  conversationDir: (ws: string, id: string) => join(ws, "conversations", id),
+  taskDir: (ws: string) => join(ws, "tasks"),
+  scheduleDir: (ws: string) => join(ws, "schedules"),
+  // Plan 25: a workflow's DEFINITION lives in teams/<team>/workflow.md; per-RUN state is here.
+  workflowsDir: (ws: string) => join(ws, "workflows"),
+  workflowRunsDir: (ws: string, id: string) => join(ws, "workflows", id, "runs"),
+  workflowRunDir: (ws: string, id: string, runId: string) => join(ws, "workflows", id, "runs", runId),
+  kbNodeDir: (ws: string) => join(ws, "kb", "nodes"),
+  kbNodeFile: (ws: string, id: string) => join(ws, "kb", "nodes", `${id}.md`),
+  kbSourceDir: (ws: string) => join(ws, "kb", "sources"),
+  kbSourceFile: (ws: string, name: string) => join(ws, "kb", "sources", name),
+  skillsDir: (ws: string) => join(ws, "skills"),
+  skillFile: (ws: string, id: string) => join(ws, "skills", `${id}.md`),
+  inputHistoryFile: (ws: string) => join(ws, ".taicho-input-history"), // Plan 24: REPL message history
+};
+
+export async function ensureWorkspace(ws: string) {
+  await mkdir(join(ws, "agents"), { recursive: true });
+  await mkdir(join(ws, "teams"), { recursive: true });
+  await mkdir(join(ws, "artifacts"), { recursive: true });
+  await mkdir(join(ws, "plans"), { recursive: true });
+  await mkdir(join(ws, "runs"), { recursive: true });
+  await mkdir(join(ws, "conversations"), { recursive: true });
+  await mkdir(join(ws, "tasks"), { recursive: true });
+  await mkdir(join(ws, "schedules"), { recursive: true });
+  await mkdir(join(ws, "workflows"), { recursive: true });
+  await mkdir(join(ws, "kb", "nodes"), { recursive: true });
+  await mkdir(join(ws, "kb", "sources"), { recursive: true });
+  await mkdir(join(ws, "skills"), { recursive: true });
+}

package/src/store/knowledge.ts

@@ -0,0 +1,201 @@
+/** Squad knowledgebase store: one file per node at kb/nodes/<kb_id>.md (YAML frontmatter = the node
+ *  minus `content`, body = content). Files are canon; kb_nodes/kb_edges in SQLite are a rebuildable
+ *  index. Mirrors store/policy.ts + store/roster.ts. */
+import { YAML } from "bun";
+import type { Database } from "bun:sqlite";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { KbNode } from "@taicho-ai/contracts/knowledge";
+import { paths } from "./files";
+import { putVector } from "./vectors";
+import { log } from "../core/logger";
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+export function mkKbId(): string {
+  return "kb_" + Math.random().toString(36).slice(2, 10);
+}
+
+export function serializeNode(n: KbNode): string {
+  const { content, ...meta } = n;
+  return `---\n${YAML.stringify(meta, null, 2)}\n---\n${content}\n`;
+}
+
+export function parseNode(text: string): KbNode {
+  const m = FRONTMATTER.exec(text);
+  if (!m) throw new Error("knowledge node missing YAML frontmatter");
+  const meta = YAML.parse(m[1]) as Record<string, unknown>;
+  return KbNode.parse({ ...meta, content: m[2].trim() });
+}
+
+/** Write a node's canonical file, then (re)index it into kb_nodes/kb_edges. */
+export function writeNode(ws: string, db: Database, node: KbNode): void {
+  mkdirSync(paths.kbNodeDir(ws), { recursive: true });
+  writeFileSync(paths.kbNodeFile(ws, node.id), serializeNode(node));
+  indexNode(db, node);
+}
+
+export function readNode(ws: string, id: string): KbNode | null {
+  const f = paths.kbNodeFile(ws, id);
+  if (!existsSync(f)) return null;
+  try { return parseNode(readFileSync(f, "utf8")); } catch { return null; }
+}
+
+export function listNodes(ws: string): KbNode[] {
+  const dir = paths.kbNodeDir(ws);
+  if (!existsSync(dir)) return [];
+  const out: KbNode[] = [];
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".md")) continue;
+    try { out.push(parseNode(readFileSync(join(dir, f), "utf8"))); }
+    catch (e) { log.warn(`skipping kb node ${f}`, e); }
+  }
+  return out;
+}
+
+export function nodeExists(db: Database, id: string): boolean {
+  return !!db.query("SELECT 1 FROM kb_nodes WHERE id = ?").get(id);
+}
+
+/** Upsert a node row and replace its outgoing edges. */
+export function indexNode(db: Database, n: KbNode): void {
+  db.query(
+    `INSERT INTO kb_nodes (id, kind, title, summary, content, source, scope, metadata, updated)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, unixepoch())
+     ON CONFLICT(id) DO UPDATE SET
+       kind=excluded.kind, title=excluded.title, summary=excluded.summary, content=excluded.content,
+       source=excluded.source, scope=excluded.scope, metadata=excluded.metadata, updated=unixepoch()`,
+  ).run(n.id, n.kind, n.title, n.summary ?? null, n.content, n.source ?? null, n.scope, n.metadata ? JSON.stringify(n.metadata) : null);
+  db.query("DELETE FROM kb_edges WHERE from_id = ?").run(n.id);
+  const ins = db.query("INSERT OR IGNORE INTO kb_edges (from_id, to_id, rel, weight, metadata) VALUES (?, ?, ?, ?, ?)");
+  for (const e of n.edges) ins.run(n.id, e.to, e.rel, e.weight, e.metadata ? JSON.stringify(e.metadata) : null);
+}
+
+export interface KbRow { id: string; kind: string; title: string; summary: string | null; content: string; }
+
+export function getNodes(db: Database, ids: string[]): Map<string, KbRow> {
+  const out = new Map<string, KbRow>();
+  if (!ids.length) return out;
+  const placeholders = ids.map(() => "?").join(",");
+  for (const r of db.query(`SELECT id, kind, title, summary, content FROM kb_nodes WHERE id IN (${placeholders})`).all(...ids) as KbRow[]) {
+    out.set(r.id, r);
+  }
+  return out;
+}
+
+/** N-hop neighbors of a seed set, walking edges in BOTH directions, keeping each node's min depth.
+ *  Optionally restricted to specific edge relations. Excludes the seeds themselves. */
+export function neighbors(db: Database, seedIds: string[], hops: number, rels?: string[]): { id: string; depth: number }[] {
+  if (seedIds.length === 0 || hops <= 0) return [];
+  const seedJson = JSON.stringify(seedIds);
+  const relFilter = rels && rels.length ? `AND e.rel IN (${rels.map(() => "?").join(",")})` : "";
+  const sql = `
+    WITH RECURSIVE reach(id, depth) AS (
+      SELECT value, 0 FROM json_each(?)
+      UNION
+      SELECT CASE WHEN e.from_id = r.id THEN e.to_id ELSE e.from_id END, r.depth + 1
+      FROM reach r JOIN kb_edges e ON (e.from_id = r.id OR e.to_id = r.id)
+      WHERE r.depth < ? ${relFilter}
+    )
+    SELECT id, MIN(depth) AS depth FROM reach
+    WHERE id NOT IN (SELECT value FROM json_each(?))
+    GROUP BY id`;
+  const params = [seedJson, hops, ...(rels && rels.length ? rels : []), seedJson];
+  return db.query(sql).all(...params) as { id: string; depth: number }[];
+}
+
+/** Plan 19 Ph1b: rewrite any node file still carrying the legacy `scope: deck` frontmatter. `parseNode`
+ *  already normalizes the value on read (schemas/knowledge.ts KbScope), so this just re-serializes what
+ *  it parsed — the files are canon and must eventually say what they mean. Idempotent, and a no-op on a
+ *  workspace that has never seen a pre-Plan-19 taicho. Runs at boot, before reindexKnowledge. */
+export function reconcileKbScope(ws: string, db: Database): number {
+  const dir = paths.kbNodeDir(ws);
+  if (!existsSync(dir)) return 0;
+  let migrated = 0;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith(".md")) continue;
+    const file = join(dir, f);
+    let raw: string;
+    try { raw = readFileSync(file, "utf8"); } catch { continue; }
+    if (!/^scope:\s*["']?deck["']?\s*$/m.test(raw)) continue;
+    try { writeNode(ws, db, parseNode(raw)); migrated++; }
+    catch (e) { log.warn(`kb scope backfill skipped ${f}`, e); }
+  }
+  if (migrated) log.info(`kb: rewrote ${migrated} node file(s) from scope 'deck' to 'squad'`);
+  return migrated;
+}
+
+/** Rebuild the kb_nodes/kb_edges index from the canonical files (proves files-are-canon). */
+export function reindexKnowledge(ws: string, db: Database): void {
+  db.exec("DELETE FROM kb_edges; DELETE FROM kb_nodes;");
+  for (const n of listNodes(ws)) indexNode(db, n);
+}
+
+export interface NodeFilter { ids?: string[]; kind?: string; sourcePrefix?: string }
+
+/** Build the WHERE clause + params for a NodeFilter, shared by the destructive (resolveNodeIds) and
+ *  list (listNodeRows) paths. Combine clauses with AND. */
+function filterClause(filter: NodeFilter): { where: string; params: (string | number)[] } {
+  const parts: string[] = [];
+  const params: (string | number)[] = [];
+  if (filter.ids?.length) { parts.push(`id IN (${filter.ids.map(() => "?").join(",")})`); params.push(...filter.ids); }
+  if (filter.kind) { parts.push("kind = ?"); params.push(filter.kind); }
+  if (filter.sourcePrefix) { parts.push("source LIKE ? ESCAPE '\\'"); params.push(likePrefix(filter.sourcePrefix)); }
+  return { where: parts.length ? `WHERE ${parts.join(" AND ")}` : "", params };
+}
+
+/** Node ids matching a filter. An EMPTY filter matches nothing (never "everything") — a safety
+ *  guard so a mis-built prune can't wipe the whole graph. Combine clauses with AND. */
+export function resolveNodeIds(db: Database, filter: NodeFilter): string[] {
+  const c = filterClause(filter);
+  if (!c.where) return []; // empty filter matches NOTHING — the destructive-path safety guard
+  return (db.query(`SELECT id FROM kb_nodes ${c.where}`).all(...c.params) as { id: string }[]).map((r) => r.id);
+}
+
+export interface NodeRow { id: string; kind: string; title: string; source: string | null }
+
+/** List semantics: an EMPTY filter lists ALL nodes — deliberately different from resolveNodeIds,
+ *  which is the destructive path and matches nothing on empty. */
+export function listNodeRows(db: Database, filter: NodeFilter): NodeRow[] {
+  const c = filterClause(filter);
+  return db.query(`SELECT id, kind, title, source FROM kb_nodes ${c.where} ORDER BY updated DESC, id`).all(...c.params) as NodeRow[];
+}
+
+/** Escape LIKE wildcards in a literal prefix, then append `%`. */
+function likePrefix(prefix: string): string {
+  return prefix.replace(/[\\%_]/g, (c) => "\\" + c) + "%";
+}
+
+/** Cascade delete: for the matched nodes, remove their edges (both directions), vectors, node rows,
+ *  and canonical files — atomically. The single prune path for /kb forget and source re-sync. */
+export function forgetNodes(ws: string, db: Database, filter: NodeFilter): { removedNodes: number; removedEdges: number } {
+  const ids = resolveNodeIds(db, filter);
+  if (!ids.length) return { removedNodes: 0, removedEdges: 0 };
+  const ph = ids.map(() => "?").join(",");
+  // Files are canon: delete them FIRST so a crash can't leave a file that boot-reindex resurrects.
+  for (const id of ids) {
+    try { rmSync(paths.kbNodeFile(ws, id)); }
+    catch (e) { if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e; }
+  }
+  let removedEdges = 0;
+  db.transaction(() => {
+    removedEdges = (db.query(`SELECT COUNT(*) c FROM kb_edges WHERE from_id IN (${ph}) OR to_id IN (${ph})`).get(...ids, ...ids) as { c: number }).c;
+    db.query(`DELETE FROM kb_edges WHERE from_id IN (${ph}) OR to_id IN (${ph})`).run(...ids, ...ids);
+    db.query(`DELETE FROM embeddings WHERE kind = 'kb' AND ref IN (${ph})`).run(...ids);
+    db.query(`DELETE FROM kb_nodes WHERE id IN (${ph})`).run(...ids);
+  })();
+  return { removedNodes: ids.length, removedEdges };
+}
+
+/** (Re)compute a vector for every kb_node from its title/summary/content. Used by /kb reindex to
+ *  refresh semantic vectors after hand-edits or a blown-away embeddings table. Best-effort per node:
+ *  one failure doesn't abort the pass. */
+export async function reembedAll(db: Database, embed: (t: string) => Promise<Float32Array>): Promise<number> {
+  const rows = db.query("SELECT id, title, summary, content FROM kb_nodes").all() as KbRow[];
+  let n = 0;
+  for (const r of rows) {
+    try { putVector(db, r.id, "kb", await embed(`${r.title}\n${r.summary ?? ""}\n${r.content}`)); n++; }
+    catch (e) { log.error(`reembed ${r.id} failed`, e); }
+  }
+  return n;
+}

package/src/store/mcp-store.ts

@@ -0,0 +1,65 @@
+/** Writable store of MCP servers added at runtime via `/mcp add`, per workspace at
+ *  <ws>/agents/.mcp/servers.json (under the gitignored agents/ dir). taicho.yaml `mcp.servers`
+ *  is read-only canon; this store layers on top — the effective set is yaml ∪ store. */
+import { z } from "zod";
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { McpServerConfig } from "./config";
+import { log } from "../core/logger";
+
+const StoreSchema = z.record(z.string(), McpServerConfig);
+export type McpStore = z.infer<typeof StoreSchema>;
+
+function storeDir(ws: string): string { return join(ws, "agents", ".mcp"); }
+function storePath(ws: string): string { return join(storeDir(ws), "servers.json"); }
+
+export function readMcpStore(ws: string): McpStore {
+  const f = storePath(ws);
+  if (!existsSync(f)) return {};
+  let raw: unknown;
+  try { raw = JSON.parse(readFileSync(f, "utf8")); } catch { return {}; }
+  if (typeof raw !== "object" || raw === null) return {};
+  // Validate per entry so one malformed server doesn't silently wipe the whole store.
+  const out: McpStore = {};
+  for (const [name, spec] of Object.entries(raw as Record<string, unknown>)) {
+    const parsed = McpServerConfig.safeParse(spec);
+    if (parsed.success) out[name] = parsed.data;
+    else log.warn(`skipping invalid MCP server "${name}" in mcp-store`);
+  }
+  return out;
+}
+
+function write(ws: string, all: McpStore): void {
+  mkdirSync(storeDir(ws), { recursive: true });
+  writeFileSync(storePath(ws), JSON.stringify(all, null, 2));
+}
+
+export function addMcpServer(ws: string, name: string, spec: McpServerConfig): void {
+  const all = readMcpStore(ws);
+  all[name] = spec;
+  write(ws, all);
+}
+
+export function removeMcpServer(ws: string, name: string): boolean {
+  const all = readMcpStore(ws);
+  if (!(name in all)) return false;
+  delete all[name];
+  write(ws, all);
+  return true;
+}
+
+/** Load every stored server's `env` into `process.env`, so a `${VAR}` ref in a url/header/arg resolves
+ *  (via `interpolateEnv`). Called on boot BEFORE the manager connects, and again right after a server is
+ *  added so it connects in the SAME session — the env travels WITH the server entry, no separate secrets
+ *  file. Idempotent (re-applying the same values is a no-op). Returns the variable NAMES applied; the
+ *  VALUES are secrets and must never be logged. */
+export function applyMcpEnv(ws: string): string[] {
+  const applied: string[] = [];
+  for (const spec of Object.values(readMcpStore(ws))) {
+    for (const [name, value] of Object.entries(spec.env ?? {})) {
+      process.env[name] = value;
+      applied.push(name);
+    }
+  }
+  return applied;
+}

package/src/store/migrate.ts

@@ -0,0 +1,278 @@
+/** Minimal versioned schema migrator for the derived SQLite cache. The DB holds derived state only
+ *  (files are canon — deleting the DB and re-indexing must always work), so migrations just create
+ *  tables/indexes; a `meta` row tracks the applied version. Run once in openDb after the baseline. */
+import type { Database } from "bun:sqlite";
+
+export function getMeta(db: Database, key: string): string | null {
+  const r = db.query("SELECT value FROM meta WHERE key = ?").get(key) as { value: string } | null;
+  return r?.value ?? null;
+}
+
+export function setMeta(db: Database, key: string, value: string): void {
+  db.query("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(key, value);
+}
+
+interface Migration { version: number; up: (db: Database) => void; }
+
+const MIGRATIONS: Migration[] = [
+  // v1: baseline — registry/embeddings/task_ledger already created by openDb's `CREATE TABLE IF NOT EXISTS`.
+  { version: 1, up: () => {} },
+  // v2: knowledgebase graph — typed nodes + typed edges. Embeddings reuse the existing table (kind='kb').
+  {
+    version: 2,
+    up: (db) =>
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS kb_nodes (
+          id       TEXT PRIMARY KEY,
+          kind     TEXT NOT NULL,
+          title    TEXT NOT NULL,
+          summary  TEXT,
+          content  TEXT NOT NULL,
+          source   TEXT,
+          scope    TEXT NOT NULL DEFAULT 'deck',
+          metadata TEXT,
+          created  INTEGER DEFAULT (unixepoch()),
+          updated  INTEGER DEFAULT (unixepoch())
+        );
+        CREATE TABLE IF NOT EXISTS kb_edges (
+          from_id  TEXT NOT NULL,
+          to_id    TEXT NOT NULL,
+          rel      TEXT NOT NULL,
+          weight   REAL DEFAULT 1.0,
+          metadata TEXT,
+          created  INTEGER DEFAULT (unixepoch()),
+          PRIMARY KEY (from_id, to_id, rel)
+        );
+        CREATE INDEX IF NOT EXISTS kb_edges_from ON kb_edges(from_id);
+        CREATE INDEX IF NOT EXISTS kb_edges_to   ON kb_edges(to_id);
+        CREATE INDEX IF NOT EXISTS kb_nodes_kind ON kb_nodes(kind);
+      `),
+  },
+  // v3: source-document tracking — one row per file in kb/sources/, holds its last-synced hash.
+  {
+    version: 3,
+    up: (db) =>
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS kb_sources (
+          path     TEXT PRIMARY KEY,   -- relative, e.g. "sources/architecture.md"
+          hash     TEXT NOT NULL,      -- content hash last synced
+          updated  INTEGER DEFAULT (unixepoch())
+        );
+      `),
+  },
+  // v4: agent skills — reusable procedure documents. Files (skills/*.md) are canon; this is the index.
+  {
+    version: 4,
+    up: (db) =>
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS skills (
+          id          TEXT PRIMARY KEY,
+          name        TEXT NOT NULL,
+          description TEXT NOT NULL,
+          tags        TEXT,
+          status      TEXT NOT NULL DEFAULT 'active',
+          body        TEXT NOT NULL,
+          updated     INTEGER DEFAULT (unixepoch())
+        );
+        CREATE INDEX IF NOT EXISTS skills_status ON skills(status);
+      `),
+  },
+  // v5: task queue index (Plan 04). Files (tasks/*.json) are canon; this is a rebuildable index so
+  // `/tasks` can list/query fast and background tasks survive restarts. reindexTasks() rebuilds it.
+  {
+    version: 5,
+    up: (db) =>
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS tasks (
+          id          TEXT PRIMARY KEY,
+          agent       TEXT,
+          goal        TEXT,
+          status      TEXT NOT NULL,
+          kind        TEXT NOT NULL DEFAULT 'chat',   -- 'chat' (a watched turn) | 'background' (dispatched)
+          root_run_id TEXT,
+          result_ref  TEXT,
+          summary     TEXT,
+          created     TEXT,
+          updated     TEXT
+        );
+        CREATE INDEX IF NOT EXISTS tasks_status ON tasks(status);
+        CREATE INDEX IF NOT EXISTS tasks_kind   ON tasks(kind);
+      `),
+  },
+  // v6: deck spend counters (Plan 09). Rolling per-period totals keyed by UTC day / ISO week so
+  // deck-wide budget ceilings span sessions. An enforcement counter, not a ledger of record — traces
+  // stay canon for /costs reporting; this just answers "how much has the deck spent this day/week".
+  // (v7 renames this table to squad_spend. Migrations are history — this DDL stays as it shipped.)
+  {
+    version: 6,
+    up: (db) =>
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS deck_spend (
+          period_kind TEXT NOT NULL,           -- 'day' | 'week'
+          period_key  TEXT NOT NULL,           -- 'YYYY-MM-DD' | 'YYYY-Www'
+          tokens      INTEGER NOT NULL DEFAULT 0,
+          cost_usd    REAL NOT NULL DEFAULT 0, -- priced runs only; subscription/unpriced commit 0
+          updated     INTEGER DEFAULT (unixepoch()),
+          PRIMARY KEY (period_kind, period_key)
+        );
+      `),
+  },
+  // v7: Plan 19 — "deck" retires in favour of "squad" (every agent in the workspace; taicho is 隊長,
+  // squad leader). Unlike the DeckLedger→SpendLedger rename this touches PERSISTED values, so it is a
+  // real migration, not a find-and-replace:
+  //   · kb_nodes.scope rows 'deck' → 'squad'. The column DEFAULT stays 'deck' because SQLite cannot
+  //     alter a default without rebuilding the table — and it is inert, since store/knowledge.ts always
+  //     supplies scope explicitly. Node FILES are canon; reconcileKbScope() rewrites their frontmatter
+  //     at boot and reindexKnowledge() then refreshes these rows anyway. This UPDATE covers the window
+  //     before that runs, and any DB whose canonical files were removed.
+  //   · deck_spend → squad_spend. Rows carry forward: silently resetting a user's running weekly total
+  //     would be rude, and the counter is cheap to move.
+  {
+    version: 7,
+    up: (db) => {
+      db.exec("UPDATE kb_nodes SET scope = 'squad' WHERE scope = 'deck'");
+      const legacy = db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'deck_spend'").get();
+      if (legacy) db.exec("ALTER TABLE deck_spend RENAME TO squad_spend");
+      else
+        db.exec(`
+          CREATE TABLE IF NOT EXISTS squad_spend (
+            period_kind TEXT NOT NULL,
+            period_key  TEXT NOT NULL,
+            tokens      INTEGER NOT NULL DEFAULT 0,
+            cost_usd    REAL NOT NULL DEFAULT 0,
+            updated     INTEGER DEFAULT (unixepoch()),
+            PRIMARY KEY (period_kind, period_key)
+          );
+        `);
+    },
+  },
+  // v8: Plan 19 — team membership on the registry index. `registry` is created by openDb's BASELINE
+  // `CREATE TABLE IF NOT EXISTS` (db.ts), not by a migration, and IF NOT EXISTS cannot add a column to a
+  // table that already exists. So the column is declared in BOTH places and both are idempotent:
+  //   · baseline db.ts  — gives a FRESH workspace the column at creation
+  //   · this ALTER      — gives every EXISTING workspace the column on upgrade
+  // Either one alone is a bug (baseline alone silently skips existing DBs; ALTER alone throws
+  // "duplicate column" on fresh ones), which is why the guard below is a check and not a try/catch.
+  // Membership is canon in agents/<id>/agent.md (`team:`); this column is the derived index that makes
+  // "who is on team news" one query instead of a full roster scan.
+  {
+    version: 8,
+    up: (db) => {
+      // migrate() also runs standalone over a bare Database in unit tests, where the baseline never ran.
+      if (!tableExists(db, "registry")) return;
+      if (!columnExists(db, "registry", "team")) db.exec("ALTER TABLE registry ADD COLUMN team TEXT");
+      db.exec("CREATE INDEX IF NOT EXISTS registry_team ON registry(team)");
+    },
+  },
+  // v9: Plan 19 — per-team spend ceilings. The counter gains a `scope` dimension ('squad' | 'team:<id>')
+  // and it belongs in the primary key: a team's daily total and the squad's must accumulate separately.
+  // SQLite cannot alter a primary key, so the table is recreated and its rows copied forward as 'squad'
+  // spend. It is only a counter, not a ledger of record (traces stay canon for /costs) — but silently
+  // resetting someone's running weekly total would be rude, so we carry it.
+  {
+    version: 9,
+    up: (db) => {
+      if (!tableExists(db, "squad_spend")) return; // bare migrate() over a Database with no baseline
+      if (columnExists(db, "squad_spend", "scope")) return; // already reshaped
+      db.exec(`
+        CREATE TABLE squad_spend_v9 (
+          scope       TEXT NOT NULL,           -- 'squad' | 'team:<id>'
+          period_kind TEXT NOT NULL,           -- 'day' | 'week'
+          period_key  TEXT NOT NULL,           -- 'YYYY-MM-DD' | 'YYYY-Www'
+          tokens      INTEGER NOT NULL DEFAULT 0,
+          cost_usd    REAL NOT NULL DEFAULT 0, -- priced runs only; subscription/unpriced commit 0
+          updated     INTEGER DEFAULT (unixepoch()),
+          PRIMARY KEY (scope, period_kind, period_key)
+        );
+        INSERT INTO squad_spend_v9 (scope, period_kind, period_key, tokens, cost_usd, updated)
+          SELECT 'squad', period_kind, period_key, tokens, cost_usd, updated FROM squad_spend;
+        DROP TABLE squad_spend;
+        ALTER TABLE squad_spend_v9 RENAME TO squad_spend;
+      `);
+    },
+  },
+  // v10: Plan 18 — the plan index. Files are canon (plans/<id>/v<N>.json + events.jsonl); this table
+  // stores only the FOLDED counters, so the panel and /plan never walk the event log to answer "how many
+  // are open". reindexPlans() rebuilds it from the files, which is what makes the DB throwaway.
+  {
+    version: 10,
+    up: (db) =>
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS plans (
+          id          TEXT PRIMARY KEY,
+          version     INTEGER NOT NULL,
+          owner       TEXT NOT NULL,
+          goal        TEXT,
+          total       INTEGER NOT NULL DEFAULT 0,
+          done        INTEGER NOT NULL DEFAULT 0,
+          open        INTEGER NOT NULL DEFAULT 0,
+          failed      INTEGER NOT NULL DEFAULT 0,
+          root_run_id TEXT,
+          created     TEXT,
+          updated     TEXT
+        );
+        CREATE INDEX IF NOT EXISTS plans_owner ON plans(owner);
+        CREATE INDEX IF NOT EXISTS plans_open  ON plans(open);
+      `),
+  },
+  // v11: Plan 22 — many-to-many team membership. An agent may sit on several teams, so the single
+  // `registry.team` column can no longer hold membership. `agent_teams` is the join (agent × team), and
+  // — unlike v8's `team` COLUMN, which needed a baseline + a guarded ALTER because IF NOT EXISTS can't
+  // add a column — a NEW TABLE is created idempotently by the migration alone, for fresh and existing
+  // DBs both. Membership is canon in agents/<id>/agent.md (`teams:`); this is the derived index, and
+  // reindex() rebuilds it every boot (adding the implicit `default` membership). The one-time carry
+  // below only bridges the window before that first reindex (and unit tests that migrate but never
+  // reindex): it lifts any pre-Plan-22 single-team rows into the join so nothing is lost.
+  {
+    version: 11,
+    up: (db) => {
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS agent_teams (
+          agent_id TEXT NOT NULL,
+          team_id  TEXT NOT NULL,
+          ord      INTEGER NOT NULL DEFAULT 0,   -- declaration order, for deterministic model resolution
+          PRIMARY KEY (agent_id, team_id)
+        );
+        CREATE INDEX IF NOT EXISTS agent_teams_team ON agent_teams(team_id);
+      `);
+      if (!tableExists(db, "registry") || !columnExists(db, "registry", "team")) return;
+      const rows = db.query("SELECT id, team FROM registry WHERE team IS NOT NULL AND team <> ''").all() as { id: string; team: string }[];
+      const ins = db.query("INSERT OR IGNORE INTO agent_teams (agent_id, team_id, ord) VALUES (?, ?, 0)");
+      for (const r of rows) ins.run(r.id, r.team);
+    },
+  },
+];
+
+function tableExists(db: Database, table: string): boolean {
+  return !!db.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?").get(table);
+}
+
+function columnExists(db: Database, table: string, column: string): boolean {
+  return (db.query(`PRAGMA table_info(${table})`).all() as { name: string }[]).some((c) => c.name === column);
+}
+
+export const SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1]!.version;
+
+export function migrate(db: Database): void {
+  db.exec("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT)");
+  const cur = Number(getMeta(db, "schema_version") ?? "0");
+  for (const m of MIGRATIONS) {
+    if (m.version > cur) {
+      db.transaction(() => m.up(db))();
+      setMeta(db, "schema_version", String(m.version));
+    }
+  }
+}
+
+/** Guard against mixing embedding models/dimensions: if the active embedder changed, wipe stale kb
+ *  vectors so cosine never compares incompatible spaces. Safe — embeddings are a derived cache that
+ *  re-fills lazily on the next remember/recall. */
+export function ensureEmbedSpace(db: Database, model: string, dim: number): void {
+  const pm = getMeta(db, "embed_model");
+  const pd = Number(getMeta(db, "embed_dim") ?? "0");
+  if (pm !== model || pd !== dim) {
+    db.query("DELETE FROM embeddings WHERE kind = 'kb'").run();
+    setMeta(db, "embed_model", model);
+    setMeta(db, "embed_dim", String(dim));
+  }
+}