synabun 2.0.0 → 2.0.7

package/neural-interface/lib/git-bash/resolver.js

@@ -0,0 +1,194 @@
+// ═══════════════════════════════════════════
+// SynaBun — Git Bash: which one Claude Code runs
+// ═══════════════════════════════════════════
+//
+// Claude Code on Windows looks for Git Bash itself, in this order (read from
+// its 2.1.302 build): CLAUDE_CODE_GIT_BASH_PATH when it names an existing
+// bash.exe / sh.exe (the `env` block of ~/.claude/settings.json is applied
+// before it looks, so a value there counts the same), then
+// C:\Program Files\Git\bin\bash.exe and C:\Program Files (x86)\Git\bin\bash.exe,
+// then the first `git` on its PATH, two folders up, bin\bash.exe. Without one,
+// its Bash tool is gone and every hook runs in PowerShell.
+//
+// resolveGitBash() answers which Git Bash a Claude Code started by SynaBun ends
+// up with, and whether SynaBun has to name it:
+//
+//   env / settings  CLAUDE_CODE_GIT_BASH_PATH of SynaBun's own environment, or
+//                   of the user's ~/.claude/settings.json: the user's choice,
+//                   which Claude Code reads by itself
+//   system          a Git Bash of the PC's own. When Claude Code finds it by
+//                   its own rules nothing is passed (SynaBun never overrides
+//                   what already works); one only SynaBun finds (git on PATH
+//                   in a layout Claude Code does not walk, a per-user or Scoop
+//                   install that is not on PATH) is passed to it
+//   bundled         SynaBun's copy inside an installed app (<resources>\git)
+//   downloaded      SynaBun's copy in the data home (a Windows npm install)
+//
+// A path inside SynaBun's own copies is never taken for the user's, whatever
+// variable or PATH entry leads to it (a server started from a SynaBun terminal
+// inherits both): it is found again as SynaBun's own, last. Every file system
+// question is injectable, so the Windows rules are tested from any system.
+
+import { statSync } from 'node:fs';
+import { win32 } from 'node:path';
+
+/** The variable Claude Code reads (and the settings `env` key SynaBun writes for the user's own CLI). */
+export const GIT_BASH_ENV = 'CLAUDE_CODE_GIT_BASH_PATH';
+
+/** The file names Claude Code accepts in CLAUDE_CODE_GIT_BASH_PATH. */
+const BASH_NAMES = new Set(['bash.exe', 'sh.exe', 'bash', 'sh']);
+
+/** Where Claude Code looks before PATH: these two, literally. */
+export const CLAUDE_FIXED_BASH = Object.freeze(['C:\\Program Files\\Git\\bin\\bash.exe', 'C:\\Program Files (x86)\\Git\\bin\\bash.exe']);
+
+const key = (path) => win32.normalize(String(path || '')).replace(/[\\/]+$/, '').toLowerCase();
+
+const defaultIsFile = (path) => { try { return statSync(path).isFile(); } catch { return false; } };
+
+/** Is `path` inside one of `roots` (or one of them)? Windows rules: case and slashes do not matter. */
+export function insideAny(path, roots) {
+  const at = key(path);
+  return roots.filter(Boolean).some((root) => { const top = key(root); return at === top || at.startsWith(`${top}\\`); });
+}
+
+/** A value of CLAUDE_CODE_GIT_BASH_PATH that Claude Code would take: a bash.exe / sh.exe that exists. */
+export function acceptableBashPath(value, { isFile = defaultIsFile } = {}) {
+  const path = String(value || '').trim();
+  if (!path || !BASH_NAMES.has(win32.basename(path).toLowerCase())) return false;
+  return isFile(path);
+}
+
+/** The PATH folders, in order, `%VARS%` of an unexpanded entry left as they are (they name no git either way). */
+function pathFolders(pathValue) {
+  return String(pathValue || '').split(';').map((entry) => entry.trim().replace(/^"(.*)"$/, '$1')).filter(Boolean);
+}
+
+/** The first git on `pathValue`, as Windows finds it (git.exe, then git.cmd), skipping SynaBun's own folders. */
+export function firstGitOnPath(pathValue, { isFile = defaultIsFile, own = [] } = {}) {
+  for (const folder of pathFolders(pathValue)) {
+    for (const name of ['git.exe', 'git.cmd']) {
+      const file = win32.join(folder, name);
+      if (!isFile(file)) continue;
+      if (insideAny(file, own)) continue;
+      return file;
+    }
+  }
+  return null;
+}
+
+/** The Git Bash a git found on PATH belongs to: Claude Code's own rule first (git\..\..\bin), then one more level up. */
+export function bashOfGit(gitFile, { isFile = defaultIsFile } = {}) {
+  if (!gitFile) return null;
+  const folder = win32.dirname(gitFile);
+  for (const candidate of [win32.join(folder, '..', 'bin', 'bash.exe'), win32.join(folder, '..', '..', 'bin', 'bash.exe')]) {
+    if (isFile(candidate)) return win32.normalize(candidate);
+  }
+  return null;
+}
+
+/** The folders Git for Windows is installed in when nothing names it: every installer's default, per machine and per user, and Scoop's. */
+export function standardGitRoots(env = {}) {
+  const roots = [];
+  const add = (base, ...rest) => { if (base) roots.push(win32.join(base, ...rest)); };
+  add(env.ProgramFiles || env.PROGRAMFILES, 'Git');
+  add(env.ProgramW6432, 'Git');
+  add(env['ProgramFiles(x86)'] || env['PROGRAMFILES(X86)'], 'Git');
+  roots.push('C:\\Program Files\\Git', 'C:\\Program Files (x86)\\Git');
+  add(env.LOCALAPPDATA, 'Programs', 'Git');
+  add(env.SCOOP, 'apps', 'git', 'current');
+  add(env.USERPROFILE, 'scoop', 'apps', 'git', 'current');
+  const seen = new Set();
+  return roots.filter((root) => { const id = key(root); if (seen.has(id)) return false; seen.add(id); return true; });
+}
+
+/**
+ * What Claude Code finds by itself, by its own rules, or null: its variable (from SynaBun's environment, then the
+ * user's settings), its two fixed places, the first git on PATH. `{ path, source }`.
+ */
+export function claudeCodeFinds({ env = {}, settingsValue = null, pathValue = '', isFile = defaultIsFile, own = [] } = {}) {
+  const fromEnv = env[GIT_BASH_ENV];
+  if (fromEnv && !insideAny(fromEnv, own) && acceptableBashPath(fromEnv, { isFile })) return { path: win32.normalize(fromEnv), source: 'env' };
+  if (settingsValue && !insideAny(settingsValue, own) && acceptableBashPath(settingsValue, { isFile })) return { path: win32.normalize(settingsValue), source: 'settings' };
+  for (const fixed of CLAUDE_FIXED_BASH) if (isFile(fixed)) return { path: fixed, source: 'system' };
+  const git = firstGitOnPath(pathValue, { isFile, own });
+  if (git) {
+    const bash = win32.normalize(win32.join(win32.dirname(git), '..', 'bin', 'bash.exe'));
+    if (isFile(bash) && !insideAny(bash, own)) return { path: bash, source: 'system' };
+  }
+  return null;
+}
+
+/** The cmd folder (with its git.exe) of the Git for Windows a bin\bash.exe belongs to, or null. */
+export function gitOfBash(bashPath, { isFile = defaultIsFile } = {}) {
+  if (!bashPath || win32.basename(win32.dirname(bashPath)).toLowerCase() !== 'bin') return null;
+  const root = win32.dirname(win32.dirname(bashPath));
+  const git = win32.join(root, 'cmd', 'git.exe');
+  return isFile(git) ? { git, cmdDir: win32.dirname(git) } : null;
+}
+
+/**
+ * Which Git Bash a Claude Code started by SynaBun ends up with, and what SynaBun has to give it.
+ *
+ * @param {object} o
+ * @param {string} [o.platform]
+ * @param {object} [o.env]            SynaBun's environment (CLAUDE_CODE_GIT_BASH_PATH, the folders above)
+ * @param {string|null} [o.settingsValue]  env.CLAUDE_CODE_GIT_BASH_PATH of the user's ~/.claude/settings.json
+ * @param {string} [o.pathValue]      the PATH a git is looked for on (this process's, then the OS PATH)
+ * @param {Array<{ source: 'bundled' | 'downloaded', root: string, ok: boolean, bash: string, git: string }>} [o.copies]
+ *                                    SynaBun's own copies, already checked (manager.js), in this order
+ * @param {string[]} [o.ownRoots]     SynaBun's own Git folders: nothing inside them is the user's
+ * @returns {{ supported: boolean, path: string|null, source: string|null, passToClaude: boolean, git: string|null, cmdDir: string|null, claudeFindsItself: boolean }}
+ */
+export function resolveGitBash({ platform = process.platform, env = process.env, settingsValue = null, pathValue = '', copies = [], ownRoots = [], isFile = defaultIsFile } = {}) {
+  const none = { supported: platform === 'win32', path: null, source: null, passToClaude: false, git: null, cmdDir: null, claudeFindsItself: false };
+  if (platform !== 'win32') return none;
+  const own = ownRoots.filter(Boolean);
+
+  // 1. What Claude Code finds by itself: nothing is passed, nothing downloaded.
+  const found = claudeCodeFinds({ env, settingsValue, pathValue, isFile, own });
+  if (found) {
+    const git = found.source === 'system' ? gitOfBash(found.path, { isFile }) : null;
+    return { ...none, path: found.path, source: found.source, git: git?.git || null, cmdDir: git?.cmdDir || null, claudeFindsItself: true };
+  }
+
+  // 2. A Git Bash of the PC that only SynaBun finds: named to Claude Code.
+  const candidates = [];
+  const onPath = firstGitOnPath(pathValue, { isFile, own });
+  const derived = bashOfGit(onPath, { isFile });
+  if (derived) candidates.push(derived);
+  for (const root of standardGitRoots(env)) candidates.push(win32.join(root, 'bin', 'bash.exe'));
+  for (const candidate of candidates) {
+    if (insideAny(candidate, own) || !isFile(candidate)) continue;
+    const git = gitOfBash(candidate, { isFile });
+    return { ...none, path: candidate, source: 'system', passToClaude: true, git: git?.git || null, cmdDir: git?.cmdDir || null };
+  }
+
+  // 3. SynaBun's own copy: the one inside the app, then the one in the data home.
+  for (const copy of copies) {
+    if (!copy?.ok) continue;
+    return { ...none, path: copy.bash, source: copy.source, passToClaude: true, git: copy.git, cmdDir: win32.dirname(copy.git) };
+  }
+  return none;
+}
+
+/** `env` with PATH (whatever its spelling: Windows keeps one, under the first name) ending in `folder`, once. */
+function appendToPath(env, folder) {
+  const keys = Object.keys(env).filter((name) => name.toUpperCase() === 'PATH');
+  const name = keys[0] || 'Path';
+  const parts = String(env[name] || '').split(';').filter(Boolean);
+  const out = { ...env };
+  for (const each of keys) delete out[each];
+  out[name] = [...parts.filter((part) => key(part) !== key(folder)), folder].join(';');
+  return out;
+}
+
+/**
+ * The environment of a Claude Code process SynaBun starts: `env` itself, unless SynaBun has to name its Git Bash
+ * (its own copy, or one only it finds): then CLAUDE_CODE_GIT_BASH_PATH, and that Git's cmd folder at the end of
+ * PATH (Claude Code's own git commands find git there). The system's PATH and registry are never changed.
+ */
+export function gitBashChildEnv(env, resolution, { platform = process.platform } = {}) {
+  if (platform !== 'win32' || !resolution?.passToClaude || !resolution.path) return env;
+  const out = { ...env, [GIT_BASH_ENV]: resolution.path };
+  return resolution.cmdDir ? appendToPath(out, resolution.cmdDir) : out;
+}

