synabun 1.3.0 → 2.0.0

package/neural-interface/lib/claude-panel-session.js

@@ -0,0 +1,272 @@
+// ── Per-tab session settings of the Claude sidepanel → SDK query options ──
+//
+// A panel tab sends its session settings with every query (`msg.session`). This
+// module is the bridge's reading of them: validate, split into what is fixed
+// when the CLI process starts and what can change on a live session, and apply
+// to the options. Pure functions; the bridge calls them for panel sessions only.
+
+const str = (v, max) => (typeof v === 'string' && v.trim() ? v.trim().slice(0, max) : '');
+const list = (v, max, itemMax) => (Array.isArray(v) ? v : []).map(x => str(x, itemMax)).filter(Boolean).slice(0, max);
+
+const MCP_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const AGENT_NAME = /^[A-Za-z][\w-]{0,63}$/;
+const TOOL_NAME = /^[A-Za-z][\w-]{0,79}$/;
+
+// MCP servers a tab adds for itself: remote ones only (http / sse, an http(s)
+// URL). A stdio server is a command line, and a web panel is not where one is
+// typed in; headers are not accepted either (a token would sit in the UI
+// state in clear text): a server that needs them belongs in the settings files.
+export function normalizeMcpServers(v) {
+  const out = [];
+  const seen = new Set();
+  for (const raw of Array.isArray(v) ? v : []) {
+    if (!raw || typeof raw !== 'object') continue;
+    const name = str(raw.name, 64);
+    if (!MCP_NAME.test(name) || name.toLowerCase() === 'synabun' || seen.has(name.toLowerCase())) continue;
+    let url;
+    try { url = new URL(str(raw.url, 2000)); } catch { continue; }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') continue;
+    const timeout = Number(raw.timeoutMs);
+    seen.add(name.toLowerCase());
+    out.push({
+      name,
+      type: raw.type === 'sse' ? 'sse' : 'http',
+      url: url.href,
+      alwaysLoad: raw.alwaysLoad === true,
+      timeoutMs: Number.isFinite(timeout) && timeout >= 1000 && timeout <= 3_600_000 ? Math.floor(timeout) : 0,
+    });
+    if (out.length >= 8) break;
+  }
+  return out;
+}
+
+// Subagents defined for one tab: { name: { description, prompt, tools?, model? } }.
+function normalizeAgents(v) {
+  const entries = Array.isArray(v) ? v.map(a => [a?.name, a]) : (v && typeof v === 'object' ? Object.entries(v) : []);
+  const out = [];
+  const seen = new Set();
+  for (const [rawName, def] of entries) {
+    const name = str(rawName, 64);
+    if (!AGENT_NAME.test(name) || seen.has(name) || !def || typeof def !== 'object') continue;
+    const description = str(def.description, 500);
+    const prompt = str(def.prompt, 8000);
+    if (!description || !prompt) continue;
+    const agent = { name, description, prompt };
+    // No `tools` means the agent inherits its parent's. A list is a restriction,
+    // and stays one: empty is "no tools", and a list whose entries are all
+    // unusable is empty too, never "inherit".
+    if (Array.isArray(def.tools)) agent.tools = list(def.tools, 40, 80).filter(t => TOOL_NAME.test(t) || /^mcp__[\w-]+(__[\w-]+)?$/.test(t));
+    const model = str(def.model, 120);
+    if (model) agent.model = model;
+    seen.add(name);
+    out.push(agent);
+    if (out.length >= 10) break;
+  }
+  return out;
+}
+
+// Settings a tab overrides for itself, from an allowlist: nothing that carries
+// hooks, permissions, environment or credentials goes through here.
+function normalizeOverlay(v) {
+  const r = v && typeof v === 'object' ? v : {};
+  return {
+    language: str(r.language, 40),
+    autoCompact: r.autoCompact === 'on' || r.autoCompact === 'off' ? r.autoCompact : 'default',
+    promptCacheTtl: r.promptCacheTtl === '5m' || r.promptCacheTtl === '1h' ? r.promptCacheTtl : '',
+    advisorModel: str(r.advisorModel, 120),
+  };
+}
+
+/** The overlay as flag settings: only the keys the tab set. */
+export function overlaySettings(overlay) {
+  const o = normalizeOverlay(overlay);
+  const settings = {};
+  if (o.language) settings.language = o.language;
+  if (o.autoCompact !== 'default') settings.autoCompactEnabled = o.autoCompact === 'on';
+  if (o.promptCacheTtl) settings.promptCacheTtl = o.promptCacheTtl;
+  if (o.advisorModel) settings.advisorModel = o.advisorModel;
+  return settings;
+}
+const OVERLAY_KEYS = ['language', 'autoCompactEnabled', 'promptCacheTtl', 'advisorModel'];
+
+/**
+ * @returns {{ start: object, live: object }}
+ *   `start`: needs a fresh process to change. `live`: applied with applyFlagSettings.
+ */
+export function normalizePanelSession(raw) {
+  const r = raw && typeof raw === 'object' ? raw : {};
+  const budget = Number(r.maxBudgetUsd);
+  const turns = Number(r.maxTurns);
+  const sandbox = r.sandbox && typeof r.sandbox === 'object' && r.sandbox.enabled === true
+    ? { autoAllowBash: r.sandbox.autoAllowBash === true }
+    : null;
+  return {
+    start: {
+      fallbackModel: str(r.fallbackModel, 120),
+      maxBudgetUsd: Number.isFinite(budget) && budget > 0 && budget <= 10_000 ? budget : 0,
+      maxTurns: Number.isInteger(turns) && turns >= 1 && turns <= 1000 ? turns : 0,
+      additionalDirectories: [...new Set(list(r.additionalDirectories, 10, 500))],
+      // The parent of the working directory is readable by default (sibling
+      // projects); a tab can remove that.
+      includeParentDir: r.includeParentDir !== false,
+      plugins: [...new Set(list(r.plugins, 10, 500))],
+      strictMcp: r.strictMcp === true,
+      systemPromptAppend: str(r.systemPromptAppend, 8000),
+      sandbox,
+      thinkingOff: r.thinking === 'off',
+      // Extra message streams. Real hook events and prompt suggestions are on
+      // unless the tab switched them off; subagent text too; the model-written
+      // progress summaries of subagents cost tokens and are opt-in.
+      hookEvents: r.hookEvents !== false,
+      promptSuggestions: r.promptSuggestions !== false,
+      subagentText: r.subagentText !== false,
+      agentSummaries: r.agentSummaries === true,
+      // Tools: rules approved without asking, tools removed, the built-in set
+      // (empty = Claude Code's own), and what plan mode is told.
+      allowedTools: [...new Set(list(r.allowedTools, 40, 200))],
+      disallowedTools: [...new Set(list(r.disallowedTools, 40, 200))],
+      tools: [...new Set(list(r.tools, 60, 80).filter(t => TOOL_NAME.test(t)))],
+      planModeInstructions: str(r.planModeInstructions, 4000),
+      // MCP: remote servers for this tab, and SynaBun's tools never deferred.
+      mcpServers: normalizeMcpServers(r.mcpServers),
+      synabunAlwaysLoad: r.synabunAlwaysLoad === true,
+      // Subagents defined for this tab, and the skills the model may see (empty = all).
+      agents: normalizeAgents(r.agents),
+      skills: [...new Set(list(r.skills, 60, 120))],
+      // A verbose log of the CLI process, written to a file the host names.
+      debug: r.debug === true,
+    },
+    live: {
+      fastMode: r.fastMode === true,
+      outputStyle: str(r.outputStyle, 120),
+      agent: str(r.agent, 120),
+      overlay: normalizeOverlay(r.overlay),
+    },
+  };
+}
+
+/** The part that needs a fresh process, as a comparable string. */
+export function startSignature(cfg) {
+  return JSON.stringify(cfg?.start || {});
+}
+
+/**
+ * The programmatic MCP server set of a session: the host's own entries (SynaBun,
+ * a brain's extras) plus the tab's. Used at start and again by setMcpServers,
+ * which replaces the whole dynamic set: the host's entries go in every time.
+ * @returns {{ servers: object, notes: string[] }}
+ */
+export function mergeTabMcpServers(hostServers, start) {
+  const servers = { ...(hostServers || {}) };
+  const notes = [];
+  const taken = new Set(Object.keys(servers).map(n => n.toLowerCase()));
+  for (const sv of start?.mcpServers || []) {
+    // The host's own entries (SynaBun) are never replaced by a tab's.
+    if (taken.has(sv.name.toLowerCase())) { notes.push(`MCP server "${sv.name}" is already defined for this session: the tab's entry was not added.`); continue; }
+    servers[sv.name] = { type: sv.type, url: sv.url, ...(sv.alwaysLoad ? { alwaysLoad: true } : {}), ...(sv.timeoutMs ? { timeout: sv.timeoutMs } : {}) };
+    taken.add(sv.name.toLowerCase());
+  }
+  if (start?.synabunAlwaysLoad && servers.SynaBun) servers.SynaBun = { ...servers.SynaBun, alwaysLoad: true };
+  return { servers, notes };
+}
+
+/**
+ * Apply a tab's session settings to the options of a new query.
+ * @param ctx.model         the model the query starts on
+ * @param ctx.parentDir     the working directory's parent (already in options.additionalDirectories when granted)
+ * @param ctx.validateDir   (path) => path|null, the bridge's working-directory check
+ * @returns {string[]} notes for the user (a directory that does not exist, …)
+ */
+export function applyPanelSessionOptions(options, cfg, ctx = {}) {
+  const notes = [];
+  if (!cfg) return notes;
+  const { start, live } = cfg;
+  const valid = typeof ctx.validateDir === 'function' ? ctx.validateDir : (p) => p;
+
+  if (start.fallbackModel && start.fallbackModel !== ctx.model) options.fallbackModel = start.fallbackModel;
+  if (start.maxBudgetUsd > 0) options.maxBudgetUsd = start.maxBudgetUsd;
+  if (start.maxTurns > 0) options.maxTurns = start.maxTurns;
+
+  const dirs = start.includeParentDir ? [...(options.additionalDirectories || [])] : [];
+  for (const dir of start.additionalDirectories) {
+    if (valid(dir)) { if (!dirs.includes(dir)) dirs.push(dir); } else notes.push(`Directory not found, not added: ${dir}`);
+  }
+  if (dirs.length) options.additionalDirectories = dirs; else delete options.additionalDirectories;
+
+  const plugins = [];
+  for (const path of start.plugins) {
+    if (valid(path)) plugins.push({ type: 'local', path }); else notes.push(`Plugin directory not found, not loaded: ${path}`);
+  }
+  if (plugins.length) options.plugins = plugins;
+
+  // Only the servers this bridge passes itself (SynaBun): none from settings or .mcp.json.
+  if (start.strictMcp) options.strictMcpConfig = true;
+  if (start.systemPromptAppend) options.systemPrompt = { type: 'preset', preset: 'claude_code', append: start.systemPromptAppend };
+  if (start.sandbox) {
+    options.sandbox = {
+      enabled: true,
+      autoAllowBashIfSandboxed: start.sandbox.autoAllowBash,
+      // SynaBun's MCP server and hooks are HTTP on this machine.
+      network: { allowedDomains: ['localhost', '127.0.0.1'], allowLocalBinding: true },
+    };
+  }
+  if (start.thinkingOff) options.thinking = { type: 'disabled' };
+  if (start.hookEvents) options.includeHookEvents = true;
+  if (start.promptSuggestions) options.promptSuggestions = true;
+  if (start.subagentText) options.forwardSubagentText = true;
+  if (start.agentSummaries) options.agentProgressSummaries = true;
+
+  // Fast mode is always stated: Off is `false`, not an absent key, or a
+  // `fastMode: true` in the user's settings would win while the panel says Off.
+  if (start.allowedTools?.length) options.allowedTools = [...new Set([...(options.allowedTools || []), ...start.allowedTools])];
+  if (start.disallowedTools?.length) options.disallowedTools = [...new Set([...(options.disallowedTools || []), ...start.disallowedTools])];
+  // An empty list would switch every built-in tool off: only a real list is passed.
+  if (start.tools?.length) options.tools = [...start.tools];
+  if (start.planModeInstructions) options.planModeInstructions = start.planModeInstructions;
+
+  if (start.mcpServers?.length || start.synabunAlwaysLoad) {
+    const merged = mergeTabMcpServers(options.mcpServers, start);
+    notes.push(...merged.notes);
+    if (Object.keys(merged.servers).length) options.mcpServers = merged.servers;
+  }
+
+  if (start.agents?.length) {
+    options.agents = { ...(options.agents || {}) };
+    for (const a of start.agents) {
+      options.agents[a.name] = { description: a.description, prompt: a.prompt, ...(a.tools ? { tools: [...a.tools] } : {}), ...(a.model ? { model: a.model } : {}) };
+    }
+  }
+  if (start.skills?.length) options.skills = [...start.skills];
+  if (start.debug) {
+    if (ctx.debugFile) { options.debug = true; options.debugFile = ctx.debugFile; }
+    else notes.push('The debug log is not available on this server: the session starts without it.');
+  }
+
+  const settings = { fastMode: live.fastMode === true, ...overlaySettings(live.overlay) };
+  if (live.outputStyle) settings.outputStyle = live.outputStyle;
+  if (Object.keys(settings).length) options.settings = settings;
+  if (live.agent) options.agent = live.agent;
+  return notes;
+}
+
+/**
+ * What applyFlagSettings needs to move a live session from one set of live
+ * settings to another (null clears a key), or null when nothing changed.
+ */
+export function liveSettingsPatch(prev, next) {
+  const a = prev || { fastMode: false, outputStyle: '', agent: '' };
+  const b = next || { fastMode: false, outputStyle: '', agent: '' };
+  const patch = {};
+  // false, not null: null removes the flag and restores the inherited setting.
+  if (a.fastMode !== b.fastMode) patch.fastMode = b.fastMode === true;
+  if (a.outputStyle !== b.outputStyle) patch.outputStyle = b.outputStyle || null;
+  if (a.agent !== b.agent) patch.agent = b.agent || null;
+  // The overlay: a key the tab set travels with its value, one it cleared goes
+  // back to what the settings files say (null removes it from the flag layer).
+  const before = overlaySettings(a.overlay);
+  const after = overlaySettings(b.overlay);
+  for (const key of OVERLAY_KEYS) {
+    if (before[key] !== after[key]) patch[key] = key in after ? after[key] : null;
+  }
+  return Object.keys(patch).length ? patch : null;
+}

