synabun 2.0.5 → 2.0.7

package/neural-interface/lib/claude-executable.js

@@ -10,7 +10,12 @@
 //
 //   resolveClaudeLauncher        what a terminal or a shell would start: the
 //                                user's configured command, else the first
-//                                `claude` on PATH that is not inside SynaBun
+//                                `claude` on PATH that is not inside SynaBun.
+//                                server.js asks lib/cli-resolver.js instead
+//                                (Settings, PATH and the OS PATH, the known
+//                                install folders, a --version that answers),
+//                                which follows a Windows `claude.cmd` with
+//                                windowsClaudeTargets below
 //   resolveClaudeSdkExecutable   what the SDK can start. It spawns with
 //                                shell:false, so an npm command file on Windows
 //                                is followed to the executable behind it

package/neural-interface/lib/claude-model-catalog.js

@@ -14,7 +14,7 @@ import { spawn } from 'node:child_process';
 import { dirname, join, sep } from 'node:path';
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { getAugmentedPath } from './augmented-path.js';
+import { withPathEnv, getAugmentedPath } from './augmented-path.js';
 
 // Effort ladder the Claude Code CLI accepts for --effort. Models advertise their
 // own subset via supportedEffortLevels; this is the superset used as a fallback
@@ -240,7 +240,7 @@ export function queryClaudeCliModels(claudeBin, { cwd, timeoutMs = DISCOVERY_TIM
     try {
       child = spawnImpl(shellCommand(bin, useShell), args, {
         cwd: cwd || process.cwd(),
-        env: { ...process.env, PATH: getAugmentedPath(), CLAUDE_CODE_ENTRYPOINT: 'sdk-cli' },
+        env: { ...withPathEnv(process.env, getAugmentedPath()), CLAUDE_CODE_ENTRYPOINT: 'sdk-cli' },
         stdio: ['pipe', 'pipe', 'ignore'],
         shell: useShell,
       });
@@ -400,7 +400,7 @@ export function queryClaudeCliVersion(claudeBin, { timeoutMs = 10000 } = {}) {
 
     try {
       child = spawn(shellCommand(bin, useShell), args, {
-        env: { ...process.env, PATH: getAugmentedPath() },
+        env: withPathEnv(process.env, getAugmentedPath()),
         stdio: ['ignore', 'pipe', 'ignore'],
         shell: useShell,
       });

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

@@ -0,0 +1,221 @@
+// Claude owns OAuth credentials and refresh. SynaBun owns only pasted keys
+// in a separate private profile file; this adapter exposes safe auth status.
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { verifyClaudeApiKey } from './claude-profile-api-key.js';
+import { validateProviderApiKey, redactProviderSecrets } from './provider-panel-api-key-auth.js';
+
+export function claudeAuthEnv(env, accountEnv) {
+  const clean = { ...env };
+  for (const key of Object.keys(clean)) {
+    if (/^(CLAUDECODE|CLAUDE_CONFIG_DIR|CLAUDE_CODE_OAUTH_TOKEN|CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR|ANTHROPIC_AUTH_TOKEN|ANTHROPIC_API_KEY|ANTHROPIC_API_KEY_FILE_DESCRIPTOR|CLAUDE_CODE_USE_BEDROCK|CLAUDE_CODE_USE_VERTEX|CLAUDE_CODE_USE_FOUNDRY)$/.test(key)) delete clean[key];
+  }
+  return { ...clean, ...accountEnv, NO_COLOR: '1', FORCE_COLOR: '0' };
+}
+
+export function claudeAuthorizationUrl(text) {
+  for (const match of text.matchAll(/https:\/\/[^\s<>"\x1b]+/g)) {
+    try {
+      const url = new URL(match[0]);
+      if (['claude.ai', 'console.anthropic.com', 'platform.claude.com'].includes(url.hostname)
+        && !url.username && !url.password && url.searchParams.has('client_id') && url.searchParams.has('code_challenge')) return url.href;
+    } catch {}
+  }
+  return '';
+}
+
+export function createClaudePanelAuth({ accounts, executable, env = () => process.env, spawnProcess = spawn, timeoutMs = 10 * 60_000, statusTimeoutMs = 15_000, verifyKey = verifyClaudeApiKey, changeCredentials = async (_id, change) => change() } = {}) {
+  const operations = new Map();
+  function account(id = 'default') {
+    if (typeof id !== 'string' || !/^[a-z0-9-]{1,64}$/.test(id)) throw Object.assign(new Error('Unknown Claude account'), { status: 404 });
+    const row = accounts.profileFor ? accounts.profileFor(id) : accounts.get(id);
+    if (!row || row.id !== id) throw Object.assign(new Error('Unknown Claude account'), { status: 404 });
+    return row;
+  }
+  function launch(id, args, extraEnv = {}) {
+    account(id);
+    const found = executable();
+    if (!found?.path) throw new Error(found?.reason || 'Claude CLI not found. Install Claude Code to sign in.');
+    const script = /\.[cm]?js$/i.test(found.path);
+    const proc = spawnProcess(script ? process.execPath : found.path, script ? [found.path, ...args] : args, {
+      env: { ...claudeAuthEnv(env(), accounts.envFor(id)), ...extraEnv }, stdio: ['pipe', 'pipe', 'pipe'], shell: false, windowsHide: true,
+    });
+    proc.stdin?.on('error', () => {}); // A native exit can race a manual-code write.
+    return proc;
+  }
+  // Claude Code's own answer about the account's login (never a credential).
+  function nativeStatus(id = 'default') {
+    account(id);
+    return new Promise((resolve, reject) => {
+      let proc;
+      try { proc = launch(id, ['auth', 'status', '--json']); } catch (error) { reject(error); return; }
+      let output = '', settled = false;
+      const finish = (error, result) => { if (settled) return; settled = true; clearTimeout(timer); error ? reject(error) : resolve(result); };
+      const timer = setTimeout(() => { proc.kill(); finish(new Error('Claude authentication status timed out. Try Refresh.')); }, statusTimeoutMs);
+      proc.stdout.on('data', chunk => { output = (output + chunk).slice(-65536); });
+      proc.stderr.on('data', () => {}); // Never forward CLI output or credential-bearing errors.
+      proc.on('error', () => finish(new Error('Could not start Claude Code. Check its installation.')));
+      proc.on('close', () => {
+        try {
+          const data = JSON.parse(output);
+          if (typeof data.loggedIn !== 'boolean') throw new Error();
+          finish(null, {
+            loggedIn: data.loggedIn, email: redactProviderSecrets(data.email || null), orgName: redactProviderSecrets(data.orgName || null),
+            authMethod: redactProviderSecrets(data.authMethod || null), subscriptionType: redactProviderSecrets(data.subscriptionType || null),
+          });
+        } catch { finish(new Error('Could not read Claude authentication. Update Claude Code to a version supporting auth status --json.')); }
+      });
+    });
+  }
+  // The account as every surface shows it (lib/claude-accounts.js describe()),
+  // after asking Claude Code about its subscription login. A failed check of an
+  // account that still has a usable API key is not an error: the key is used.
+  async function read(id = 'default') {
+    account(id);
+    // An account running on its API key is signed in whatever its subscription
+    // says: no process is started for the answer. The subscription half is
+    // asked in the background, so the account list can show it later.
+    const current = accounts.describeForClient?.(id);
+    if (current?.mode === 'apiKey' && current.signedIn === true) {
+      Promise.resolve(accounts.refreshStatus?.([id])).catch(() => {});
+      return { accountId: id, account: current, state: snapshot(id) };
+    }
+    let status = null, failure = null;
+    try { status = await nativeStatus(id); } catch (error) { failure = error; }
+    account(id); // A profile removed meanwhile is gone, whatever the CLI said.
+    if (status) accounts.noteNativeStatus?.(id, status);
+    const row = accounts.describeForClient ? accounts.describeForClient(id) : null;
+    if (failure && !(row?.mode === 'apiKey' && row.signedIn)) throw failure;
+    return { accountId: id, account: row || legacyAccount(id, status), state: snapshot(id) };
+  }
+  // A host without the account model (an older caller, a test double).
+  function legacyAccount(id, status) {
+    if (accounts.readApiKey?.(id)) return { loggedIn: true, email: null, authMethod: 'apiKey', subscriptionType: null };
+    return { loggedIn: status.loggedIn, email: status.email, authMethod: status.authMethod, subscriptionType: status.subscriptionType };
+  }
+  const keyPending = new Set();
+  async function signInApiKey(id, key) {
+    account(id); key = validateProviderApiKey('claude', key);
+    if (keyPending.has(id) || ['starting', 'pending'].includes(snapshot(id).status)) throw Object.assign(new Error('Sign-in already pending'), { status: 409 });
+    keyPending.add(id);
+    try {
+      await verifyKey(key);
+      account(id); // A removed profile must never be recreated by a late reply.
+      await changeCredentials(id, () => { account(id); accounts.saveApiKey(id, key); });
+      operations.set(id, { status: 'success', authUrl: '' });
+    } finally { keyPending.delete(id); key = null; }
+  }
+  // `credential`: 'apiKey' removes the key SynaBun keeps, 'subscription' runs
+  // Claude Code's own logout in the account's config directory, 'all' both.
+  async function signOut(id, credential = 'all') {
+    account(id);
+    if (!['all', 'apiKey', 'subscription'].includes(credential)) throw Object.assign(new Error('Choose which sign-in to remove.'), { status: 400 });
+    if (keyPending.has(id)) throw Object.assign(new Error('Sign-in already pending'), { status: 409 });
+    const op = operations.get(id);
+    if (op && ['starting', 'pending'].includes(op.status) && credential !== 'apiKey') cancel(id, op.operationId);
+    keyPending.add(id);
+    try {
+      await changeCredentials(id, async () => {
+        if (credential !== 'subscription') accounts.clearApiKey(id);
+        if (credential === 'apiKey') return;
+        operations.delete(id);
+        await new Promise((resolve, reject) => {
+          let proc, timer;
+          try { proc = launch(id, ['auth', 'logout']); } catch { reject(new Error('Could not sign out of Claude. Try again.')); return; }
+          let settled = false;
+          const finish = ok => { if (settled) return; settled = true; clearTimeout(timer); ok ? resolve() : reject(new Error('Could not sign out of Claude. Try again.')); };
+          proc.stdout.on('data', () => {}); proc.stderr.on('data', () => {});
+          proc.on('error', () => finish(false)); proc.on('close', code => finish(code === 0));
+          timer = setTimeout(() => { proc.kill(); finish(false); }, statusTimeoutMs);
+        });
+        accounts.noteNativeStatus?.(id, { loggedIn: false });
+      });
+    } finally { keyPending.delete(id); }
+  }
+  // What the account's sessions use from now on; its idle panel processes end
+  // so the next message starts under the new credential.
+  async function setMode(id, mode) {
+    account(id);
+    if (keyPending.has(id) || ['starting', 'pending'].includes(snapshot(id).status)) throw Object.assign(new Error('Finish sign-in first.'), { status: 409 });
+    return changeCredentials(id, () => accounts.setMode(id, mode));
+  }
+  function snapshot(id) {
+    const op = operations.get(id);
+    return op ? { accountId: id, operationId: op.operationId, status: op.status, authUrl: op.authUrl, error: op.error || '' } : { accountId: id, status: 'idle' };
+  }
+  function start(id = 'default') {
+    account(id);
+    if (keyPending.has(id)) throw Object.assign(new Error('Sign-in already pending'), { status: 409 });
+    const existing = operations.get(id);
+    if (existing && ['starting', 'pending'].includes(existing.status)) return snapshot(id);
+    // BROWSER is a supported Claude Code handoff. Suppress its OS browser launch:
+    // the panel opens the URL printed by the native command instead.
+    const dir = mkdtempSync(join(tmpdir(), 'synabun-claude-oauth-'));
+    const browser = join(dir, process.platform === 'win32' ? 'browser.cmd' : 'browser');
+    writeFileSync(browser, process.platform === 'win32' ? '@exit /b 0\r\n' : '#!/bin/sh\nexit 0\n', { mode: 0o700 });
+    const op = { operationId: randomUUID(), status: 'starting', authUrl: '', process: null };
+    operations.set(id, op);
+    let timer, forceTimer, output = '';
+    const cleanup = () => { clearTimeout(timer); clearTimeout(forceTimer); rmSync(dir, { recursive: true, force: true }); };
+    const finish = (status, error = '') => {
+      if (!['starting', 'pending'].includes(op.status)) return;
+      op.status = status; op.error = error; op.authUrl = '';
+      clearTimeout(timer);
+    };
+    op.stop = (status, error) => {
+      finish(status, error);
+      op.process?.kill();
+      forceTimer = setTimeout(() => op.process?.kill('SIGKILL'), 2000); forceTimer.unref?.();
+    };
+    try {
+      op.process = launch(id, ['auth', 'login', '--claudeai'], { BROWSER: browser });
+      const collect = chunk => {
+        output = (output + chunk).slice(-65536);
+        if (['starting', 'pending'].includes(op.status)) {
+          const url = claudeAuthorizationUrl(output.slice(0, output.lastIndexOf('\n') + 1));
+          if (url) { op.authUrl = url; op.status = 'pending'; }
+        }
+      };
+      op.process.stdout.on('data', collect); op.process.stderr.on('data', collect);
+      op.process.on('error', () => { finish('error', 'Could not start Claude Code. Check its installation.'); cleanup(); });
+      op.process.on('close', async code => {
+        cleanup();
+        if (!['starting', 'pending'].includes(op.status)) return;
+        if (code !== 0) { finish('error', 'Claude sign-in failed. Retry, or update Claude Code if auth login is unavailable.'); return; }
+        try {
+          const status = await nativeStatus(id);
+          if (status.loggedIn) {
+            // A subscription just signed into is what the account uses from now on.
+            if (accounts.noteSubscriptionSignIn) accounts.noteSubscriptionSignIn(id, status);
+            else accounts.recordIdentity?.(id);
+            finish('success');
+          } else finish('error', 'Claude Code finished without confirming sign-in. Try again.');
+        } catch (error) { finish('error', error.message); }
+      });
+      timer = setTimeout(() => op.stop('error', 'Claude sign-in timed out. Try again.'), timeoutMs); timer.unref?.();
+    } catch (error) { finish('error', error.message); cleanup(); }
+    return snapshot(id);
+  }
+  function cancel(id, operationId) {
+    account(id);
+    const op = operations.get(id);
+    if (!op || op.operationId !== operationId) throw Object.assign(new Error('This sign-in attempt is no longer active. Refresh its status.'), { status: 409 });
+    if (['starting', 'pending'].includes(op.status)) op.stop('cancelled', '');
+    return snapshot(id);
+  }
+  function submitCode(id, operationId, code) {
+    account(id);
+    const op = operations.get(id);
+    if (!op || op.operationId !== operationId || op.status !== 'pending') throw Object.assign(new Error('This sign-in attempt is no longer active. Refresh its status.'), { status: 409 });
+    if (typeof code !== 'string' || !code.trim() || code.length > 4096 || /[\r\n\0]/.test(code)) throw Object.assign(new Error('Paste a single sign-in code from Claude.'), { status: 400 });
+    if (!op.process?.stdin?.writable) throw new Error('Claude Code is no longer accepting a sign-in code. Retry sign-in.');
+    op.process.stdin.write(`${code.trim()}\n`, error => {
+      if (error && op.status === 'pending') op.stop('error', 'Claude Code stopped accepting the sign-in code. Retry sign-in.');
+    });
+    return snapshot(id);
+  }
+  return { start, read, nativeStatus, cancel, submitCode, snapshot, signInApiKey, signOut, setMode, close: () => { for (const [id, op] of operations) if (['starting', 'pending'].includes(op.status)) cancel(id, op.operationId); } };
+}

package/neural-interface/lib/claude-profile-api-key.js

@@ -0,0 +1,62 @@
+// SynaBun's own file, never Claude's native credential store. Atomic 0600 writes
+// work on every supported platform without a Keychain prompt or service naming.
+import { constants, openSync, closeSync, fstatSync, readFileSync, writeFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { validateProviderApiKey, providerApiKeyError } from './provider-panel-api-key-auth.js';
+export const CLAUDE_API_KEY_FILE = '.synabun-api-key';
+// The same file holds an account's key for either provider (Claude: an
+// Anthropic key in its CLAUDE_CONFIG_DIR; Codex: an OpenAI key in its
+// CODEX_HOME, lib/codex-accounts.js), checked against that provider's format.
+export function readProfileApiKey(home, provider = 'claude') {
+  let fd;
+  try {
+    fd = openSync(join(home, CLAUDE_API_KEY_FILE), constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || (process.platform !== 'win32' && (stat.mode & 0o077))) throw new Error('Unsafe credential permissions');
+    return validateProviderApiKey(provider, readFileSync(fd, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error('Could not read the saved API key. Sign in again.');
+  } finally { if (fd !== undefined) closeSync(fd); }
+}
+export function readClaudeProfileApiKey(home) { return readProfileApiKey(home, 'claude'); }
+export function saveProfileApiKey(home, key, provider = 'claude') {
+  key = validateProviderApiKey(provider, key);
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  const target = join(home, CLAUDE_API_KEY_FILE), temp = `${target}.${randomUUID()}.tmp`;
+  try { writeFileSync(temp, key, { mode: 0o600, flag: 'wx' }); renameSync(temp, target); }
+  finally { rmSync(temp, { force: true }); }
+}
+export function saveClaudeProfileApiKey(home, key) { saveProfileApiKey(home, key, 'claude'); }
+export function clearProfileApiKey(home) { rmSync(join(home, CLAUDE_API_KEY_FILE), { force: true }); }
+export function clearClaudeProfileApiKey(home) { clearProfileApiKey(home); }
+export async function verifyClaudeApiKey(key, fetchRequest = fetch) {
+  let response;
+  try {
+    response = await fetchRequest('https://api.anthropic.com/v1/models?limit=1', {
+      headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01' }, signal: AbortSignal.timeout(15000), redirect: 'error',
+    });
+  } catch { throw providerApiKeyError('verification_unreachable'); }
+  finally { key = null; }
+  // Discard the body without letting a cleanup failure mask the HTTP result.
+  // Neither provider response bodies nor exception text are surfaced or logged.
+  try { await response.body?.cancel(); } catch {}
+  if ([401, 403].includes(response.status)) throw providerApiKeyError('key_rejected');
+  if (!response.ok) throw providerApiKeyError('verification_unavailable');
+}
+
+// OpenAI's read-only model list answers whether a key is accepted. The key goes
+// in the Authorization header only; the body and any error text are dropped.
+export async function verifyOpenAiApiKey(key, fetchRequest = fetch) {
+  let response;
+  try {
+    response = await fetchRequest('https://api.openai.com/v1/models', {
+      headers: { authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(15000), redirect: 'error',
+    });
+  } catch { throw providerApiKeyError('verification_unreachable', 'codex'); }
+  finally { key = null; }
+  try { await response.body?.cancel(); } catch {}
+  if ([401, 403].includes(response.status)) throw providerApiKeyError('key_rejected', 'codex');
+  if (!response.ok) throw providerApiKeyError('verification_unavailable', 'codex');
+}

package/neural-interface/lib/cli-install-api.js

@@ -0,0 +1,137 @@
+// ═══════════════════════════════════════════
+// SynaBun — /api/cli/install: the side panels' Install button
+// ═══════════════════════════════════════════
+//
+//   GET  /api/cli/install         { ok, jobs: { [tool]: { state, step, code, error, log, … } } }
+//   POST /api/cli/install/:tool   NDJSON: start, step, progress, log … done (lib/cli-install.js)
+//   GET  /api/cli/git-bash        Git Bash for Claude Code on Windows (lib/git-bash/), and
+//   POST /api/cli/git-bash/install|recheck  its download and a new look (createGitBashApi below)
+//
+// Installing software is the owner's own act on this computer, so these routes
+// take the guards of SynaBun's other local mutating endpoints (lib/http-guards.js,
+// as /api/whatsapp): a loopback socket and no proxy header, a localhost Host,
+// no invite guest; a POST also its own Origin, a JSON body, X-SynaBun-UI: 1 and
+// no agent header. (`/api/cli` is admin-only in lib/request-gate.js too.) A
+// request names a tool and nothing else: what runs is fixed by
+// lib/cli-install.js for this system.
+//
+// Refusals before anything starts are JSON: 400 UNKNOWN_TOOL, 409 BUSY (that
+// tool is being installed), 422 UNSUPPORTED (no one-click method here). A tab
+// that goes away does not stop an install; its result is in GET and in the next
+// /api/system/tool-versions.
+
+import { Router } from 'express';
+import { guestForbidden, noStore, requireLocal, requireLocalHost, requireSameOriginJson, sendGuardError, uiOnly } from './http-guards.js';
+import { openNdjsonStream } from './whatsapp/api.js';
+
+export const INSTALLABLE_TOOLS = Object.freeze(['claude-code', 'codex', 'opencode']);
+
+/**
+ * @param {object} deps
+ * @param {ReturnType<import('./cli-install.js').createCliInstaller>} deps.installer
+ * @param {(req) => boolean} [deps.isGuestRequest]
+ * @param {number|(() => number)} [deps.port]  the port the page is served from (Host / Origin checks)
+ */
+function localCliRouter({ isGuestRequest = () => false, port = 3344 } = {}) {
+  const router = Router();
+  const portOf = () => Number(typeof port === 'function' ? port() : port);
+  const built = new Map();
+  const perPort = (name, factory) => (req, res, next) => {
+    const key = `${name}:${portOf()}`;
+    let guard = built.get(key);
+    if (!guard) {
+      try { guard = factory(portOf()); } catch { return sendGuardError(res, 500, 'BAD_PORT', 'The install API has no valid port.'); }
+      built.set(key, guard);
+    }
+    return guard(req, res, next);
+  };
+
+  router.use(noStore, guestForbidden(isGuestRequest), requireLocal, perPort('host', requireLocalHost));
+  const mutating = [perPort('origin', requireSameOriginJson), uiOnly];
+  return { router, mutating };
+}
+
+export function createCliInstallApi({ installer, isGuestRequest = () => false, port = 3344, log = () => {} } = {}) {
+  if (!installer) throw new Error('createCliInstallApi needs the installer');
+  const { router, mutating } = localCliRouter({ isGuestRequest, port });
+
+  router.get('/', (req, res) => {
+    res.json({ ok: true, jobs: installer.jobs() });
+  });
+
+  router.post('/:tool', ...mutating, (req, res) => {
+    const tool = String(req.params.tool || '');
+    if (!INSTALLABLE_TOOLS.includes(tool)) {
+      return res.status(400).json({ ok: false, code: 'UNKNOWN_TOOL', error: `Unknown CLI: ${tool.slice(0, 40)}` });
+    }
+    let stream = null;
+    const onEvent = (event) => {
+      if (!stream) stream = openNdjsonStream(res);
+      stream.write(event);
+      if (event?.type === 'done') stream.end();
+    };
+    let started;
+    try {
+      started = installer.start(tool, { onEvent });
+    } catch (error) {
+      const code = error?.code === 'busy' ? 'BUSY' : error?.code === 'unsupported' ? 'UNSUPPORTED' : 'INTERNAL';
+      if (code === 'INTERNAL') log(`[cli-install] ${tool} could not start: ${error?.message || error}`);
+      if (stream) return stream.end({ type: 'done', ok: false, code: 'internal', error: String(error?.message || error) });
+      return res.status(code === 'BUSY' ? 409 : code === 'UNSUPPORTED' ? 422 : 500).json({ ok: false, code, error: String(error?.message || error) });
+    }
+    if (!stream) stream = openNdjsonStream(res);
+    stream.onAbort(() => started.unsubscribe());
+  });
+
+  return router;
+}
+
+/**
+ * /api/cli/git-bash: the Git Bash every Claude Code SynaBun starts gets on Windows (lib/git-bash/manager.js),
+ * beside the CLIs' install and PATH, with the same guards.
+ *
+ *   GET  /           { ok, state: unsupported | system | ready | missing | downloading | failed, … }
+ *   POST /install    start the download of SynaBun's copy now (Settings: Download, Try again); answers at once,
+ *                    the page follows it with GET. 422 UNSUPPORTED where there is no Windows Git to fetch
+ *   POST /recheck    look again (a Git for Windows installed meanwhile), then the status
+ *
+ * A request names nothing: what is downloaded is the pinned release (lib/git-bash/pins.json), and a body is refused.
+ */
+export function createGitBashApi({ manager, onRecheck = async () => {}, isGuestRequest, port } = {}) {
+  if (!manager) throw new Error('createGitBashApi needs the Git Bash manager');
+  const { router, mutating } = localCliRouter({ isGuestRequest, port });
+  const noBody = (req, res, next) => (Object.keys(req.body || {}).length ? res.status(400).json({ ok: false, code: 'UNEXPECTED_BODY' }) : next());
+  router.get('/', (req, res) => { res.json({ ok: true, ...manager.status() }); });
+  router.post('/install', ...mutating, noBody, (req, res) => {
+    const before = manager.status();
+    if (before.state === 'unsupported') return res.status(422).json({ ok: false, code: 'UNSUPPORTED', ...before });
+    manager.ensure({ reason: 'settings' });
+    res.json({ ok: true, ...manager.status() });
+  });
+  router.post('/recheck', ...mutating, noBody, async (req, res) => {
+    manager.refresh();
+    try { await onRecheck(); } catch { /* the status says what is known */ }
+    res.json({ ok: true, ...manager.status() });
+  });
+  return router;
+}
+
+/** The same owner/localhost/Origin/UI guards as Install. Never accepts a folder. */
+export function createCliPathApi({ pathManager, resolver, diagnostics = async () => ({}), isGuestRequest, port } = {}) {
+  const { router, mutating } = localCliRouter({ isGuestRequest, port });
+  router.get('/', async (req, res) => {
+    try { res.json({ ok: true, ...await diagnostics() }); }
+    catch (error) { res.status(500).json({ ok: false, error: error.message }); }
+  });
+  router.post('/:tool', ...mutating, async (req, res) => {
+    if (!INSTALLABLE_TOOLS.includes(req.params.tool)) return res.status(400).json({ ok: false, code: 'UNKNOWN_TOOL' });
+    if (Object.keys(req.body || {}).length) return res.status(400).json({ ok: false, code: 'UNEXPECTED_BODY' });
+    try {
+      const status = await resolver.resolve(req.params.tool, { force: true });
+      const result = await pathManager.add(status);
+      if (!result.changed) return res.status(409).json({ ok: false, code: 'NOT_NEEDED', ...result });
+      res.json({ ok: true, ...result });
+    } catch (error) { res.status(error.status || 500).json({ ok: false, error: error.message }); }
+  });
+  return router;
+}