package/neural-interface/lib/git-diff-api.js

@@ -0,0 +1,103 @@
+// ── The working tree's changes of one folder, as text ──
+// GET /api/git/diff?path=&maxLines= answers with what `git diff` and
+// `git diff --cached` print for a folder, and the files git does not track.
+// The Codex side panel shows it; the MCP `git` tool reads it.
+//
+// The folder is checked like every file path of the code editor: inside a
+// registered root as written, and as the filesystem resolves it (a link that
+// leaves its project is refused). Who may ask is the route's own business: the
+// `guard` it is handed (server.js: lib/http-guards.js ownerRouteGuard) refuses
+// invite guests. git is run with an argument array, never through a shell, and
+// only with commands that read: nothing in the repository, its index or its
+// working tree is changed. Dependencies are injected: tested without server.js.
+
+import { Router } from 'express';
+import { statSync } from 'node:fs';
+import { PathConfineError } from './path-confine.js';
+import { canonicalInside } from './confined-fs.js';
+import { useFileRoot } from './editor-files-api.js';
+import { runGit } from './editor-git-api.js';
+
+/** The most one git command may print here. */
+export const GIT_DIFF_MAX_BYTES = 2 * 1024 * 1024;
+export const GIT_DIFF_LINES = Object.freeze({ fallback: 500, min: 50, max: 2000 });
+
+const text = (result) => result.stdout.toString('utf8');
+
+/** A text cut to `maxLines` lines. */
+function firstLines(value, maxLines) {
+  const lines = value.split('\n');
+  if (lines.length <= maxLines) return { text: value, truncated: false };
+  return { text: lines.slice(0, maxLines).join('\n'), truncated: true };
+}
+
+/**
+ * GET /api/git/diff?path=&maxLines=
+ *   200 { ok, branch, diff, stagedDiff, untrackedFiles, truncated }
+ *   400 no path · 400 { error: 'Not a git repository' } (also a path that is not a folder)
+ *   403 outside the registered roots, or out of one through a link; an invite guest (the guard's answer)
+ *   500 git failed, or printed more than `maxBytes`
+ * @param {object} deps
+ * @param {() => { dirs: string[], files: string[] }} deps.fileRoots the roots the editor's file routes allow
+ * @param {(args: string[], o: object) => Promise<object>} [deps.git] lib/editor-git-api.js runGit, or a stand-in
+ * @param {(req: object, res: object, next: () => void) => void} [deps.guard] who may use the route; on the route
+ *   itself, as the router is mounted at the root
+ * @param {number} [deps.maxBytes]
+ */
+export function createGitDiffRouter({ fileRoots, git = runGit, guard = null, maxBytes = GIT_DIFF_MAX_BYTES } = {}) {
+  if (typeof fileRoots !== 'function') throw new Error('createGitDiffRouter requires fileRoots');
+  const router = Router();
+  const owner = typeof guard === 'function' ? guard : (req, res, next) => next();
+
+  router.get('/api/git/diff', owner, async (req, res) => {
+    try {
+      const dir = req.query.path;
+      if (!dir || typeof dir !== 'string') return res.status(400).json({ error: 'path required' });
+      const asked = parseInt(req.query.maxLines, 10) || GIT_DIFF_LINES.fallback;
+      const maxLines = Math.min(Math.max(asked, GIT_DIFF_LINES.min), GIT_DIFF_LINES.max);
+
+      const folder = useFileRoot(dir, fileRoots(), (match) => canonicalInside(match.base, match.path, { allowBase: true }));
+      let isFolder = false;
+      try { isFolder = statSync(folder).isDirectory(); } catch { isFolder = false; }
+      const run = (args, timeoutMs) => git(args, { cwd: folder, maxBuffer: maxBytes, timeoutMs });
+      if (!isFolder || !(await run(['rev-parse', '--is-inside-work-tree'], 3000)).ok) {
+        return res.status(400).json({ error: 'Not a git repository' });
+      }
+
+      let branch = '';
+      const current = await run(['branch', '--show-current'], 3000);
+      if (current.ok) branch = text(current).trim();
+      if (!branch) {
+        const head = await run(['rev-parse', '--short', 'HEAD'], 3000);
+        if (head.ok) branch = text(head).trim();
+      }
+
+      const [unstaged, staged, others] = await Promise.all([
+        run(['diff', '--no-color'], 10000),
+        run(['diff', '--cached', '--no-color'], 10000),
+        run(['ls-files', '--others', '--exclude-standard'], 5000),
+      ]);
+      const failed = [unstaged, staged, others].find((result) => !result.ok);
+      if (failed) {
+        return res.status(500).json({ error: failed.tooLarge ? `The changes are larger than ${Math.round(maxBytes / (1024 * 1024))} MB` : 'git could not read the changes' });
+      }
+
+      const d = firstLines(text(unstaged), maxLines);
+      const s = firstLines(text(staged), maxLines);
+      const untracked = text(others).trim();
+      res.json({
+        ok: true,
+        branch,
+        diff: d.text,
+        stagedDiff: s.text,
+        untrackedFiles: untracked ? untracked.split('\n').filter(Boolean) : [],
+        truncated: d.truncated || s.truncated,
+      });
+    } catch (error) {
+      if (error instanceof PathConfineError) return res.status(error.status).json({ error: error.message });
+      res.status(500).json({ error: error?.message || String(error) });
+    }
+  });
+
+  return router;
+}