package/neural-interface/lib/claude-permission-rules.js

@@ -0,0 +1,153 @@
+// ── Permission rules as Claude Code's settings files hold them ──
+// The sidepanel's /permissions view: what is allowed, denied or asked about, per
+// settings scope. The files are the CLI's, written by the CLI (a permission
+// card's "Always" goes through it). The SDK has no public call that lists or
+// edits a session's live rules (0.3.288), so this reads the same files the CLI
+// does, and removing a rule takes that one string out of its list: nothing
+// else in the file is touched, and the CLI picks the change up by itself.
+
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, sep } from 'node:path';
+import { canonicalInside, readConfinedFile, replaceFileAtomic } from './confined-fs.js';
+
+const MAX_RULES = 300;
+const MAX_SETTINGS_BYTES = 4 * 1024 * 1024;
+
+// The text of one settings file, read as the regular file it has to be: opened
+// without waiting on a FIFO, refused when it is a FIFO, a device or a folder
+// before a byte is read, and never more than MAX_SETTINGS_BYTES
+// (lib/confined-fs.js). `project`: the file arrived with a repository, so it
+// must really be inside that project; a link that leads out is not followed.
+// Without it the file is the user's own (of the default or a named account),
+// which may be a link into their dotfiles: the file behind the link is read.
+function readSettingsText(path, project) {
+  if (project) return readConfinedFile(project, path, { maxBytes: MAX_SETTINGS_BYTES, encoding: 'utf-8' });
+  const target = realpathSync(path);
+  return readConfinedFile(dirname(target), target, { maxBytes: MAX_SETTINGS_BYTES, encoding: 'utf-8' });
+}
+
+function readScope(path, project = '') {
+  const scope = { path, exists: false, defaultMode: '', allow: [], deny: [], ask: [], additionalDirectories: [], error: '' };
+  if (!path || !existsSync(path)) return scope;
+  scope.exists = true;
+  let text;
+  try { text = readSettingsText(path, project); }
+  catch (err) {
+    // Not read, and said as that: nothing here claims the file has no rules.
+    scope.error = project && err?.status === 403
+      ? 'is a link that leads out of the project, so it is not read here (Claude Code itself may still apply it)'
+      : `could not be read (${err?.message || err})`;
+    return scope;
+  }
+  try {
+    const settings = JSON.parse(text);
+    const p = settings && typeof settings === 'object' && settings.permissions && typeof settings.permissions === 'object' ? settings.permissions : {};
+    const list = (v) => (Array.isArray(v) ? v.filter(x => typeof x === 'string').slice(0, MAX_RULES) : []);
+    scope.allow = list(p.allow);
+    scope.deny = list(p.deny);
+    scope.ask = list(p.ask);
+    scope.additionalDirectories = list(p.additionalDirectories);
+    scope.defaultMode = typeof p.defaultMode === 'string' ? p.defaultMode : '';
+  } catch (err) {
+    // A file that does not parse is skipped by the CLI, rules and all: say so.
+    scope.error = `could not be read (${err.message})`;
+  }
+  return scope;
+}
+
+const real = (p) => { try { return realpathSync(p); } catch { return ''; } };
+
+/**
+ * The user-scope settings file of a tab. The default account: the one in
+ * <home>/.claude. A tab under a named Claude account (`accountHome`, its config
+ * directory) reads that account's settings.json, which SynaBun links to the
+ * default account's file unless the account was given its own.
+ *   path      what the CLI of that account reads
+ *   writePath the real file behind it, so a removal lands where the rule is read
+ *             from and a link stays a link; '' when the link leads to a file
+ *             SynaBun does not manage (never written through)
+ *   shared    it is the default account's file: a change shows in both
+ *   own       a file of its own, or none yet
+ */
+export function userSettingsFile({ home, accountHome = '' } = {}) {
+  const defaultPath = home ? join(home, '.claude', 'settings.json') : '';
+  if (!accountHome) return { path: defaultPath, writePath: defaultPath, shared: false, own: true };
+  const path = join(accountHome, 'settings.json');
+  const target = real(path);
+  if (!target) return { path, writePath: existsSync(path) ? '' : path, shared: false, own: true };
+  const base = real(accountHome);
+  if (base && (target === join(base, 'settings.json') || target.startsWith(base + sep))) return { path, writePath: target, shared: false, own: true };
+  if (defaultPath && target === real(defaultPath)) return { path, writePath: target, shared: true, own: false };
+  return { path, writePath: '', shared: false, own: false };
+}
+
+/**
+ * @param o.home        the user's home directory
+ * @param o.accountHome the config directory of the tab's Claude account ('' = the default account)
+ * @param o.project     the project directory, or '' for user scope only
+ * @returns {{ user: object, project: object|null, local: object|null }}
+ */
+export function readPermissionRules({ home, accountHome = '', project = '' } = {}) {
+  const file = userSettingsFile({ home, accountHome });
+  const user = readScope(file.path);
+  // A named account: say whose file this is, and whether Remove can edit it.
+  if (accountHome) { user.shared = file.shared; user.editable = !!file.writePath; }
+  return {
+    user,
+    project: project ? readScope(join(project, '.claude', 'settings.json'), project) : null,
+    local: project ? readScope(join(project, '.claude', 'settings.local.json'), project) : null,
+  };
+}
+
+const SCOPE_FILES = { user: (home) => join(home, '.claude', 'settings.json'), project: (_, project) => join(project, '.claude', 'settings.json'), local: (_, project) => join(project, '.claude', 'settings.local.json') };
+const RULE_LISTS = ['allow', 'ask', 'deny', 'additionalDirectories'];
+
+export class PermissionRuleError extends Error {
+  constructor(status, message) { super(message); this.status = status; }
+}
+
+/**
+ * Remove one rule (an exact string) from one list of one settings file.
+ * @param o.scope 'user' | 'project' | 'local'
+ * @param o.list  'allow' | 'ask' | 'deny' | 'additionalDirectories'
+ * @returns {{ removed: boolean, path: string }}
+ */
+export function removePermissionRule({ home, accountHome = '', project = '', scope, list, rule } = {}) {
+  if (!SCOPE_FILES[scope]) throw new PermissionRuleError(400, 'Unknown settings scope');
+  if (!RULE_LISTS.includes(list)) throw new PermissionRuleError(400, 'Unknown rule list');
+  if (typeof rule !== 'string' || !rule || rule.length > 2000) throw new PermissionRuleError(400, 'A rule is required');
+  if (scope === 'user' ? !(home || accountHome) : !project) throw new PermissionRuleError(400, scope === 'user' ? 'No home directory' : 'A registered project is required');
+  // The user scope of a tab under a named account is that account's file.
+  let path = SCOPE_FILES[scope](home, project);
+  if (scope === 'user' && accountHome) {
+    path = userSettingsFile({ home, accountHome }).writePath;
+    if (!path) throw new PermissionRuleError(409, "This account's settings file is a link to a file SynaBun does not manage. Remove the rule there by hand.");
+  }
+  if (!existsSync(path)) return { removed: false, path };
+  // The file that is rewritten. The user's own settings may be a link
+  // (dotfiles): the file behind it is edited and the link stays. A project's
+  // files arrive with its repository: its `.claude` folder must really be in
+  // the project and the settings file must be a file, not a link, or nothing
+  // is written (a link there could point the write anywhere).
+  let target;
+  if (scope === 'user') target = real(path) || path;
+  else {
+    try { target = join(canonicalInside(project, dirname(path)), basename(path)); }
+    catch { throw new PermissionRuleError(409, "This project's .claude folder is a link that leads out of the project. Remove the rule there by hand."); }
+  }
+  let before;
+  try { before = lstatSync(target); } catch { return { removed: false, path }; }
+  if (before.isSymbolicLink() || !before.isFile()) throw new PermissionRuleError(409, 'That settings file is a link or not a regular file. Remove the rule there by hand.');
+  let settings;
+  try { settings = JSON.parse(readConfinedFile(dirname(target), target, { maxBytes: MAX_SETTINGS_BYTES, encoding: 'utf-8' })); }
+  catch (err) { throw new PermissionRuleError(409, `The settings file could not be read (${err.message}). Fix it by hand first.`); }
+  const current = settings?.permissions?.[list];
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings) || !Array.isArray(current) || !current.includes(rule)) return { removed: false, path };
+  settings.permissions[list] = current.filter(x => x !== rule);
+  // Written through a temporary file nobody can name in advance, created
+  // exclusively next to the settings file and never through a link, then
+  // renamed over it. A file that changed since it was read is left alone.
+  try { replaceFileAtomic(target, `${JSON.stringify(settings, null, 2)}\n`, { mode: before.mode & 0o777, expect: before }); }
+  catch (err) { throw new PermissionRuleError(err?.status === 409 ? 409 : 500, err?.status === 409 ? 'The settings file changed while the rule was being removed. Nothing was written; try again.' : `The settings file could not be written (${err?.message || err}).`); }
+  return { removed: true, path };
+}

