@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/src/lib/scaffold/resolve-cloudflare-account.js

@@ -0,0 +1,37 @@
+/**
+ * Shared Cloudflare account resolution for scaffold wizards.
+ * Reuses the same detection the CLI's `agentsam env init cloudflare` flow
+ * already relies on — never ask the user to hand-paste an account ID that
+ * `wrangler whoami` (or an existing env override) can already answer.
+ */
+import { detectCloudflareAccounts } from '../../commands/env.js';
+
+export async function resolveCloudflareAccountId({ text, select, isCancel, cancel, note, pc, detectAccounts = detectCloudflareAccounts }) {
+  const detected = detectAccounts();
+
+  if (detected.accounts.length === 1) {
+    const acct = detected.accounts[0];
+    note(`Detected Cloudflare account: ${pc.cyan(acct.name || acct.id)}`, 'Cloudflare account');
+    return acct.id;
+  }
+
+  if (detected.accounts.length > 1) {
+    const choice = await select({
+      message: 'Which Cloudflare account?',
+      options: detected.accounts.map((a) => ({ value: a.id, label: a.name || a.id, hint: a.id })),
+    });
+    if (isCancel(choice)) { cancel('Cancelled.'); process.exit(0); }
+    return choice;
+  }
+
+  note('Could not auto-detect a Cloudflare account (run `agentsam cloudflare` to check login status).', 'Cloudflare account');
+  const cfAccountId = await text({
+    message: 'Cloudflare account ID? (from dash.cloudflare.com → right sidebar)',
+    placeholder: 'abc123...',
+    validate(val) {
+      if (!val || val.trim().length === 0) return 'Required.';
+    },
+  });
+  if (isCancel(cfAccountId)) { cancel('Cancelled.'); process.exit(0); }
+  return cfAccountId.trim();
+}

package/src/lib/scaffold/wizards/cms.js