package/neural-interface/lib/git-read.js

@@ -0,0 +1,234 @@
+// ═══════════════════════════════════════════
+// SynaBun — git, for a read
+// ═══════════════════════════════════════════
+//
+// A repository's own configuration can name programs, and git starts them for
+// commands that only read. `git status` in a folder runs what that folder's
+// `core.fsmonitor` names; `git diff` runs its external diff and textconv
+// drivers; `git log` runs `gpg.program` when `log.showSignature` is on; a
+// partial clone fetches a missing object through whatever its remote names
+// (`uploadpack`, an `ext::` address, a credential helper); an index that a read
+// refreshes runs the `post-index-change` hook. The routes that read (the
+// status, the log, the changes, the committed version of a file) take the
+// folder from the request, and a folder may hold a repository somebody else
+// prepared: for a read none of those programs is started.
+//
+// gitRead() / gitReadSync() give the arguments and the environment one read is
+// run with (runGitReadSync() runs one, for a caller without a runner of its
+// own). What they switch off, and by what:
+//
+//   core.fsmonitor     `-c core.fsmonitor=false` when the repository names a
+//                      program there. When its value is a boolean, git's own
+//                      (built-in) monitor is kept as it is set: a large
+//                      repository stays fast. The repository is asked once
+//                      (`git config --type=bool --get core.fsmonitor`, which
+//                      runs nothing) and the answer is remembered for a few
+//                      seconds; the value is always given on the command
+//                      line, so what the file says later does not matter.
+//   hooks              `-c core.hooksPath=<the null device>`: no hook of the
+//                      repository is found (post-index-change is the one a
+//                      read reaches).
+//   optional locks     GIT_OPTIONAL_LOCKS=0: `git status` takes no index lock
+//                      and writes no index. (`git diff` still refreshes the
+//                      index's file times for a file that was only touched:
+//                      git does not put that under this setting. Nothing is
+//                      started for it: the hook an index write has is one of
+//                      the hooks above.)
+//   external diff,     `--no-ext-diff --no-textconv` on diff, show and log
+//   textconv           (diff.external, diff.<driver>.command, .textconv).
+//   signatures         `-c log.showSignature=false`: gpg.program is not asked.
+//   fetching           GIT_NO_LAZY_FETCH=1, and GIT_ALLOW_PROTOCOL set and
+//                      empty: no transport is allowed, so nothing a remote
+//                      names is started (uploadpack, ext::, ssh, a credential
+//                      helper, a proxy command). A read never needs a remote.
+//   a pager, a prompt  `--no-pager`, GIT_TERMINAL_PROMPT=0.
+//
+// The options given with `-c` reach the git that git starts inside a submodule
+// as well: a submodule's own configuration is under the same rule.
+//
+// What is NOT switched off: clean and process filters (`filter.<driver>.clean`,
+// `filter.<driver>.process`, for the files `.gitattributes` gives that driver).
+// git reads a working-tree file through its filter to compare it with the
+// index: `git diff` against the working tree for every such file it looks at,
+// `git status` for one whose time changed while its size did not. Without the
+// filter the comparison is wrong for every repository that uses one on purpose
+// (git-lfs, git-crypt), so it stays. Smudge filters are not run by a read.
+//
+// Writes are not run through here: a commit by the owner runs the
+// repository's hooks, and that is what a commit does.
+//
+// On a Windows PC without git, SynaBun's own copy of Git for Windows
+// (lib/git-bash/) is the git of every read: its folder is put at the end of
+// the read's PATH (setGitFallbackFolder, withGitFallback, which the commit
+// routes use too). Nothing changes where the computer has a git of its own.
+
+import { execFile, spawnSync } from 'node:child_process';
+import { devNull } from 'node:os';
+import { delimiter } from 'node:path';
+
+/** What the environment of a read adds. */
+export const GIT_READ_ENV = Object.freeze({
+  GIT_OPTIONAL_LOCKS: '0',
+  GIT_NO_LAZY_FETCH: '1',
+  GIT_ALLOW_PROTOCOL: '',
+  GIT_TERMINAL_PROMPT: '0',
+});
+
+/** Commands that take diff options. */
+const DIFF_COMMANDS = new Set(['diff', 'show', 'log']);
+/** Commands that compare the index with the working tree: the file system monitor is asked by these. */
+const INDEX_COMMANDS = new Set(['status', 'diff', 'ls-files']);
+
+const PROBE = ['config', '--type=bool', '--get', 'core.fsmonitor'];
+const PROBE_TIMEOUT_MS = 3000;
+export const MONITOR_MEMO_MS = 10_000;
+const MONITOR_MEMO_MAX = 200;
+
+let fallbackFolder = () => null;
+
+/**
+ * Where SynaBun's own git is on a computer that has none (Windows: the cmd folder of SynaBun's copy of Git for
+ * Windows, lib/git-bash/manager.js), as a function asked at every start; null while git is the computer's own.
+ * The folder goes at the end of PATH, so a git of the computer's, installed meanwhile, still comes first.
+ */
+export function setGitFallbackFolder(folder) {
+  fallbackFolder = typeof folder === 'function' ? folder : () => null;
+}
+
+/** `env` with the fallback folder at the end of its PATH (whatever its spelling), or `env` itself without one. */
+export function withGitFallback(env = process.env) {
+  let folder = null;
+  try { folder = fallbackFolder(); } catch { folder = null; }
+  if (!folder) return env;
+  const keys = Object.keys(env).filter((name) => name.toUpperCase() === 'PATH');
+  const name = keys[0] || (process.platform === 'win32' ? 'Path' : 'PATH');
+  const parts = String(env[name] || '').split(delimiter).filter(Boolean);
+  if (parts.some((part) => part.toLowerCase() === folder.toLowerCase())) return env;
+  const out = { ...env };
+  for (const each of keys) delete out[each];
+  out[name] = [...parts, folder].join(delimiter);
+  return out;
+}
+
+/** The environment a read is run in: `env` and what a read adds to it (and SynaBun's git, where the computer has none). */
+export function gitReadEnv(env = process.env) {
+  return withGitFallback({ ...env, ...GIT_READ_ENV });
+}
+
+/** Does this command compare the index with the working tree (and so ask the file system monitor)? */
+export function readsIndex(args) {
+  return Array.isArray(args) && INDEX_COMMANDS.has(args[0]);
+}
+
+/**
+ * The arguments of one read: git's own options first, then the command with what switches its external programs
+ * off, then the caller's own arguments unchanged.
+ * @param {string[]} args the command and its arguments, the command first (['status', '--porcelain'])
+ * @param {{ monitor?: boolean }} [o] `monitor`: the repository has git's built-in file system monitor switched on
+ */
+export function gitReadArgs(args, { monitor = false } = {}) {
+  const [command, ...rest] = Array.isArray(args) ? args : [];
+  const own = [
+    '--no-pager',
+    '-c', `core.fsmonitor=${monitor === true ? 'true' : 'false'}`,
+    '-c', `core.hooksPath=${devNull}`,
+    '-c', 'log.showSignature=false',
+  ];
+  if (command === undefined) return own;
+  return [...own, command, ...(DIFF_COMMANDS.has(command) ? ['--no-ext-diff', '--no-textconv'] : []), ...rest];
+}
+
+/**
+ * What is remembered of the repositories that were asked for their monitor: per folder, for a few seconds, for at
+ * most so many folders. Whatever is remembered, a read is given a boolean on its command line: a stale answer
+ * can keep git's own monitor on or off for a moment, it can never let a program through.
+ */
+export function createMonitorMemo({ ttlMs = MONITOR_MEMO_MS, max = MONITOR_MEMO_MAX, now = Date.now } = {}) {
+  const known = new Map();   // folder → { on, at }, the one asked longest ago first
+  return {
+    get(cwd) {
+      const entry = known.get(cwd);
+      if (!entry) return undefined;
+      if (now() - entry.at >= ttlMs) { known.delete(cwd); return undefined; }
+      return entry.on;
+    },
+    set(cwd, on) {
+      known.delete(cwd);
+      known.set(cwd, { on: on === true, at: now() });
+      while (known.size > max) known.delete(known.keys().next().value);
+      return on === true;
+    },
+    size: () => known.size,
+  };
+}
+
+const memo = createMonitorMemo();
+// The question itself: no value is given for core.fsmonitor here (the command line's would be the answer), and
+// `git config` reads no index, so it asks no monitor.
+const probeArgs = () => ['--no-pager', '-c', `core.hooksPath=${devNull}`, ...PROBE];
+// "true" and nothing else: unset (exit 1), a program's path (exit 128: not a boolean), false, no git, a timeout.
+const saysOn = (status, stdout) => status === 0 && String(stdout || '').trim() === 'true';
+
+/**
+ * Is git's built-in file system monitor switched on for the repository `cwd` is in? False for every other answer:
+ * not set, a program's path, no repository, no git.
+ * @param {string} cwd
+ * @param {{ binary?: string, env?: object, remembered?: ReturnType<typeof createMonitorMemo> }} [o]
+ * @returns {Promise<boolean>}
+ */
+export function builtInMonitor(cwd, { binary = 'git', env = process.env, remembered = memo } = {}) {
+  const known = remembered.get(cwd);
+  if (known !== undefined) return Promise.resolve(known);
+  return new Promise((done) => {
+    try {
+      execFile(binary, probeArgs(), { cwd, env: gitReadEnv(env), timeout: PROBE_TIMEOUT_MS, windowsHide: true, shell: false, encoding: 'utf8' }, (error, stdout) => {
+        done(remembered.set(cwd, saysOn(error ? (typeof error.code === 'number' ? error.code : -1) : 0, stdout)));
+      });
+    } catch {
+      done(remembered.set(cwd, false));
+    }
+  });
+}
+
+/** builtInMonitor, for a caller that runs git synchronously. */
+export function builtInMonitorSync(cwd, { binary = 'git', env = process.env, remembered = memo, spawn = spawnSync } = {}) {
+  const known = remembered.get(cwd);
+  if (known !== undefined) return known;
+  let on = false;
+  try {
+    const result = spawn(binary, probeArgs(), { cwd, env: gitReadEnv(env), timeout: PROBE_TIMEOUT_MS, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+    on = !result.error && saysOn(result.status, result.stdout);
+  } catch { on = false; }
+  return remembered.set(cwd, on);
+}
+
+/**
+ * How to run one read in `cwd`: `{ args, env }` for the program `git`. The repository is asked for its monitor
+ * only for a command that compares the index with the working tree.
+ * @param {string} cwd
+ * @param {string[]} args the command first
+ * @param {{ binary?: string, env?: object, remembered?: object }} [o]
+ * @returns {Promise<{ args: string[], env: object }>}
+ */
+export async function gitRead(cwd, args, o = {}) {
+  const monitor = readsIndex(args) ? await builtInMonitor(cwd, o) : false;
+  return { args: gitReadArgs(args, { monitor }), env: gitReadEnv(o.env) };
+}
+
+/** gitRead, for a caller that runs git synchronously. */
+export function gitReadSync(cwd, args, o = {}) {
+  const monitor = readsIndex(args) ? builtInMonitorSync(cwd, o) : false;
+  return { args: gitReadArgs(args, { monitor }), env: gitReadEnv(o.env) };
+}
+
+/**
+ * One read, run now, for a caller that has no runner of its own: what spawnSync answers.
+ * @param {string} cwd
+ * @param {string[]} args the command first
+ * @param {object} [options] spawnSync's (`encoding`, `timeout`, `maxBuffer`, …); `cwd` and what a read adds to
+ *   the environment are not the caller's to change
+ */
+export function runGitReadSync(cwd, args, options = {}) {
+  const read = gitReadSync(cwd, args, { env: options.env });
+  return spawnSync('git', read.args, { windowsHide: true, ...options, cwd, env: read.env });
+}

package/neural-interface/lib/greeting/api.js

@@ -0,0 +1,89 @@
+// ═══════════════════════════════════════════
+// SynaBun — Greeting: the HTTP surface (/api/greeting)
+// ═══════════════════════════════════════════
+//
+//   GET  /            the setting, what the engine can do, the last greeting shown
+//   PUT  /            { enabled }                              the one switch
+//   POST /open        { surface, cwd?, project?, session?, note? }   a fresh interactive session opened
+//   POST /preview     { project?, cwd?, write? }               what a new session would be greeted with now
+//   POST /rearm       { project?, cwd? }                       greet the next session there once (first live look)
+//
+// Mounted synchronously, before the engine exists: until then, and when it did
+// not start, every route answers 503 with the reason, so Settings can tell an
+// engine that failed from a server that is older than the page (404). A
+// greeting is about the owner's own work: invite guests get 403.
+
+import { Router, json } from 'express';
+import { ID_RE, SURFACES } from './budgets.js';
+
+const text = (value, max) => (typeof value === 'string' && value.length <= max ? value : null);
+
+export function createGreetingApi({ getEngine = () => null, getError = () => null, isGuestRequest = () => false, defaultProject = () => 'global', log = () => {} } = {}) {
+  const router = Router();
+  router.use(json({ limit: '32kb' }));
+  router.use((req, res, next) => {
+    let guest = false;
+    try { guest = !!isGuestRequest(req); } catch { guest = true; }
+    if (guest) return res.status(403).json({ ok: false, code: 'FORBIDDEN', error: 'Not available to guests' });
+    const engine = getEngine();
+    if (!engine) {
+      let reason = null;
+      try { reason = getError(); } catch { reason = null; }
+      return res.status(503).json({ ok: false, code: 'GREETING_UNAVAILABLE', error: 'The greeting engine is not running', reason: reason || 'starting' });
+    }
+    req.greeting = engine;
+    next();
+  });
+  const place = (body = {}) => {
+    const project = text(body.project, 120);
+    const cwd = text(body.cwd, 2048);
+    if (project && /^[A-Za-z0-9_.-]+$/.test(project)) return { project };
+    if (cwd) return { cwd };
+    return {};
+  };
+  const fail = (res, error) => {
+    log('greeting:api-error', error?.message || String(error));
+    res.status(500).json({ ok: false, error: String(error?.message || error).slice(0, 200) });
+  };
+
+  router.get('/', (req, res) => {
+    try { res.json({ ok: true, ...req.greeting.status() }); } catch (error) { fail(res, error); }
+  });
+
+  router.put('/', (req, res) => {
+    try {
+      if (typeof req.body?.enabled !== 'boolean') return res.status(400).json({ ok: false, code: 'BAD_REQUEST', error: 'enabled must be true or false' });
+      req.greeting.setEnabled(req.body.enabled);
+      res.json({ ok: true, ...req.greeting.status() });
+    } catch (error) { fail(res, error); }
+  });
+
+  router.post('/open', async (req, res) => {
+    try {
+      const body = req.body || {};
+      const surface = text(body.surface, 40);
+      if (!surface || !Object.prototype.hasOwnProperty.call(SURFACES, surface)) return res.status(400).json({ ok: false, code: 'BAD_REQUEST', error: 'Unknown surface' });
+      const session = text(body.session, 160);
+      const answer = await req.greeting.open({ surface, ...place(body), session: session && ID_RE.test(session) ? session : null, note: body.note === true });
+      res.json({ ok: true, ...answer });
+    } catch (error) { fail(res, error); }
+  });
+
+  router.post('/preview', async (req, res) => {
+    try {
+      const where = place(req.body || {});
+      if (!where.project && !where.cwd) { try { where.project = String(defaultProject() || 'global'); } catch { where.project = 'global'; } }
+      res.json({ ok: true, preview: await req.greeting.preview({ ...where, write: req.body?.write === true }) });
+    } catch (error) { fail(res, error); }
+  });
+
+  router.post('/rearm', (req, res) => {
+    try {
+      const where = place(req.body || {});
+      if (!where.project && !where.cwd) { try { where.project = String(defaultProject() || 'global'); } catch { where.project = 'global'; } }
+      res.json({ ok: true, project: req.greeting.rearm(where) });
+    } catch (error) { fail(res, error); }
+  });
+
+  return router;
+}