synabun 2.0.5 → 2.0.7

package/lib/child-path.js

@@ -0,0 +1,303 @@
+/**
+ * SynaBun — the PATH of everything SynaBun starts, and where npm puts global commands
+ *
+ * A packaged application (packaging/) brings its own Node runtime, npm and npx.
+ * They are a fallback: on the PATH of every process the application starts,
+ * the order is
+ *
+ *   1. the user's own PATH, as it came
+ *   2. the bin folder of npm's global prefix, when the PATH lacks it (where
+ *      `npm i -g` through SynaBun's npm puts commands: the user's own prefix
+ *      when they set one, else a per-user folder of SynaBun's, never the app)
+ *   3. the packaged runtime, last
+ *
+ * packagedPathLast() is that order, and the one implementation of it: the
+ * entry points of a packaged build (lib/packaged-runtime.js packagedChildEnv:
+ * the bootstrap, the hook handler, the headless MCP server) and every PATH the
+ * Neural Interface builds (neural-interface/lib/augmented-path.js) use it.
+ *
+ * npm's global prefix is read here the way npm 10 (@npmcli/config) settles it,
+ * from plain files, without starting npm:
+ *
+ *   1. the environment: npm_config_prefix, in any letter case, when not empty
+ *   2. the user's config file: npm_config_userconfig, else ~/.npmrc
+ *   3. the global config file: npm_config_globalconfig, else `globalconfig=` in
+ *      the user's (or the builtin) file, else <the prefix so far>/etc/npmrc
+ *   4. the builtin config of that npm (<npm>/npmrc: a packaged build writes one)
+ *   5. the default: $PREFIX, else the folder of the node running npm (Windows)
+ *      or the folder above it
+ *
+ * (The command line comes first for npm and is never known here; a project's
+ * .npmrc is ignored by npm for a global install.) Every value goes through
+ * npm's ${VAR} substitution; a path then has a leading `~/` (on Windows also
+ * `~\`) replaced by the home folder (HOME, else the account's) and is made
+ * absolute. Files are read as npm's ini reader reads them: `;` and `#`
+ * comments, quotes, inline comments; a `prefix` inside a [section] is not the
+ * prefix. One difference: an empty `prefix=` counts as not set (npm would use
+ * the folder it happens to run in, which is no folder to put on a PATH).
+ *
+ * Only node: modules here: neural-interface/lib/augmented-path.js imports this
+ * file, and tests copy both into scratch trees.
+ */
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+const MEMO_MS = 5_000;
+let _memo = null; // { key, at, value }
+
+const implFor = (platform) => (platform === 'win32' ? path.win32 : path.posix);
+
+/** The value of an env's PATH, whatever its spelling (Windows: Path). */
+export function pathEnvValue(env = process.env) {
+  return env[Object.keys(env).find(key => key.toUpperCase() === 'PATH')] || '';
+}
+
+/**
+ * `env` with PATH set to `value`. Windows environment names are
+ * case-insensitive and JS object keys are not: the base's spelling is kept and
+ * every alias removed before an env reaches Node or ConPTY.
+ */
+export function withPathEnv(env = process.env, value = pathEnvValue(env), platform = process.platform) {
+  if (platform !== 'win32') return { ...env, PATH: value };
+  const keys = Object.keys(env).filter(key => key.toUpperCase() === 'PATH');
+  const key = keys[0] || 'Path';
+  const out = { ...env };
+  for (const alias of keys) delete out[alias];
+  out[key] = value;
+  return out;
+}
+
+/**
+ * PATH `value` with a packaged application's folders after the user's: each
+ * `extra` folder (npm's global bin) appended when the PATH does not have it
+ * yet, then every `last` folder (the runtime) moved to the very end. Nothing
+ * else moves; each folder stays once (Windows compares without case and
+ * trailing separators).
+ */
+export function packagedPathLast(value, { platform = process.platform, last = [], extra = [] } = {}) {
+  const delimiter = platform === 'win32' ? ';' : ':';
+  const id = (entry) => (platform === 'win32' ? entry.toLowerCase().replace(/[\\/]+$/, '') : entry.replace(/\/+$/, '') || '/');
+  const lastIds = new Set(last.filter(Boolean).map(id));
+  const seen = new Set();
+  const out = [];
+  const add = (entry) => {
+    if (!entry) return;
+    const key = id(entry);
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(entry);
+  };
+  for (const entry of String(value || '').split(delimiter)) if (entry && !lastIds.has(id(entry))) add(entry);
+  for (const entry of extra) if (entry && !lastIds.has(id(entry))) add(entry);
+  for (const entry of last) add(entry);
+  return out.join(delimiter);
+}
+
+/** Where npm puts the commands of global packages under `prefix`: the prefix itself on Windows, its bin/ elsewhere. */
+export function npmGlobalBinFor(prefix, platform = process.platform) {
+  if (!prefix) return null;
+  return platform === 'win32' ? prefix : implFor(platform).join(prefix, 'bin');
+}
+
+/** The builtin npmrc of the npm in a packaged runtime whose executables are in `runtimeBin`. */
+export function bundledNpmrcPath(runtimeBin, platform = process.platform) {
+  if (!runtimeBin) return null;
+  const impl = implFor(platform);
+  return platform === 'win32'
+    ? impl.join(runtimeBin, 'node_modules', 'npm', 'npmrc')
+    : impl.join(runtimeBin, '..', 'lib', 'node_modules', 'npm', 'npmrc');
+}
+
+function envLookup(env, name, platform) {
+  if (env[name] !== undefined) return env[name];
+  if (platform !== 'win32') return undefined;
+  const key = Object.keys(env).find(candidate => candidate.toUpperCase() === name.toUpperCase());
+  return key === undefined ? undefined : env[key];
+}
+
+/**
+ * npm's ${VAR} substitution (@npmcli/config env-replace.js): `${NAME}` is the
+ * variable's value, a name that is not set stays as written, and a backslash
+ * before `${` escapes it (an even number of them is that many halved, then the value).
+ */
+export function npmEnvReplace(text, env = process.env, platform = process.platform) {
+  return String(text).replace(/(?<!\\)(\\*)\$\{([^${}]+)\}/g, (orig, esc, name) => {
+    const found = envLookup(env, name, platform);
+    const value = found !== undefined ? found : `\${${name}}`;
+    if (esc.length % 2) return orig.slice((esc.length + 1) / 2);
+    return esc.slice(esc.length / 2) + value;
+  });
+}
+
+// The ini reader npm uses (ini 4.x unsafe()): quotes, then `;` / `#` ending the value unless escaped.
+function iniValue(raw) {
+  let value = String(raw || '').trim();
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    if (value.charAt(0) === "'") value = value.slice(1, -1);
+    try { value = JSON.parse(value); } catch { /* kept as it is */ }
+    return value;
+  }
+  let escaped = false;
+  let out = '';
+  for (const char of value) {
+    if (escaped) {
+      out += '\\;#'.includes(char) ? char : `\\${char}`;
+      escaped = false;
+    } else if (char === ';' || char === '#') {
+      break;
+    } else if (char === '\\') {
+      escaped = true;
+    } else {
+      out += char;
+    }
+  }
+  if (escaped) out += '\\';
+  return out.trim();
+}
+
+/**
+ * The top-level settings of an .npmrc, as npm's ini reader gives them (a key
+ * inside a [section] is the section's; `true` / `false` / `null` are those
+ * values; `key[]` makes a list; the last of a repeated key wins).
+ */
+export function parseNpmrc(text) {
+  const out = Object.create(null);
+  for (const line of String(text || '').split(/[\r\n]+/g)) {
+    if (!line || /^\s*[;#]/.test(line) || /^\s*$/.test(line)) continue;
+    if (/^\[([^\]]*)\]\s*$/.test(line)) break;
+    const match = line.match(/^([^=]+)(=(.*))?$/);
+    if (!match) continue;
+    const rawKey = iniValue(match[1]);
+    const isList = rawKey.length > 2 && rawKey.endsWith('[]');
+    const key = isList ? rawKey.slice(0, -2) : rawKey;
+    if (!key || key === '__proto__') continue;
+    const raw = match[2] ? iniValue(match[3]) : true;
+    const value = raw === 'true' || raw === 'false' || raw === 'null' ? JSON.parse(raw) : raw;
+    if (isList) {
+      if (!Array.isArray(out[key])) out[key] = out[key] === undefined ? [] : [out[key]];
+    }
+    if (Array.isArray(out[key])) out[key].push(value);
+    else out[key] = value;
+  }
+  return out;
+}
+
+/** The npm_config_* settings of an environment, as npm reads them (any letter case, `_` as `-`, empty ones skipped; the last spelling wins). */
+export function npmEnvConfig(env = process.env) {
+  const out = Object.create(null);
+  for (const [name, value] of Object.entries(env)) {
+    if (!/^npm_config_/i.test(name) || value === '' || value === undefined) continue;
+    let key = name.slice('npm_config_'.length);
+    if (!key.startsWith('//')) key = key.replace(/(?!^)_/g, '-').toLowerCase();
+    out[key] = value;
+  }
+  return out;
+}
+
+/** A path setting as npm parses it: ${VAR}, then `~/`, then absolute. null for one that is not a usable string. */
+export function npmPathValue(value, { env = process.env, platform = process.platform, home, cwd = process.cwd() } = {}) {
+  if (typeof value !== 'string') return null;
+  const text = npmEnvReplace(value.trim(), env, platform);
+  if (!text) return null;
+  const impl = implFor(platform);
+  const homePattern = platform === 'win32' ? /^~(\/|\\)/ : /^~\//;
+  if (homePattern.test(text) && home) return impl.resolve(home, text.slice(2));
+  return impl.resolve(cwd, text);
+}
+
+/** The home folder npm uses: HOME, else the account's (os.homedir(); on Windows USERPROFILE). */
+export function npmHome(env = process.env, platform = process.platform) {
+  if (env.HOME) return env.HOME;
+  if (env === process.env) return homedir();
+  if (platform === 'win32') return envLookup(env, 'USERPROFILE', platform) || homedir();
+  return homedir();
+}
+
+/**
+ * npm's global prefix, as described at the top. `builtin` is the builtin npmrc
+ * of the npm that will run (lib/packaged-runtime.js names the packaged one),
+ * `execPath` the node it runs on (for the default); leave both out to get only
+ * what the user set (`source` then never says 'builtin' or 'default').
+ *
+ * Returns { prefix, bin, source, from, userconfig, globalconfig }: `prefix` an
+ * absolute folder or null, `source` 'env' | 'userconfig' | 'globalconfig' |
+ * 'builtin' | 'default' | null, `from` what set it (the variable or the file).
+ */
+export function resolveNpmPrefix({
+  env = process.env,
+  platform = process.platform,
+  home = npmHome(env, platform),
+  cwd = process.cwd(),
+  readFile = readFileSync,
+  builtin = null,
+  execPath = null,
+} = {}) {
+  const impl = implFor(platform);
+  const parse = { env, platform, home, cwd };
+  const read = (file) => {
+    if (!file) return Object.create(null);
+    try { return parseNpmrc(readFile(file, 'utf8')); } catch { return Object.create(null); }
+  };
+  const fromEnv = npmEnvConfig(env);
+  const envPrefix = npmPathValue(fromEnv.prefix, parse);
+  const userconfig = npmPathValue(fromEnv.userconfig, parse) || (home ? impl.resolve(home, '.npmrc') : null);
+  const user = read(userconfig);
+  const userPrefix = npmPathValue(user.prefix, parse);
+  const builtinConfig = read(builtin);
+  const builtinPrefix = npmPathValue(builtinConfig.prefix, parse);
+  let defaultPrefix = null;
+  if (execPath) {
+    if (env.PREFIX) defaultPrefix = npmPathValue(env.PREFIX, parse);
+    else if (platform === 'win32') defaultPrefix = impl.dirname(execPath);
+    else defaultPrefix = env.DESTDIR ? impl.join(env.DESTDIR, impl.dirname(impl.dirname(execPath))) : impl.dirname(impl.dirname(execPath));
+  }
+  const soFar = envPrefix || userPrefix || builtinPrefix || defaultPrefix;
+  const globalconfig = npmPathValue(fromEnv.globalconfig, parse)
+    || npmPathValue(user.globalconfig, parse)
+    || npmPathValue(builtinConfig.globalconfig, parse)
+    || (soFar ? impl.resolve(soFar, 'etc', 'npmrc') : null);
+  const globalPrefix = npmPathValue(read(globalconfig).prefix, parse);
+  const levels = [
+    ['env', envPrefix, 'npm_config_prefix'],
+    ['userconfig', userPrefix, userconfig],
+    ['globalconfig', globalPrefix, globalconfig],
+    ['builtin', builtinPrefix, builtin],
+    ['default', defaultPrefix, execPath],
+  ];
+  const found = levels.find(([, value]) => value);
+  const prefix = found ? found[1] : null;
+  return {
+    prefix,
+    bin: npmGlobalBinFor(prefix, platform),
+    source: found ? found[0] : null,
+    from: found ? found[2] : null,
+    userconfig,
+    globalconfig,
+  };
+}
+
+/**
+ * resolveNpmPrefix() for this process, kept for a few seconds: every PATH
+ * SynaBun builds asks, and a changed ~/.npmrc counts within seconds. Options
+ * other than `builtin` and `execPath` (an env that is not process.env, a
+ * readFile) are not cached.
+ */
+export function effectiveNpmPrefix(options = {}) {
+  const { builtin = null, execPath = null, ...rest } = options;
+  const live = Object.keys(rest).every(key => (key === 'env' ? rest.env === process.env : key === 'platform' ? rest.platform === process.platform : false));
+  if (!live) return resolveNpmPrefix(options);
+  const env = process.env;
+  const relevant = Object.entries(env).filter(([name]) => /^npm_config_/i.test(name) || ['HOME', 'USERPROFILE', 'APPDATA', 'PREFIX', 'DESTDIR'].includes(name.toUpperCase()));
+  const key = JSON.stringify([builtin, execPath, process.cwd(), relevant]);
+  if (_memo && _memo.key === key && Date.now() - _memo.at < MEMO_MS) return _memo.value;
+  const value = resolveNpmPrefix({ builtin, execPath });
+  _memo = { key, at: Date.now(), value };
+  return value;
+}
+
+/** Forget what effectiveNpmPrefix() keeps (a test, or a settings change that must count at once). */
+export function forgetNpmPrefix() {
+  _memo = null;
+}

package/lib/claude-hooks.js

@@ -78,7 +78,8 @@ export function isSynaBunHookCommand(command, scriptName) {
 /**
  * Why this run must not write hook commands, or null when it may. A packaged
  * application with no path that outlives the run (macOS started it from a
- * temporary copy) would leave every handler pointing at nothing.
+ * temporary copy, or from the disk image it came in) would leave every handler
+ * pointing at nothing.
  */
 export function hookInstallBlocker(runtime = packagedRuntime()) {
   if (!runtime || durableEntry(runtime)) return null;

package/lib/data-home-migration.js

@@ -52,6 +52,8 @@ function isRuntimeOnlyMigrationFile(relativePath) {
   return name === '.DS_Store'
     || MIGRATION_RUNTIME_ONLY_FILES.has(normalized)
     || /(?:^|\/)server-(?:stdout|stderr)\.log(?:\.1)?$/i.test(normalized)
+    // The desktop app's own log (packaging/desktop) and the launcher's rotated one, written from the first start on.
+    || /^data\/(?:desktop\.log(?:\.1)?|launcher\.log\.1)$/i.test(normalized)
     || /(?:^|\/)(?:restart-requested|opencode-managed\.pid)$/i.test(normalized);
 }
 

package/lib/desktop-app.js

@@ -0,0 +1,265 @@
+/**
+ * SynaBun — the desktop app's server
+ *
+ * The Electron window of a packaged build (packaging/desktop/) does not decide
+ * anything about the server itself: it runs `<entry> app-backend --json`
+ * (packaging/runtime/bootstrap.mjs), which comes here. This module finds the
+ * server the window should show, and starts one through the same Start Server
+ * launcher an npm install uses (lib/start-launcher.js runLauncher: the launch
+ * lock, the supervisor record, the health check), so two starts never race.
+ *
+ *   reuse      a server of this install (same entry, same version) answers:
+ *              on the port the window used last, where this data home's
+ *              supervisor says it listens, or on the configured port
+ *   replace    a server of this install from before an update answers: it is
+ *              asked to shut down, and the new version starts in its place
+ *   refuse     another installation of SynaBun answers on the port with this
+ *              same data home (or cannot say which one it uses): it is never
+ *              stopped or adopted, and the window says so
+ *   move       the port is taken by something else (a program, a SynaBun on
+ *              another data home): this install starts on a free port
+ *
+ * Every step is reported as an event ({ type: 'plan' | 'existing' | 'step' |
+ * 'supervisor' | 'ready' | 'conflict' | 'failed', ... }); the window shows them.
+ */
+
+import { createHash } from 'node:crypto';
+import { realpathSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/**
+ * Which data home a server uses, without saying where it is: the first 16 hex
+ * characters of a SHA-256 of its real path (lower case on Windows, where case
+ * does not tell paths apart). /api/health reports it, so the app can tell a
+ * second copy on the same data from one on another.
+ */
+export function dataHomeId(dataHome, platform = process.platform) {
+  let path = resolve(String(dataHome || ''));
+  try { path = realpathSync.native(path); } catch {}
+  if (platform === 'win32') path = path.toLowerCase();
+  return createHash('sha256').update(path).digest('hex').slice(0, 16);
+}
+
+function samePath(a, b, platform) {
+  const norm = (value) => {
+    let path = String(value || '').replace(/\\/g, '/');
+    try { path = realpathSync.native(path).replace(/\\/g, '/'); } catch {}
+    return platform === 'win32' ? path.toLowerCase() : path;
+  };
+  return !!a && !!b && norm(a) === norm(b);
+}
+
+/**
+ * What answers on a port, for this install:
+ *   'none'               nothing answers
+ *   'other'              something answers that is not a SynaBun server
+ *   'ours'               this install, this version
+ *   'ours-stale'         this install, another version (from before an update)
+ *   'foreign'            another installation, on another data home
+ *   'foreign-same-data'  another installation on this data home, or one that does not say
+ */
+export function classifyServer(health, { entry, packageRoot, version, dataHomeId: ours, platform = process.platform, answered = true } = {}) {
+  if (!health) return { kind: answered ? 'other' : 'none' };
+  if (health.ok !== true || health.storage !== 'sqlite' || typeof health.projectDir !== 'string') return { kind: 'other', health };
+  // This install: the entry it runs from (installEntry; `entry` is only the path that outlives the run, empty for a
+  // copy on its disk image or a translocated one), or the very same application folder. An AppImage's folder is a
+  // new mount every run, and its entry (the image file) is what matches.
+  const theirEntry = health.installEntry || health.entry;
+  if ((entry && theirEntry && samePath(theirEntry, entry, platform)) || (packageRoot && samePath(health.projectDir, packageRoot, platform))) {
+    return { kind: String(health.version || '') === String(version) ? 'ours' : 'ours-stale', health };
+  }
+  if (health.dataHomeId && health.dataHomeId !== ours) return { kind: 'foreign', health };
+  // Said so (the same data home), or said nothing (a server from before 2026-10-17 reports no data home).
+  return { kind: 'foreign-same-data', health, known: !!health.dataHomeId };
+}
+
+/** A server that answers its health check completely: ready for the window. */
+export function serverReady(health) {
+  return !!health && health.ok === true && health.storage === 'sqlite' && typeof health.projectDir === 'string' && !!health.startLauncher;
+}
+
+async function defaultHealth(port, { fetchImpl = globalThis.fetch, timeoutMs = 1500 } = {}) {
+  try {
+    const response = await fetchImpl(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: 'application/json' } });
+    if (!response.ok) return { status: response.status };
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+
+/**
+ * Find or start the server for the desktop app. Resolves with the final event
+ * ('ready', 'conflict' or 'failed'); `emit` receives every event on the way.
+ * Everything that touches the system is a parameter, for the tests.
+ */
+export async function runAppBackend({
+  env = process.env,
+  runtime,
+  packageRoot,
+  dataHome,
+  preferPort = null,
+  platform = process.platform,
+  emit = () => {},
+  launcher,            // lib/start-launcher.js (runLauncher, resolvePort, portAccepts, launcherStatePaths, pidAlive)
+  backgroundCommand,   // lib/desktop-pwa.js: the background start of a packaged build
+  spawn,
+  health = defaultHealth,
+  shutdown = null,
+  sleep = (ms) => new Promise(done => setTimeout(done, ms)),
+  now = () => Date.now(),
+  readyWaitMs = 5 * 60 * 1000,
+  searchSpan = 20,
+} = {}) {
+  const ours = { entry: runtime?.entry || null, packageRoot: packageRoot || runtime?.packageRoot || null, version: runtime?.version || '', dataHomeId: dataHomeId(dataHome, platform), platform };
+  const { runLauncher, resolvePort, portAccepts, launcherStatePaths, pidAlive } = launcher;
+  const configured = resolvePort({ env, dataHome });
+  const paths = launcherStatePaths(dataHome);
+  const supervisorRecord = () => readJson(paths.supervisor);
+  const look = async (port) => {
+    const answer = await health(port);
+    if (answer && answer.ok === undefined && answer.status) return classifyServer(null, { ...ours, answered: true });
+    if (answer) return classifyServer(answer, ours);
+    return classifyServer(null, { ...ours, answered: await portAccepts(port).catch(() => false) });
+  };
+  const ready = (port, extra) => {
+    const record = supervisorRecord();
+    return { type: 'ready', port, supervisorPid: record && !record.endedAt && pidAlive(record.pid) ? record.pid : null, ...extra };
+  };
+  const conflict = (port, found) => ({ type: 'conflict', port, projectDir: found.health?.projectDir || null, install: found.health?.install || null, version: found.health?.version || null });
+
+  emit({ type: 'plan', dataHome, port: configured, preferredPort: configured, dataHomeId: ours.dataHomeId });
+
+  // This install's server from before an update: its files are gone or replaced. It goes; the new one starts.
+  const stopStale = async (stalePort, staleVersion) => {
+    const asked = shutdown ? await shutdown(stalePort) : false;
+    const deadline = now() + 20000;
+    while (await portAccepts(stalePort).catch(() => false)) {
+      if (now() >= deadline) return { type: 'failed', code: 'STALE_SERVER', message: `An older SynaBun server of this copy (v${staleVersion}) still runs on port ${stalePort} and did not stop${asked ? '' : ' when asked'}.`, log: paths.log };
+      await sleep(300);
+    }
+    return null;
+  };
+
+  // 1. A server of this install that is already up: where the window was last,
+  //    or where this data home's supervisor says its server listens. Another
+  //    installation on this data home there is never a reason to start a second one.
+  const record = supervisorRecord();
+  const recordPort = record && !record.endedAt && pidAlive(record.pid) && record.phase === 'listening' ? Number(record.detail?.port) || null : null;
+  for (const earlier of [...new Set([preferPort, recordPort].filter(value => value && value !== configured))]) {
+    const seen = await look(earlier);
+    if (seen.kind === 'none') continue;
+    emit({ type: 'existing', port: earlier, kind: seen.kind, version: seen.health?.version || null });
+    if (seen.kind === 'ours') return finish(ready(earlier, { reused: true, started: false, version: seen.health.version }));
+    // Another installation on this data home, or one too old to say which data home it uses (every server from
+    // before 2026-10-17): the window is told where it runs. Starting this install beside it could mean two
+    // servers on one data home.
+    if (seen.kind === 'foreign-same-data') return finish(conflict(earlier, seen));
+    if (seen.kind === 'ours-stale') {
+      const failed = await stopStale(earlier, seen.health.version);
+      if (failed) return finish(failed);
+    }
+  }
+
+  // 2. The configured port.
+  let port = configured;
+  let alternative = false;
+  const found = await look(configured);
+  if (found.kind !== 'none') emit({ type: 'existing', port: configured, kind: found.kind, version: found.health?.version || null });
+  if (found.kind === 'ours') return finish(ready(configured, { reused: true, started: false, version: found.health.version }));
+  if (found.kind === 'foreign-same-data') return finish(conflict(configured, found));
+  if (found.kind === 'ours-stale') {
+    const failed = await stopStale(configured, found.health.version);
+    if (failed) return finish(failed);
+  } else if (found.kind === 'foreign' || found.kind === 'other') {
+    const free = await freePort([preferPort, ...Array.from({ length: searchSpan }, (_, i) => configured + 1 + i)]);
+    if (!free) return finish({ type: 'failed', code: 'NO_PORT', message: `Port ${configured} is in use by another program, and no free port was found near it.`, log: paths.log });
+    port = free;
+    alternative = true;
+    emit({ type: 'plan', dataHome, port, preferredPort: configured, alternativePort: true, dataHomeId: ours.dataHomeId });
+  }
+
+  async function freePort(candidates) {
+    for (const candidate of [...new Set(candidates.filter(value => Number.isInteger(value) && value > 0 && value < 65536))]) {
+      if (!(await portAccepts(candidate).catch(() => true))) return candidate;
+    }
+    return null;
+  }
+
+  // 3. Start, through the launcher (lock, supervisor record, background start).
+  let launcherPid = null;
+  let lastPhase = null;
+  const reportPhase = (current) => {
+    if (!current?.phase || current.phase === lastPhase) return;
+    lastPhase = current.phase;
+    emit({ type: 'supervisor', phase: current.phase, detail: current.detail || null });
+  };
+  const reporter = () => ({
+    get listening() { return false; },
+    listen: async () => false,
+    step: (id) => emit({ type: 'step', id: String(id) }),
+    supervisor: reportPhase,
+    finish: () => {},
+    linger: async () => {},
+    close: () => {},
+  });
+  const result = await runLauncher({
+    argv: ['--port', String(port)],
+    env: { ...env, NEURAL_PORT: String(port) },
+    packageRoot,
+    background: true,
+    beacon: reporter,
+    spawnImpl: (file, args, options) => {
+      const command = backgroundCommand(runtime, options.env);
+      const child = spawn(command.file, command.args, { ...options, env: command.env, cwd: command.cwd || options.cwd });
+      launcherPid = child.pid || null;
+      return child;
+    },
+  });
+  if (result.outcome === 'failed') {
+    const failure = supervisorRecord();
+    return finish({ type: 'failed', code: failure?.error?.code || 'START_FAILED', message: failure?.phase === 'failed' && failure.error?.message ? failure.error.message : 'SynaBun\'s server could not be started.', log: paths.log });
+  }
+
+  // 4. Until it answers completely (a first start downloads the automation browser and backs up the data).
+  const deadline = now() + readyWaitMs;
+  for (;;) {
+    const answer = await health(port);
+    if (serverReady(answer)) {
+      const kind = classifyServer(answer, ours).kind;
+      if (kind !== 'ours') return finish(kind === 'foreign-same-data' ? conflict(port, { health: answer }) : { type: 'failed', code: 'NOT_OURS', message: `Another program took port ${port} while SynaBun started.`, log: paths.log });
+      return finish(ready(port, { reused: result.outcome !== 'started', started: result.outcome === 'started', launcherPid, version: answer.version, alternativePort: alternative, preferredPort: configured }));
+    }
+    const current = supervisorRecord();
+    reportPhase(current);
+    if (current?.phase === 'failed' && current.error) return finish({ type: 'failed', code: current.error.code || 'START_FAILED', message: current.error.message, log: paths.log });
+    if (now() >= deadline) return finish({ type: 'failed', code: 'NO_ANSWER', message: `SynaBun's server did not answer within ${Math.round(readyWaitMs / 60000)} minutes.`, log: paths.log });
+    await sleep(400);
+  }
+
+  function finish(event) {
+    emit(event);
+    return event;
+  }
+}
+
+/** POST /api/server/shutdown on the loopback address: the server's own graceful stop. */
+export async function requestServerShutdown(port, { fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const response = await fetchImpl(`http://127.0.0.1:${port}/api/server/shutdown`, {
+      method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}', signal: AbortSignal.timeout(3000),
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+/** Where the launcher writes its log for a data home (what "Open logs" shows). */
+export function launcherLogOf(dataHome) {
+  return join(dataHome, 'data', 'launcher.log');
+}

package/lib/external-tools.js

@@ -2,9 +2,13 @@
  * SynaBun — external tools stay external
  *
  * Claude Code, Codex, OpenCode and Gemini CLI are programs of their own. The
- * user installs them; SynaBun finds what is installed (PATH, Homebrew, npm, the
- * native installers' folders) and talks to it, through a thin JavaScript SDK
- * where there is one. It never installs, ships or runs a copy of its own.
+ * user installs them; SynaBun finds what is installed (Settings, PATH and the
+ * OS PATH, the folders of every install method:
+ * neural-interface/lib/cli-resolver.js) and talks to it, through a thin
+ * JavaScript SDK where there is one. It never ships or runs a copy of its own.
+ * When one is missing, the side panels can run its vendor's official installer
+ * on the user's click (neural-interface/lib/cli-install.js), which installs it
+ * where that installer always does, as the user's own.
  *
  * npm has no way to say "this SDK, without the program it carries": the Claude
  * Agent SDK brings the Claude Code executable as a per-platform optional