synabun 2.0.10 → 2.2.0

package/neural-interface/lib/antigravity/catalog.js

@@ -0,0 +1,273 @@
+// ═══════════════════════════════════════════
+// SynaBun — Antigravity's models and past sessions, asked of the CLI itself
+// ═══════════════════════════════════════════
+//
+// Models: what an ACP session offers, because SynaBun drives every Antigravity brain, run and panel
+// over ACP. agy 1.4.12's ACP sessions offer a model option of base models (gemini-4-argon,
+// gemini-3.8-flash) and a thinking-level option (low / medium / high), and list each pair as one
+// id (`models.availableModels`: gemini-4-argon-high …). `agy models` lists more (Claude and GPT-OSS
+// models its own TUI runs), which ACP refuses ("Unknown model ID"), and it has no
+// `--output-format` in 1.4.12. So the list is read from a short-lived `agy acp` in a throwaway
+// home (lib/antigravity/home.js; the sign-in is the keychain's, nothing of the user's changes),
+// and `agy models` (text, or JSON from a later agy) is only the fallback of an agy without ACP.
+// Nothing here names a model of its own: what Antigravity offers is the list.
+//
+// Sessions: ACP session/list on a short-lived `agy acp` (lib/antigravity/acp-connection.js),
+// page by page, grouped under SynaBun's registered projects for the Resume window.
+// Both answer `{ ..., error, authRequired }` instead of throwing: a CLI that is
+// missing, signed out or slow is a state the page shows.
+
+import { spawn as nodeSpawn } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve, sep } from 'node:path';
+import { acpErrorInfo, createAcpConnection, isAuthRequired, redactSecrets } from './acp-connection.js';
+
+const MODELS_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT = 2 * 1024 * 1024;
+/** Antigravity's thinking levels, lowest first (`--effort` takes low … max; ACP sessions offer what each model has). */
+export const ANTIGRAVITY_THINKING_LEVELS = Object.freeze(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+const LEVEL_SUFFIX = new RegExp(`^(.+)-(${ANTIGRAVITY_THINKING_LEVELS.join('|')})$`);
+
+/**
+ * An Antigravity model id as its base model and thinking level: "gemini-4-argon-high" → { model: 'gemini-4-argon',
+ * effort: 'high' }. `known` (base ids, optional): the split is made only when the base is one of them. An id
+ * without a level suffix is its own base ({ model, effort: null }).
+ */
+export function splitAntigravityModel(id, known = null) {
+  const text = String(id || '').trim();
+  const match = LEVEL_SUFFIX.exec(text);
+  if (!match) return { model: text || null, effort: null };
+  const list = known instanceof Set ? known : Array.isArray(known) ? new Set(known) : null;
+  if (list && !list.has(match[1]) && list.has(text)) return { model: text, effort: null };
+  if (list && !list.has(match[1])) return { model: text, effort: null };
+  return { model: match[1], effort: match[2] };
+}
+
+/**
+ * The models an ACP session offers ({ models, configOptions } of session/new or session/resume):
+ * [{ id, label, efforts, default? }], one row per base model, its thinking levels from the session's own
+ * model × level ids (else the level option's values). [] when the session lists none.
+ */
+export function antigravitySessionModels(session) {
+  const options = Array.isArray(session?.configOptions) ? session.configOptions : [];
+  const modelOption = options.find((option) => option?.category === 'model' || option?.id === 'model');
+  const levelOption = options.find((option) => option?.category === 'thought_level' || option?.id === 'thought_level');
+  const flat = (option) => {
+    const out = [];
+    for (const entry of Array.isArray(option?.options) ? option.options : []) {
+      for (const value of Array.isArray(entry?.options) ? entry.options : [entry]) {
+        if (value && value.value !== undefined && value.value !== null) out.push({ value: String(value.value), name: typeof value.name === 'string' ? value.name : String(value.value), description: typeof value.description === 'string' ? value.description : '' });
+      }
+    }
+    return out;
+  };
+  const levels = flat(levelOption).map((entry) => entry.value);
+  const available = Array.isArray(session?.models?.availableModels) ? session.models.availableModels : [];
+  const bases = flat(modelOption);
+  const known = new Set(bases.map((entry) => entry.value));
+  // A session without a model option still names its model × level pairs: their bases are the models.
+  if (!bases.length) {
+    for (const row of available) {
+      const { model } = splitAntigravityModel(row?.modelId);
+      if (model && !known.has(model)) { known.add(model); bases.push({ value: model, name: String(row?.name || model).replace(/\s*\([^)]*\)\s*$/, ''), description: '' }); }
+    }
+  }
+  const efforts = new Map();
+  for (const row of available) {
+    const { model, effort } = splitAntigravityModel(row?.modelId, known);
+    if (model && effort) { if (!efforts.has(model)) efforts.set(model, []); efforts.get(model).push(effort); }
+  }
+  const current = modelOption?.currentValue !== undefined ? String(modelOption.currentValue) : splitAntigravityModel(session?.models?.currentModelId, known).model;
+  const order = (list) => [...new Set(list)].sort((a, b) => ANTIGRAVITY_THINKING_LEVELS.indexOf(a) - ANTIGRAVITY_THINKING_LEVELS.indexOf(b));
+  return bases.map((entry) => {
+    const row = { id: entry.value, label: entry.name || entry.value };
+    if (entry.description) row.description = entry.description;
+    const own = efforts.get(entry.value);
+    const list = own?.length ? order(own) : (entry.value === current && levels.length ? order(levels) : []);
+    if (list.length) row.efforts = list;
+    if (entry.value === current) row.default = true;
+    return row;
+  });
+}
+
+/** Rows from `agy models` text output: one `<id>\t<label>` line per model (status lines without a tab are skipped). */
+export function parseAntigravityModelLines(text) {
+  const rows = [];
+  const seen = new Set();
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const [id, ...rest] = line.split('\t');
+    const key = String(id || '').trim();
+    if (!key || !rest.length || seen.has(key) || /\s/.test(key)) continue;
+    seen.add(key);
+    rows.push({ id: key, label: rest.join('\t').trim() || key });
+  }
+  return rows;
+}
+
+const pick = (row, keys) => {
+  for (const key of keys) {
+    const value = row?.[key];
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return '';
+};
+
+/** Rows from a JSON model list (a later agy's `agy models`, a stand-in): [{ id, label, description?, default? }] (never throws). */
+export function parseAntigravityModels(text) {
+  let data;
+  try { data = JSON.parse(String(text || '').trim()); } catch { return []; }
+  const list = Array.isArray(data) ? data
+    : Array.isArray(data?.models) ? data.models
+      : Array.isArray(data?.availableModels) ? data.availableModels
+        : Array.isArray(data?.data) ? data.data : [];
+  const rows = [];
+  const seen = new Set();
+  for (const entry of list) {
+    if (typeof entry === 'string') {
+      if (entry.trim() && !seen.has(entry.trim())) { seen.add(entry.trim()); rows.push({ id: entry.trim(), label: entry.trim() }); }
+      continue;
+    }
+    if (!entry || typeof entry !== 'object') continue;
+    const id = pick(entry, ['id', 'model_id', 'modelId', 'slug', 'model', 'value', 'name']);
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    const row = { id, label: pick(entry, ['display_name', 'displayName', 'label', 'name']) || id };
+    const description = pick(entry, ['description', 'tagline', 'summary']);
+    if (description) row.description = description;
+    if (entry.is_default === true || entry.isDefault === true || entry.default === true || entry.selected === true || entry.current === true) row.default = true;
+    const efforts = Array.isArray(entry.efforts) ? entry.efforts : Array.isArray(entry.thinking_levels) ? entry.thinking_levels : Array.isArray(entry.effort_levels) ? entry.effort_levels : null;
+    if (efforts) row.efforts = efforts.map((e) => (typeof e === 'string' ? e : e?.id || e?.value || e?.name)).filter((e) => typeof e === 'string' && e);
+    rows.push(row);
+  }
+  return rows;
+}
+
+/**
+ * The models Antigravity offers SynaBun: those of an ACP session in a throwaway home (antigravitySessionModels),
+ * else (an agy without ACP) `agy models`. `launch`: { command, args } of the CLI (null: not installed).
+ * Answers { models, source: 'live' | 'unavailable', via: 'acp' | 'cli', error?, authRequired? }.
+ */
+export async function listAntigravityModels({ launch, env = process.env, spawnImpl = nodeSpawn, connect = createAcpConnection, timeoutMs = MODELS_TIMEOUT_MS, tempRoot = tmpdir() } = {}) {
+  if (!launch?.command) return { models: [], source: 'unavailable', error: 'The Antigravity CLI (agy) is not installed.', cliMissing: true };
+  let scratch = null;
+  let conn = null;
+  let acpError = null;
+  try {
+    scratch = mkdtempSync(join(tempRoot, 'synabun-agy-models-'));
+    conn = connect({ command: launch.command, args: launch.args || [], acpArgs: ['--gemini-dir', scratch], env, cwd: scratch, spawnImpl, clientInfo: { name: 'synabun', title: 'SynaBun', version: '0' } });
+    await conn.initialize();
+    const session = await conn.request('session/new', { cwd: scratch, mcpServers: [] }, { timeoutMs });
+    const models = antigravitySessionModels(session);
+    // The plan the sign-in is on, as the session says it (_meta.antigravity.tier: "Google AI Pro" …).
+    const tier = typeof session?._meta?.antigravity?.tier?.name === 'string' ? session._meta.antigravity.tier.name : null;
+    try { if (session?.sessionId) await conn.request('session/close', { sessionId: session.sessionId }, { timeoutMs: 5_000 }); } catch { /* the home goes anyway */ }
+    if (models.length) return { models, source: 'live', via: 'acp', signedIn: true, tier };
+    acpError = { message: 'The Antigravity session offered no models.' };
+  } catch (error) {
+    if (isAuthRequired(error)) return { models: [], source: 'unavailable', error: 'Antigravity is not signed in.', authRequired: true, signedIn: false };
+    acpError = acpErrorInfo(error);
+  } finally {
+    try { await conn?.close(); } catch { /* gone */ }
+    if (scratch) { try { rmSync(scratch, { recursive: true, force: true }); } catch { /* the temp folder's own cleanup */ } }
+  }
+  const viaCli = await listAntigravityCliModels({ launch, env, spawnImpl, timeoutMs });
+  if (viaCli.models.length) return viaCli;
+  return { ...viaCli, error: viaCli.error || acpError?.message || 'Antigravity listed no models.' };
+}
+
+/**
+ * `agy models` (its text lines; JSON from an agy that prints JSON): the fallback of an agy whose ACP session
+ * could not list models. Answers { models, source, via: 'cli', error?, authRequired? }.
+ */
+export function listAntigravityCliModels({ launch, env = process.env, spawnImpl = nodeSpawn, timeoutMs = MODELS_TIMEOUT_MS } = {}) {
+  if (!launch?.command) return Promise.resolve({ models: [], source: 'unavailable', via: 'cli', error: 'The Antigravity CLI (agy) is not installed.', cliMissing: true });
+  return new Promise((resolveResult) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let child;
+    const finish = (result) => { if (!settled) { settled = true; clearTimeout(timer); resolveResult(result); } };
+    try {
+      child = spawnImpl(launch.command, [...(launch.args || []), 'models'], { env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    } catch (error) {
+      resolveResult({ models: [], source: 'unavailable', via: 'cli', error: redactSecrets(error?.message || String(error)) });
+      return;
+    }
+    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } finish({ models: [], source: 'unavailable', via: 'cli', error: `agy models did not answer within ${Math.round(timeoutMs / 1000)} s.` }); }, timeoutMs);
+    timer.unref?.();
+    child.stdout?.on('data', (chunk) => { if (stdout.length < MAX_OUTPUT) stdout += chunk; });
+    child.stderr?.on('data', (chunk) => { if (stderr.length < 16_384) stderr += chunk; });
+    child.on('error', (error) => finish({ models: [], source: 'unavailable', via: 'cli', error: redactSecrets(error?.message || String(error)) }));
+    child.on('close', (code) => {
+      // A later agy may print JSON; 1.4.12 prints `<id>\t<label>` lines after a status line.
+      const json = parseAntigravityModels(stdout);
+      const models = json.length ? json : parseAntigravityModelLines(stdout);
+      if (models.length) { finish({ models, source: 'live', via: 'cli' }); return; }
+      const said = redactSecrets((stderr || stdout).trim()).split('\n').filter(Boolean).slice(-3).join(' ');
+      const authRequired = /sign in|log in|authenticat/i.test(said);
+      finish({ models: [], source: 'unavailable', via: 'cli', error: said || `agy models exited with code ${code}.`, ...(authRequired ? { authRequired: true } : {}) });
+    });
+  });
+}
+
+/**
+ * Every session ACP's session/list reports (all pages, up to `maxSessions`), through a short-lived `agy acp`.
+ * Answers { sessions: [{ sessionId, cwd, title, updatedAt }], error?, authRequired? }.
+ */
+export async function listAntigravitySessions({ launch, env = process.env, connect = createAcpConnection, maxSessions = 500, cwd } = {}) {
+  if (!launch?.command) return { sessions: [], error: 'The Antigravity CLI (agy) is not installed.', cliMissing: true };
+  const conn = connect({ command: launch.command, args: launch.args || [], env, cwd, clientInfo: { name: 'synabun', title: 'SynaBun', version: '0' } });
+  const sessions = [];
+  try {
+    await conn.initialize();
+    let cursor = null;
+    for (let page = 0; page < 50 && sessions.length < maxSessions; page++) {
+      const answer = await conn.request('session/list', cursor ? { cursor } : {}, { timeoutMs: 20_000 });
+      for (const row of Array.isArray(answer?.sessions) ? answer.sessions : []) {
+        if (row && typeof row.sessionId === 'string') sessions.push({ sessionId: row.sessionId, cwd: typeof row.cwd === 'string' ? row.cwd : '', title: typeof row.title === 'string' ? row.title : '', updatedAt: typeof row.updatedAt === 'string' ? row.updatedAt : null });
+      }
+      cursor = typeof answer?.nextCursor === 'string' && answer.nextCursor ? answer.nextCursor : null;
+      if (!cursor) break;
+    }
+    return { sessions: sessions.slice(0, maxSessions) };
+  } catch (error) {
+    return { sessions, error: acpErrorInfo(error).message, ...(isAuthRequired(error) ? { authRequired: true } : {}) };
+  } finally {
+    conn.close();
+  }
+}
+
+/** The Resume window's shape: one entry per registered project, its sessions newest first, searched and paged. */
+export function groupSessionsByProject(sessions, projects, { targetProject = null, search = '', offset = 0, limit = 30 } = {}) {
+  const roots = (Array.isArray(projects) ? projects : []).map((project) => ({ project, root: resolve(project.path) }))
+    // The deepest project wins a session that sits in a nested one.
+    .sort((a, b) => b.root.length - a.root.length);
+  const byRoot = new Map(roots.map(({ root }) => [root, []]));
+  for (const session of Array.isArray(sessions) ? sessions : []) {
+    if (!session?.cwd) continue;
+    const dir = resolve(session.cwd);
+    const owner = roots.find(({ root }) => dir === root || dir.startsWith(root + sep));
+    if (!owner) continue;
+    byRoot.get(owner.root).push({
+      sessionId: session.sessionId,
+      firstPrompt: session.title || '',
+      messageCount: null,
+      created: null,
+      modified: session.updatedAt || null,
+      gitBranch: null,
+      cwd: session.cwd,
+    });
+  }
+  const needle = String(search || '').toLowerCase().trim();
+  const result = [];
+  for (const project of Array.isArray(projects) ? projects : []) {
+    const root = resolve(project.path);
+    if (targetProject && root !== resolve(targetProject)) continue;
+    let entries = byRoot.get(root) || [];
+    entries.sort((a, b) => (Date.parse(b.modified || 0) || 0) - (Date.parse(a.modified || 0) || 0));
+    if (needle) entries = entries.filter((e) => e.firstPrompt.toLowerCase().includes(needle) || e.sessionId.toLowerCase().includes(needle));
+    result.push({ path: project.path, label: project.label || basename(project.path), total: entries.length, sessions: entries.slice(offset, offset + limit) });
+  }
+  return result;
+}