@@ -22,6 +22,7 @@ import {
 import pc from 'picocolors';
 import { writeFileTree } from '../writer.js';
 import { cmsTemplates } from '../templates/cms/index.js';
+import { resolveCloudflareAccountId } from '../resolve-cloudflare-account.js';
 
 export async function runCmsWizard() {
   note('A Cloudflare Worker + D1 + R2 CMS site with reusable page templates.', 'CMS Site');
@@ -111,14 +112,7 @@ export async function runCmsWizard() {
   }
 
   // ── Step 7: Cloudflare account details ────────────────────────────────────
-  const cfAccountId = await text({
-    message: 'Cloudflare account ID? (from dash.cloudflare.com → right sidebar)',
-    placeholder: 'abc123...',
-    validate(val) {
-      if (!val || val.trim().length === 0) return 'Required for wrangler.toml.';
-    },
-  });
-  if (isCancel(cfAccountId)) { cancel('Cancelled.'); process.exit(0); }
+  const cfAccountId = await resolveCloudflareAccountId({ text, select, isCancel, cancel, note, pc });
 
   // ── Step 8: Confirm before writing ───────────────────────────────────────
   const summary = [

package/src/lib/scaffold/wizards/worker-api.js

@@ -16,6 +16,7 @@ import {
 import pc from 'picocolors';
 import { writeFileTree } from '../writer.js';
 import { workerApiTemplates } from '../templates/worker-api/index.js';
+import { resolveCloudflareAccountId } from '../resolve-cloudflare-account.js';
 
 export async function runWorkerApiWizard() {
   note('A typed Cloudflare Worker with route handlers, D1 binding, and CORS ready.', 'Worker API');
@@ -52,14 +53,7 @@ export async function runWorkerApiWizard() {
   });
   if (isCancel(dbKind)) { cancel('Cancelled.'); process.exit(0); }
 
-  const cfAccountId = await text({
-    message: 'Cloudflare account ID?',
-    placeholder: 'abc123...',
-    validate(val) {
-      if (!val || val.trim().length === 0) return 'Required.';
-    },
-  });
-  if (isCancel(cfAccountId)) { cancel('Cancelled.'); process.exit(0); }
+  const cfAccountId = await resolveCloudflareAccountId({ text, select, isCancel, cancel, note, pc });
 
   const confirmed = await confirm({ message: `Write files to ./${projectName.trim()}/?` });
   if (isCancel(confirmed) || !confirmed) { cancel('Cancelled.'); process.exit(0); }

package/src/lib/slash-commands.js

@@ -8,8 +8,9 @@ export const SLASH_COMMANDS = [
   { cmd: '/fast', description: 'Use provider Fast processing when the selected model supports it', lane: 'model' },
   { cmd: '/flex', description: 'Use provider Flex processing when the selected model supports it', lane: 'model' },
   { cmd: '/standard', description: 'Return to Standard provider processing', lane: 'model' },
+  { cmd: '/compact', description: 'Compact active provider context; status shows support, threshold, and receipt', lane: 'context' },
   { cmd: '/context', description: 'Show model context economics; add repo for Git bridge context', lane: 'context' },
-  { cmd: '/status', description: 'Local project, DB, Git, and PTY health', lane: 'local' },
+  { cmd: '/status', description: 'Honest project awareness: account, models, terminal, live deploy', lane: 'local' },
   { cmd: '/models', description: 'Probe providers and provider-verified known models', lane: 'model' },
   { cmd: '/providers', description: 'Configure and verify machine provider credentials', lane: 'model' },
   { cmd: '/login', description: 'Sign in to Inner Animal Media and save the machine-local Agent Sam session', lane: 'identity' },
@@ -18,16 +19,23 @@ export const SLASH_COMMANDS = [
   { cmd: '/session', description: 'Show current session usage, cost, and resume receipt', lane: 'observability' },
   { cmd: '/usage', description: 'Show token usage, spend breakdown, and resume command', lane: 'observability' },
   { cmd: '/cf', description: 'Cloudflare native reads, Wrangler status, and CPU profile analysis', lane: 'cloudflare' },
+  { cmd: '/connections', description: 'Inspect live account, terminal, Worker, and Cloudflare connection evidence', lane: 'cloudflare' },
+  { cmd: '/tunnel', description: 'Choose and run a real Cloudflare Tunnel through Wrangler', lane: 'cloudflare' },
   { cmd: '/settings', description: 'Choose project, runtime, terminal, and model policy' },
   { cmd: '/pwd', description: 'Print working directory', lane: 'terminal' },
   { cmd: '/cd', description: 'Change working directory', lane: 'terminal' },
   { cmd: '/git', description: 'Run an explicit Git subcommand', lane: 'git' },
   { cmd: '/diff', description: 'Show the current Git diff', lane: 'git' },
-  { cmd: '/db', description: 'Local SQLite status and query helpers', lane: 'data' },
+  { cmd: '/db', description: 'SQLite status; sources discovers stores; select knowledge sqlite|postgres [ENV]', lane: 'data' },
   { cmd: '/agent', description: 'Send a goal to the configured local Agent Sam runtime', lane: 'agent' },
+  { cmd: '/goap', description: 'Inspect and manage GOAP blackboard: /goap [status|goal|why|plan|list|new|switch|close]', lane: 'agent' },
+  { cmd: '/brand', description: 'Brand intelligence: /brand [scan|resolve|plan|inspect]', lane: 'product' },
+  { cmd: '/plan', description: 'Composable plans: /plan brand', lane: 'product' },
+  { cmd: '/next', description: 'Suggested next actions from session progression', lane: 'product' },
   { cmd: '/logs', description: 'Show local Agent Sam execution events', lane: 'observability' },
   { cmd: '/deploy', description: 'Add a cloud adapter and deploy intentionally', lane: 'deploy' },
   { cmd: '/clear', description: 'Clear the terminal display', lane: 'terminal' },
+  { cmd: '/skills', description: 'List resolvable slash skill vocabulary', lane: 'agent' },
   { cmd: '/help', description: 'Show the factual implemented command catalog' },
   { cmd: '/exit', description: 'Exit Agent Sam shell and return to the host terminal' },
 ];

package/src/local/migrations.js

@@ -37,6 +37,52 @@ function checksumSource(source) {
   return 'fnv1a32:' + (hash >>> 0).toString(16).padStart(8, '0');
 }
 
+// A naive source.split(';') breaks on ANY semicolon -- including one
+// inside a wrapped comment line's prose ("...available; standalone...")
+// and every semicolon inside a CREATE TRIGGER's BEGIN...END body. Both
+// happen in real migration files (this one has both). Comment-strip first,
+// then split statement-aware: only treat ';' as a terminator outside a
+// BEGIN/END block, so a trigger body survives as one statement instead of
+// fragmenting into pieces that don't individually look like anything.
+function stripSqlComments(source) {
+  return source
+    .split('\n')
+    .map((line) => (line.trim().startsWith('--') ? '' : line))
+    .join('\n');
+}
+
+function splitSqlStatements(source) {
+  const clean = stripSqlComments(source);
+  // CASE ... END is also closed by the bare keyword END (no BEGIN of its
+  // own) -- a trigger body containing a CASE expression has one more END
+  // than BEGIN. Track BEGIN and CASE as the same depth-increasing class so
+  // a CASE's END doesn't prematurely close the enclosing trigger's depth.
+  const tokens = clean.split(/(\bBEGIN\b|\bCASE\b|\bEND\b|;)/i);
+  const statements = [];
+  let current = '';
+  let depth = 0;
+  for (const token of tokens) {
+    if (/^(BEGIN|CASE)$/i.test(token)) { depth += 1; current += token; continue; }
+    if (/^END$/i.test(token)) { depth = Math.max(0, depth - 1); current += token; continue; }
+    if (token === ';' && depth === 0) {
+      const trimmed = current.trim();
+      if (trimmed) statements.push(trimmed);
+      current = '';
+      continue;
+    }
+    current += token;
+  }
+  const trimmed = current.trim();
+  if (trimmed) statements.push(trimmed);
+  return statements;
+}
+
+function isIdempotentSafe(source) {
+  const statements = splitSqlStatements(source);
+  const IDEMPOTENT_RE = /^(CREATE\s+TABLE\s+IF\s+NOT\s+EXISTS|CREATE\s+(UNIQUE\s+)?INDEX\s+IF\s+NOT\s+EXISTS|CREATE\s+TRIGGER\s+IF\s+NOT\s+EXISTS|PRAGMA)/i;
+  return statements.length > 0 && statements.every((stmt) => IDEMPOTENT_RE.test(stmt.trim()));
+}
+
 export async function listAppliedMigrations(db) {
   ensureLedger(db);
   const result = await db.prepare(
@@ -60,7 +106,23 @@ export async function applyRuntimeMigrations(db, options = {}) {
 
     if (previous) {
       if (previous.checksum && previous.checksum !== checksum) {
-        throw new Error('migration_checksum_mismatch:' + id);
+        if (!isIdempotentSafe(source)) throw new Error('migration_checksum_mismatch:' + id);
+        // File grew via additive, idempotent statements only (e.g. a new
+        // CREATE TABLE IF NOT EXISTS appended for a later feature). Safe to
+        // re-run and accept the new checksum rather than hard-lock the CLI.
+        db.exec('BEGIN IMMEDIATE');
+        try {
+          db.exec(source);
+          await db.prepare(
+            'UPDATE agentsam_schema_migrations SET checksum = ? WHERE id = ?'
+          ).bind(checksum, id).run();
+          db.exec('COMMIT');
+          results.push({ id, filename, status: 'repaired', checksum, previous_checksum: previous.checksum });
+          continue;
+        } catch (error) {
+          try { db.exec('ROLLBACK'); } catch {}
+          throw new Error('migration_repair_failed:' + id + ':' + (error?.message || error));
+        }
       }
       results.push({ id, filename, status: 'already_applied', checksum });
       continue;
@@ -88,6 +150,52 @@ export async function applyRuntimeMigrations(db, options = {}) {
   });
 }
 
+// Synchronous entry point for the interactive shell. Both runners consume the
+// same versioned SQL and checksums; schema ownership stays in migrations/runtime.
+export function applyRuntimeMigrationsSync(db, options = {}) {
+  const dir = path.resolve(options.migrationsDir || DEFAULT_MIGRATIONS_DIR);
+  ensureLedger(db);
+  const applied = new Map(db.prepare(
+    'SELECT id, applied_at_unix, checksum FROM agentsam_schema_migrations ORDER BY id'
+  ).all().map((row) => [String(row.id), row]));
+  const results = [];
+  for (const filename of migrationFiles(dir)) {
+    const id = filename.replace(/\.sql$/i, '');
+    const source = fs.readFileSync(path.join(dir, filename), 'utf8');
+    const checksum = checksumSource(source);
+    const previous = applied.get(id);
+    if (previous) {
+      if (previous.checksum && previous.checksum !== checksum) {
+        if (!isIdempotentSafe(source)) throw new Error('migration_checksum_mismatch:' + id);
+        db.exec('BEGIN IMMEDIATE');
+        try {
+          db.exec(source);
+          db.prepare('UPDATE agentsam_schema_migrations SET checksum = ? WHERE id = ?').run(checksum, id);
+          db.exec('COMMIT');
+          results.push({ id, filename, status: 'repaired', checksum, previous_checksum: previous.checksum });
+          continue;
+        } catch (error) {
+          try { db.exec('ROLLBACK'); } catch {}
+          throw new Error('migration_repair_failed:' + id + ':' + (error?.message || error));
+        }
+      }
+      results.push({ id, filename, status: 'already_applied', checksum });
+      continue;
+    }
+    db.exec('BEGIN IMMEDIATE');
+    try {
+      db.exec(source);
+      db.prepare('INSERT INTO agentsam_schema_migrations (id, checksum) VALUES (?, ?)').run(id, checksum);
+      db.exec('COMMIT');
+      results.push({ id, filename, status: 'applied', checksum });
+    } catch (error) {
+      try { db.exec('ROLLBACK'); } catch {}
+      throw new Error('migration_failed:' + id + ':' + (error?.message || error));
+    }
+  }
+  return Object.freeze({ migrationsDir: dir, total: results.length, applied: results.filter((row) => row.status === 'applied').length, results: Object.freeze(results) });
+}
+
 export function runtimeMigrationsDirectory() {
   return DEFAULT_MIGRATIONS_DIR;
 }

package/src/local/runtime-store.js

@@ -2,12 +2,28 @@ import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { createLocalSqliteDatabase } from './sqlite.js';
 import { applyRuntimeMigrations } from './migrations.js';
+import { findCliProjectRoot } from '../lib/cli-preferences.js';
+import { getLocalDatabasePath, tryReadProjectConfig } from '../lib/project-config.js';
 
 function clean(value) { return value == null ? '' : String(value).trim(); }
 function hash(value) { return createHash('sha256').update(String(value || '')).digest('hex'); }
 
-export function runtimeDatabasePath(cwd = process.cwd()) {
-  return path.join(path.resolve(cwd), '.agentsam', 'data', 'agentsam.sqlite');
+export const SQLITE_RUNTIME_CAPABILITIES = Object.freeze({
+  transactions: true,
+  relational_queries: true,
+  ttl_cleanup: 'application_managed',
+  remote_shared_state: false,
+  local_only: true,
+  concurrent_writers: 'sqlite_serialized',
+  migrations: true,
+  vector_search: false,
+  blob_storage: false,
+  distributed_actor_semantics: false,
+});
+
+export function runtimeDatabasePath(startDir = process.cwd()) {
+  const root = findCliProjectRoot(startDir);
+  return path.resolve(root, getLocalDatabasePath(tryReadProjectConfig(root)));
 }
 
 async function withStore(cwd, fn) {
@@ -26,7 +42,7 @@ export function createRuntimeRunId() {
 
 export async function startRuntimeRun(value = {}) {
   const id = clean(value.id) || createRuntimeRunId();
-  await withStore(value.cwd, async (db) => {
+  await withStore(value.projectRoot || value.cwd, async (db) => {
     await db.prepare(`
       INSERT INTO agentsam_agent_run (
         id, account_id, source_client, surface, mode, model_key,
@@ -46,7 +62,7 @@ export async function startRuntimeRun(value = {}) {
 
 export async function finishRuntimeRun(value = {}) {
   if (!clean(value.id)) return;
-  await withStore(value.cwd, async (db) => {
+  await withStore(value.projectRoot || value.cwd, async (db) => {
     const usage = value.usage || {};
     await db.prepare(`
       UPDATE agentsam_agent_run
@@ -87,7 +103,7 @@ export async function recordRuntimeCompaction(value = {}) {
   const after = Math.max(0, Math.round(Number(value.tokens_after || 0)));
   const sourceHash = hash(summary || JSON.stringify(value.metadata || {}));
 
-  await withStore(value.cwd, async (db) => {
+  await withStore(value.projectRoot || value.cwd, async (db) => {
     await db.prepare(`
       INSERT INTO agentsam_compaction_events (
         id, account_id, agent_run_id, compaction_type, compaction_scope,
@@ -139,3 +155,13 @@ export async function recordRuntimeCompaction(value = {}) {
   });
   return id;
 }
+
+export async function pruneExpiredRuntimeState(value = {}) {
+  const nowUnix = Number.isFinite(Number(value.nowUnix)) ? Math.floor(Number(value.nowUnix)) : Math.floor(Date.now() / 1000);
+  return withStore(value.projectRoot || value.cwd, async (db) => {
+    const digests = await db.prepare('DELETE FROM agentsam_context_digest WHERE expires_at_unix IS NOT NULL AND expires_at_unix <= ?').bind(nowUnix).run();
+    const compactions = await db.prepare('DELETE FROM agentsam_compaction_events WHERE expires_at_epoch IS NOT NULL AND expires_at_epoch <= ?').bind(nowUnix).run();
+    const approvals = await db.prepare("UPDATE agentsam_approval_queue SET status = 'expired' WHERE status = 'pending' AND expires_at IS NOT NULL AND expires_at <= ?").bind(nowUnix).run();
+    return { digests: Number(digests.changes || 0), compactions: Number(compactions.changes || 0), approvals_expired: Number(approvals.changes || 0) };
+  });
+}

package/src/local/sqlite.js

@@ -1,7 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { applyRuntimeMigrations } from './migrations.js';
 
+const require = createRequire(import.meta.url);
+
 async function loadSqlite() {
   try {
     return await import('node:sqlite');
@@ -18,11 +21,43 @@ function resolveFile(filePath) {
   return path.resolve(String(filePath || '.agentsam/data/agentsam.sqlite'));
 }
 
+function prepareDatabaseFile(resolved) {
+  const dir = path.dirname(resolved);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(dir, 0o700); } catch { /* platform policy may own directory mode */ }
+  }
+}
+
+function restrictDatabaseFile(resolved) {
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(resolved, 0o600); } catch { /* platform policy may own file mode */ }
+  }
+}
+
+// The shell's session API is synchronous. It uses the same database file and
+// migration directory as the async runtime store, with no second state store.
+export function createLocalSqliteDatabaseSync(filePath = '.agentsam/data/agentsam.sqlite') {
+  let DatabaseSync;
+  try { ({ DatabaseSync } = require('node:sqlite')); }
+  catch (error) {
+    const wrapped = new Error('Local SQLite requires Node 22.5+ (node:sqlite). Upgrade Node, then retry.');
+    wrapped.cause = error;
+    throw wrapped;
+  }
+  const resolved = resolveFile(filePath);
+  prepareDatabaseFile(resolved);
+  const db = new DatabaseSync(resolved);
+  restrictDatabaseFile(resolved);
+  return db;
+}
+
 export async function createLocalSqliteDatabase(filePath = '.agentsam/data/agentsam.sqlite') {
   const { DatabaseSync } = await loadSqlite();
   const resolved = resolveFile(filePath);
-  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  prepareDatabaseFile(resolved);
   const database = new DatabaseSync(resolved);
+  restrictDatabaseFile(resolved);
 
   return {
     filePath: resolved,

package/src/local-fs/capability.js

@@ -0,0 +1,121 @@
+/**
+ * Local runtime workspace capability — short-lived FS/PTY authority for one root.
+ *
+ * Compatible with later:
+ *   account → terminal connection → enrolled instance → approved workspace root
+ *
+ * Local today:
+ *   start-local binds one root + mints one capability.
+ *   Browser cannot invent an absolute root to gain authority.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const WORKSPACE_CAPABILITY_HEADER = 'x-agentsam-workspace-capability';
+export const LOCAL_RUNTIME_FILE = 'local-runtime.json';
+
+/**
+ * @param {{ root: string, port: number, host?: string }} opts
+ */
+export function mintWorkspaceCapability(opts) {
+  const root = path.resolve(opts.root);
+  const workspace_id = `ws_${crypto.randomBytes(10).toString('hex')}`;
+  const capability = `awc_${crypto.randomBytes(24).toString('hex')}`;
+  const expires_at = new Date(Date.now() + 12 * 60 * 60 * 1000).toISOString();
+  return Object.freeze({
+    schema: 'agentsam.local-workspace-capability.v1',
+    workspace_id,
+    capability,
+    root,
+    host: opts.host || '127.0.0.1',
+    port: opts.port,
+    runtimeBaseUrl: `http://${opts.host || '127.0.0.1'}:${opts.port}`,
+    fsBaseUrl: `http://${opts.host || '127.0.0.1'}:${opts.port}/v1/fs`,
+    expires_at,
+    purpose: 'local.filesystem+pty',
+  });
+}
+
+/**
+ * Persist capability beside the authorized root (machine-local; not file content authority).
+ * @param {object} record
+ */
+export function writeLocalRuntimeRecord(record) {
+  const dir = path.join(record.root, '.agentsam');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, LOCAL_RUNTIME_FILE);
+  fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+  return file;
+}
+
+/**
+ * @param {string} root
+ */
+export function readLocalRuntimeRecord(root) {
+  const file = path.join(path.resolve(root), '.agentsam', LOCAL_RUNTIME_FILE);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {string} expected
+ */
+export function extractCapability(req, expected) {
+  const header = req.headers[WORKSPACE_CAPABILITY_HEADER]
+    || req.headers.authorization
+    || '';
+  let token = '';
+  if (typeof header === 'string') {
+    if (header.toLowerCase().startsWith('bearer ')) token = header.slice(7).trim();
+    else token = header.trim();
+  }
+  if (!token && req.url) {
+    try {
+      const u = new URL(req.url, 'http://127.0.0.1');
+      token = u.searchParams.get('capability') || '';
+    } catch {
+      /* ignore */
+    }
+  }
+  return {
+    ok: Boolean(expected && token && token === expected),
+    token,
+  };
+}
+
+/**
+ * Loopback + Studio origin allowlist. Never `*`.
+ * @param {string|undefined} origin
+ * @param {string[]} [extra]
+ */
+export function isAllowedStudioOrigin(origin, extra = []) {
+  if (!origin || origin === 'null') return true; // non-browser / same-origin tooling
+  const allow = [
+    'http://127.0.0.1:8080',
+    'http://localhost:8080',
+    'http://127.0.0.1:5173',
+    'http://localhost:5173',
+    'http://127.0.0.1:3000',
+    'http://localhost:3000',
+    ...extra,
+  ];
+  return allow.includes(origin);
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ */
+export function isLoopbackRemote(req) {
+  const raw = req.socket?.remoteAddress || '';
+  return raw === '127.0.0.1'
+    || raw === '::1'
+    || raw === '::ffff:127.0.0.1'
+    || raw.endsWith('127.0.0.1');
+}

package/src/local-fs/freshness.js

@@ -0,0 +1,75 @@
+/**
+ * Minimal repository/index freshness bridge.
+ * Filesystem writes mark generation stale — do not re-index on every keystroke.
+ */
+
+/** @type {Map<string, { generation: number, stale_paths: Set<string>, updated_at: string }>} */
+const roots = new Map();
+
+/**
+ * @param {string} root
+ * @param {{ paths?: string[], reason?: string }} [opts]
+ */
+export function markRepositoryStale(root, opts = {}) {
+  const key = String(root);
+  const prev = roots.get(key) || {
+    generation: 0,
+    stale_paths: new Set(),
+    updated_at: null,
+  };
+  const nextGen = prev.generation + 1;
+  const stale_paths = new Set(prev.stale_paths);
+  for (const p of opts.paths || []) stale_paths.add(String(p));
+  const record = {
+    generation: nextGen,
+    stale_paths,
+    updated_at: new Date().toISOString(),
+    reason: opts.reason || 'filesystem_write',
+  };
+  roots.set(key, record);
+  return {
+    ok: true,
+    schema: 'agentsam.repository-freshness.v1',
+    root: key,
+    generation: record.generation,
+    stale_paths: [...stale_paths].slice(0, 200),
+    updated_at: record.updated_at,
+    reason: record.reason,
+  };
+}
+
+/**
+ * @param {string} root
+ */
+export function getRepositoryFreshness(root) {
+  const key = String(root);
+  const record = roots.get(key);
+  if (!record) {
+    return {
+      ok: true,
+      schema: 'agentsam.repository-freshness.v1',
+      root: key,
+      generation: 0,
+      stale: false,
+      stale_paths: [],
+    };
+  }
+  return {
+    ok: true,
+    schema: 'agentsam.repository-freshness.v1',
+    root: key,
+    generation: record.generation,
+    stale: record.stale_paths.size > 0 || record.generation > 0,
+    stale_paths: [...record.stale_paths].slice(0, 200),
+    updated_at: record.updated_at,
+    reason: record.reason,
+  };
+}
+
+/**
+ * @param {string} root
+ */
+export function clearRepositoryFreshness(root) {
+  roots.delete(String(root));
+  return { ok: true };
+}