zam-core 0.3.7 → 0.3.11

package/dist/index.js

@@ -1,76 +1,84 @@
 // src/kernel/analytics/stats.ts
-function q(db, sql, ...params) {
-  return db.prepare(sql).get(...params);
+async function q(db, sql, ...params) {
+  return await db.prepare(sql).get(...params);
 }
-function getUserStats(db, userId) {
+async function count(db, sql, ...params) {
+  return (await q(db, sql, ...params)).n;
+}
+async function getUserStats(db, userId) {
+  const avgRow = await q(
+    db,
+    "SELECT AVG(stability) as v FROM cards WHERE user_id = ? AND reps > 0",
+    userId
+  );
+  const lastSessionRow = await db.prepare(
+    "SELECT started_at FROM sessions WHERE user_id = ? ORDER BY started_at DESC LIMIT 1"
+  ).get(userId);
   return {
     userId,
-    totalTokens: q(db, "SELECT COUNT(*) as n FROM tokens").n,
-    cardsInDeck: q(db, "SELECT COUNT(*) as n FROM cards WHERE user_id = ?", userId).n,
-    dueToday: q(
+    totalTokens: await count(db, "SELECT COUNT(*) as n FROM tokens"),
+    cardsInDeck: await count(
+      db,
+      "SELECT COUNT(*) as n FROM cards WHERE user_id = ?",
+      userId
+    ),
+    dueToday: await count(
       db,
       "SELECT COUNT(*) as n FROM cards WHERE user_id = ? AND blocked = 0 AND due_at <= datetime('now')",
       userId
-    ).n,
-    blocked: q(
+    ),
+    blocked: await count(
       db,
       "SELECT COUNT(*) as n FROM cards WHERE user_id = ? AND blocked = 1",
       userId
-    ).n,
-    mature: q(
+    ),
+    mature: await count(
       db,
       "SELECT COUNT(*) as n FROM cards WHERE user_id = ? AND reps >= 3 AND stability >= 21",
       userId
-    ).n,
-    avgStability: (() => {
-      const v = q(
-        db,
-        "SELECT AVG(stability) as v FROM cards WHERE user_id = ? AND reps > 0",
-        userId
-      );
-      return v.v ? Math.round(v.v * 100) / 100 : null;
-    })(),
-    totalSessions: q(db, "SELECT COUNT(*) as n FROM sessions WHERE user_id = ?", userId).n,
-    lastSession: (() => {
-      const r = db.prepare(
-        "SELECT started_at FROM sessions WHERE user_id = ? ORDER BY started_at DESC LIMIT 1"
-      ).get(userId);
-      return r?.started_at ?? null;
-    })()
+    ),
+    avgStability: avgRow.v ? Math.round(avgRow.v * 100) / 100 : null,
+    totalSessions: await count(
+      db,
+      "SELECT COUNT(*) as n FROM sessions WHERE user_id = ?",
+      userId
+    ),
+    lastSession: lastSessionRow?.started_at ?? null
   };
 }
-function getDomainCompetence(db, userId) {
-  const domains = db.prepare(
+async function getDomainCompetence(db, userId) {
+  const domains = await db.prepare(
     `SELECT DISTINCT t.domain FROM cards c
        JOIN tokens t ON t.id = c.token_id
        WHERE c.user_id = ? AND t.domain != ''`
   ).all(userId);
-  return domains.map((d) => {
-    const total = q(
+  const competences = [];
+  for (const d of domains) {
+    const total = await count(
       db,
       `SELECT COUNT(*) as n FROM cards c
        JOIN tokens t ON t.id = c.token_id
        WHERE c.user_id = ? AND t.domain = ?`,
       userId,
       d.domain
-    ).n;
-    const mature = q(
+    );
+    const mature = await count(
       db,
       `SELECT COUNT(*) as n FROM cards c
        JOIN tokens t ON t.id = c.token_id
        WHERE c.user_id = ? AND t.domain = ? AND c.reps >= 3 AND c.stability >= 21`,
       userId,
       d.domain
-    ).n;
-    const avgStab = q(
+    );
+    const avgStab = (await q(
       db,
       `SELECT AVG(c.stability) as v FROM cards c
        JOIN tokens t ON t.id = c.token_id
        WHERE c.user_id = ? AND t.domain = ? AND c.reps > 0`,
       userId,
       d.domain
-    ).v ?? 0;
-    const reviews = q(
+    )).v ?? 0;
+    const reviews = await q(
       db,
       `SELECT COUNT(*) as total,
               SUM(CASE WHEN rating >= 2 THEN 1 ELSE 0 END) as passed
@@ -88,19 +96,26 @@ function getDomainCompetence(db, userId) {
     } else {
       suggestedMode = "shadowing";
     }
-    return {
+    competences.push({
       domain: d.domain,
       totalCards: total,
       matureCards: mature,
       avgStability: Math.round(avgStab * 100) / 100,
       retentionRate: Math.round(retentionRate * 1e3) / 1e3,
       suggestedMode
-    };
-  });
+    });
+  }
+  return competences;
 }
 
 // src/kernel/credentials.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
 import { homedir } from "os";
 import { dirname, join } from "path";
 var DEFAULT_CREDENTIALS_PATH = join(homedir(), ".zam", "credentials.json");
@@ -116,22 +131,37 @@ function loadCredentials(path) {
 function saveCredentials(creds, path) {
   const p = path ?? DEFAULT_CREDENTIALS_PATH;
   const dir = dirname(p);
+  let createdDirectory = false;
   if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
+    mkdirSync(dir, { recursive: true, mode: 448 });
+    createdDirectory = true;
+  }
+  if (process.platform !== "win32" && (path === void 0 || createdDirectory)) {
+    chmodSync(dir, 448);
   }
   writeFileSync(p, `${JSON.stringify(creds, null, 2)}
-`, "utf-8");
+`, {
+    encoding: "utf-8",
+    mode: 384
+  });
+  if (process.platform !== "win32") {
+    chmodSync(p, 384);
+  }
 }
 function getTursoCredentials(path) {
   const creds = loadCredentials(path);
   if (creds.turso?.url && creds.turso?.token) {
-    return { url: creds.turso.url, token: creds.turso.token };
+    return {
+      url: creds.turso.url,
+      token: creds.turso.token,
+      ...creds.turso.mode ? { mode: creds.turso.mode } : {}
+    };
   }
   return null;
 }
-function setTursoCredentials(url, token, path) {
+function setTursoCredentials(url, token, path, mode) {
   const creds = loadCredentials(path);
-  creds.turso = { url, token };
+  creds.turso = { url, token, ...mode ? { mode } : {} };
   saveCredentials(creds, path);
 }
 function clearTursoCredentials(path) {
@@ -222,7 +252,255 @@ import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as rea
 import { createRequire } from "module";
 import { homedir as homedir2 } from "os";
 import { dirname as dirname2, join as join2 } from "path";
-import BetterSqlite3 from "better-sqlite3";
+
+// src/kernel/db/remote/hrana.ts
+var DEFAULT_TIMEOUT_MS = 15e3;
+var DEFAULT_MAX_ATTEMPTS = 2;
+function toHttpUrl(url) {
+  return url.replace(/^libsql:\/\//i, "https://").replace(/^wss:\/\//i, "https://").replace(/^ws:\/\//i, "http://").replace(/\/+$/, "");
+}
+function encodeValue(param) {
+  if (param === null) return { type: "null" };
+  if (typeof param === "string") return { type: "text", value: param };
+  if (typeof param === "bigint") {
+    return { type: "integer", value: param.toString() };
+  }
+  if (typeof param === "number") {
+    if (Number.isSafeInteger(param)) {
+      return { type: "integer", value: param.toString() };
+    }
+    return { type: "float", value: param };
+  }
+  if (param instanceof Uint8Array) {
+    return { type: "blob", base64: Buffer.from(param).toString("base64") };
+  }
+  throw new TypeError(
+    `Cannot bind a value of type ${typeof param} to a SQL parameter`
+  );
+}
+function decodeValue(value) {
+  switch (value.type) {
+    case "null":
+      return null;
+    case "integer":
+      return Number(value.value);
+    case "float":
+      return value.value;
+    case "text":
+      return value.value;
+    case "blob":
+      return new Uint8Array(Buffer.from(value.base64, "base64"));
+  }
+}
+function rowsToObjects(result) {
+  return result.rows.map((row) => {
+    const obj = {};
+    row.forEach((value, i) => {
+      obj[result.cols[i]?.name ?? `col${i}`] = decodeValue(value);
+    });
+    return obj;
+  });
+}
+function isRetryableTransportError(err) {
+  if (!(err instanceof Error) || err.name === "HranaResponseError") {
+    return false;
+  }
+  const code = err.cause?.code;
+  return code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN";
+}
+var HranaResponseError = class extends Error {
+  name = "HranaResponseError";
+};
+var HranaTransport = class {
+  pipelineUrl;
+  authToken;
+  timeoutMs;
+  maxAttempts;
+  constructor(options) {
+    this.pipelineUrl = `${toHttpUrl(options.url)}/v3/pipeline`;
+    this.authToken = options.authToken;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  }
+  /**
+   * POST one pipeline of requests. Returns the server results plus the baton
+   * for continuing an open stream. Retries transport-level failures only for
+   * stateless pipelines (no baton involved on either side).
+   */
+  async pipeline(requests, baton, baseUrl) {
+    const url = baseUrl ? `${toHttpUrl(baseUrl)}/v3/pipeline` : this.pipelineUrl;
+    const keepsState = baton != null || !requests.some((r) => r.type === "close");
+    const attempts = keepsState ? 1 : this.maxAttempts;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+      try {
+        return await this.post(url, { baton: baton ?? null, requests });
+      } catch (err) {
+        lastError = err;
+        if (!isRetryableTransportError(err) || attempt === attempts) {
+          throw this.offline(err);
+        }
+      }
+    }
+    throw this.offline(lastError);
+  }
+  async post(url, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          ...this.authToken ? { authorization: `Bearer ${this.authToken}` } : {}
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.status === 401 || response.status === 403) {
+      throw new HranaResponseError(
+        `Turso rejected the configured credentials (HTTP ${response.status}). Refresh the token with: zam connector setup turso`
+      );
+    }
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "");
+      throw new HranaResponseError(
+        `Turso request failed with HTTP ${response.status}${detail ? `: ${detail.slice(0, 200)}` : ""}`
+      );
+    }
+    return await response.json();
+  }
+  offline(err) {
+    if (err instanceof HranaResponseError) return err;
+    const cause = err instanceof Error ? err.cause?.message ?? err.message : String(err);
+    return new HranaResponseError(
+      `Cannot reach the Turso database at ${this.pipelineUrl}: ${cause}. Check your network connection, or switch to the local provider (ZAM_DB_PROVIDER=local).`
+    );
+  }
+};
+function unwrapResult(response, index) {
+  const entry = response.results[index];
+  if (!entry) {
+    throw new HranaResponseError(`Turso response is missing result #${index}`);
+  }
+  if (entry.type === "error") {
+    throw new Error(entry.error.message);
+  }
+  return entry.response.result;
+}
+
+// src/kernel/db/remote/provider.ts
+var TABLE_INFO_PRAGMA = /^\s*table_info\s*\(\s*['"]?(\w+)['"]?\s*\)\s*$/i;
+function toRunResult(result) {
+  return {
+    changes: result?.affected_row_count ?? 0,
+    lastInsertRowid: result?.last_insert_rowid != null ? Number(result.last_insert_rowid) : 0
+  };
+}
+function makeStatement(sql, run) {
+  const execute = async (params, wantRows) => {
+    const { results } = await run([
+      {
+        type: "execute",
+        stmt: { sql, args: params.map(encodeValue), want_rows: wantRows }
+      }
+    ]);
+    return results[0];
+  };
+  return {
+    async run(...params) {
+      return toRunResult(await execute(params, false));
+    },
+    async get(...params) {
+      const result = await execute(params, true);
+      return result ? rowsToObjects(result)[0] : void 0;
+    },
+    async all(...params) {
+      const result = await execute(params, true);
+      return result ? rowsToObjects(result) : [];
+    }
+  };
+}
+function makeDatabase(run, transport) {
+  let txTail = Promise.resolve();
+  const db = {
+    prepare(sql) {
+      return makeStatement(sql, run);
+    },
+    async exec(sql) {
+      await run([{ type: "sequence", sql }]);
+    },
+    async pragma(source) {
+      const tableInfo = TABLE_INFO_PRAGMA.exec(source);
+      const sql = tableInfo ? `SELECT * FROM pragma_table_info('${tableInfo[1]}')` : `PRAGMA ${source}`;
+      return db.prepare(sql).all();
+    },
+    transaction(fn) {
+      const next = txTail.then(async () => {
+        const stream = openStream(transport);
+        try {
+          await stream.run([
+            {
+              type: "execute",
+              stmt: { sql: "BEGIN IMMEDIATE", want_rows: false }
+            }
+          ]);
+          const result = await fn(makeDatabase(stream.run, transport));
+          await stream.run(
+            [{ type: "execute", stmt: { sql: "COMMIT", want_rows: false } }],
+            true
+          );
+          return result;
+        } catch (err) {
+          await stream.run(
+            [
+              {
+                type: "execute",
+                stmt: { sql: "ROLLBACK", want_rows: false }
+              }
+            ],
+            true
+          ).catch(() => {
+          });
+          throw err;
+        }
+      });
+      txTail = next.catch(() => {
+      });
+      return next;
+    },
+    async close() {
+    }
+  };
+  return db;
+}
+function openStream(transport) {
+  let baton = null;
+  let baseUrl = null;
+  return {
+    async run(requests, close = false) {
+      const sent = close ? [...requests, { type: "close" }] : requests;
+      const response = await transport.pipeline(sent, baton, baseUrl);
+      baton = response.baton;
+      baseUrl = response.base_url ?? baseUrl;
+      return {
+        results: requests.map((_, i) => unwrapResult(response, i))
+      };
+    }
+  };
+}
+function openRemoteDatabase(options) {
+  const transport = new HranaTransport(options);
+  const statelessRun = async (requests) => {
+    const response = await transport.pipeline([...requests, { type: "close" }]);
+    return { results: requests.map((_, i) => unwrapResult(response, i)) };
+  };
+  return makeDatabase(statelessRun, transport);
+}
 
 // src/kernel/db/schema.ts
 var SCHEMA = `
@@ -303,6 +581,22 @@ CREATE TABLE IF NOT EXISTS session_steps (
   created_at  TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
+-- Confirmed ratings synthesized from monitor evidence.
+-- The composite primary key makes repeated synthesis idempotent per token.
+CREATE TABLE IF NOT EXISTS session_syntheses (
+  session_id       TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  token_id         TEXT NOT NULL REFERENCES tokens(id) ON DELETE CASCADE,
+  card_id          TEXT NOT NULL REFERENCES cards(id) ON DELETE CASCADE,
+  inferred_rating  INTEGER NOT NULL CHECK (inferred_rating BETWEEN 1 AND 4),
+  confirmed_rating INTEGER NOT NULL CHECK (confirmed_rating BETWEEN 1 AND 4),
+  confidence       TEXT NOT NULL CHECK (confidence IN ('medium', 'high')),
+  evidence         TEXT NOT NULL DEFAULT '{}',
+  review_log_id    TEXT NOT NULL REFERENCES review_logs(id) ON DELETE CASCADE,
+  session_step_id  TEXT NOT NULL REFERENCES session_steps(id) ON DELETE CASCADE,
+  created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (session_id, token_id)
+);
+
 -- User configuration
 CREATE TABLE IF NOT EXISTS user_config (
   key         TEXT PRIMARY KEY,
@@ -335,14 +629,70 @@ CREATE INDEX IF NOT EXISTS idx_review_logs_user ON review_logs(user_id, reviewed
 CREATE INDEX IF NOT EXISTS idx_session_steps_session ON session_steps(session_id);
 `;
 
+// src/kernel/db/sync-adapter.ts
+function wrapSyncDatabase(driver) {
+  let txTail = Promise.resolve();
+  const db = {
+    prepare(sql) {
+      return {
+        async run(...params) {
+          return driver.prepare(sql).run(...params);
+        },
+        async get(...params) {
+          return driver.prepare(sql).get(...params);
+        },
+        async all(...params) {
+          return driver.prepare(sql).all(...params);
+        }
+      };
+    },
+    async exec(sql) {
+      driver.exec(sql);
+    },
+    async pragma(source) {
+      return driver.pragma(source);
+    },
+    transaction(fn) {
+      const run = txTail.then(async () => {
+        driver.exec("BEGIN IMMEDIATE");
+        try {
+          const result = await fn(db);
+          driver.exec("COMMIT");
+          return result;
+        } catch (err) {
+          driver.exec("ROLLBACK");
+          throw err;
+        }
+      });
+      txTail = run.catch(() => {
+      });
+      return run;
+    },
+    ...driver.sync ? {
+      async sync() {
+        driver.sync?.();
+      }
+    } : {},
+    async close() {
+      driver.close();
+    }
+  };
+  return db;
+}
+
 // src/kernel/db/connection.ts
 var DEFAULT_DB_DIR = join2(homedir2(), ".zam");
 var DEFAULT_DB_PATH = join2(DEFAULT_DB_DIR, "zam.db");
 var require2 = createRequire(import.meta.url);
 function isRemoteDatabasePath(dbPath) {
-  return /^(libsql|https?):\/\//i.test(dbPath);
+  return /^(libsql|https?|wss?):\/\//i.test(dbPath);
+}
+function isDatabaseProvider(value) {
+  return value === "local" || value === "native" || value === "remote";
 }
 function openLocalSqlite(dbPath) {
+  const mod = require2("better-sqlite3");
+  const BetterSqlite3 = "default" in mod ? mod.default : mod;
   return new BetterSqlite3(dbPath);
 }
 function loadLibsql() {
@@ -352,11 +702,11 @@ function loadLibsql() {
   } catch (err) {
     const detail = err instanceof Error ? ` ${err.message}` : "";
     throw new Error(
-      `Turso sync requires the optional native libsql backend, which is not available for ${process.platform}/${process.arch}.${detail}`
+      `Turso sync requires the optional native libsql backend, which is not available for ${process.platform}/${process.arch}. Switch to the HTTP provider instead: zam connector setup turso --mode remote (or set ZAM_DB_PROVIDER=remote).${detail}`
     );
   }
 }
-function openDatabase(options = {}) {
+async function openDatabase(options = {}) {
   const configuredCloud = options.useConfiguredCloud !== false && !options.dbPath && !options.syncUrl ? getTursoCredentials() : null;
   let requiresTurso = false;
   try {
@@ -377,7 +727,26 @@ function openDatabase(options = {}) {
   const dbPath = configuredCloud?.url ?? options.dbPath ?? DEFAULT_DB_PATH;
   const isRemote = isRemoteDatabasePath(dbPath);
   const isEmbeddedReplica = Boolean(options.syncUrl);
-  if (options.initialize && !isRemote) {
+  const provider = resolveProvider(options, configuredCloud?.mode, isRemote);
+  const shouldInitialize = options.initialize === true || !isRemote && !isEmbeddedReplica && !existsSync2(dbPath);
+  if (provider === "remote") {
+    const url = isRemote ? dbPath : options.syncUrl;
+    if (!url) {
+      throw new Error(
+        "The remote database provider is selected but no Turso URL is configured. Run: zam connector setup turso"
+      );
+    }
+    const db2 = openRemoteDatabase({
+      url,
+      authToken: configuredCloud?.token ?? options.authToken
+    });
+    if (options.initialize) {
+      await db2.exec(SCHEMA);
+    }
+    await runMigrations(db2);
+    return db2;
+  }
+  if (shouldInitialize && !isRemote) {
     const dir = dirname2(dbPath);
     if (!existsSync2(dir)) {
       mkdirSync2(dir, { recursive: true });
@@ -402,66 +771,93 @@ function openDatabase(options = {}) {
   if (authToken) {
     dbOpts.authToken = authToken;
   }
-  let db;
+  let driver;
   if (isRemote || isEmbeddedReplica) {
-    const LibsqlDatabase = loadLibsql();
     try {
-      db = new LibsqlDatabase(dbPath, dbOpts);
-    } catch (err) {
-      const msg = err.message;
-      if (msg.includes("InvalidLocalState") && options.syncUrl) {
-        const metaPath = `${dbPath}.meta`;
-        const infoPath = `${dbPath}-info`;
-        if (existsSync2(metaPath)) rmSync(metaPath);
-        if (existsSync2(infoPath)) rmSync(infoPath);
-        db = new LibsqlDatabase(dbPath, dbOpts);
-      } else {
-        throw err;
+      const LibsqlDatabase = loadLibsql();
+      try {
+        driver = new LibsqlDatabase(dbPath, dbOpts);
+      } catch (err) {
+        const msg = err.message;
+        if (msg.includes("InvalidLocalState") && options.syncUrl) {
+          const metaPath = `${dbPath}.meta`;
+          const infoPath = `${dbPath}-info`;
+          if (existsSync2(metaPath)) rmSync(metaPath);
+          if (existsSync2(infoPath)) rmSync(infoPath);
+          driver = new LibsqlDatabase(dbPath, dbOpts);
+        } else {
+          throw err;
+        }
+      }
+    } catch (nativeErr) {
+      const fallbackUrl = isRemote ? dbPath : options.syncUrl;
+      if (isRemote && !isEmbeddedReplica && fallbackUrl) {
+        const db2 = openRemoteDatabase({
+          url: fallbackUrl,
+          authToken: configuredCloud?.token ?? options.authToken
+        });
+        if (options.initialize) {
+          await db2.exec(SCHEMA);
+        }
+        await runMigrations(db2);
+        return db2;
       }
+      throw nativeErr;
     }
   } else {
-    db = openLocalSqlite(dbPath);
+    driver = openLocalSqlite(dbPath);
   }
   if (!isRemote && !isEmbeddedReplica) {
-    db.pragma("journal_mode = WAL");
+    driver.pragma("journal_mode = WAL");
   }
-  db.pragma("foreign_keys = ON");
+  driver.pragma("foreign_keys = ON");
   if (!isRemote) {
-    db.pragma("busy_timeout = 5000");
+    driver.pragma("busy_timeout = 5000");
   }
+  const db = wrapSyncDatabase(driver);
   if (isEmbeddedReplica) {
-    db.sync?.();
+    await db.sync?.();
   }
-  if (options.initialize) {
-    db.exec(SCHEMA);
+  if (shouldInitialize) {
+    await db.exec(SCHEMA);
   }
-  runMigrations(db);
+  await runMigrations(db);
   return db;
 }
-function openDatabaseWithSync(options = {}) {
+function resolveProvider(options, credentialsMode, isRemote) {
+  if (options.provider) return options.provider;
+  const env = process.env.ZAM_DB_PROVIDER;
+  if (isDatabaseProvider(env)) return env;
+  if (isDatabaseProvider(credentialsMode) && (isRemote || options.syncUrl)) {
+    return credentialsMode;
+  }
+  if (isRemote || options.syncUrl) return "native";
+  return "local";
+}
+async function openDatabaseWithSync(options = {}) {
   return openDatabase(options);
 }
 function getDefaultDbPath() {
   return DEFAULT_DB_PATH;
 }
-function runMigrations(db) {
-  const sessionCols = db.pragma("table_info(sessions)");
+async function runMigrations(db) {
+  const sessionCols = await db.pragma("table_info(sessions)");
   if (sessionCols.length > 0 && !sessionCols.some((c) => c.name === "execution_context")) {
-    db.exec(
+    await db.exec(
       `ALTER TABLE sessions ADD COLUMN execution_context TEXT NOT NULL DEFAULT 'shell'`
     );
   }
-  const tokenCols = db.pragma("table_info(tokens)");
+  const tokenCols = await db.pragma("table_info(tokens)");
   if (tokenCols.length > 0 && !tokenCols.some((c) => c.name === "deprecated_at")) {
-    db.exec(`ALTER TABLE tokens ADD COLUMN deprecated_at TEXT`);
+    await db.exec(`ALTER TABLE tokens ADD COLUMN deprecated_at TEXT`);
   }
   if (tokenCols.length > 0 && !tokenCols.some((c) => c.name === "source_link")) {
-    db.exec(`ALTER TABLE tokens ADD COLUMN source_link TEXT`);
+    await db.exec(`ALTER TABLE tokens ADD COLUMN source_link TEXT`);
   }
   if (tokenCols.length > 0 && !tokenCols.some((c) => c.name === "question")) {
-    db.exec(`ALTER TABLE tokens ADD COLUMN question TEXT`);
+    await db.exec(`ALTER TABLE tokens ADD COLUMN question TEXT`);
   }
-  db.exec(`
+  await db.exec(`
     CREATE TABLE IF NOT EXISTS agent_skills (
       id          TEXT PRIMARY KEY,
       slug        TEXT NOT NULL UNIQUE,
@@ -473,6 +869,165 @@ function runMigrations(db) {
       updated_at  TEXT NOT NULL DEFAULT (datetime('now'))
     )
   `);
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS session_syntheses (
+      session_id       TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+      token_id         TEXT NOT NULL REFERENCES tokens(id) ON DELETE CASCADE,
+      card_id          TEXT NOT NULL REFERENCES cards(id) ON DELETE CASCADE,
+      inferred_rating  INTEGER NOT NULL CHECK (inferred_rating BETWEEN 1 AND 4),
+      confirmed_rating INTEGER NOT NULL CHECK (confirmed_rating BETWEEN 1 AND 4),
+      confidence       TEXT NOT NULL CHECK (confidence IN ('medium', 'high')),
+      evidence         TEXT NOT NULL DEFAULT '{}',
+      review_log_id    TEXT NOT NULL REFERENCES review_logs(id) ON DELETE CASCADE,
+      session_step_id  TEXT NOT NULL REFERENCES session_steps(id) ON DELETE CASCADE,
+      created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY (session_id, token_id)
+    )
+  `);
+}
+
+// src/kernel/db/snapshot.ts
+import { createHash } from "crypto";
+var SNAPSHOT_FORMAT = "zam-snapshot";
+var SNAPSHOT_VERSION = 1;
+var MANIFEST_PREFIX = "-- zam-snapshot: ";
+var SNAPSHOT_TABLES = [
+  "tokens",
+  "sessions",
+  "cards",
+  "prerequisites",
+  "session_steps",
+  "review_logs",
+  "session_syntheses",
+  "user_config",
+  "agent_skills"
+];
+function quoteValue(value) {
+  if (value === null || value === void 0) return "NULL";
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? String(value) : "NULL";
+  }
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value === "string") return `'${value.replace(/'/g, "''")}'`;
+  if (value instanceof Uint8Array) {
+    let hex = "";
+    for (const byte of value) hex += byte.toString(16).padStart(2, "0");
+    return `X'${hex}'`;
+  }
+  throw new Error(`Cannot serialize value of type ${typeof value} to SQL`);
+}
+async function getColumns(db, table) {
+  const cols = await db.pragma(`table_info(${table})`);
+  return cols.map((c) => c.name);
+}
+async function countRows(db, table) {
+  const row = await db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get();
+  return Number(row.n);
+}
+async function exportSnapshot(db, options = {}) {
+  const createdAt = options.createdAt ?? (/* @__PURE__ */ new Date()).toISOString();
+  const tables = {};
+  const sections = [];
+  for (const table of SNAPSHOT_TABLES) {
+    const columns = await getColumns(db, table);
+    if (columns.length === 0) {
+      tables[table] = 0;
+      continue;
+    }
+    const colList = columns.join(", ");
+    const rows = await db.prepare(`SELECT ${colList} FROM ${table}`).all();
+    tables[table] = rows.length;
+    if (rows.length === 0) continue;
+    const lines = [`-- ${table} (${rows.length})`];
+    for (const row of rows) {
+      const values = columns.map((c) => quoteValue(row[c])).join(", ");
+      lines.push(`INSERT INTO ${table} (${colList}) VALUES (${values});`);
+    }
+    sections.push(lines.join("\n"));
+  }
+  const body = sections.length > 0 ? `${sections.join("\n\n")}
+` : "";
+  const checksum = createHash("sha256").update(body).digest("hex");
+  const manifest = {
+    format: SNAPSHOT_FORMAT,
+    version: SNAPSHOT_VERSION,
+    createdAt,
+    tables,
+    checksum
+  };
+  return `${MANIFEST_PREFIX}${JSON.stringify(manifest)}
+${body}`;
+}
+function parseSnapshot(snapshot) {
+  const newline = snapshot.indexOf("\n");
+  const header = (newline === -1 ? snapshot : snapshot.slice(0, newline)).trim();
+  const body = newline === -1 ? "" : snapshot.slice(newline + 1);
+  if (!header.startsWith(MANIFEST_PREFIX)) {
+    throw new Error("Not a ZAM snapshot: missing manifest header.");
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(header.slice(MANIFEST_PREFIX.length));
+  } catch {
+    throw new Error("Snapshot manifest is not valid JSON.");
+  }
+  if (manifest.format !== SNAPSHOT_FORMAT) {
+    throw new Error(`Unsupported snapshot format: ${manifest.format}`);
+  }
+  if (manifest.version > SNAPSHOT_VERSION) {
+    throw new Error(
+      `Snapshot version ${manifest.version} is newer than supported (${SNAPSHOT_VERSION}). Upgrade ZAM to import it.`
+    );
+  }
+  return { manifest, body };
+}
+function verifySnapshot(snapshot) {
+  const { manifest, body } = parseSnapshot(snapshot);
+  const actual = createHash("sha256").update(body).digest("hex");
+  if (actual !== manifest.checksum) {
+    throw new Error("Snapshot is corrupted: checksum mismatch.");
+  }
+  return manifest;
+}
+async function importSnapshot(db, snapshot, options = {}) {
+  const { manifest, body } = parseSnapshot(snapshot);
+  const actual = createHash("sha256").update(body).digest("hex");
+  if (actual !== manifest.checksum) {
+    throw new Error("Snapshot is corrupted: checksum mismatch.");
+  }
+  return db.transaction(async (tx) => {
+    let existing = 0;
+    for (const table of SNAPSHOT_TABLES) {
+      existing += await countRows(tx, table);
+    }
+    if (existing > 0 && !options.force) {
+      throw new Error(
+        `Target database already holds ${existing} row(s). Pass force to overwrite it.`
+      );
+    }
+    if (options.force) {
+      for (const table of [...SNAPSHOT_TABLES].reverse()) {
+        await tx.exec(`DELETE FROM ${table};`);
+      }
+    }
+    if (body.trim().length > 0) {
+      await tx.exec(body);
+    }
+    const tables = {};
+    let total = 0;
+    for (const table of SNAPSHOT_TABLES) {
+      const count2 = await countRows(tx, table);
+      tables[table] = count2;
+      total += count2;
+      const expected = manifest.tables[table] ?? 0;
+      if (count2 !== expected) {
+        throw new Error(
+          `Restore verification failed for ${table}: expected ${expected} row(s), found ${count2}.`
+        );
+      }
+    }
+    return { tables, total };
+  });
 }
 
 // src/kernel/goals/engine.ts
@@ -670,14 +1225,14 @@ function parseRow(row) {
     token_slugs: JSON.parse(row.token_slugs)
   };
 }
-function createAgentSkill(db, input) {
-  const existing = db.prepare("SELECT * FROM agent_skills WHERE slug = ?").get(input.slug);
+async function createAgentSkill(db, input) {
+  const existing = await db.prepare("SELECT * FROM agent_skills WHERE slug = ?").get(input.slug);
   if (existing) {
     throw new Error(`Agent skill already exists: ${input.slug}`);
   }
   const id = ulid();
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  db.prepare(
+  await db.prepare(
     `INSERT INTO agent_skills (id, slug, description, steps, token_slugs, source, created_at, updated_at)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
   ).run(
@@ -691,38 +1246,38 @@ function createAgentSkill(db, input) {
     now
   );
   return parseRow(
-    db.prepare("SELECT * FROM agent_skills WHERE id = ?").get(id)
+    await db.prepare("SELECT * FROM agent_skills WHERE id = ?").get(id)
   );
 }
-function getAgentSkill(db, slug) {
-  const row = db.prepare("SELECT * FROM agent_skills WHERE slug = ?").get(slug);
+async function getAgentSkill(db, slug) {
+  const row = await db.prepare("SELECT * FROM agent_skills WHERE slug = ?").get(slug);
   return row ? parseRow(row) : void 0;
 }
-function listAgentSkills(db) {
-  const rows = db.prepare("SELECT * FROM agent_skills ORDER BY created_at ASC").all();
+async function listAgentSkills(db) {
+  const rows = await db.prepare("SELECT * FROM agent_skills ORDER BY created_at ASC").all();
   return rows.map(parseRow);
 }
 
 // src/kernel/models/card.ts
 import { ulid as ulid2 } from "ulid";
-function ensureCard(db, tokenId, userId) {
-  const existing = db.prepare("SELECT * FROM cards WHERE token_id = ? AND user_id = ?").get(tokenId, userId);
+async function ensureCard(db, tokenId, userId) {
+  const existing = await db.prepare("SELECT * FROM cards WHERE token_id = ? AND user_id = ?").get(tokenId, userId);
   if (existing) return existing;
   const id = ulid2();
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  db.prepare(
+  await db.prepare(
     `INSERT INTO cards (id, token_id, user_id, due_at)
      VALUES (?, ?, ?, ?)`
   ).run(id, tokenId, userId, now);
-  return db.prepare("SELECT * FROM cards WHERE id = ?").get(id);
+  return await db.prepare("SELECT * FROM cards WHERE id = ?").get(id);
 }
-function getCard(db, tokenId, userId) {
-  return db.prepare("SELECT * FROM cards WHERE token_id = ? AND user_id = ?").get(tokenId, userId);
+async function getCard(db, tokenId, userId) {
+  return await db.prepare("SELECT * FROM cards WHERE token_id = ? AND user_id = ?").get(tokenId, userId);
 }
-function getCardById(db, cardId) {
-  return db.prepare("SELECT * FROM cards WHERE id = ?").get(cardId);
+async function getCardById(db, cardId) {
+  return await db.prepare("SELECT * FROM cards WHERE id = ?").get(cardId);
 }
-function updateCard(db, cardId, updates) {
+async function updateCard(db, cardId, updates) {
   const fields = [];
   const values = [];
   if (updates.stability !== void 0) {
@@ -769,32 +1324,32 @@ function updateCard(db, cardId, updates) {
     throw new Error("updateCard called with no fields to update");
   }
   values.push(cardId);
-  const result = db.prepare(`UPDATE cards SET ${fields.join(", ")} WHERE id = ?`).run(...values);
+  const result = await db.prepare(`UPDATE cards SET ${fields.join(", ")} WHERE id = ?`).run(...values);
   if (result.changes === 0) {
     throw new Error(`Card not found: ${cardId}`);
   }
-  return db.prepare("SELECT * FROM cards WHERE id = ?").get(cardId);
+  return await db.prepare("SELECT * FROM cards WHERE id = ?").get(cardId);
 }
-function getCardDeletionImpact(db, tokenId, userId) {
-  const card = getCard(db, tokenId, userId);
+async function getCardDeletionImpact(db, tokenId, userId) {
+  const card = await getCard(db, tokenId, userId);
   if (!card) {
     throw new Error(`Card not found for token ${tokenId} and user ${userId}`);
   }
-  const reviewLogs = db.prepare("SELECT COUNT(*) AS n FROM review_logs WHERE card_id = ?").get(card.id);
+  const reviewLogs = await db.prepare("SELECT COUNT(*) AS n FROM review_logs WHERE card_id = ?").get(card.id);
   return { review_logs: reviewLogs.n };
 }
-function deleteCardForUser(db, tokenId, userId) {
-  const card = getCard(db, tokenId, userId);
+async function deleteCardForUser(db, tokenId, userId) {
+  const card = await getCard(db, tokenId, userId);
   if (!card) {
     throw new Error(`Card not found for token ${tokenId} and user ${userId}`);
   }
-  const impact = getCardDeletionImpact(db, tokenId, userId);
-  db.prepare("DELETE FROM cards WHERE id = ?").run(card.id);
+  const impact = await getCardDeletionImpact(db, tokenId, userId);
+  await db.prepare("DELETE FROM cards WHERE id = ?").run(card.id);
   return { card, impact };
 }
-function getDueCards(db, userId, now) {
+async function getDueCards(db, userId, now) {
   const cutoff = now ?? (/* @__PURE__ */ new Date()).toISOString();
-  return db.prepare(
+  return await db.prepare(
     `SELECT c.*, t.slug, t.concept, t.domain, t.bloom_level
        FROM cards c
        JOIN tokens t ON t.id = c.token_id
@@ -802,8 +1357,8 @@ function getDueCards(db, userId, now) {
        ORDER BY t.bloom_level ASC, c.due_at ASC`
   ).all(userId, cutoff);
 }
-function getBlockedCards(db, userId) {
-  return db.prepare(
+async function getBlockedCards(db, userId) {
+  return await db.prepare(
     `SELECT c.*, t.slug, t.concept, t.domain, t.bloom_level
        FROM cards c
        JOIN tokens t ON t.id = c.token_id
@@ -812,253 +1367,43 @@ function getBlockedCards(db, userId) {
   ).all(userId);
 }
 
-// src/kernel/models/prerequisite.ts
-function buildAncestorMap(db) {
-  const rows = db.prepare("SELECT token_id, requires_id FROM prerequisites").all();
-  const map = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    let ancestors = map.get(row.token_id);
-    if (!ancestors) {
-      ancestors = /* @__PURE__ */ new Set();
-      map.set(row.token_id, ancestors);
-    }
-    ancestors.add(row.requires_id);
-  }
-  return map;
-}
-function wouldCreateCycle(db, tokenId, requiresId) {
-  if (tokenId === requiresId) return true;
-  const ancestors = buildAncestorMap(db);
-  const visited = /* @__PURE__ */ new Set();
-  const queue = [requiresId];
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (current === tokenId) return true;
-    if (visited.has(current)) continue;
-    visited.add(current);
-    const parents = ancestors.get(current);
-    if (parents) {
-      for (const parent of parents) {
-        if (!visited.has(parent)) queue.push(parent);
-      }
-    }
-  }
-  return false;
-}
-function addPrerequisite(db, tokenId, requiresId) {
-  if (tokenId === requiresId) {
-    throw new Error("A token cannot be a prerequisite of itself");
-  }
-  if (wouldCreateCycle(db, tokenId, requiresId)) {
-    throw new Error(
-      `Cannot add prerequisite: would create a cycle. ${requiresId} already depends on ${tokenId} (directly or transitively).`
-    );
-  }
-  db.prepare(
-    "INSERT OR IGNORE INTO prerequisites (token_id, requires_id) VALUES (?, ?)"
-  ).run(tokenId, requiresId);
-}
-function getPrerequisites(db, tokenId) {
-  return db.prepare(
-    `SELECT p.token_id, p.requires_id, t.slug, t.concept, t.domain, t.bloom_level
-       FROM prerequisites p
-       JOIN tokens t ON t.id = p.requires_id
-       WHERE p.token_id = ?`
-  ).all(tokenId);
-}
-function getDependents(db, tokenId) {
-  return db.prepare(
-    `SELECT p.token_id, p.requires_id, t.slug, t.concept, t.domain, t.bloom_level
-       FROM prerequisites p
-       JOIN tokens t ON t.id = p.token_id
-       WHERE p.requires_id = ?`
-  ).all(tokenId);
-}
-
-// src/kernel/models/review.ts
+// src/kernel/models/token.ts
 import { ulid as ulid3 } from "ulid";
-function logReview(db, input) {
-  if (input.rating < 1 || input.rating > 4) {
-    throw new Error(`Rating must be between 1 and 4, got ${input.rating}`);
-  }
+async function createToken(db, input) {
   const id = ulid3();
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  db.prepare(
-    `INSERT INTO review_logs (id, card_id, token_id, user_id, rating, response_time_ms, reviewed_at, scheduled_at, session_id)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
-  ).run(
+  const bloom = input.bloom_level ?? 1;
+  if (bloom < 1 || bloom > 5) {
+    throw new Error(`bloom_level must be between 1 and 5, got ${bloom}`);
+  }
+  await db.prepare(`
+    INSERT INTO tokens (id, slug, concept, domain, bloom_level, context, symbiosis_mode, source_link, question, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
     id,
-    input.card_id,
-    input.token_id,
-    input.user_id,
-    input.rating,
-    input.response_time_ms ?? null,
+    input.slug,
+    input.concept,
+    input.domain ?? "",
+    bloom,
+    input.context ?? "",
+    input.symbiosis_mode ?? null,
+    input.source_link ?? null,
+    input.question ?? null,
     now,
-    input.scheduled_at,
-    input.session_id ?? null
+    now
   );
-  return db.prepare("SELECT * FROM review_logs WHERE id = ?").get(id);
+  return await getTokenById(db, id);
 }
-function getReviewsForCard(db, cardId) {
-  return db.prepare(
-    "SELECT * FROM review_logs WHERE card_id = ? ORDER BY reviewed_at ASC"
-  ).all(cardId);
+async function getTokenBySlug(db, slug) {
+  return await db.prepare("SELECT * FROM tokens WHERE slug = ?").get(slug);
 }
-function getReviewsForUser(db, userId, options) {
-  const conditions = ["user_id = ?"];
-  const params = [userId];
-  if (options?.after) {
-    conditions.push("reviewed_at > ?");
-    params.push(options.after);
-  }
-  if (options?.before) {
-    conditions.push("reviewed_at < ?");
-    params.push(options.before);
-  }
-  let sql = `SELECT * FROM review_logs WHERE ${conditions.join(" AND ")} ORDER BY reviewed_at DESC`;
-  if (options?.limit) {
-    sql += " LIMIT ?";
-    params.push(options.limit);
-  }
-  return db.prepare(sql).all(...params);
-}
-
-// src/kernel/models/session.ts
-import { ulid as ulid4 } from "ulid";
-function startSession(db, input) {
-  const id = ulid4();
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const ctx = input.execution_context ?? "shell";
-  db.prepare(
-    `INSERT INTO sessions (id, user_id, task, execution_context, started_at)
-     VALUES (?, ?, ?, ?, ?)`
-  ).run(id, input.user_id, input.task, ctx, now);
-  return db.prepare("SELECT * FROM sessions WHERE id = ?").get(id);
-}
-function endSession(db, sessionId) {
-  const session = db.prepare("SELECT * FROM sessions WHERE id = ?").get(sessionId);
-  if (!session) {
-    throw new Error(`Session not found: ${sessionId}`);
-  }
-  if (session.completed_at) {
-    throw new Error(`Session already completed: ${sessionId}`);
-  }
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  db.prepare("UPDATE sessions SET completed_at = ? WHERE id = ?").run(
-    now,
-    sessionId
-  );
-  return db.prepare("SELECT * FROM sessions WHERE id = ?").get(sessionId);
-}
-function logStep(db, input) {
-  if (input.done_by !== "user" && input.done_by !== "agent") {
-    throw new Error(
-      `done_by must be 'user' or 'agent', got '${input.done_by}'`
-    );
-  }
-  if (input.rating != null && (input.rating < 1 || input.rating > 4)) {
-    throw new Error(`Rating must be between 1 and 4, got ${input.rating}`);
-  }
-  const session = db.prepare("SELECT id FROM sessions WHERE id = ?").get(input.session_id);
-  if (!session) {
-    throw new Error(`Session not found: ${input.session_id}`);
-  }
-  const id = ulid4();
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  db.prepare(
-    `INSERT INTO session_steps (id, session_id, token_id, done_by, rating, notes, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?)`
-  ).run(
-    id,
-    input.session_id,
-    input.token_id,
-    input.done_by,
-    input.rating ?? null,
-    input.notes ?? null,
-    now
-  );
-  return db.prepare("SELECT * FROM session_steps WHERE id = ?").get(id);
-}
-function getSessionSummary(db, sessionId) {
-  const session = db.prepare("SELECT * FROM sessions WHERE id = ?").get(sessionId);
-  if (!session) {
-    throw new Error(`Session not found: ${sessionId}`);
-  }
-  const steps = db.prepare(
-    `SELECT ss.*, t.slug, t.concept, t.domain, t.bloom_level
-       FROM session_steps ss
-       JOIN tokens t ON t.id = ss.token_id
-       WHERE ss.session_id = ?
-       ORDER BY ss.created_at ASC`
-  ).all(sessionId);
-  return { session, steps };
-}
-
-// src/kernel/models/settings.ts
-function getSetting(db, key) {
-  const row = db.prepare("SELECT value FROM user_config WHERE key = ?").get(key);
-  return row?.value;
-}
-function getAllSettings(db) {
-  const rows = db.prepare("SELECT key, value FROM user_config ORDER BY key").all();
-  const map = {};
-  for (const row of rows) {
-    map[row.key] = row.value;
-  }
-  return map;
-}
-function getAllSettingsDetailed(db) {
-  return db.prepare("SELECT key, value, updated_at FROM user_config ORDER BY key").all();
-}
-function setSetting(db, key, value) {
-  db.prepare(
-    `INSERT INTO user_config (key, value, updated_at)
-     VALUES (?, ?, datetime('now'))
-     ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`
-  ).run(key, value);
-}
-function deleteSetting(db, key) {
-  const result = db.prepare("DELETE FROM user_config WHERE key = ?").run(key);
-  return result.changes > 0;
-}
-
-// src/kernel/models/token.ts
-import { ulid as ulid5 } from "ulid";
-function createToken(db, input) {
-  const id = ulid5();
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const bloom = input.bloom_level ?? 1;
-  if (bloom < 1 || bloom > 5) {
-    throw new Error(`bloom_level must be between 1 and 5, got ${bloom}`);
-  }
-  db.prepare(`
-    INSERT INTO tokens (id, slug, concept, domain, bloom_level, context, symbiosis_mode, source_link, question, created_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(
-    id,
-    input.slug,
-    input.concept,
-    input.domain ?? "",
-    bloom,
-    input.context ?? "",
-    input.symbiosis_mode ?? null,
-    input.source_link ?? null,
-    input.question ?? null,
-    now,
-    now
-  );
-  return getTokenById(db, id);
-}
-function getTokenBySlug(db, slug) {
-  return db.prepare("SELECT * FROM tokens WHERE slug = ?").get(slug);
-}
-function getTokenById(db, id) {
-  return db.prepare("SELECT * FROM tokens WHERE id = ?").get(id);
-}
-function updateToken(db, slug, updates) {
-  const token = getTokenBySlug(db, slug);
-  if (!token) {
-    throw new Error(`Token not found: ${slug}`);
+async function getTokenById(db, id) {
+  return await db.prepare("SELECT * FROM tokens WHERE id = ?").get(id);
+}
+async function updateToken(db, slug, updates) {
+  const token = await getTokenBySlug(db, slug);
+  if (!token) {
+    throw new Error(`Token not found: ${slug}`);
   }
   const fields = [];
   const values = [];
@@ -1105,13 +1450,11 @@ function updateToken(db, slug, updates) {
   fields.push("updated_at = ?");
   values.push((/* @__PURE__ */ new Date()).toISOString());
   values.push(slug);
-  db.prepare(`UPDATE tokens SET ${fields.join(", ")} WHERE slug = ?`).run(
-    ...values
-  );
-  return getTokenBySlug(db, slug);
+  await db.prepare(`UPDATE tokens SET ${fields.join(", ")} WHERE slug = ?`).run(...values);
+  return await getTokenBySlug(db, slug);
 }
-function deprecateToken(db, slug) {
-  const token = getTokenBySlug(db, slug);
+async function deprecateToken(db, slug) {
+  const token = await getTokenBySlug(db, slug);
   if (!token) {
     throw new Error(`Token not found: ${slug}`);
   }
@@ -1119,25 +1462,25 @@ function deprecateToken(db, slug) {
     throw new Error(`Token already deprecated: ${slug}`);
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  db.prepare(
+  await db.prepare(
     "UPDATE tokens SET deprecated_at = ?, updated_at = ? WHERE slug = ?"
   ).run(now, now, slug);
-  return getTokenBySlug(db, slug);
+  return await getTokenBySlug(db, slug);
 }
-function getTokenDeleteImpact(db, slug) {
-  const token = getTokenBySlug(db, slug);
+async function getTokenDeleteImpact(db, slug) {
+  const token = await getTokenBySlug(db, slug);
   if (!token) {
     throw new Error(`Token not found: ${slug}`);
   }
-  const cards = db.prepare("SELECT COUNT(*) AS n FROM cards WHERE token_id = ?").get(token.id);
-  const reviewLogs = db.prepare("SELECT COUNT(*) AS n FROM review_logs WHERE token_id = ?").get(token.id);
-  const prereqsFrom = db.prepare("SELECT COUNT(*) AS n FROM prerequisites WHERE token_id = ?").get(token.id);
-  const prereqsTo = db.prepare("SELECT COUNT(*) AS n FROM prerequisites WHERE requires_id = ?").get(token.id);
-  const sessionSteps = db.prepare("SELECT COUNT(*) AS n FROM session_steps WHERE token_id = ?").get(token.id);
-  const sessionsTouched = db.prepare(
+  const cards = await db.prepare("SELECT COUNT(*) AS n FROM cards WHERE token_id = ?").get(token.id);
+  const reviewLogs = await db.prepare("SELECT COUNT(*) AS n FROM review_logs WHERE token_id = ?").get(token.id);
+  const prereqsFrom = await db.prepare("SELECT COUNT(*) AS n FROM prerequisites WHERE token_id = ?").get(token.id);
+  const prereqsTo = await db.prepare("SELECT COUNT(*) AS n FROM prerequisites WHERE requires_id = ?").get(token.id);
+  const sessionSteps = await db.prepare("SELECT COUNT(*) AS n FROM session_steps WHERE token_id = ?").get(token.id);
+  const sessionsTouched = await db.prepare(
     "SELECT COUNT(DISTINCT session_id) AS n FROM session_steps WHERE token_id = ?"
   ).get(token.id);
-  const skillRows = db.prepare("SELECT token_slugs FROM agent_skills").all();
+  const skillRows = await db.prepare("SELECT token_slugs FROM agent_skills").all();
   const agentSkills = skillRows.filter((row) => {
     const tokenSlugs = JSON.parse(row.token_slugs);
     return tokenSlugs.includes(slug);
@@ -1152,34 +1495,29 @@ function getTokenDeleteImpact(db, slug) {
     agent_skills: agentSkills
   };
 }
-function deleteToken(db, slug) {
-  const token = getTokenBySlug(db, slug);
+async function deleteToken(db, slug) {
+  const token = await getTokenBySlug(db, slug);
   if (!token) {
     throw new Error(`Token not found: ${slug}`);
   }
-  const impact = getTokenDeleteImpact(db, slug);
-  db.exec("BEGIN");
-  try {
+  const impact = await getTokenDeleteImpact(db, slug);
+  await db.transaction(async (tx) => {
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const skillRows = db.prepare("SELECT id, token_slugs FROM agent_skills").all();
+    const skillRows = await tx.prepare("SELECT id, token_slugs FROM agent_skills").all();
     for (const row of skillRows) {
       const tokenSlugs = JSON.parse(row.token_slugs);
       const filtered = tokenSlugs.filter((tokenSlug) => tokenSlug !== slug);
       if (filtered.length !== tokenSlugs.length) {
-        db.prepare(
+        await tx.prepare(
           "UPDATE agent_skills SET token_slugs = ?, updated_at = ? WHERE id = ?"
         ).run(JSON.stringify(filtered), now, row.id);
       }
     }
-    db.prepare("DELETE FROM tokens WHERE id = ?").run(token.id);
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+    await tx.prepare("DELETE FROM tokens WHERE id = ?").run(token.id);
+  });
   return { token, impact };
 }
-function findTokens(db, query) {
+async function findTokens(db, query) {
   const normalised = query.toLowerCase();
   const searchTokens = normalised.split(/[\s,.\-_/\\:;!?()[\]{}]+/).filter((t2) => t2.length > 0);
   if (searchTokens.length === 0) return [];
@@ -1189,7 +1527,7 @@ function findTokens(db, query) {
   const likeSQL = `SELECT * FROM tokens WHERE deprecated_at IS NULL AND (lower(slug) LIKE ? OR lower(concept) LIKE ? OR lower(domain) LIKE ?)`;
   for (const term of longTerms) {
     const pattern = `%${term}%`;
-    const rows = db.prepare(likeSQL).all(pattern, pattern, pattern);
+    const rows = await db.prepare(likeSQL).all(pattern, pattern, pattern);
     for (const row of rows) {
       const entry = scoreMap.get(row.id);
       if (entry) {
@@ -1200,7 +1538,7 @@ function findTokens(db, query) {
     }
   }
   if (shortTerms.length > 0 || longTerms.length === 0) {
-    const allTokens = db.prepare("SELECT * FROM tokens WHERE deprecated_at IS NULL").all();
+    const allTokens = await db.prepare("SELECT * FROM tokens WHERE deprecated_at IS NULL").all();
     for (const token of allTokens) {
       const words = `${token.slug} ${token.concept} ${token.domain}`.toLowerCase().split(/[\s,.\-_/\\:;!?()[\]{}]+/).filter(Boolean);
       let matchCount = 0;
@@ -1230,96 +1568,368 @@ function findTokens(db, query) {
   scored.sort((a, b) => b.score - a.score);
   return scored;
 }
-function listTokens(db, options) {
+async function listTokens(db, options) {
   if (options?.domain) {
-    return db.prepare(
+    return await db.prepare(
       "SELECT * FROM tokens WHERE domain = ? AND deprecated_at IS NULL ORDER BY bloom_level, slug"
     ).all(options.domain);
   }
-  return db.prepare(
+  return await db.prepare(
     "SELECT * FROM tokens WHERE deprecated_at IS NULL ORDER BY bloom_level, domain, slug"
   ).all();
 }
 
-// src/kernel/observation/analyzer.ts
-function parseMonitorLog(jsonl) {
-  const events = [];
-  for (const line of jsonl.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    try {
-      events.push(JSON.parse(trimmed));
-    } catch {
+// src/kernel/models/prerequisite.ts
+async function buildAncestorMap(db) {
+  const rows = await db.prepare("SELECT token_id, requires_id FROM prerequisites").all();
+  const map = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    let ancestors = map.get(row.token_id);
+    if (!ancestors) {
+      ancestors = /* @__PURE__ */ new Set();
+      map.set(row.token_id, ancestors);
     }
+    ancestors.add(row.requires_id);
   }
-  return events;
+  return map;
 }
-function pairCommands(events) {
-  const starts = /* @__PURE__ */ new Map();
-  const records = [];
-  for (const e of events) {
-    if (e.type === "command_start" && e.seq != null) {
-      const key = `${e.pid ?? 0}:${e.seq}`;
-      starts.set(key, e);
-    } else if (e.type === "command_end" && e.seq != null) {
-      const key = `${e.pid ?? 0}:${e.seq}`;
-      const start = starts.get(key);
-      if (start) {
-        const startMs = new Date(start.ts).getTime();
-        const endMs = new Date(e.ts).getTime();
-        records.push({
-          seq: e.seq,
-          pid: e.pid ?? 0,
-          command: start.command ?? "",
-          cwd: start.cwd ?? "",
-          startedAt: start.ts,
-          endedAt: e.ts,
-          durationMs: endMs - startMs,
-          exitCode: e.exit_code ?? null
-        });
-        starts.delete(key);
+async function wouldCreateCycle(db, tokenId, requiresId) {
+  if (tokenId === requiresId) return true;
+  const ancestors = await buildAncestorMap(db);
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [requiresId];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === tokenId) return true;
+    if (visited.has(current)) continue;
+    visited.add(current);
+    const parents = ancestors.get(current);
+    if (parents) {
+      for (const parent of parents) {
+        if (!visited.has(parent)) queue.push(parent);
       }
     }
   }
-  for (const [, start] of starts) {
-    records.push({
-      seq: start.seq ?? 0,
-      pid: start.pid ?? 0,
-      command: start.command ?? "",
-      cwd: start.cwd ?? "",
-      startedAt: start.ts,
-      endedAt: null,
-      durationMs: null,
-      exitCode: null
-    });
+  return false;
+}
+async function addPrerequisite(db, tokenId, requiresId) {
+  if (tokenId === requiresId) {
+    throw new Error("A token cannot be a prerequisite of itself");
   }
-  records.sort(
-    (a, b) => new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime()
-  );
-  return records;
+  if (await wouldCreateCycle(db, tokenId, requiresId)) {
+    throw new Error(
+      `Cannot add prerequisite: would create a cycle. ${requiresId} already depends on ${tokenId} (directly or transitively).`
+    );
+  }
+  await db.prepare(
+    "INSERT OR IGNORE INTO prerequisites (token_id, requires_id) VALUES (?, ?)"
+  ).run(tokenId, requiresId);
 }
-var HELP_PATTERNS = ["--help", "man ", "tldr ", "help "];
-var HELP_WINDOW_MS = 6e4;
-function matchesToken(command, patterns) {
-  const lower = command.toLowerCase();
-  return patterns.some((p) => lower.includes(p.toLowerCase()));
+async function getPrerequisites(db, tokenId) {
+  return await db.prepare(
+    `SELECT p.token_id, p.requires_id, t.slug, t.concept, t.domain, t.bloom_level
+       FROM prerequisites p
+       JOIN tokens t ON t.id = p.requires_id
+       WHERE p.token_id = ?`
+  ).all(tokenId);
 }
-function isHelpCommand(command) {
-  const lower = command.toLowerCase();
-  return HELP_PATTERNS.some((p) => lower.includes(p));
+async function getDependents(db, tokenId) {
+  return await db.prepare(
+    `SELECT p.token_id, p.requires_id, t.slug, t.concept, t.domain, t.bloom_level
+       FROM prerequisites p
+       JOIN tokens t ON t.id = p.token_id
+       WHERE p.requires_id = ?`
+  ).all(tokenId);
 }
-function commandPrefix(command) {
-  return command.split(/\s+/).slice(0, 2).join(" ").toLowerCase();
+async function getTokenNeighborhood(db, tokenId, userId) {
+  const token = await getTokenById(db, tokenId);
+  if (!token) {
+    throw new Error(`Token not found: ${tokenId}`);
+  }
+  const centerCard = userId ? await getCard(db, tokenId, userId) : void 0;
+  const prereqRows = await getPrerequisites(db, tokenId);
+  const depRows = await getDependents(db, tokenId);
+  const relatedTokenIds = /* @__PURE__ */ new Set();
+  for (const p of prereqRows) relatedTokenIds.add(p.requires_id);
+  for (const d of depRows) relatedTokenIds.add(d.token_id);
+  const cardMap = /* @__PURE__ */ new Map();
+  if (userId && relatedTokenIds.size > 0) {
+    const ids = Array.from(relatedTokenIds);
+    const placeholders = ids.map(() => "?").join(",");
+    const rows = await db.prepare(
+      `SELECT * FROM cards WHERE token_id IN (${placeholders}) AND user_id = ?`
+    ).all(...ids, userId);
+    for (const row of rows) {
+      cardMap.set(row.token_id, row);
+    }
+  }
+  const toNode = (t2, card) => ({
+    id: t2.id,
+    slug: t2.slug,
+    concept: t2.concept,
+    domain: t2.domain,
+    bloom_level: t2.bloom_level,
+    card: card ? {
+      state: card.state,
+      reps: card.reps,
+      stability: card.stability,
+      difficulty: card.difficulty,
+      blocked: card.blocked === 1,
+      due_at: card.due_at,
+      last_review_at: card.last_review_at
+    } : null
+  });
+  const center = toNode(token, centerCard);
+  const prerequisites = prereqRows.map(
+    (p) => toNode(
+      {
+        id: p.requires_id,
+        slug: p.slug,
+        concept: p.concept,
+        domain: p.domain,
+        bloom_level: p.bloom_level
+      },
+      cardMap.get(p.requires_id)
+    )
+  );
+  const dependents = depRows.map(
+    (d) => toNode(
+      {
+        id: d.token_id,
+        slug: d.slug,
+        concept: d.concept,
+        domain: d.domain,
+        bloom_level: d.bloom_level
+      },
+      cardMap.get(d.token_id)
+    )
+  );
+  return { center, prerequisites, dependents };
 }
-function computeMedian(values) {
-  if (values.length === 0) return null;
-  const sorted = [...values].sort((a, b) => a - b);
-  const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+
+// src/kernel/models/review.ts
+import { ulid as ulid4 } from "ulid";
+async function logReview(db, input) {
+  if (input.rating < 1 || input.rating > 4) {
+    throw new Error(`Rating must be between 1 and 4, got ${input.rating}`);
+  }
+  const id = ulid4();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await db.prepare(
+    `INSERT INTO review_logs (id, card_id, token_id, user_id, rating, response_time_ms, reviewed_at, scheduled_at, session_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    id,
+    input.card_id,
+    input.token_id,
+    input.user_id,
+    input.rating,
+    input.response_time_ms ?? null,
+    now,
+    input.scheduled_at,
+    input.session_id ?? null
+  );
+  return await db.prepare("SELECT * FROM review_logs WHERE id = ?").get(id);
 }
-function analyzeObservation(commands, tokenPatterns) {
-  const matchedSet = /* @__PURE__ */ new Set();
-  const ratings = [];
+async function getReviewsForCard(db, cardId) {
+  return await db.prepare(
+    "SELECT * FROM review_logs WHERE card_id = ? ORDER BY reviewed_at ASC"
+  ).all(cardId);
+}
+async function getReviewsForUser(db, userId, options) {
+  const conditions = ["user_id = ?"];
+  const params = [userId];
+  if (options?.after) {
+    conditions.push("reviewed_at > ?");
+    params.push(options.after);
+  }
+  if (options?.before) {
+    conditions.push("reviewed_at < ?");
+    params.push(options.before);
+  }
+  let sql = `SELECT * FROM review_logs WHERE ${conditions.join(" AND ")} ORDER BY reviewed_at DESC`;
+  if (options?.limit) {
+    sql += " LIMIT ?";
+    params.push(options.limit);
+  }
+  return await db.prepare(sql).all(...params);
+}
+
+// src/kernel/models/session.ts
+import { ulid as ulid5 } from "ulid";
+async function startSession(db, input) {
+  const id = ulid5();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const ctx = input.execution_context ?? "shell";
+  await db.prepare(
+    `INSERT INTO sessions (id, user_id, task, execution_context, started_at)
+     VALUES (?, ?, ?, ?, ?)`
+  ).run(id, input.user_id, input.task, ctx, now);
+  return await db.prepare("SELECT * FROM sessions WHERE id = ?").get(id);
+}
+async function endSession(db, sessionId) {
+  const session = await db.prepare("SELECT * FROM sessions WHERE id = ?").get(sessionId);
+  if (!session) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  if (session.completed_at) {
+    throw new Error(`Session already completed: ${sessionId}`);
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await db.prepare("UPDATE sessions SET completed_at = ? WHERE id = ?").run(now, sessionId);
+  return await db.prepare("SELECT * FROM sessions WHERE id = ?").get(sessionId);
+}
+async function logStep(db, input) {
+  if (input.done_by !== "user" && input.done_by !== "agent") {
+    throw new Error(
+      `done_by must be 'user' or 'agent', got '${input.done_by}'`
+    );
+  }
+  if (input.rating != null && (input.rating < 1 || input.rating > 4)) {
+    throw new Error(`Rating must be between 1 and 4, got ${input.rating}`);
+  }
+  const session = await db.prepare("SELECT id FROM sessions WHERE id = ?").get(input.session_id);
+  if (!session) {
+    throw new Error(`Session not found: ${input.session_id}`);
+  }
+  const id = ulid5();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await db.prepare(
+    `INSERT INTO session_steps (id, session_id, token_id, done_by, rating, notes, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    id,
+    input.session_id,
+    input.token_id,
+    input.done_by,
+    input.rating ?? null,
+    input.notes ?? null,
+    now
+  );
+  return await db.prepare("SELECT * FROM session_steps WHERE id = ?").get(id);
+}
+async function getSessionSummary(db, sessionId) {
+  const session = await db.prepare("SELECT * FROM sessions WHERE id = ?").get(sessionId);
+  if (!session) {
+    throw new Error(`Session not found: ${sessionId}`);
+  }
+  const steps = await db.prepare(
+    `SELECT ss.*, t.slug, t.concept, t.domain, t.bloom_level
+       FROM session_steps ss
+       JOIN tokens t ON t.id = ss.token_id
+       WHERE ss.session_id = ?
+       ORDER BY ss.created_at ASC`
+  ).all(sessionId);
+  return { session, steps };
+}
+
+// src/kernel/models/settings.ts
+async function getSetting(db, key) {
+  const row = await db.prepare("SELECT value FROM user_config WHERE key = ?").get(key);
+  return row?.value;
+}
+async function getAllSettings(db) {
+  const rows = await db.prepare("SELECT key, value FROM user_config ORDER BY key").all();
+  const map = {};
+  for (const row of rows) {
+    map[row.key] = row.value;
+  }
+  return map;
+}
+async function getAllSettingsDetailed(db) {
+  return await db.prepare("SELECT key, value, updated_at FROM user_config ORDER BY key").all();
+}
+async function setSetting(db, key, value) {
+  await db.prepare(
+    `INSERT INTO user_config (key, value, updated_at)
+     VALUES (?, ?, datetime('now'))
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`
+  ).run(key, value);
+}
+async function deleteSetting(db, key) {
+  const result = await db.prepare("DELETE FROM user_config WHERE key = ?").run(key);
+  return result.changes > 0;
+}
+
+// src/kernel/observation/analyzer.ts
+function parseMonitorLog(jsonl) {
+  const events = [];
+  for (const line of jsonl.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      events.push(JSON.parse(trimmed));
+    } catch {
+    }
+  }
+  return events;
+}
+function pairCommands(events) {
+  const starts = /* @__PURE__ */ new Map();
+  const records = [];
+  for (const e of events) {
+    if (e.type === "command_start" && e.seq != null) {
+      const key = `${e.pid ?? 0}:${e.seq}`;
+      starts.set(key, e);
+    } else if (e.type === "command_end" && e.seq != null) {
+      const key = `${e.pid ?? 0}:${e.seq}`;
+      const start = starts.get(key);
+      if (start) {
+        const startMs = new Date(start.ts).getTime();
+        const endMs = new Date(e.ts).getTime();
+        records.push({
+          seq: e.seq,
+          pid: e.pid ?? 0,
+          command: start.command ?? "",
+          cwd: start.cwd ?? "",
+          startedAt: start.ts,
+          endedAt: e.ts,
+          durationMs: endMs - startMs,
+          exitCode: e.exit_code ?? null
+        });
+        starts.delete(key);
+      }
+    }
+  }
+  for (const [, start] of starts) {
+    records.push({
+      seq: start.seq ?? 0,
+      pid: start.pid ?? 0,
+      command: start.command ?? "",
+      cwd: start.cwd ?? "",
+      startedAt: start.ts,
+      endedAt: null,
+      durationMs: null,
+      exitCode: null
+    });
+  }
+  records.sort(
+    (a, b) => new Date(a.startedAt).getTime() - new Date(b.startedAt).getTime()
+  );
+  return records;
+}
+var HELP_PATTERNS = ["--help", "man ", "tldr ", "help "];
+var HELP_WINDOW_MS = 6e4;
+function matchesToken(command, patterns) {
+  const lower = command.toLowerCase();
+  return patterns.some((p) => lower.includes(p.toLowerCase()));
+}
+function isHelpCommand(command) {
+  const lower = command.toLowerCase();
+  return HELP_PATTERNS.some((p) => lower.includes(p));
+}
+function commandPrefix(command) {
+  return command.split(/\s+/).slice(0, 2).join(" ").toLowerCase();
+}
+function computeMedian(values) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 !== 0 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+function analyzeObservation(commands, tokenPatterns) {
+  const matchedSet = /* @__PURE__ */ new Set();
+  const ratings = [];
   for (const tp of tokenPatterns) {
     const matchIndices = [];
     const matchedTexts = [];
@@ -1374,8 +1984,8 @@ function analyzeObservation(commands, tokenPatterns) {
       const prefix = commandPrefix(commands[mi].command);
       prefixGroups.set(prefix, (prefixGroups.get(prefix) ?? 0) + 1);
     }
-    for (const count of prefixGroups.values()) {
-      if (count > 1) selfCorrections += count - 1;
+    for (const count2 of prefixGroups.values()) {
+      if (count2 > 1) selfCorrections += count2 - 1;
     }
     const gaps = [];
     for (let k = 1; k < matchIndices.length; k++) {
@@ -1461,54 +2071,504 @@ function inferRating(signals) {
   return 4;
 }
 
-// src/kernel/observation/monitor-io.ts
-import {
-  appendFileSync,
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync3,
-  readFileSync as readFileSync4,
-  statSync
-} from "fs";
-import { homedir as homedir3 } from "os";
-import { join as join4 } from "path";
-var MONITOR_DIR = join4(homedir3(), ".zam", "monitor");
-function getMonitorDir() {
-  return MONITOR_DIR;
-}
-function getMonitorPath(sessionId) {
-  return join4(MONITOR_DIR, `${sessionId}.jsonl`);
+// src/kernel/observation/monitor-io.ts
+import {
+  appendFileSync,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync4,
+  statSync
+} from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join4 } from "path";
+var MONITOR_DIR = join4(homedir3(), ".zam", "monitor");
+function getMonitorDir() {
+  return MONITOR_DIR;
+}
+function getMonitorPath(sessionId) {
+  return join4(MONITOR_DIR, `${sessionId}.jsonl`);
+}
+function ensureMonitorDir() {
+  if (!existsSync4(MONITOR_DIR)) {
+    mkdirSync3(MONITOR_DIR, { recursive: true, mode: 448 });
+  }
+}
+function writeMonitorEvent(sessionId, event) {
+  ensureMonitorDir();
+  const path = getMonitorPath(sessionId);
+  appendFileSync(path, `${JSON.stringify(event)}
+`);
+}
+function readMonitorLog(sessionId) {
+  const path = getMonitorPath(sessionId);
+  if (!existsSync4(path)) {
+    return [];
+  }
+  const content = readFileSync4(path, "utf-8");
+  return parseMonitorLog(content);
+}
+function monitorLogExists(sessionId) {
+  return existsSync4(getMonitorPath(sessionId));
+}
+function getMonitorLogStats(sessionId) {
+  const path = getMonitorPath(sessionId);
+  if (!existsSync4(path)) {
+    return { exists: false, sizeBytes: 0, lineCount: 0 };
+  }
+  const stat = statSync(path);
+  const content = readFileSync4(path, "utf-8");
+  const lineCount = content.split("\n").filter((l) => l.trim()).length;
+  return { exists: true, sizeBytes: stat.size, lineCount };
+}
+
+// src/kernel/observation/session-synthesis.ts
+import { ulid as ulid7 } from "ulid";
+
+// src/kernel/recall/evaluator.ts
+import { ulid as ulid6 } from "ulid";
+
+// src/kernel/scheduler/fsrs.ts
+var DEFAULT_W = [
+  0.4072,
+  1.1829,
+  3.1262,
+  15.4722,
+  // w0–w3:  initial stability per rating
+  7.2102,
+  0.5316,
+  1.0651,
+  // w4–w6:  difficulty
+  92e-4,
+  1.5988,
+  0.1176,
+  1.0014,
+  // w7–w10: stability after forgetting
+  2.0032,
+  0.0266,
+  0.3077,
+  0.15,
+  // w11–w14: stability increase
+  0,
+  2.7849,
+  0.3477,
+  0.6831
+  // w15–w18: additional parameters
+];
+var DEFAULT_REQUEST_RETENTION = 0.9;
+function clamp(value, lo, hi) {
+  return Math.min(hi, Math.max(lo, value));
+}
+function daysBetween(a, b) {
+  return (b.getTime() - a.getTime()) / (1e3 * 60 * 60 * 24);
+}
+function initialStability(w, rating) {
+  return w[rating - 1];
+}
+function initialDifficulty(w, rating) {
+  return clamp(w[4] - Math.exp(w[5] * (rating - 1)) + 1, 1, 10);
+}
+function nextDifficulty(w, d, rating) {
+  const d0ForGood = initialDifficulty(w, 3);
+  const updated = w[7] * d0ForGood + (1 - w[7]) * (d - w[6] * (rating - 3));
+  return clamp(updated, 1, 10);
+}
+function retrievability(elapsed, stability) {
+  if (stability <= 0) return 0;
+  return (1 + elapsed / (9 * stability)) ** -1;
+}
+function stabilityAfterSuccess(w, s, d, r, rating) {
+  const hardPenalty = rating === 2 ? w[15] : 1;
+  const easyBonus = rating === 4 ? w[16] : 1;
+  const inner = Math.exp(w[8]) * (11 - d) * s ** -w[9] * (Math.exp(w[10] * (1 - r)) - 1) * hardPenalty * easyBonus;
+  return s * (inner + 1);
+}
+function stabilityAfterForgetting(w, s, d, r) {
+  return w[11] * d ** -w[12] * ((s + 1) ** w[13] - 1) * Math.exp(w[14] * (1 - r));
+}
+function nextInterval(stability, requestRetention) {
+  const interval = 9 * stability * (1 / requestRetention - 1);
+  return Math.max(1, Math.round(interval));
+}
+function createFSRS(params) {
+  const resolvedParams = {
+    w: params?.w ?? [...DEFAULT_W],
+    requestRetention: params?.requestRetention ?? DEFAULT_REQUEST_RETENTION
+  };
+  function schedule(card, rating, now) {
+    const reviewTime = now ?? /* @__PURE__ */ new Date();
+    const w = resolvedParams.w;
+    const elapsed = card.lastReviewAt !== null ? Math.max(0, daysBetween(card.lastReviewAt, reviewTime)) : 0;
+    if (card.state === "new") {
+      const s = initialStability(w, rating);
+      const d = initialDifficulty(w, rating);
+      const interval2 = nextInterval(s, resolvedParams.requestRetention);
+      const dueAt2 = new Date(reviewTime);
+      dueAt2.setDate(dueAt2.getDate() + interval2);
+      return {
+        stability: s,
+        difficulty: d,
+        elapsedDays: 0,
+        scheduledDays: interval2,
+        reps: rating >= 2 ? 1 : 0,
+        lapses: rating === 1 ? 1 : 0,
+        state: "learning",
+        dueAt: dueAt2,
+        lastReviewAt: reviewTime
+      };
+    }
+    const r = retrievability(elapsed, card.stability);
+    let newStability;
+    let newDifficulty;
+    let newReps;
+    let newLapses;
+    let newState;
+    if (rating === 1) {
+      newStability = stabilityAfterForgetting(
+        w,
+        card.stability,
+        card.difficulty,
+        r
+      );
+      newDifficulty = nextDifficulty(w, card.difficulty, rating);
+      newReps = 0;
+      newLapses = card.lapses + 1;
+      newState = "relearning";
+    } else {
+      newStability = stabilityAfterSuccess(
+        w,
+        card.stability,
+        card.difficulty,
+        r,
+        rating
+      );
+      newDifficulty = nextDifficulty(w, card.difficulty, rating);
+      newReps = card.reps + 1;
+      newLapses = card.lapses;
+      newState = "review";
+    }
+    const interval = nextInterval(
+      newStability,
+      resolvedParams.requestRetention
+    );
+    const dueAt = new Date(reviewTime);
+    dueAt.setDate(dueAt.getDate() + interval);
+    return {
+      stability: newStability,
+      difficulty: newDifficulty,
+      elapsedDays: elapsed,
+      scheduledDays: interval,
+      reps: newReps,
+      lapses: newLapses,
+      state: newState,
+      dueAt,
+      lastReviewAt: reviewTime
+    };
+  }
+  return {
+    schedule,
+    params: Object.freeze(resolvedParams)
+  };
+}
+
+// src/kernel/recall/evaluator.ts
+async function evaluateRating(db, input) {
+  return db.transaction((tx) => evaluateRatingWithinTransaction(tx, input));
+}
+async function evaluateRatingWithinTransaction(db, input) {
+  const card = await db.prepare("SELECT * FROM cards WHERE id = ?").get(input.cardId);
+  if (!card) {
+    throw new Error(`Card not found: ${input.cardId}`);
+  }
+  const now = /* @__PURE__ */ new Date();
+  const fsrs = createFSRS();
+  const schedulingCard = {
+    stability: card.stability,
+    difficulty: card.difficulty,
+    elapsedDays: card.elapsed_days,
+    scheduledDays: card.scheduled_days,
+    reps: card.reps,
+    lapses: card.lapses,
+    state: card.state,
+    dueAt: new Date(card.due_at),
+    lastReviewAt: card.last_review_at ? new Date(card.last_review_at) : null
+  };
+  const updated = fsrs.schedule(schedulingCard, input.rating, now);
+  await updateCard(db, input.cardId, {
+    stability: updated.stability,
+    difficulty: updated.difficulty,
+    elapsed_days: updated.elapsedDays,
+    scheduled_days: updated.scheduledDays,
+    reps: updated.reps,
+    lapses: updated.lapses,
+    state: updated.state,
+    due_at: updated.dueAt.toISOString(),
+    last_review_at: now.toISOString()
+  });
+  const reviewLogId = input.reviewLogId ?? ulid6();
+  await db.prepare(
+    `INSERT INTO review_logs (id, card_id, token_id, user_id, rating, response_time_ms, reviewed_at, scheduled_at, session_id)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    reviewLogId,
+    input.cardId,
+    input.tokenId,
+    input.userId,
+    input.rating,
+    input.responseTimeMs ?? null,
+    now.toISOString(),
+    card.due_at,
+    input.sessionId ?? null
+  );
+  return {
+    nextDueAt: updated.dueAt.toISOString(),
+    stability: updated.stability,
+    difficulty: updated.difficulty,
+    state: updated.state,
+    scheduledDays: updated.scheduledDays,
+    reps: updated.reps,
+    lapses: updated.lapses
+  };
+}
+
+// src/kernel/scheduler/blocker.ts
+async function cascadeBlock(db, userId, tokenSlug) {
+  const token = await getTokenBySlug(db, tokenSlug);
+  if (!token) {
+    throw new Error(`Unknown token slug: ${tokenSlug}`);
+  }
+  const prereqs = await getPrerequisites(db, token.id);
+  if (prereqs.length === 0) {
+    throw new Error(`Cannot block ${tokenSlug}: token has no prerequisites`);
+  }
+  await ensureCard(db, token.id, userId);
+  await db.prepare("UPDATE cards SET blocked = 1 WHERE token_id = ? AND user_id = ?").run(token.id, userId);
+  const surfaced = [];
+  for (const prereq of prereqs) {
+    const card = await ensureCard(db, prereq.requires_id, userId);
+    if (card.blocked === 1) {
+      const prereqOfPrereq = await db.prepare("SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?").get(prereq.requires_id);
+      if (prereqOfPrereq.n === 0) {
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        await db.prepare(
+          "UPDATE cards SET blocked = 0, due_at = ? WHERE token_id = ? AND user_id = ?"
+        ).run(now, prereq.requires_id, userId);
+      }
+    }
+    surfaced.push({
+      slug: prereq.slug,
+      concept: prereq.concept,
+      bloomLevel: prereq.bloom_level
+    });
+  }
+  return {
+    blockedSlug: tokenSlug,
+    prerequisites: surfaced
+  };
+}
+async function unblockReady(db, userId) {
+  const blockedCards = await db.prepare(
+    `SELECT c.token_id, t.slug, t.concept
+       FROM cards c
+       JOIN tokens t ON t.id = c.token_id
+       WHERE c.user_id = ? AND c.blocked = 1`
+  ).all(userId);
+  const unblocked = [];
+  for (const card of blockedCards) {
+    const totalPrereqs = await db.prepare("SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?").get(card.token_id);
+    const metPrereqs = await db.prepare(
+      `SELECT COUNT(*) as n FROM cards c
+         JOIN prerequisites p ON p.requires_id = c.token_id
+         WHERE p.token_id = ? AND c.user_id = ? AND c.reps >= 1 AND c.blocked = 0`
+    ).get(card.token_id, userId);
+    if (totalPrereqs.n === 0 || metPrereqs.n === totalPrereqs.n) {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      await db.prepare(
+        "UPDATE cards SET blocked = 0, due_at = ? WHERE token_id = ? AND user_id = ?"
+      ).run(now, card.token_id, userId);
+      unblocked.push({ slug: card.slug, concept: card.concept });
+    }
+  }
+  return { unblocked };
+}
+
+// src/kernel/observation/session-synthesis.ts
+function parseSynthesisRow(row) {
+  return {
+    ...row,
+    evidence: JSON.parse(row.evidence)
+  };
 }
-function ensureMonitorDir() {
-  if (!existsSync4(MONITOR_DIR)) {
-    mkdirSync3(MONITOR_DIR, { recursive: true, mode: 448 });
+function confidenceRank(confidence) {
+  return confidence === "high" ? 2 : confidence === "medium" ? 1 : 0;
+}
+function normalizeSkillStep(step) {
+  const codeSpans = [...step.matchAll(/`([^`]+)`/g)].map((match) => match[1].trim()).filter(Boolean);
+  if (codeSpans.length > 0) return codeSpans;
+  const normalized = step.trim().replace(/^(?:[-*]|\d+[.)])\s+/, "").replace(/^(?:run|execute)\s+/i, "").replace(/^`|`$/g, "").trim();
+  return normalized ? [normalized] : [];
+}
+async function buildSkillPatterns(db) {
+  const byToken = /* @__PURE__ */ new Map();
+  for (const skill of await listAgentSkills(db)) {
+    if (skill.token_slugs.length !== 1) continue;
+    const patterns = skill.steps.flatMap(normalizeSkillStep);
+    for (const slug of skill.token_slugs) {
+      const tokenPatterns = byToken.get(slug) ?? /* @__PURE__ */ new Set();
+      for (const pattern of patterns) tokenPatterns.add(pattern);
+      byToken.set(slug, tokenPatterns);
+    }
   }
+  return [...byToken.entries()].map(([slug, patterns]) => ({
+    slug,
+    patterns: [...patterns]
+  }));
 }
-function writeMonitorEvent(sessionId, event) {
-  ensureMonitorDir();
-  const path = getMonitorPath(sessionId);
-  appendFileSync(path, `${JSON.stringify(event)}
-`);
-}
-function readMonitorLog(sessionId) {
-  const path = getMonitorPath(sessionId);
-  if (!existsSync4(path)) {
-    return [];
+function mergePatterns(automatic, explicit) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const entry of [...automatic, ...explicit]) {
+    const patterns = merged.get(entry.slug) ?? /* @__PURE__ */ new Set();
+    for (const pattern of entry.patterns) {
+      const trimmed = pattern.trim();
+      if (trimmed) patterns.add(trimmed);
+    }
+    merged.set(entry.slug, patterns);
   }
-  const content = readFileSync4(path, "utf-8");
-  return parseMonitorLog(content);
+  return [...merged.entries()].filter(([, patterns]) => patterns.size > 0).map(([slug, patterns]) => ({ slug, patterns: [...patterns] }));
 }
-function monitorLogExists(sessionId) {
-  return existsSync4(getMonitorPath(sessionId));
+async function getSession(db, sessionId) {
+  const session = await db.prepare("SELECT * FROM sessions WHERE id = ?").get(sessionId);
+  if (!session) throw new Error(`Session not found: ${sessionId}`);
+  return session;
 }
-function getMonitorLogStats(sessionId) {
-  const path = getMonitorPath(sessionId);
-  if (!existsSync4(path)) {
-    return { exists: false, sizeBytes: 0, lineCount: 0 };
+async function getSessionSynthesisRecords(db, sessionId) {
+  const rows = await db.prepare(
+    "SELECT * FROM session_syntheses WHERE session_id = ? ORDER BY created_at"
+  ).all(sessionId);
+  return rows.map(parseSynthesisRow);
+}
+async function prepareSessionSynthesis(db, input) {
+  const session = await getSession(db, input.sessionId);
+  const patterns = mergePatterns(
+    await buildSkillPatterns(db),
+    input.explicitPatterns ?? []
+  );
+  const validPatterns = [];
+  const tokens = /* @__PURE__ */ new Map();
+  for (const pattern of patterns) {
+    const token = await getTokenBySlug(db, pattern.slug);
+    if (!token || token.deprecated_at) continue;
+    validPatterns.push(pattern);
+    tokens.set(pattern.slug, token);
+  }
+  const commands = input.commands ?? pairCommands(readMonitorLog(input.sessionId));
+  const analysis = analyzeObservation(commands, validPatterns);
+  const applied = new Set(
+    (await getSessionSynthesisRecords(db, input.sessionId)).map(
+      (record) => record.token_id
+    )
+  );
+  const minRank = confidenceRank(input.minConfidence ?? "medium");
+  let skippedLowConfidence = 0;
+  const candidates = [];
+  for (const rating of analysis.ratings) {
+    const token = tokens.get(rating.tokenSlug);
+    if (!token || rating.rating == null || applied.has(token.id)) continue;
+    if (confidenceRank(rating.confidence) < minRank) {
+      skippedLowConfidence++;
+      continue;
+    }
+    candidates.push({
+      tokenId: token.id,
+      tokenSlug: token.slug,
+      concept: token.concept,
+      domain: token.domain,
+      inferredRating: rating.rating,
+      confidence: rating.confidence,
+      evidence: rating.evidence,
+      matchedCommandTexts: rating.matchedCommandTexts
+    });
   }
-  const stat = statSync(path);
-  const content = readFileSync4(path, "utf-8");
-  const lineCount = content.split("\n").filter((l) => l.trim()).length;
-  return { exists: true, sizeBytes: stat.size, lineCount };
+  return {
+    sessionId: session.id,
+    userId: session.user_id,
+    patternCount: validPatterns.length,
+    commandCount: commands.length,
+    alreadyApplied: applied.size,
+    skippedLowConfidence,
+    candidates,
+    unmatchedCommands: analysis.unmatchedCommands,
+    timeSpan: analysis.timeSpan
+  };
+}
+async function applySessionSynthesis(db, input) {
+  return db.transaction(async (tx) => {
+    const session = await getSession(tx, input.sessionId);
+    const token = await getTokenBySlug(tx, input.tokenSlug);
+    if (!token || token.deprecated_at) {
+      throw new Error(`Active token not found: ${input.tokenSlug}`);
+    }
+    const existing = await tx.prepare(
+      "SELECT * FROM session_syntheses WHERE session_id = ? AND token_id = ?"
+    ).get(session.id, token.id);
+    if (existing) {
+      return { applied: false, record: parseSynthesisRow(existing) };
+    }
+    const card = await ensureCard(tx, token.id, session.user_id);
+    const reviewLogId = ulid7();
+    await evaluateRatingWithinTransaction(tx, {
+      cardId: card.id,
+      tokenId: token.id,
+      userId: session.user_id,
+      rating: input.confirmedRating,
+      sessionId: session.id,
+      reviewLogId
+    });
+    let blocked;
+    if (input.confirmedRating === 1) {
+      const prerequisites = await getPrerequisites(tx, token.id);
+      if (prerequisites.length > 0) {
+        blocked = await cascadeBlock(tx, session.user_id, token.slug);
+      }
+    }
+    const notes = `Observation synthesis (${input.confidence}, inferred ${input.inferredRating}): ${input.matchedCommandTexts.slice(0, 3).join(" | ")}`;
+    const step = await logStep(tx, {
+      session_id: session.id,
+      token_id: token.id,
+      done_by: "user",
+      rating: input.confirmedRating,
+      notes
+    });
+    const evidence = {
+      signals: input.evidence,
+      matchedCommandTexts: input.matchedCommandTexts
+    };
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    await tx.prepare(
+      `INSERT INTO session_syntheses (
+           session_id, token_id, card_id, inferred_rating, confirmed_rating,
+           confidence, evidence, review_log_id, session_step_id, created_at
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(
+      session.id,
+      token.id,
+      card.id,
+      input.inferredRating,
+      input.confirmedRating,
+      input.confidence,
+      JSON.stringify(evidence),
+      reviewLogId,
+      step.id,
+      now
+    );
+    const record = await tx.prepare(
+      "SELECT * FROM session_syntheses WHERE session_id = ? AND token_id = ?"
+    ).get(session.id, token.id);
+    return {
+      applied: true,
+      record: parseSynthesisRow(record),
+      blocked
+    };
+  });
 }
 
 // src/kernel/observation/shell-hooks.ts
@@ -1810,379 +2870,121 @@ function normalizeCommand(command) {
   }
   return parts.slice(0, Math.min(2, parts.length)).join(" ").toLowerCase();
 }
-function extractSequences(commands, minLen, maxLen) {
-  const filtered = commands.filter((c) => {
-    const lower = c.command.toLowerCase().trim();
-    return lower.length > 0 && !lower.startsWith("cd ") && lower !== "cd" && lower !== "ls" && lower !== "pwd" && lower !== "clear" && lower !== "exit" && !lower.startsWith("echo ");
-  });
-  const normalized = filtered.map((c) => normalizeCommand(c.command));
-  const sequences = [];
-  for (let len = minLen; len <= maxLen; len++) {
-    for (let i = 0; i <= normalized.length - len; i++) {
-      const seq = normalized.slice(i, i + len);
-      if (new Set(seq).size >= 2) {
-        sequences.push(seq);
-      }
-    }
-  }
-  return sequences;
-}
-function findExamplesForSequence(commands, steps) {
-  const normalized = commands.map((c) => ({
-    norm: normalizeCommand(c.command),
-    full: c.command
-  }));
-  for (let i = 0; i <= normalized.length - steps.length; i++) {
-    let match = true;
-    for (let j = 0; j < steps.length; j++) {
-      if (normalized[i + j].norm !== steps[j]) {
-        match = false;
-        break;
-      }
-    }
-    if (match) {
-      return normalized.slice(i, i + steps.length).map((n) => n.full);
-    }
-  }
-  return [];
-}
-function removeSubsequences(candidates) {
-  const sorted = [...candidates].sort(
-    (a, b) => b.steps.length - a.steps.length
-  );
-  const result = [];
-  for (const candidate of sorted) {
-    const key = candidate.steps.join(" \u2192 ");
-    const isSubsequence = result.some((longer) => {
-      const longerKey = longer.steps.join(" \u2192 ");
-      return longerKey.includes(key) && longerKey !== key;
-    });
-    if (!isSubsequence) {
-      result.push(candidate);
-    }
-  }
-  return result;
-}
-function generateSlug(steps) {
-  return steps.map((s) => {
-    const parts = s.split(/\s+/);
-    return parts[parts.length - 1];
-  }).join("-");
-}
-function describeSequence(steps) {
-  return `Recurring pattern: ${steps.join(" \u2192 ")}`;
-}
-
-// src/kernel/scheduler/blocker.ts
-function cascadeBlock(db, userId, tokenSlug) {
-  const token = getTokenBySlug(db, tokenSlug);
-  if (!token) {
-    throw new Error(`Unknown token slug: ${tokenSlug}`);
-  }
-  ensureCard(db, token.id, userId);
-  db.prepare(
-    "UPDATE cards SET blocked = 1 WHERE token_id = ? AND user_id = ?"
-  ).run(token.id, userId);
-  const prereqs = getPrerequisites(db, token.id);
-  const surfaced = [];
-  for (const prereq of prereqs) {
-    const card = ensureCard(db, prereq.requires_id, userId);
-    if (card.blocked === 1) {
-      const prereqOfPrereq = db.prepare("SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?").get(prereq.requires_id);
-      if (prereqOfPrereq.n === 0) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
-        db.prepare(
-          "UPDATE cards SET blocked = 0, due_at = ? WHERE token_id = ? AND user_id = ?"
-        ).run(now, prereq.requires_id, userId);
-      }
-    }
-    surfaced.push({
-      slug: prereq.slug,
-      concept: prereq.concept,
-      bloomLevel: prereq.bloom_level
-    });
-  }
-  return {
-    blockedSlug: tokenSlug,
-    prerequisites: surfaced
-  };
-}
-function unblockReady(db, userId) {
-  const blockedCards = db.prepare(
-    `SELECT c.token_id, t.slug, t.concept
-       FROM cards c
-       JOIN tokens t ON t.id = c.token_id
-       WHERE c.user_id = ? AND c.blocked = 1`
-  ).all(userId);
-  const unblocked = [];
-  for (const card of blockedCards) {
-    const totalPrereqs = db.prepare("SELECT COUNT(*) as n FROM prerequisites WHERE token_id = ?").get(card.token_id);
-    const metPrereqs = db.prepare(
-      `SELECT COUNT(*) as n FROM cards c
-         JOIN prerequisites p ON p.requires_id = c.token_id
-         WHERE p.token_id = ? AND c.user_id = ? AND c.reps >= 1 AND c.blocked = 0`
-    ).get(card.token_id, userId);
-    if (totalPrereqs.n === 0 || metPrereqs.n === totalPrereqs.n) {
-      const now = (/* @__PURE__ */ new Date()).toISOString();
-      db.prepare(
-        "UPDATE cards SET blocked = 0, due_at = ? WHERE token_id = ? AND user_id = ?"
-      ).run(now, card.token_id, userId);
-      unblocked.push({ slug: card.slug, concept: card.concept });
-    }
-  }
-  return { unblocked };
-}
-
-// src/kernel/recall/evaluator.ts
-import { ulid as ulid6 } from "ulid";
-
-// src/kernel/scheduler/fsrs.ts
-var DEFAULT_W = [
-  0.4072,
-  1.1829,
-  3.1262,
-  15.4722,
-  // w0–w3:  initial stability per rating
-  7.2102,
-  0.5316,
-  1.0651,
-  // w4–w6:  difficulty
-  92e-4,
-  1.5988,
-  0.1176,
-  1.0014,
-  // w7–w10: stability after forgetting
-  2.0032,
-  0.0266,
-  0.3077,
-  0.15,
-  // w11–w14: stability increase
-  0,
-  2.7849,
-  0.3477,
-  0.6831
-  // w15–w18: additional parameters
-];
-var DEFAULT_REQUEST_RETENTION = 0.9;
-function clamp(value, lo, hi) {
-  return Math.min(hi, Math.max(lo, value));
-}
-function daysBetween(a, b) {
-  return (b.getTime() - a.getTime()) / (1e3 * 60 * 60 * 24);
-}
-function initialStability(w, rating) {
-  return w[rating - 1];
-}
-function initialDifficulty(w, rating) {
-  return clamp(w[4] - Math.exp(w[5] * (rating - 1)) + 1, 1, 10);
-}
-function nextDifficulty(w, d, rating) {
-  const d0ForGood = initialDifficulty(w, 3);
-  const updated = w[7] * d0ForGood + (1 - w[7]) * (d - w[6] * (rating - 3));
-  return clamp(updated, 1, 10);
-}
-function retrievability(elapsed, stability) {
-  if (stability <= 0) return 0;
-  return (1 + elapsed / (9 * stability)) ** -1;
-}
-function stabilityAfterSuccess(w, s, d, r, rating) {
-  const hardPenalty = rating === 2 ? w[15] : 1;
-  const easyBonus = rating === 4 ? w[16] : 1;
-  const inner = Math.exp(w[8]) * (11 - d) * s ** -w[9] * (Math.exp(w[10] * (1 - r)) - 1) * hardPenalty * easyBonus;
-  return s * (inner + 1);
-}
-function stabilityAfterForgetting(w, s, d, r) {
-  return w[11] * d ** -w[12] * ((s + 1) ** w[13] - 1) * Math.exp(w[14] * (1 - r));
-}
-function nextInterval(stability, requestRetention) {
-  const interval = 9 * stability * (1 / requestRetention - 1);
-  return Math.max(1, Math.round(interval));
+function extractSequences(commands, minLen, maxLen) {
+  const filtered = commands.filter((c) => {
+    const lower = c.command.toLowerCase().trim();
+    return lower.length > 0 && !lower.startsWith("cd ") && lower !== "cd" && lower !== "ls" && lower !== "pwd" && lower !== "clear" && lower !== "exit" && !lower.startsWith("echo ");
+  });
+  const normalized = filtered.map((c) => normalizeCommand(c.command));
+  const sequences = [];
+  for (let len = minLen; len <= maxLen; len++) {
+    for (let i = 0; i <= normalized.length - len; i++) {
+      const seq = normalized.slice(i, i + len);
+      if (new Set(seq).size >= 2) {
+        sequences.push(seq);
+      }
+    }
+  }
+  return sequences;
 }
-function createFSRS(params) {
-  const resolvedParams = {
-    w: params?.w ?? [...DEFAULT_W],
-    requestRetention: params?.requestRetention ?? DEFAULT_REQUEST_RETENTION
-  };
-  function schedule(card, rating, now) {
-    const reviewTime = now ?? /* @__PURE__ */ new Date();
-    const w = resolvedParams.w;
-    const elapsed = card.lastReviewAt !== null ? Math.max(0, daysBetween(card.lastReviewAt, reviewTime)) : 0;
-    if (card.state === "new") {
-      const s = initialStability(w, rating);
-      const d = initialDifficulty(w, rating);
-      const interval2 = nextInterval(s, resolvedParams.requestRetention);
-      const dueAt2 = new Date(reviewTime);
-      dueAt2.setDate(dueAt2.getDate() + interval2);
-      return {
-        stability: s,
-        difficulty: d,
-        elapsedDays: 0,
-        scheduledDays: interval2,
-        reps: rating >= 2 ? 1 : 0,
-        lapses: rating === 1 ? 1 : 0,
-        state: "learning",
-        dueAt: dueAt2,
-        lastReviewAt: reviewTime
-      };
+function findExamplesForSequence(commands, steps) {
+  const normalized = commands.map((c) => ({
+    norm: normalizeCommand(c.command),
+    full: c.command
+  }));
+  for (let i = 0; i <= normalized.length - steps.length; i++) {
+    let match = true;
+    for (let j = 0; j < steps.length; j++) {
+      if (normalized[i + j].norm !== steps[j]) {
+        match = false;
+        break;
+      }
     }
-    const r = retrievability(elapsed, card.stability);
-    let newStability;
-    let newDifficulty;
-    let newReps;
-    let newLapses;
-    let newState;
-    if (rating === 1) {
-      newStability = stabilityAfterForgetting(
-        w,
-        card.stability,
-        card.difficulty,
-        r
-      );
-      newDifficulty = nextDifficulty(w, card.difficulty, rating);
-      newReps = 0;
-      newLapses = card.lapses + 1;
-      newState = "relearning";
-    } else {
-      newStability = stabilityAfterSuccess(
-        w,
-        card.stability,
-        card.difficulty,
-        r,
-        rating
-      );
-      newDifficulty = nextDifficulty(w, card.difficulty, rating);
-      newReps = card.reps + 1;
-      newLapses = card.lapses;
-      newState = "review";
+    if (match) {
+      return normalized.slice(i, i + steps.length).map((n) => n.full);
     }
-    const interval = nextInterval(
-      newStability,
-      resolvedParams.requestRetention
-    );
-    const dueAt = new Date(reviewTime);
-    dueAt.setDate(dueAt.getDate() + interval);
-    return {
-      stability: newStability,
-      difficulty: newDifficulty,
-      elapsedDays: elapsed,
-      scheduledDays: interval,
-      reps: newReps,
-      lapses: newLapses,
-      state: newState,
-      dueAt,
-      lastReviewAt: reviewTime
-    };
   }
-  return {
-    schedule,
-    params: Object.freeze(resolvedParams)
-  };
+  return [];
 }
-
-// src/kernel/recall/evaluator.ts
-function evaluateRating(db, input) {
-  const card = db.prepare("SELECT * FROM cards WHERE id = ?").get(input.cardId);
-  if (!card) {
-    throw new Error(`Card not found: ${input.cardId}`);
-  }
-  const now = /* @__PURE__ */ new Date();
-  const fsrs = createFSRS();
-  const schedulingCard = {
-    stability: card.stability,
-    difficulty: card.difficulty,
-    elapsedDays: card.elapsed_days,
-    scheduledDays: card.scheduled_days,
-    reps: card.reps,
-    lapses: card.lapses,
-    state: card.state,
-    dueAt: new Date(card.due_at),
-    lastReviewAt: card.last_review_at ? new Date(card.last_review_at) : null
-  };
-  const updated = fsrs.schedule(schedulingCard, input.rating, now);
-  updateCard(db, input.cardId, {
-    stability: updated.stability,
-    difficulty: updated.difficulty,
-    elapsed_days: updated.elapsedDays,
-    scheduled_days: updated.scheduledDays,
-    reps: updated.reps,
-    lapses: updated.lapses,
-    state: updated.state,
-    due_at: updated.dueAt.toISOString(),
-    last_review_at: now.toISOString()
-  });
-  db.prepare(
-    `INSERT INTO review_logs (id, card_id, token_id, user_id, rating, response_time_ms, reviewed_at, scheduled_at, session_id)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
-  ).run(
-    ulid6(),
-    input.cardId,
-    input.tokenId,
-    input.userId,
-    input.rating,
-    input.responseTimeMs ?? null,
-    now.toISOString(),
-    card.due_at,
-    input.sessionId ?? null
+function removeSubsequences(candidates) {
+  const sorted = [...candidates].sort(
+    (a, b) => b.steps.length - a.steps.length
   );
-  return {
-    nextDueAt: updated.dueAt.toISOString(),
-    stability: updated.stability,
-    difficulty: updated.difficulty,
-    state: updated.state,
-    scheduledDays: updated.scheduledDays,
-    reps: updated.reps,
-    lapses: updated.lapses
-  };
+  const result = [];
+  for (const candidate of sorted) {
+    const key = candidate.steps.join(" \u2192 ");
+    const isSubsequence = result.some((longer) => {
+      const longerKey = longer.steps.join(" \u2192 ");
+      return longerKey.includes(key) && longerKey !== key;
+    });
+    if (!isSubsequence) {
+      result.push(candidate);
+    }
+  }
+  return result;
+}
+function generateSlug(steps) {
+  return steps.map((s) => {
+    const parts = s.split(/\s+/);
+    return parts[parts.length - 1];
+  }).join("-");
+}
+function describeSequence(steps) {
+  return `Recurring pattern: ${steps.join(" \u2192 ")}`;
 }
 
 // src/kernel/recall/actions.ts
-function getReviewTarget(db, cardId, userId) {
-  const card = getCardById(db, cardId);
+async function getReviewTarget(db, cardId, userId) {
+  const card = await getCardById(db, cardId);
   if (!card) {
     throw new Error(`Card not found: ${cardId}`);
   }
   if (card.user_id !== userId) {
     throw new Error(`Card ${cardId} does not belong to user ${userId}`);
   }
-  const token = getTokenById(db, card.token_id);
+  const token = await getTokenById(db, card.token_id);
   if (!token) {
     throw new Error(`Token not found for card ${cardId}`);
   }
   return { cardId: card.id, token };
 }
-function executeReviewAction(db, input) {
-  const target = getReviewTarget(db, input.cardId, input.userId);
-  switch (input.action) {
-    case "rate": {
-      if (input.rating == null) {
-        throw new Error("rating is required for action=rate");
-      }
-      const evaluation = evaluateRating(db, {
-        cardId: target.cardId,
-        tokenId: target.token.id,
+async function executeReviewAction(db, input) {
+  if (input.action === "rate") {
+    if (input.rating == null) {
+      throw new Error("rating is required for action=rate");
+    }
+    const rating = input.rating;
+    return db.transaction(async (tx) => {
+      const target2 = await getReviewTarget(tx, input.cardId, input.userId);
+      const evaluation = await evaluateRatingWithinTransaction(tx, {
+        cardId: target2.cardId,
+        tokenId: target2.token.id,
         userId: input.userId,
-        rating: input.rating
+        rating
       });
       let blocked;
-      if (input.rating === 1) {
-        const prereqs = getPrerequisites(db, target.token.id);
+      if (rating === 1) {
+        const prereqs = await getPrerequisites(tx, target2.token.id);
         if (prereqs.length > 0) {
-          blocked = cascadeBlock(db, input.userId, target.token.slug);
+          blocked = await cascadeBlock(tx, input.userId, target2.token.slug);
         }
       }
       return {
         action: input.action,
-        token: target.token,
+        token: target2.token,
         evaluation,
         blocked
       };
-    }
+    });
+  }
+  const target = await getReviewTarget(db, input.cardId, input.userId);
+  switch (input.action) {
     case "skip":
       return { action: input.action, token: target.token, skipped: true };
     case "stop":
       return { action: input.action, token: target.token, stopped: true };
     case "edit-token": {
-      const updatedToken = updateToken(
+      const updatedToken = await updateToken(
         db,
         target.token.slug,
         input.tokenUpdates ?? {}
@@ -2194,7 +2996,7 @@ function executeReviewAction(db, input) {
       };
     }
     case "deprecate-token": {
-      const updatedToken = deprecateToken(db, target.token.slug);
+      const updatedToken = await deprecateToken(db, target.token.slug);
       return {
         action: input.action,
         token: target.token,
@@ -2202,7 +3004,7 @@ function executeReviewAction(db, input) {
       };
     }
     case "delete-token": {
-      const deletedToken = deleteToken(db, target.token.slug);
+      const deletedToken = await deleteToken(db, target.token.slug);
       return {
         action: input.action,
         token: target.token,
@@ -2210,7 +3012,11 @@ function executeReviewAction(db, input) {
       };
     }
     case "delete-card": {
-      const deletedCard = deleteCardForUser(db, target.token.id, input.userId);
+      const deletedCard = await deleteCardForUser(
+        db,
+        target.token.id,
+        input.userId
+      );
       return {
         action: input.action,
         token: target.token,
@@ -2514,12 +3320,12 @@ function interleave(items, maxConsecutive = 2) {
 }
 
 // src/kernel/scheduler/queue.ts
-function buildReviewQueue(db, options) {
+async function buildReviewQueue(db, options) {
   const maxNew = options.maxNew ?? 10;
   const maxReviews = options.maxReviews ?? 50;
   const now = options.now ?? /* @__PURE__ */ new Date();
   const nowISO = now.toISOString();
-  const dueRows = db.prepare(
+  const dueRows = await db.prepare(
     `SELECT
          c.id       AS card_id,
          c.token_id AS token_id,
@@ -2540,7 +3346,7 @@ function buildReviewQueue(db, options) {
          AND t.deprecated_at IS NULL
        ORDER BY c.due_at ASC`
   ).all(options.userId, nowISO);
-  const newRows = db.prepare(
+  const newRows = await db.prepare(
     `SELECT
          c.id       AS card_id,
          c.token_id AS token_id,
@@ -3055,11 +3861,61 @@ function t(locale, key, params = {}) {
   return str;
 }
 
+// src/kernel/system/install-config.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
+import { homedir as homedir5 } from "os";
+import { dirname as dirname4, join as join7 } from "path";
+var DEFAULT_CONFIG_PATH = join7(homedir5(), ".zam", "config.json");
+function loadInstallConfig(path = DEFAULT_CONFIG_PATH) {
+  if (!existsSync7(path)) return {};
+  try {
+    return JSON.parse(readFileSync7(path, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function saveInstallConfig(config, path = DEFAULT_CONFIG_PATH) {
+  const dir = dirname4(path);
+  if (!existsSync7(dir)) mkdirSync5(dir, { recursive: true });
+  writeFileSync4(path, `${JSON.stringify(config, null, 2)}
+`, "utf-8");
+}
+function getInstallMode(path = DEFAULT_CONFIG_PATH) {
+  return loadInstallConfig(path).mode ?? "developer";
+}
+function setInstallMode(mode, path = DEFAULT_CONFIG_PATH) {
+  const config = loadInstallConfig(path);
+  config.mode = mode;
+  saveInstallConfig(config, path);
+}
+function getInstallChannel(path = DEFAULT_CONFIG_PATH) {
+  const config = loadInstallConfig(path);
+  if (config.channel) return config.channel;
+  return (config.mode ?? "developer") === "developer" ? "developer" : "direct";
+}
+function setInstallChannel(channel, path = DEFAULT_CONFIG_PATH) {
+  const config = loadInstallConfig(path);
+  config.channel = channel;
+  saveInstallConfig(config, path);
+}
+function detectSyncProvider(dir) {
+  const p = dir.toLowerCase();
+  if (p.includes("onedrive")) return "OneDrive";
+  if (p.includes("dropbox")) return "Dropbox";
+  if (p.includes("google drive") || p.includes("googledrive") || p.includes("/my drive")) {
+    return "Google Drive";
+  }
+  if (p.includes("icloud") || p.includes("mobile documents")) {
+    return "iCloud Drive";
+  }
+  return null;
+}
+
 // src/kernel/system/installer.ts
 import { execFileSync, execSync } from "child_process";
-import { existsSync as existsSync7 } from "fs";
-import { homedir as homedir5 } from "os";
-import { join as join7 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { homedir as homedir6 } from "os";
+import { join as join8 } from "path";
 function hasCommand(cmd) {
   try {
     const checkCmd = process.platform === "win32" ? `where ${cmd}` : `which ${cmd}`;
@@ -3076,7 +3932,7 @@ function installFastFlowLM() {
       message: "FastFlowLM is only supported on Windows."
     };
   }
-  const hasFlm = hasCommand("flm") || existsSync7("C:\\Program Files\\flm\\flm.exe");
+  const hasFlm = hasCommand("flm") || existsSync8("C:\\Program Files\\flm\\flm.exe");
   if (hasFlm) {
     return { success: true, message: "FastFlowLM is already installed." };
   }
@@ -3103,8 +3959,8 @@ function installFastFlowLM() {
 function installOllama() {
   const isMac = process.platform === "darwin";
   const isWin = process.platform === "win32";
-  const hasOllama = hasCommand("ollama") || isMac && existsSync7("/Applications/Ollama.app") || isWin && existsSync7(
-    join7(homedir5(), "AppData", "Local", "Programs", "Ollama", "ollama.exe")
+  const hasOllama = hasCommand("ollama") || isMac && existsSync8("/Applications/Ollama.app") || isWin && existsSync8(
+    join8(homedir6(), "AppData", "Local", "Programs", "Ollama", "ollama.exe")
   );
   if (hasOllama) {
     return { success: true, message: "Ollama is already installed." };
@@ -3164,8 +4020,8 @@ function installOllama() {
 function resolveOllamaCommand() {
   if (hasCommand("ollama")) return "ollama";
   const candidates = process.platform === "win32" ? [
-    join7(
-      homedir5(),
+    join8(
+      homedir6(),
       "AppData",
       "Local",
       "Programs",
@@ -3173,7 +4029,7 @@ function resolveOllamaCommand() {
       "ollama.exe"
     )
   ] : process.platform === "darwin" ? ["/Applications/Ollama.app/Contents/Resources/ollama"] : [];
-  return candidates.find((candidate) => existsSync7(candidate));
+  return candidates.find((candidate) => existsSync8(candidate));
 }
 function prepareLocalModel(runner, model) {
   if (runner === "fastflowlm") {
@@ -3206,6 +4062,63 @@ function prepareLocalModel(runner, model) {
     };
   }
 }
+function planOpenCodeInstall(env) {
+  if (env.hasNpm) {
+    return { method: "npm", command: "npm install -g opencode-ai" };
+  }
+  if (env.platform === "darwin") {
+    if (env.hasBrew) {
+      return {
+        method: "homebrew",
+        command: "brew install anomalyco/tap/opencode"
+      };
+    }
+    return {
+      method: "script",
+      command: "curl -fsSL https://opencode.ai/install | bash"
+    };
+  }
+  if (env.platform === "win32") {
+    if (env.hasScoop)
+      return { method: "scoop", command: "scoop install opencode" };
+    if (env.hasChoco) {
+      return { method: "chocolatey", command: "choco install opencode" };
+    }
+    return null;
+  }
+  return {
+    method: "script",
+    command: "curl -fsSL https://opencode.ai/install | bash"
+  };
+}
+function installOpenCode() {
+  if (hasCommand("opencode")) {
+    return { success: true, message: "opencode is already installed." };
+  }
+  const plan = planOpenCodeInstall({
+    platform: process.platform,
+    hasNpm: hasCommand("npm"),
+    hasBrew: hasCommand("brew"),
+    hasScoop: hasCommand("scoop"),
+    hasChoco: hasCommand("choco")
+  });
+  if (!plan) {
+    return {
+      success: false,
+      message: "Could not find a way to install opencode automatically. Install npm, Scoop, or Chocolatey, or follow https://opencode.ai/docs (native Apple Silicon and Windows on ARM builds are available)."
+    };
+  }
+  console.log(`Installing opencode via ${plan.method}...`);
+  try {
+    execSync(plan.command, { stdio: "inherit" });
+    return { success: true, message: `opencode installed via ${plan.method}.` };
+  } catch (err) {
+    return {
+      success: false,
+      message: `Failed to install opencode: ${err.message}. Try manually: ${plan.command}`
+    };
+  }
+}
 
 // src/kernel/system/locale.ts
 import { execSync as execSync2 } from "child_process";
@@ -3304,72 +4217,164 @@ function getSystemProfile() {
 }
 
 // src/kernel/system/repos.ts
-import { existsSync as existsSync8 } from "fs";
+import { existsSync as existsSync9 } from "fs";
 import { resolve as resolve2 } from "path";
-function getRepoPaths(db) {
-  const personalSetting = getSetting(db, "repo.personal") || getSetting(db, "personal.workspace_dir");
-  const teamSetting = getSetting(db, "repo.team");
-  const orgSetting = getSetting(db, "repo.org");
+async function getRepoPaths(db) {
+  const personalSetting = await getSetting(db, "repo.personal") || await getSetting(db, "personal.workspace_dir");
+  const teamSetting = await getSetting(db, "repo.team");
+  const orgSetting = await getSetting(db, "repo.org");
   return {
     personal: personalSetting ? resolve2(personalSetting) : null,
     team: teamSetting ? resolve2(teamSetting) : null,
     org: orgSetting ? resolve2(orgSetting) : null
   };
 }
-function resolveRepoPath(db, type) {
-  const paths = getRepoPaths(db);
+async function resolveRepoPath(db, type) {
+  const paths = await getRepoPaths(db);
   return paths[type];
 }
-function resolveAllBeliefPaths(db) {
-  const paths = getRepoPaths(db);
+async function resolveAllBeliefPaths(db) {
+  const paths = await getRepoPaths(db);
   const dirs = [];
   if (paths.personal) {
     const personalDir = resolve2(paths.personal, "beliefs");
-    if (existsSync8(personalDir)) dirs.push(personalDir);
+    if (existsSync9(personalDir)) dirs.push(personalDir);
   }
   if (paths.team) {
     const teamDir = resolve2(paths.team, "beliefs");
-    if (existsSync8(teamDir)) dirs.push(teamDir);
+    if (existsSync9(teamDir)) dirs.push(teamDir);
   }
   if (paths.org) {
     const orgDir = resolve2(paths.org, "beliefs");
-    if (existsSync8(orgDir)) dirs.push(orgDir);
+    if (existsSync9(orgDir)) dirs.push(orgDir);
   }
   return dirs;
 }
-function resolveAllGoalPaths(db) {
-  const paths = getRepoPaths(db);
+async function resolveAllGoalPaths(db) {
+  const paths = await getRepoPaths(db);
   const dirs = [];
   if (paths.personal) {
     const personalDir = resolve2(paths.personal, "goals");
-    if (existsSync8(personalDir)) dirs.push(personalDir);
+    if (existsSync9(personalDir)) dirs.push(personalDir);
   }
   if (paths.team) {
     const teamDir = resolve2(paths.team, "goals");
-    if (existsSync8(teamDir)) dirs.push(teamDir);
+    if (existsSync9(teamDir)) dirs.push(teamDir);
   }
   if (paths.org) {
     const orgDir = resolve2(paths.org, "goals");
-    if (existsSync8(orgDir)) dirs.push(orgDir);
+    if (existsSync9(orgDir)) dirs.push(orgDir);
   }
   return dirs;
 }
+
+// src/kernel/system/update-check.ts
+var WINGET_PACKAGE_ID = "ZAM.ZAM";
+var HOMEBREW_CASK = "zam";
+function parseVersion(version) {
+  const clean = version.trim().replace(/^v/i, "");
+  const [main, pre = ""] = clean.split("-", 2);
+  const core = main.split(".").map((n) => Number.parseInt(n, 10) || 0);
+  while (core.length < 3) core.push(0);
+  return { core, pre: pre ? pre.split(".") : [] };
+}
+function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  for (let i = 0; i < 3; i++) {
+    if (pa.core[i] !== pb.core[i]) return pa.core[i] > pb.core[i] ? 1 : -1;
+  }
+  if (pa.pre.length === 0 && pb.pre.length === 0) return 0;
+  if (pa.pre.length === 0) return 1;
+  if (pb.pre.length === 0) return -1;
+  const len = Math.max(pa.pre.length, pb.pre.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa.pre[i];
+    const y = pb.pre[i];
+    if (x === void 0) return -1;
+    if (y === void 0) return 1;
+    const xNum = /^\d+$/.test(x);
+    const yNum = /^\d+$/.test(y);
+    if (xNum && yNum) {
+      const dx = Number(x);
+      const dy = Number(y);
+      if (dx !== dy) return dx > dy ? 1 : -1;
+    } else if (xNum !== yNum) {
+      return xNum ? -1 : 1;
+    } else if (x !== y) {
+      return x > y ? 1 : -1;
+    }
+  }
+  return 0;
+}
+function decideUpdate(input) {
+  const { currentVersion, latestVersion, channel } = input;
+  const base = { currentVersion, latestVersion, channel };
+  if (compareVersions(latestVersion, currentVersion) <= 0) {
+    return {
+      ...base,
+      updateAvailable: false,
+      action: "none",
+      reason: "Already on the latest version."
+    };
+  }
+  switch (channel) {
+    case "direct":
+      return {
+        ...base,
+        updateAvailable: true,
+        action: "self-update",
+        reason: "A signed update can be installed in place."
+      };
+    case "winget":
+      return {
+        ...base,
+        updateAvailable: true,
+        action: "run-command",
+        command: `winget upgrade --id ${WINGET_PACKAGE_ID}`,
+        reason: "Update available through winget."
+      };
+    case "homebrew":
+      return {
+        ...base,
+        updateAvailable: true,
+        action: "run-command",
+        command: `brew upgrade --cask ${HOMEBREW_CASK}`,
+        reason: "Update available through Homebrew."
+      };
+    default:
+      return {
+        ...base,
+        updateAvailable: true,
+        action: "inform",
+        command: "git pull && npm install && npm run build",
+        reason: "Developer install \u2014 update from source."
+      };
+  }
+}
 export {
   DEFAULT_REVIEW_CONTEXT_MAX_CHARS,
+  HOMEBREW_CASK,
+  SNAPSHOT_VERSION,
+  WINGET_PACKAGE_ID,
   addPrerequisite,
   analyzeObservation,
+  applySessionSynthesis,
   buildReviewQueue,
   cascadeBlock,
   clearADOCredentials,
   clearTursoCredentials,
+  compareVersions,
   createAgentSkill,
   createFSRS,
   createGoal,
   createToken,
+  decideUpdate,
   deleteCardForUser,
   deleteSetting,
   deleteToken,
   deprecateToken,
+  detectSyncProvider,
   detectSystemLocale,
   discoverSkills,
   distributeGlobalSkills,
@@ -3378,6 +4383,7 @@ export {
   ensureMonitorDir,
   evaluateRating,
   executeReviewAction,
+  exportSnapshot,
   extractTasks,
   extractTokenRefs,
   fetchActiveWorkItems,
@@ -3404,6 +4410,8 @@ export {
   getDueCards,
   getGoal,
   getGoalTree,
+  getInstallChannel,
+  getInstallMode,
   getMonitorDir,
   getMonitorLogStats,
   getMonitorPath,
@@ -3413,23 +4421,28 @@ export {
   getReviewsForCard,
   getReviewsForUser,
   getSessionSummary,
+  getSessionSynthesisRecords,
   getSetting,
   getSystemProfile,
   getTokenById,
   getTokenBySlug,
   getTokenDeleteImpact,
+  getTokenNeighborhood,
   getTursoCredentials,
   getUserStats,
   hasCommand,
+  importSnapshot,
   injectShellHooks,
   installFastFlowLM,
   installOllama,
+  installOpenCode,
   interleave,
   listAgentSkills,
   listGoals,
   listTokens,
   loadADOConfig,
   loadCredentials,
+  loadInstallConfig,
   logReview,
   logStep,
   matchesFilePath,
@@ -3438,10 +4451,14 @@ export {
   normalizePath,
   openDatabase,
   openDatabaseWithSync,
+  openRemoteDatabase,
   pairCommands,
   parseGoalFile,
   parseMonitorLog,
+  parseSnapshot,
+  planOpenCodeInstall,
   prepareLocalModel,
+  prepareSessionSynthesis,
   readMonitorLog,
   resolveAllBeliefPaths,
   resolveAllGoalPaths,
@@ -3449,8 +4466,11 @@ export {
   resolveRepoPath,
   resolveReviewContext,
   saveCredentials,
+  saveInstallConfig,
   serializeGoal,
   setADOCredentials,
+  setInstallChannel,
+  setInstallMode,
   setSetting,
   setTursoCredentials,
   startSession,
@@ -3459,6 +4479,7 @@ export {
   updateCard,
   updateGoalStatus,
   updateToken,
+  verifySnapshot,
   wouldCreateCycle,
   writeMonitorEvent
 };