synabun 2.0.0-beta → 2.0.5

package/neural-interface/lib/file-explorer-watch.js

@@ -0,0 +1,239 @@
+// ── The File Explorer's watcher ──
+// Tells the page which of the folders it shows changed on disk, and when the
+// git state of the project may have, without the page asking again and again.
+// It costs nothing while nothing changes: the operating system reports changes,
+// nothing is polled.
+//
+// Two ways to watch, by what the system offers:
+//   recursive  one watcher on the project's folder (macOS and Windows have it
+//              natively). Every change below the folder arrives; the ones the
+//              page did not ask about are dropped here.
+//   folders    one watcher per folder the page shows (Linux, where a recursive
+//              watch is a watch per sub-folder), plus one on .git.
+// Changes are collected for a moment and sent together. Dependencies are
+// injected: the tests drive it with real folders and with a fake `watch`.
+//
+// A watcher that exists is not a watch that works: the system may have no
+// watches left (ENOSPC on Linux), or lose one it had. `state()` says what is
+// really watched, and `onState` when that changes, so the page can read again
+// by itself where nothing will tell it.
+//
+// A watch that failed is not asked for again at once. A watch that is lost
+// each time it is opened would otherwise be opened, lost and opened again as
+// fast as the page and the system can answer one another. It is tried again
+// after a wait that doubles (a second, two, four, ... a minute at most) and
+// starts over once a watch has held for a minute; until then it stays a watch
+// that is not there, whatever folders the page shows meanwhile.
+
+import { existsSync, watch as fsWatch } from 'node:fs';
+import { dirname, join, relative, sep } from 'node:path';
+
+export const MAX_WATCHED_DIRS = 600;
+/** A watch that failed is tried again after this long, then after twice that, and so on. */
+export const RETRY_FIRST_MS = 1000;
+/** ... and never less often than this. */
+export const RETRY_MAX_MS = 60000;
+/** A watch that held this long was no part of a run of failures: the next wait is the first one again. */
+export const RETRY_QUIET_MS = 60000;
+/** The files of .git whose change means "commit, stage, checkout or merge": the git state is read again. */
+const GIT_STATE_FILES = /^(index|HEAD|ORIG_HEAD|MERGE_HEAD|CHERRY_PICK_HEAD|REVERT_HEAD|packed-refs)$/;
+/** A folder that is not there (any more) is no watch that failed: its next listing says what is true. */
+const NOT_THERE = new Set(['ENOENT', 'ENOTDIR']);
+
+/** Which way this system is watched. */
+export function watchStrategy(platform = process.platform) {
+  return platform === 'darwin' || platform === 'win32' ? 'recursive' : 'folders';
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.root the project's folder, canonical
+ * @param {'recursive' | 'folders'} [o.strategy]
+ * @param {(change: { dirs: string[], git: boolean }) => void} o.onChange `dirs`: watched folders (canonical) whose
+ *   entries changed; `git`: the git state may have changed
+ * @param {(error: Error) => void} [o.onError] the watch on the project's folder was lost
+ * @param {(state: { scope: 'tree' | 'folders', live: 'full' | 'partial' | 'none' }) => void} [o.onState] what is
+ *   really watched changed (see `state()`); not called for the state it starts in
+ * @param {(relativePath: string) => boolean} [o.ignoresGit] a path git ignores: a change there is no change of state
+ * @param {typeof fsWatch} [o.watch] @param {(path: string) => boolean} [o.exists]
+ * @param {number} [o.debounceMs] @param {number} [o.maxWaitMs]
+ * @param {() => number} [o.now] @param {(fn: () => void, ms: number) => any} [o.setTimer] @param {(timer: any) => void} [o.clearTimer]
+ *   the clock of the waits between two attempts at a watch that failed (a test moves it by hand)
+ * @returns {{ setDirs: (dirs: string[]) => void, close: () => void, count: () => number, strategy: string,
+ *   state: () => { scope: 'tree' | 'folders', live: 'full' | 'partial' | 'none' } }}
+ */
+export function createTreeWatcher({
+  root, strategy = watchStrategy(), onChange, onError = () => {}, onState = () => {}, ignoresGit = () => false,
+  watch = fsWatch, exists = existsSync, debounceMs = 120, maxWaitMs = 500,
+  now = () => Date.now(), setTimer = (fn, ms) => setTimeout(fn, ms), clearTimer = (timer) => clearTimeout(timer),
+}) {
+  let closed = false;
+  let wanted = new Set([root]);        // the folders the page shows
+  let capped = false;                  // the page shows more folders than are watched
+  const watchers = new Map();          // what is watched → FSWatcher
+  const failed = new Set();            // what should be watched and is not (no watches left, a watch that was lost)
+  const openedAt = new Map();          // what is watched → when that watch was opened
+  let retryMs = 0;                     // the wait that is running, or ran last
+  let retryAt = 0;                     // nothing that failed is asked for again before this
+  let retryTimer = null;
+  let refused = false;                 // the system refused a watch in the pass that is under way
+  let said = null;                     // the `live` that was last reported
+  const pending = new Set();
+  let pendingGit = false;
+  let timer = null;
+  let firstAt = 0;
+
+  const slashed = (path) => (sep === '/' ? path : path.split(sep).join('/'));
+
+  function flush() {
+    timer = null;
+    if (closed || (!pending.size && !pendingGit)) return;
+    const change = { dirs: [...pending], git: pendingGit };
+    pending.clear();
+    pendingGit = false;
+    try { onChange(change); } catch { /* a listener's failure is not the watcher's */ }
+  }
+
+  // Sent a moment after the last change, and never later than `maxWaitMs` after the first of a burst.
+  function schedule() {
+    const now = Date.now();
+    if (!timer) firstAt = now;
+    else clearTimeout(timer);
+    const wait = Math.max(0, Math.min(debounceMs, firstAt + maxWaitMs - now));
+    timer = setTimeout(flush, wait);
+    timer.unref?.();
+  }
+
+  // One change, by its path below the root ('' is the root itself).
+  function note(rel) {
+    if (closed) return;
+    const path = slashed(rel || '');
+    if (path === '.git' || path.startsWith('.git/')) {
+      const inside = path.slice(5);
+      if (GIT_STATE_FILES.test(inside) || inside.startsWith('refs/')) pendingGit = true;
+    } else if (!path || !ignoresGit(path)) {
+      pendingGit = true;
+    }
+    const parent = path.includes('/') ? join(root, dirname(path)) : root;
+    if (wanted.has(parent)) pending.add(parent);
+    // A watched folder that was itself removed or renamed: whoever shows it reads it again and finds out.
+    const self = path ? join(root, path) : root;
+    if (self !== parent && wanted.has(self)) pending.add(self);
+    if (pending.size || pendingGit) schedule();
+  }
+
+  /**
+   * What is really watched. `scope`: every change below the project (`tree`), or only changes in the folders the
+   * page shows and in git's own files (`folders`: a change inside a closed folder is not seen). `live`: `full`
+   * when all of that is watched, `partial` when some of it could not be, `none` when the project's folder is not.
+   */
+  const state = () => ({
+    scope: strategy === 'recursive' ? 'tree' : 'folders',
+    live: failed.has(root) || !watchers.has(root) ? 'none' : failed.size || capped ? 'partial' : 'full',
+  });
+  function report() {
+    if (closed) return;
+    const is = state();
+    if (is.live === said) return;
+    said = is.live;
+    try { onState(is); } catch { /* a listener's failure is not the watcher's */ }
+  }
+
+  // Something that should be watched is not: everything that failed is asked for again together, after a wait.
+  // One wait covers whatever fails while it runs; the next one is twice as long, unless the watch that failed
+  // had held for a while (`heldSince`): that was no part of a run of failures.
+  function backOff(heldSince) {
+    const at = now();
+    if (retryTimer !== null && at < retryAt) return;
+    if (heldSince !== undefined && at - heldSince >= RETRY_QUIET_MS) retryMs = 0;
+    retryMs = retryMs ? Math.min(retryMs * 2, RETRY_MAX_MS) : RETRY_FIRST_MS;
+    retryAt = at + retryMs;
+    if (retryTimer !== null) clearTimer(retryTimer);
+    retryTimer = setTimer(() => { retryTimer = null; if (closed) return; sync(); report(); }, retryMs);
+    retryTimer?.unref?.();
+  }
+
+  function open(key, path, options, handler) {
+    if (watchers.has(key) || closed) return;
+    // Still in its wait: the folders the page shows do not ask the system again for a watch it just refused or lost.
+    if (failed.has(key) && now() < retryAt) return;
+    let watcher;
+    try { watcher = watch(path, { persistent: false, ...options }, handler); }
+    catch (error) {
+      // A folder that is gone says so in its next listing. Anything else (no watches left) is a change nobody
+      // will be told of: it is counted, and the page reads again by itself.
+      if (key === root || !NOT_THERE.has(error?.code)) { failed.add(key); refused = true; }
+      return;
+    }
+    failed.delete(key);
+    openedAt.set(key, now());
+    watcher.on?.('error', () => {
+      try { watcher.close(); } catch { /* already closed */ }
+      if (watchers.get(key) !== watcher) return;   // let go of since: not a watch that was lost
+      watchers.delete(key);
+      if (closed) return;
+      // Tried again after its wait; until then it is a watch that is not there.
+      if (key === root || exists(path)) { failed.add(key); backOff(openedAt.get(key)); }
+      report();
+      if (key === root) { try { onError(new Error('The watch on the project folder was lost.')); } catch { /* as above */ } } else note(relative(root, path));
+    });
+    watchers.set(key, watcher);
+  }
+
+  function sync() {
+    if (closed) return;
+    refused = false;
+    try { place(); } finally { if (refused) backOff(); }
+  }
+
+  function place() {
+    if (strategy === 'recursive') {
+      open(root, root, { recursive: true }, (type, name) => note(name ? String(name) : ''));
+      return;
+    }
+    for (const [key, watcher] of watchers) {
+      if (key === '.git' || wanted.has(key)) continue;
+      try { watcher.close(); } catch { /* already closed */ }
+      watchers.delete(key);
+      openedAt.delete(key);
+    }
+    for (const key of failed) if (key !== '.git' && !wanted.has(key)) failed.delete(key);
+    for (const dir of wanted) {
+      const rel = relative(root, dir);
+      open(dir, dir, {}, (type, name) => note(name ? join(rel, String(name)) : rel));
+    }
+    open('.git', join(root, '.git'), {}, (type, name) => { if (name) note(join('.git', String(name))); });
+  }
+
+  sync();
+  said = state().live;
+
+  return {
+    strategy,
+    /** The folders the page shows now (canonical paths, the root or below it). */
+    setDirs(dirs) {
+      const next = new Set([root]);
+      capped = false;
+      for (const dir of dirs || []) {
+        if (typeof dir !== 'string' || !(dir === root || dir.startsWith(root.endsWith(sep) ? root : root + sep)) || next.has(dir)) continue;
+        if (next.size >= MAX_WATCHED_DIRS) { capped = strategy !== 'recursive'; break; }
+        next.add(dir);
+      }
+      wanted = next;
+      sync();
+      report();
+    },
+    state,
+    count: () => watchers.size,
+    close() {
+      closed = true;
+      if (timer) clearTimeout(timer);
+      timer = null;
+      if (retryTimer !== null) clearTimer(retryTimer);
+      retryTimer = null;
+      for (const watcher of watchers.values()) { try { watcher.close(); } catch { /* already closed */ } }
+      watchers.clear();
+      pending.clear();
+    },
+  };
+}

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,202 @@
+// ═══════════════════════════════════════════
+// 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.
+
+import { execFile, spawnSync } from 'node:child_process';
+import { devNull } from 'node:os';
+
+/** 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;
+
+/** The environment a read is run in: `env` and what a read adds to it. */
+export function gitReadEnv(env = process.env) {
+  return { ...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;
+}