package/neural-interface/lib/antigravity/home.js

@@ -0,0 +1,260 @@
+import { acpReadOnlyKind, acpToolPaths } from './tool-call.js';
+// ═══════════════════════════════════════════
+// SynaBun — Antigravity homes: the Antigravity folder of each Assistant brain and each run
+// ═══════════════════════════════════════════
+//
+// `agy acp --gemini-dir <dir>` reads everything that shapes a session from <dir> instead of
+// ~/.gemini: its MCP servers (config/mcp_config.json), its hooks (config/hooks.json), its global
+// rules (config/GEMINI.md), extra skill folders (config/skills.json) and its settings
+// (antigravity-cli/settings.json: tool permissions, permission rules); its conversations are kept
+// there too (antigravity-cli/conversations). The sign-in is not: agy keeps its token in the
+// system keychain, which every gemini dir shares, so a SynaBun home never signs in or out.
+// Measured on agy 1.4.12 (docs/antigravity-sidepanel.md → Assistant).
+//
+// So each brain and each run SynaBun starts gets a home of its own, written before agy starts:
+//   - exactly the MCP servers the run may use (SynaBun's own entry, then the external servers its
+//     tool list names, copied from the user's ~/.gemini/config/mcp_config.json); project MCP config
+//     loads separately, so managed starts refuse enabled project servers before starting agy;
+//   - one PreToolUse hook (lib/antigravity/policy-hook.mjs) that asks SynaBun about every call
+//     before it runs (route gate, browser policy, worker confinement, MCP scope): a refusal reaches
+//     the model with its reason and the turn goes on;
+//   - settings that ask before writes, commands, MCP and the web (toolPermission request-review) and
+//     deny Antigravity's own web reading and browser (read_url, execute_url) outright, plus the
+//     user's own sign-in related keys (Gemini API key mode, Google Cloud project, AI credits);
+//   - the user's global rules (a copy of ~/.gemini/config/GEMINI.md, SynaBun's block included) and
+//     skills (~/.gemini/config/skills through skills.json).
+// Plugins of the user's are not loaded (they can bring MCP servers and hooks of their own).
+// A home is kept while its brain or run may resume; pruneAntigravityHomes removes the rest.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+
+/** The settings keys of the user's own Antigravity settings a SynaBun home keeps: how they sign in and which models they get. */
+export const KEPT_USER_SETTINGS = Object.freeze(['modelProvider', 'customModelsConfig', 'gcp', 'useG1Credits']);
+/** Antigravity's own web reading and browser: denied in every SynaBun home (the SynaBun browser policy). */
+export const SYNABUN_HOME_DENY = Object.freeze(['read_url_content(*)', 'execute_url(*)']);
+/** The hook's time limit, in seconds (Antigravity's default is 30). */
+export const POLICY_HOOK_TIMEOUT_S = 20;
+
+const HOME_KINDS = new Set(['brain', 'run', 'models']);
+
+/** Where SynaBun's Antigravity homes live: <data home>/runtime/antigravity/homes (outside data/, which is backed up). */
+export function antigravityHomesRoot(dataHome) {
+  return resolve(String(dataHome || join(homedir(), '.synabun')), 'runtime', 'antigravity', 'homes');
+}
+
+/** The home of one brain ('brain', its Assistant session id) or run ('run', its run id): a stable folder name per id. */
+export function antigravityHomeDir(root, kind, id) {
+  if (!HOME_KINDS.has(kind)) throw new Error(`Unknown Antigravity home kind ${kind}`);
+  const raw = String(id || '');
+  if (!raw) throw new Error('An Antigravity home needs an id');
+  const readable = raw.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 48);
+  const digest = createHash('sha256').update(raw).digest('hex').slice(0, 10);
+  return join(resolve(root), `${kind}-${readable}-${digest}`);
+}
+
+/** The user's own gemini dir (what agy reads without --gemini-dir). */
+export function userGeminiDir(home = homedir()) {
+  return join(home, '.gemini');
+}
+
+function readJson(path) {
+  try {
+    const text = readFileSync(path, 'utf8').replace(/^\uFEFF/, '');
+    if (!text.trim()) return {};
+    const value = JSON.parse(text);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch { return {}; }
+}
+
+function writePrivate(path, text) {
+  writeFileSync(path, text, { encoding: 'utf8', mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch { /* a filesystem without modes */ }
+}
+
+function ensurePrivateDir(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  try { chmodSync(path, 0o700); } catch { /* a filesystem without modes */ }
+}
+
+/** The MCP servers of the user's own Antigravity configuration ({ name: entry }), read loosely ({} when there is none). */
+export function userAntigravityMcpServers(geminiDir = userGeminiDir()) {
+  const config = readJson(join(geminiDir, 'config', 'mcp_config.json'));
+  const servers = config.mcpServers && typeof config.mcpServers === 'object' && !Array.isArray(config.mcpServers) ? config.mcpServers : {};
+  const out = {};
+  for (const [name, entry] of Object.entries(servers)) if (entry && typeof entry === 'object' && !Array.isArray(entry)) out[name] = entry;
+  return out;
+}
+
+/** The user's own Antigravity settings (~/.gemini/antigravity-cli/settings.json), read loosely ({} when there are none). */
+export function userAntigravitySettings(geminiDir = userGeminiDir()) {
+  return readJson(join(geminiDir, 'antigravity-cli', 'settings.json'));
+}
+
+/**
+ * An MCP server definition as mcp_config.json holds it: a remote server `{ serverUrl, headers }`, a local one
+ * `{ command, args, env }` (the inventory of lib/mcp-external-servers.js names a remote address `url`).
+ */
+export function toAntigravityMcpEntry(definition) {
+  const source = definition && typeof definition === 'object' ? definition : {};
+  const url = typeof source.serverUrl === 'string' && source.serverUrl ? source.serverUrl : (typeof source.url === 'string' ? source.url : '');
+  if (url) {
+    const entry = { serverUrl: url };
+    if (source.headers && typeof source.headers === 'object' && Object.keys(source.headers).length) entry.headers = { ...source.headers };
+    return entry;
+  }
+  const entry = { command: typeof source.command === 'string' ? source.command : '' };
+  if (Array.isArray(source.args) && source.args.length) entry.args = source.args.map(String);
+  if (source.env && typeof source.env === 'object' && Object.keys(source.env).length) entry.env = { ...source.env };
+  if (typeof source.cwd === 'string' && source.cwd) entry.cwd = source.cwd;
+  return entry;
+}
+
+/**
+ * The settings of a SynaBun home: `toolPermission` (request-review asks before writes, commands, MCP and the
+ * web; Antigravity's own default), SynaBun's deny rules plus `deny`, and the user's own KEPT_USER_SETTINGS.
+ */
+export function antigravityHomeSettings({ userSettings = {}, toolPermission = 'request-review', deny = [], allow = [] } = {}) {
+  const out = {};
+  for (const key of KEPT_USER_SETTINGS) if (userSettings[key] !== undefined) out[key] = userSettings[key];
+  out.toolPermission = toolPermission;
+  const denyRules = [...new Set([...SYNABUN_HOME_DENY, ...(Array.isArray(deny) ? deny : [])].filter((rule) => typeof rule === 'string' && rule))];
+  const allowRules = [...new Set((Array.isArray(allow) ? allow : []).filter((rule) => typeof rule === 'string' && rule))];
+  out.permissions = { deny: denyRules, ...(allowRules.length ? { allow: allowRules } : {}) };
+  return out;
+}
+
+/** The hooks.json of a SynaBun home: one PreToolUse hook for every tool, the command `hookCommand`. */
+export function antigravityHomeHooks(hookCommand, { timeoutSec = POLICY_HOOK_TIMEOUT_S } = {}) {
+  return { 'synabun-policy': { PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: hookCommand, timeout: timeoutSec }] }] } };
+}
+
+/** A shell word for the hook command line (sh -c on Unix, cmd /c on Windows): double quotes, inner ones escaped. */
+export function shellWord(value) {
+  const text = String(value ?? '');
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(text)) return text;
+  return `"${text.replace(/(["\\$`])/g, '\\$1')}"`;
+}
+
+/** The command line that runs the policy hook: Node, the hook script. */
+export function policyHookCommand({ node = process.execPath, script } = {}) {
+  if (!script) throw new Error('The policy hook needs its script');
+  return `${shellWord(node)} ${shellWord(script)}`;
+}
+
+/**
+ * Write (or rewrite) a home before agy starts. `mcpServers`: { name: entry } exactly as mcp_config.json holds
+ * them; `hookCommand`: the policy hook's command line (null: no hook, which only a test does); `settings`:
+ * antigravityHomeSettings(); `userGemini`: the user's gemini dir (rules and skills come from there).
+ * → { dir, configDir, appDir }. Conversations already in the home are kept (a resume needs them).
+ */
+export function prepareAntigravityHome({ dir, mcpServers = {}, hookCommand = null, settings = null, userGemini = userGeminiDir(), rules = true, skills = true } = {}) {
+  if (!dir) throw new Error('prepareAntigravityHome needs a dir');
+  const configDir = join(dir, 'config');
+  const appDir = join(dir, 'antigravity-cli');
+  ensurePrivateDir(dir);
+  ensurePrivateDir(configDir);
+  ensurePrivateDir(appDir);
+  writePrivate(join(configDir, 'mcp_config.json'), `${JSON.stringify({ mcpServers }, null, 2)}\n`);
+  if (hookCommand) writePrivate(join(configDir, 'hooks.json'), `${JSON.stringify(antigravityHomeHooks(hookCommand), null, 2)}\n`);
+  else rmSync(join(configDir, 'hooks.json'), { force: true });
+  writePrivate(join(appDir, 'settings.json'), `${JSON.stringify(settings || antigravityHomeSettings({ userSettings: userAntigravitySettings(userGemini) }), null, 2)}\n`);
+  // The user's global rules (SynaBun's own block included), as they are now.
+  const rulesTarget = join(configDir, 'GEMINI.md');
+  const rulesSource = join(userGemini, 'config', 'GEMINI.md');
+  if (rules && existsSync(rulesSource)) {
+    try { writePrivate(rulesTarget, readFileSync(rulesSource, 'utf8')); } catch { rmSync(rulesTarget, { force: true }); }
+  } else rmSync(rulesTarget, { force: true });
+  // The user's skills folder, read in place (Skills Studio installs Antigravity skills there).
+  const skillsTarget = join(configDir, 'skills.json');
+  const skillsSource = join(userGemini, 'config', 'skills');
+  let hasSkills = false;
+  try { hasSkills = skills && statSync(skillsSource).isDirectory(); } catch { hasSkills = false; }
+  if (hasSkills) writePrivate(skillsTarget, `${JSON.stringify({ entries: [{ path: resolve(skillsSource) }] }, null, 2)}\n`);
+  else rmSync(skillsTarget, { force: true });
+  return { dir, configDir, appDir };
+}
+
+/** Whether a home holds Antigravity's record of a conversation (a resume needs it). */
+export function homeHasConversation(dir, sessionId) {
+  const id = String(sessionId || '');
+  if (!dir || !/^[A-Za-z0-9_-]{4,128}$/.test(id)) return false;
+  return existsSync(join(dir, 'antigravity-cli', 'conversations', `${id}.db`)) || existsSync(join(dir, 'antigravity-cli', 'brain', id));
+}
+
+/** Whether Antigravity has listed the tools of an MCP server in a home (it writes one schema file per tool once connected). */
+export function homeMcpTools(dir, server) {
+  try {
+    return readdirSync(join(dir, 'antigravity-cli', 'mcp', String(server)))
+      .filter((name) => name.endsWith('.json'))
+      .map((name) => name.slice(0, -5));
+  } catch { return []; }
+}
+
+/**
+ * Remove the homes under `root` nobody needs: older than `maxAgeMs` (by their last change) and not named in
+ * `keep` (folder names). Never a folder outside the root or one that is not a home. → the names removed.
+ */
+export function pruneAntigravityHomes(root, { keep = new Set(), maxAgeMs = 7 * 24 * 60 * 60_000, now = Date.now(), kinds = ['run', 'models'] } = {}) {
+  const removed = [];
+  let names = [];
+  try { names = readdirSync(root, { withFileTypes: true }).filter((item) => item.isDirectory()).map((item) => item.name); } catch { return removed; }
+  const keepSet = keep instanceof Set ? keep : new Set(keep || []);
+  for (const name of names) {
+    const kind = name.split('-')[0];
+    if (!kinds.includes(kind) || keepSet.has(name)) continue;
+    const path = join(root, name);
+    // Its last use: the folder, its MCP list (rewritten at every start) or its conversations, whichever is newest.
+    let changed = 0;
+    for (const part of ['', join('config', 'mcp_config.json'), join('antigravity-cli', 'conversations')]) {
+      try { changed = Math.max(changed, statSync(part ? join(path, part) : path).mtimeMs); } catch { /* not there */ }
+    }
+    if (!changed || now - changed < maxAgeMs) continue;
+    try { rmSync(path, { recursive: true, force: true }); removed.push(name); } catch { /* left for the next pass */ }
+  }
+  return removed;
+}
+
+/** Project MCP processes start before PreToolUse. Refuse them before any managed agent/session starts.
+ * Scan ancestors too, so a nested cwd cannot hide a project config. Even a named server could replace the
+ * trusted definition with an arbitrary command: managed sessions use only their prepared home definitions.
+ */
+export function assertSafeAntigravityProject(cwd) {
+  for (let dir = resolve(cwd || process.cwd()); ; dir = dirname(dir)) {
+    const file = join(dir, '.agents', 'mcp_config.json');
+    const unsafe = (reason) => Object.assign(new Error(`Antigravity did not start: ${file} ${reason}. Project MCP processes start before SynaBun's policy. Disable those project servers and use the session's configured MCP servers.`), { code: 'PROJECT_MCP_UNSAFE' });
+    let config;
+    try {
+      if (statSync(file).size > 1024 * 1024) throw unsafe('exceeds the configuration size limit');
+      config = JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, '') || '{}');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw unsafe('could not be safely read');
+    }
+    if (config !== undefined) {
+      if (!config || typeof config !== 'object' || Array.isArray(config)) throw unsafe('is not a valid configuration');
+      const servers = config.mcpServers;
+      if (servers !== undefined && (!servers || typeof servers !== 'object' || Array.isArray(servers))) throw unsafe('has an invalid server list');
+      if (Object.values(servers || {}).some((entry) => !entry || typeof entry !== 'object' || entry.disabled !== true)) throw unsafe('defines enabled MCP servers');
+    }
+    if (dirname(dir) === dir) break;
+  }
+}
+
+/** The only automatic reads in a managed home are MCP tool schemas. Config/settings copy credentials.
+ * null for a call outside the home; deny mixed reads so a safe schema cannot mask another file.
+ */
+export function antigravityHomeReadPolicy(call, { homeDir, cwd } = {}) {
+  if (!homeDir || !acpReadOnlyKind(call.kind)) return null;
+  const paths = acpToolPaths(call).map((raw) => {
+    const path = raw.trim();
+    if (path === '~' || path.startsWith('~/')) return resolve(homedir(), path.slice(2));
+    if (/^\$\{?HOME\}?(\/|$)/.test(path)) return resolve(homedir(), path.replace(/^\$\{?HOME\}?\/?/, ''));
+    return resolve(cwd || process.cwd(), path);
+  });
+  const inside = (path) => { const rel = relative(resolve(homeDir), path); return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)); };
+  if (!paths.some(inside)) return null;
+  if (paths.every((path) => inside(path) && /^antigravity-cli[\\/]mcp[\\/][^\\/]+[\\/][^\\/]+\.json$/.test(relative(resolve(homeDir), path)))) return { decision: 'allow' };
+  return { decision: 'deny', reason: 'SynaBun refuses reads of its Antigravity home configuration: it can contain MCP credentials and sign-in settings. Only tool schemas may be read here.' };
+}