package/neural-interface/lib/claude-session-cleanup.js

@@ -0,0 +1,71 @@
+// ── What SynaBun itself keeps about a Claude Code session ──
+// deleteSession (the Agent SDK) removes the transcript. SynaBun holds four more
+// records keyed by the same id: the per-session cost row, the indexed chunks,
+// the session list / search cache, and the panel's rendered snapshot. A deleted
+// session must not leave them behind. The host passes one function per record
+// (server.js owns the stores); a step that fails is reported and never stops
+// the others, and none of them can undo the delete that already happened.
+
+import { isSessionId } from './path-confine.js';
+
+/**
+ * @param o.steps { name: (sessionId) => any } one function per record to drop
+ * @param o.log   (message) => void
+ * @returns (sessionId) => { name: 'ok' | 'failed: …' }
+ */
+export function createSessionCleanup({ steps = {}, log = () => {} } = {}) {
+  const entries = Object.entries(steps).filter(([, fn]) => typeof fn === 'function');
+  return function cleanupSession(sessionId) {
+    const report = {};
+    if (!isSessionId(sessionId)) return report;
+    for (const [name, fn] of entries) {
+      try { fn(sessionId); report[name] = 'ok'; }
+      catch (err) {
+        report[name] = `failed: ${err?.message || err}`;
+        try { log(`[claude-session] cleanup of ${name} for ${sessionId} failed: ${err?.message || err}`); } catch {}
+      }
+    }
+    return report;
+  };
+}
+
+/** The steps of a cleanup report that failed (their names), in order. */
+export function cleanupFailures(report) {
+  if (!report || typeof report !== 'object') return [];
+  return Object.entries(report).filter(([, v]) => typeof v === 'string' && v.startsWith('failed')).map(([k]) => k);
+}
+
+/** Drop the per-session cost row. The month's totals stay: the money was spent. */
+export function dropSessionCost(data, sessionId) {
+  if (!data?.sessionCosts || !(sessionId in data.sessionCosts)) return false;
+  delete data.sessionCosts[sessionId];
+  return true;
+}
+
+/**
+ * Drop the rows derived from one session in memory.db: its indexed chunks and
+ * its session list / search cache entries. Memories are never touched.
+ * A table that does not exist is nothing to drop (session_chunks belongs to the
+ * MCP server's schema: absent on a store that never indexed). Any other
+ * database error is thrown after every table was tried, with what was dropped
+ * in `partial`: rows left behind are a failed cleanup, not a clean one.
+ * @param db a node:sqlite database handle
+ */
+export function deleteSessionRows(db, sessionId, provider) {
+  const out = { chunks: 0, cache: 0, fts: 0 };
+  if (!isSessionId(sessionId)) return out;
+  const failures = [];
+  const drop = (key, table, sql, ...params) => {
+    try { out[key] = Number(db.prepare(sql).run(...params).changes) || 0; }
+    catch (err) {
+      const message = String(err?.message || err);
+      if (/no such table/i.test(message)) return;
+      failures.push(`${table}: ${message}`);
+    }
+  };
+  drop('chunks', 'session_chunks', 'DELETE FROM session_chunks WHERE session_id = ?', sessionId);
+  drop('fts', 'session_fts', 'DELETE FROM session_fts WHERE session_id = ? AND provider = ?', sessionId, provider);
+  drop('cache', 'session_cache', 'DELETE FROM session_cache WHERE session_id = ? AND provider = ?', sessionId, provider);
+  if (failures.length) throw Object.assign(new Error(failures.join('; ')), { partial: out });
+  return out;
+}

package/neural-interface/lib/claude-session-list.js

@@ -0,0 +1,82 @@
+// ── What the CLI knows about a session, over SynaBun's own session list ──
+// The session menu is built from SynaBun's transcript scan (message counts, the
+// "deleted" cache). It never read what the CLI itself keeps per session: the
+// title set with /rename or `renameSession`, the summary, the tag. The Agent
+// SDK's listSessions() does, from the head and tail of each file (measured on
+// 738 sessions / 1.1 GB: 0.5 s for all of a project, 0.1 s for a page).
+// This keeps one such list per project and serves it stale-while-revalidate:
+// the menu is polled, and a list that cannot be read must never break it.
+
+const text = (v, max) => (typeof v === 'string' ? v.trim().slice(0, max) : '');
+
+/**
+ * @param o.listSessions (opts) => Promise<SDKSessionInfo[]>  the SDK function (injected)
+ * @param o.ttlMs        how long a list is served before a refresh starts
+ * @param o.firstWaitMs  how long the first request for a project waits for its list
+ */
+export function createSessionListOverlay({ listSessions, ttlMs = 30_000, firstWaitMs = 1500, now = Date.now, log = () => {} } = {}) {
+  const cache = new Map(); // dir → { at, map, pending }
+  const EMPTY = new Map();
+
+  function refresh(dir) {
+    const entry = cache.get(dir) || { at: 0, map: null, pending: null };
+    if (entry.pending) return entry.pending;
+    entry.pending = Promise.resolve()
+      .then(() => listSessions({ dir }))
+      .then((rows) => {
+        const map = new Map();
+        for (const r of Array.isArray(rows) ? rows : []) {
+          if (!r || typeof r.sessionId !== 'string') continue;
+          map.set(r.sessionId, {
+            title: text(r.customTitle, 200),
+            summary: text(r.summary, 200),
+            tag: text(r.tag, 60),
+            createdAt: Number.isFinite(r.createdAt) ? r.createdAt : null,
+          });
+        }
+        entry.map = map;
+        entry.at = now();
+        return map;
+      })
+      .catch((err) => { try { log(`[claude-sessions] listSessions failed for ${dir}: ${err?.message || err}`); } catch {} return entry.map || EMPTY; })
+      .finally(() => { entry.pending = null; });
+    cache.set(dir, entry);
+    return entry.pending;
+  }
+
+  return {
+    /** sessionId → { title, summary, tag, createdAt } for one project directory. Never rejects. */
+    async forProject(dir) {
+      if (!dir || typeof listSessions !== 'function') return EMPTY;
+      const entry = cache.get(dir);
+      if (entry?.map) {
+        if (now() - entry.at > ttlMs) refresh(dir); // serve what is there, refresh behind it
+        return entry.map;
+      }
+      // Nothing yet: wait a moment for the first list, then go on without it.
+      let timer;
+      const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(EMPTY), firstWaitMs); timer.unref?.(); });
+      try { return await Promise.race([refresh(dir), timeout]); } finally { clearTimeout(timer); }
+    },
+    /** A title or a tag changed, a session was deleted or forked: read again on the next request. */
+    invalidate(dir) {
+      if (dir) { const e = cache.get(dir); if (e) e.at = 0; return; }
+      for (const e of cache.values()) e.at = 0;
+    },
+  };
+}
+
+/** The entries of SynaBun's own list with the CLI's title, summary and tag added. */
+export function overlaySessions(entries, meta) {
+  return (Array.isArray(entries) ? entries : []).map((e) => {
+    const m = meta?.get?.(e.sessionId);
+    return m ? { ...e, title: m.title || '', summary: m.summary || '', tag: m.tag || '' } : e;
+  });
+}
+
+/** Does a session match the menu's search text or tag filter, counting the CLI's title and tag? */
+export function matchesSessionFilter(entry, { search = '', tag = '' } = {}) {
+  if (tag && (entry.tag || '') !== tag) return false;
+  if (!search) return true;
+  return [entry.firstPrompt, entry.gitBranch, entry.sessionId, entry.title, entry.tag].some(v => String(v || '').toLowerCase().includes(search));
+}