synabun 2.0.5 → 2.0.7

package/neural-interface/lib/os-path.js

@@ -0,0 +1,319 @@
+// ═══════════════════════════════════════════
+// SynaBun — the OS PATH a new terminal would get
+// ═══════════════════════════════════════════
+//
+// A process keeps the PATH it was started with. SynaBun started from Finder,
+// the Dock, the Start menu or a login item got the desktop's PATH, often
+// without ~/.local/bin or Homebrew; started before a CLI was installed, it
+// never sees the folder the installer added. This reads the PATH the
+// operating system would give a terminal opened now:
+//
+//   Windows        the machine PATH, then the user PATH, from the registry
+//                  (`reg query`; REG_EXPAND_SZ expanded with this process's
+//                  environment), which is how Windows builds a new process's
+//                  PATH. No PowerShell.
+//   macOS, Linux   the PATH the user's login shell ends up with
+//                  (`$SHELL -i -l -c`, which runs .zprofile/.zshrc,
+//                  .bash_profile/.bashrc: nvm, asdf, mise, fnm, Homebrew's
+//                  shellenv), started from the launchd default PATH, in a
+//                  session of its own with no terminal, under a short timeout;
+//                  on macOS also /etc/paths and /etc/paths.d
+//
+// The answer is cached briefly (`ttlMs`), read again in the background when it
+// goes stale, and handed to augmented-path.js (rememberOsPath), whose PATH
+// every lookup and spawn of a user's CLI uses. Re-check reads it again at once
+// (refresh({ force: true })). A failed read keeps the previous answer and is
+// retried sooner. Nothing here throws.
+
+import { execFile, spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { readFileSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { rememberOsPath } from './augmented-path.js';
+
+/** Where Windows keeps PATH: the machine's, then the user's (the order Windows joins them in). */
+export const WINDOWS_PATH_KEYS = Object.freeze([
+  'HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment',
+  'HKCU\\Environment',
+]);
+
+/** The PATH launchd gives an app on macOS (and a sane start on Linux): what a new terminal's shell begins from. */
+export const LAUNCHD_PATH = '/usr/bin:/bin:/usr/sbin:/sbin';
+
+/** Shells that take `-i -l -c`. Others (csh, nu, xonsh, pwsh …) are read through /bin/sh -l. */
+const INTERACTIVE_LOGIN_SHELLS = new Set(['bash', 'zsh', 'ksh', 'ksh93', 'mksh', 'fish', 'yash']);
+const LOGIN_ONLY_SHELLS = new Set(['sh', 'dash']);
+const MAX_SHELL_OUTPUT = 1024 * 1024;
+
+export function splitPathValue(value, platform = process.platform) {
+  return String(value || '').split(platform === 'win32' ? ';' : ':')
+    .map(entry => platform === 'win32' ? entry.trim().replace(/^"(.*)"$/, '$1').trim() : entry.trim())
+    .filter(Boolean);
+}
+
+export function dedupePath(entries, platform = process.platform) {
+  const seen = new Set();
+  return entries.filter((entry) => {
+    const text = String(entry || '').trim();
+    if (!text) return false;
+    const key = platform === 'win32' ? text.toLowerCase().replace(/[\\/]+$/, '') : text.replace(/\/+$/, '') || '/';
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * The Path value in what `reg query <key> /v Path` prints:
+ *
+ *   HKEY_CURRENT_USER\Environment
+ *       Path    REG_EXPAND_SZ    %USERPROFILE%\AppData\Local\Microsoft\WindowsApps;C:\Users\you\.local\bin
+ *
+ * → { type: 'REG_EXPAND_SZ', value: '…' }, or null when there is none.
+ */
+export function parseRegQuery(text) {
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const match = line.match(/^\s+(\S+)\s+(REG_EXPAND_SZ|REG_SZ)(?:\s+(.*))?$/i);
+    if (match && match[1].toLowerCase() === 'path') return { type: match[2].toUpperCase(), value: (match[3] || '').trim() };
+  }
+  return null;
+}
+
+/** %NAME% replaced from `env` (names compared without case, as Windows does); unknown names stay as written. */
+export function expandWindowsVars(value, env = process.env) {
+  const lookup = new Map(Object.entries(env || {}).map(([name, val]) => [name.toUpperCase(), val]));
+  return String(value || '').replace(/%([^%;]+)%/g, (whole, name) => {
+    const found = lookup.get(name.toUpperCase());
+    return found == null || found === '' ? whole : String(found);
+  });
+}
+
+function decodeUtf8(buffer) {
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(buffer); } catch { return null; }
+}
+
+/**
+ * `reg query <key> /v Path`, its output as text. reg.exe writes in the
+ * console's code page; a folder name outside ASCII (C:\Users\João) is then not
+ * UTF-8, and the query is asked again through a console switched to UTF-8
+ * (chcp 65001). Fixed strings only: nothing of a request reaches either line.
+ */
+export async function runRegQuery(key, { env = process.env, timeoutMs = 3000, execFileImpl = execFile } = {}) {
+  const systemRoot = env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows';
+  const reg = path.win32.join(systemRoot, 'System32', 'reg.exe');
+  const comspec = env.ComSpec || env.COMSPEC || path.win32.join(systemRoot, 'System32', 'cmd.exe');
+  const run = (file, args, extra = {}) => new Promise((resolve) => {
+    try {
+      execFileImpl(file, args, { encoding: 'buffer', timeout: timeoutMs, windowsHide: true, env, maxBuffer: 1024 * 1024, ...extra }, (error, stdout) => {
+        resolve({ error, stdout: Buffer.isBuffer(stdout) ? stdout : Buffer.from(String(stdout || '')) });
+      });
+    } catch (error) {
+      resolve({ error, stdout: Buffer.alloc(0) });
+    }
+  });
+  const first = await run(reg, ['query', key, '/v', 'Path']);
+  if (!first.stdout.length) throw first.error || new Error('reg.exe printed nothing');
+  const text = decodeUtf8(first.stdout);
+  if (text !== null) return text;
+  const second = await run(comspec, ['/d', '/s', '/c', `"chcp 65001 >nul & "${reg}" query "${key}" /v Path"`], { windowsVerbatimArguments: true });
+  return (second.stdout.length && decodeUtf8(second.stdout)) || first.stdout.toString('latin1');
+}
+
+/** The registry's PATH: machine entries, then user entries, each once. */
+export async function readWindowsPath({ env = process.env, query = runRegQuery, timeoutMs = 3000 } = {}) {
+  const entries = [];
+  const sources = [];
+  const errors = [];
+  for (const key of WINDOWS_PATH_KEYS) {
+    try {
+      const found = parseRegQuery(await query(key, { env, timeoutMs }));
+      if (found) {
+        const part = splitPathValue(expandWindowsVars(found.value, env), 'win32');
+        entries.push(...part);
+        sources.push(...part.map(dir => ({ dir, source: key.startsWith('HKLM') ? 'system' : 'user' })));
+      }
+    } catch (error) {
+      errors.push(`${key}: ${String(error?.message || error).split(/\r?\n/)[0]}`);
+    }
+  }
+  return { entries: dedupePath(entries, 'win32'), sources, ok: entries.length > 0, errors };
+}
+
+/** The user's login shell: $SHELL, else the account's (a launchd- or desktop-started app may have no SHELL). */
+export function loginShellOf({ env = process.env, userInfo = () => os.userInfo() } = {}) {
+  if (env.SHELL) return env.SHELL;
+  try { return userInfo()?.shell || null; } catch { return null; }
+}
+
+/**
+ * How to ask `shell` for the PATH a login session ends with. The PATH is
+ * printed on a line of its own between two marker lines, so whatever the
+ * startup files print around it (banners, warnings) is ignored.
+ */
+export function loginShellCommand(shell, marker) {
+  const name = path.posix.basename(String(shell || '')).toLowerCase();
+  const script = `printf '%s\\n' '${marker}' "$PATH" '${marker}'`;
+  if (INTERACTIVE_LOGIN_SHELLS.has(name)) return { file: shell, args: ['-i', '-l', '-c', script] };
+  if (LOGIN_ONLY_SHELLS.has(name)) return { file: shell, args: ['-l', '-c', script] };
+  return { file: '/bin/sh', args: ['-l', '-c', script] };
+}
+
+/** The PATH line between the two markers, or null. */
+export function parseLoginShellOutput(text, marker) {
+  const lines = String(text || '').split(/\r?\n/);
+  for (let i = 0; i + 2 < lines.length; i++) {
+    if (lines[i] === marker && lines[i + 2] === marker) return lines[i + 1];
+  }
+  return null;
+}
+
+/**
+ * The PATH the user's login shell builds. Started in a session of its own
+ * (detached: no controlling terminal, so a startup file cannot wait on
+ * /dev/tty), from the launchd default PATH, in the home folder; killed with
+ * its whole group after `timeoutMs`.
+ */
+export function readLoginShellPath({
+  env = process.env,
+  platform = process.platform,
+  shell = loginShellOf({ env }),
+  spawnImpl = spawn,
+  timeoutMs = 4000,
+  home = env.HOME || os.homedir(),
+} = {}) {
+  return new Promise((resolve) => {
+    const marker = `SYNABUN_PATH_${randomBytes(6).toString('hex').toUpperCase()}`;
+    const command = loginShellCommand(shell || '/bin/sh', marker);
+    const childEnv = { ...env, PATH: LAUNCHD_PATH, TERM: 'dumb' };
+    let child = null;
+    let out = '';
+    let settled = false;
+    let timer = null;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ shell: command.file, ...result });
+    };
+    const killGroup = () => {
+      try { process.kill(-child.pid, 'SIGKILL'); } catch { try { child?.kill('SIGKILL'); } catch { /* gone */ } }
+    };
+    try {
+      child = spawnImpl(command.file, command.args, { env: childEnv, cwd: home, stdio: ['ignore', 'pipe', 'ignore'], detached: platform !== 'win32' });
+    } catch (error) {
+      return finish({ entries: [], ok: false, error: `${command.file} could not be started: ${error?.message || error}` });
+    }
+    timer = setTimeout(() => {
+      killGroup();
+      finish({ entries: [], ok: false, error: `${command.file} did not answer within ${Math.round(timeoutMs / 100) / 10} s` });
+    }, timeoutMs);
+    timer.unref?.();
+    child.on('error', (error) => finish({ entries: [], ok: false, error: `${command.file} could not be started: ${error?.message || error}` }));
+    child.stdout?.setEncoding?.('utf8');
+    child.stdout?.on('data', (chunk) => {
+      out += chunk;
+      if (out.length > MAX_SHELL_OUTPUT) {
+        killGroup();
+        finish({ entries: [], ok: false, error: `${command.file} printed too much` });
+      }
+    });
+    child.on('close', () => {
+      const line = parseLoginShellOutput(out, marker);
+      if (line == null) return finish({ entries: [], ok: false, error: `${command.file} did not print a PATH` });
+      finish({ entries: dedupePath(splitPathValue(line, platform), platform), ok: true, error: null });
+    });
+  });
+}
+
+/** macOS's /etc/paths, then each file of /etc/paths.d in name order (what path_helper builds a login PATH from). */
+export function readEtcPaths({ readFile = readFileSync, readdir = readdirSync } = {}) {
+  const out = [];
+  const take = (file) => {
+    try {
+      for (const line of String(readFile(file, 'utf8')).split(/\r?\n/)) {
+        const entry = line.trim();
+        if (entry && !entry.startsWith('#')) out.push(entry);
+      }
+    } catch { /* not there */ }
+  };
+  take('/etc/paths');
+  let names = [];
+  try { names = readdir('/etc/paths.d').map(String).sort(); } catch { /* not there */ }
+  for (const name of names) take(`/etc/paths.d/${name}`);
+  return out;
+}
+
+/**
+ * A cached reader of the OS PATH. `cached()` answers at once (and starts a
+ * read in the background when the answer is stale); `refresh()` waits for one.
+ */
+export function createOsPathReader({
+  platform = process.platform,
+  env = process.env,
+  ttlMs = 60_000,
+  failureTtlMs = 15_000,
+  readWindows = readWindowsPath,
+  readLoginShell = readLoginShellPath,
+  readEtc = readEtcPaths,
+  remember = rememberOsPath,
+  now = Date.now,
+} = {}) {
+  let state = { entries: [], at: 0, ok: false, source: null, error: null, shell: null };
+  let inflight = null;
+
+  async function read() {
+    if (env.SYNABUN_TOOL_DISCOVERY === 'path') return { entries: [], ok: true, source: 'off', error: null, shell: null };
+    if (platform === 'win32') {
+      const found = await readWindows({ env });
+      return { entries: found.entries, sources: found.sources || [], ok: found.ok, source: 'registry', error: found.errors?.length ? found.errors.join('; ') : null, shell: null };
+    }
+    const found = await readLoginShell({ env, platform });
+    const etc = platform === 'darwin' ? readEtc() : [];
+    const entries = dedupePath([...(found.entries || []), ...etc], platform);
+    return {
+      entries,
+      ok: !!found.ok,
+      source: found.ok ? 'login-shell' : etc.length ? 'etc-paths' : 'none',
+      error: found.error || null,
+      shell: found.shell || null,
+    };
+  }
+
+  function snapshot() {
+    return { entries: state.entries.slice(), sources: (state.sources || []).map(entry => ({ ...entry })), at: state.at, ok: state.ok, source: state.source, error: state.error, shell: state.shell };
+  }
+
+  function stale() {
+    return !state.at || now() - state.at >= (state.ok ? ttlMs : failureTtlMs);
+  }
+
+  function refresh({ force = false } = {}) {
+    if (inflight) return inflight;
+    if (!force && !stale()) return Promise.resolve(snapshot());
+    inflight = (async () => {
+      let result;
+      try { result = await read(); } catch (error) { result = { entries: [], ok: false, source: 'none', error: String(error?.message || error), shell: null }; }
+      // A read that failed keeps what an earlier one found.
+      const entries = result.ok || !state.entries.length ? result.entries : state.entries;
+      state = { ...result, entries, at: now() };
+      try { remember(entries); } catch { /* nothing to tell */ }
+      return snapshot();
+    })().finally(() => { inflight = null; });
+    return inflight;
+  }
+
+  function cached() {
+    if (stale() && !inflight) refresh().catch(() => {});
+    return state.entries.slice();
+  }
+
+  function invalidate() {
+    state = { ...state, at: 0 };
+  }
+
+  return { refresh, cached, invalidate, snapshot, stale };
+}
+
+/** This process's reader (server.js starts it at boot; Re-check forces it). */
+export const osPath = createOsPathReader();

package/neural-interface/lib/provider-panel-api-key-auth.js

@@ -0,0 +1,92 @@
+const API_KEY_ERRORS = {
+  invalid_key: { status: 400, message: "That doesn't look like an API key for this provider." },
+  oauth_token: { status: 400, message: "That's a Claude sign-in token. Use Sign in with Claude." },
+  key_rejected: { status: 401, message: 'The provider rejected that key.' },
+  account_unavailable: { status: 404, message: 'This account is no longer available. Select an account again.' },
+  account_busy: { status: 409, message: 'Finish sign-in or reconnect this account and try again.' },
+  verification_unreachable: { status: 503, message: "Couldn't reach {vendor} to check the key. Try again." },
+  verification_unavailable: { status: 503, message: "{vendor} couldn't check the key. Try again shortly." },
+  storage_failed: { status: 500, message: "Couldn't save the key for this account." },
+};
+// `provider` names the vendor in the two verification messages (Anthropic for Claude, OpenAI for Codex).
+export function providerApiKeyError(code, provider = 'claude') {
+  const { status, message } = Object.hasOwn(API_KEY_ERRORS, code) ? API_KEY_ERRORS[code] : API_KEY_ERRORS.storage_failed;
+  return Object.assign(new Error(message.replace('{vendor}', provider === 'codex' ? 'OpenAI' : 'Anthropic')), { status, code });
+}
+
+// Return the normalized value: clipboard padding is not part of a credential.
+export function validateProviderApiKey(provider, key) {
+  if (!['claude', 'codex'].includes(provider)) throw Object.assign(new Error('Unknown provider'), { status: 404 });
+  if (typeof key !== 'string' || key.length > 4096) throw providerApiKeyError('invalid_key');
+  key = key.trim();
+  // setup-token produces an OAuth token, not an Anthropic API key. Never send
+  // it to x-api-key or persist it under the API-key authentication method.
+  if (provider === 'claude' && key.startsWith('sk-ant-oat01-')) throw providerApiKeyError('oauth_token');
+  const pattern = provider === 'claude' ? /^sk-ant-[A-Za-z0-9_-]{16,}$/ : /^sk-(?!ant-)[A-Za-z0-9_-]{16,}$/;
+  if (!pattern.test(key)) throw providerApiKeyError('invalid_key');
+  return key;
+}
+
+// Defense in depth for native diagnostics/events. Never forward credential fields.
+export function redactProviderSecrets(value) {
+  if (typeof value === 'string') return value.replace(/sk-[A-Za-z0-9_-]{16,}/g, '[redacted]');
+  if (Array.isArray(value)) return value.map(redactProviderSecrets);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !/^(api_?key|access_?token|refresh_?token|id_?token|authorization)$/i.test(key))
+    .map(([key, item]) => [key, redactProviderSecrets(item)]));
+  return value;
+}
+
+export function registerProviderPanelApiKeyAuthRoutes(app, { guard, claude, codex }) {
+  app.post('/api/provider-panel-auth/:provider/:accountId/api-key', guard, async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    const { provider, accountId } = req.params;
+    let key = req.body?.key;
+    // Express's parsed request body must not outlive this handler with a secret.
+    if (req.body) delete req.body.key;
+    try {
+      key = validateProviderApiKey(provider, key);
+      if (!/^[a-z0-9-]{1,64}$/.test(accountId)) throw providerApiKeyError('account_unavailable');
+      // Codex keys are kept by SynaBun per account too (lib/codex-accounts.js): an older
+      // page may still send the `target` of its live connection, which is not needed now.
+      if (provider === 'claude') await claude(accountId, key);
+      else await codex(accountId, key);
+      res.json({ ok: true });
+    } catch (error) {
+      // Never serialize provider exceptions; a native error may echo its input.
+      const fallback = { 400: 'invalid_key', 401: 'key_rejected', 404: 'account_unavailable', 409: 'account_busy', 503: 'verification_unavailable' }[error.status] || 'storage_failed';
+      const code = Object.hasOwn(API_KEY_ERRORS, error.code) ? error.code : fallback;
+      const safe = providerApiKeyError(code, provider);
+      res.status(safe.status).json({ code, error: safe.message });
+    } finally { key = null; }
+  });
+}
+
+// Install immediately after the global JSON parser: its SyntaxError may contain
+// a fragment of the secret-bearing body. Never pass that error to Express logs.
+export function providerApiKeyBodyError(error, req, res, next) {
+  if (req.method !== 'POST' || !/^\/api\/provider-panel-auth\/[^/]+\/[^/]+\/api-key(?:\?|$)/.test(req.originalUrl || req.url || '')) return next(error);
+  delete error.body;
+  req.body = undefined;
+  res.setHeader('Cache-Control', 'no-store');
+  return res.status(error.status === 413 ? 413 : 400).json({ code: 'invalid_key', error: API_KEY_ERRORS.invalid_key.message });
+}
+
+// Native stderr arrives in arbitrary chunks. Redact complete lines so a split
+// credential cannot leave an unmasked suffix; omit unterminated/oversized lines.
+export function providerDiagnosticSink(write, maxChars = 65536) {
+  let buffer = '', dropping = false;
+  return chunk => {
+    const parts = String(chunk).split(/\r?\n/);
+    for (let i = 0; i < parts.length; i++) {
+      if (!dropping) {
+        buffer += parts[i];
+        if (buffer.length > maxChars) { buffer = ''; dropping = true; }
+      }
+      if (i < parts.length - 1) {
+        if (!dropping && buffer.trim()) write(redactProviderSecrets(buffer.trim()));
+        buffer = ''; dropping = false;
+      }
+    }
+  };
+}

package/neural-interface/lib/provider-panel-terminal-auth.js

@@ -0,0 +1,95 @@
+import { randomBytes } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { claudeAuthEnv } from './claude-panel-auth.js';
+import { applyCodexLaunchEnv } from './codex-accounts.js';
+
+// Only server-owned account records and resolved executables enter the PTY.
+export function providerLoginSpec({ provider, accountId, claudeAccounts, codexAccount, claudeExecutable, codexExecutable, env }) {
+  if (!['claude', 'codex'].includes(provider) || typeof accountId !== 'string' || !/^[a-z0-9-]{1,64}$/.test(accountId)) {
+    throw Object.assign(new Error('Unknown provider account'), { status: 404 });
+  }
+  const account = provider === 'claude' ? claudeAccounts.profileFor(accountId) : codexAccount(accountId);
+  if (!account || account.id !== accountId) throw Object.assign(new Error('Unknown provider account'), { status: 404 });
+  const file = provider === 'claude' ? claudeExecutable()?.path : codexExecutable();
+  if (!file || !isAbsolute(file) || /\.(cmd|bat)$/i.test(file)) {
+    throw new Error(`Could not resolve the ${provider === 'claude' ? 'Claude' : 'Codex'} executable. Check its installation.`);
+  }
+  let baseEnv = { ...env };
+  if (provider === 'codex') {
+    // Every Codex account, Default too: `codex login` writes to that account's CODEX_HOME, with no
+    // inherited OpenAI/Codex credential around it (lib/codex-accounts.js CODEX_CREDENTIAL_ENV).
+    if (!account.home) throw new Error('This Codex account has no home folder.');
+    baseEnv = applyCodexLaunchEnv(baseEnv, { env: { CODEX_HOME: account.home } });
+  } else if (accountId !== 'default') {
+    if (!account.home) throw new Error('This Claude account has no isolated home.');
+    baseEnv = claudeAuthEnv(baseEnv, { CLAUDE_CONFIG_DIR: account.home });
+  }
+  const args = provider === 'claude' ? ['auth', 'login', '--claudeai'] : ['login'];
+  return { launch: /\.[cm]?js$/i.test(file) ? { shell: process.execPath, args: [file, ...args] } : { shell: file, args }, baseEnv };
+}
+
+// `onSettled(provider, id, status)` (optional): told once when a sign-in terminal ends ('exited' when the
+// CLI exited 0, else 'error'), so the host can ask the provider what it now says about the account.
+export function createProviderPanelTerminalAuth({ resolveSpec, createSession, whenSpawned, killSession, timeoutMs = 10 * 60_000, onSettled = null }) {
+  const operations = new Map();
+  const key = (provider, id) => `${provider}:${id}`;
+  const snapshot = op => ({ sessionId: op.sessionId, status: op.status, error: op.error || '' });
+  function read(provider, id) {
+    resolveSpec(provider, id); // Validate deleted accounts and unsupported providers on reads too.
+    const op = operations.get(key(provider, id));
+    return op ? snapshot(op) : { status: 'idle' };
+  }
+  async function start(provider, id) {
+    const spec = resolveSpec(provider, id);
+    const existing = operations.get(key(provider, id));
+    if (existing && ['starting', 'pending'].includes(existing.status)) { await existing.ready; return snapshot(existing); }
+    const op = { sessionId: randomBytes(16).toString('hex'), status: 'starting' };
+    operations.set(key(provider, id), op);
+    let timer;
+    const finish = (status, error = '') => {
+      if (!['starting', 'pending'].includes(op.status)) return;
+      clearTimeout(timer); op.status = status; op.error = error;
+      if (typeof onSettled === 'function') Promise.resolve().then(() => onSettled(provider, id, status)).catch(() => {});
+    };
+    op.ready = (async () => {
+      try {
+        createSession('shell', 120, 30, undefined, { ...spec, sessionId: op.sessionId,
+          onExit: ({ exitCode }) => finish(exitCode === 0 ? 'exited' : 'error', exitCode === 0 ? '' : 'Sign-in failed. Try again.'),
+          onClosed: () => finish('error', 'Sign-in terminal closed. Try again.'),
+        });
+        let spawnTimer;
+        try {
+          await Promise.race([whenSpawned(op.sessionId), new Promise((_, reject) => {
+            spawnTimer = setTimeout(() => reject(new Error('Terminal host did not respond')), 15000);
+          })]);
+        } finally { clearTimeout(spawnTimer); }
+        if (op.status === 'starting') {
+          op.status = 'pending';
+          timer = setTimeout(() => { finish('error', 'Sign-in timed out. Try again.'); killSession(op.sessionId); }, timeoutMs);
+          timer.unref?.();
+        }
+      } catch {
+        finish('error', 'Could not open the sign-in terminal. Try again.');
+        killSession(op.sessionId);
+      }
+    })();
+    await op.ready;
+    return snapshot(op);
+  }
+  return { start, read };
+}
+
+export function registerProviderPanelTerminalAuthRoutes(app, { guard, auth }) {
+  const route = '/api/provider-panel-auth/:provider/:id/terminal';
+  app.get(route, guard, (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    try { res.json({ terminal: auth.read(req.params.provider, req.params.id) }); }
+    catch (error) { res.status(error.status || 500).json({ error: error.message }); }
+  });
+  app.post(route, guard, async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    if (Object.keys(req.body || {}).length) return res.status(400).json({ error: 'Only provider and account selection are accepted.' });
+    try { res.json({ terminal: await auth.start(req.params.provider, req.params.id) }); }
+    catch (error) { res.status(error.status || 500).json({ error: error.message }); }
+  });
+}

package/neural-interface/lib/pty-host/core.js

@@ -18,6 +18,7 @@ import { createTerminalModel } from './snapshot.js';
 import { evaluateFlow } from './flow.js';
 import { EV, OP, HOST_DEFAULTS } from './protocol.js';
 import { createEventLoopMonitor } from '../event-loop-monitor.js';
+import { withPathEnv } from '../augmented-path.js';
 
 const IS_WIN = process.platform === 'win32';
 const IS_LINUX = process.platform === 'linux';
@@ -74,7 +75,7 @@ export function createPtyHostCore({ send, config = {}, pty: injectedPty = null }
     }
     const cols = clampInt(spec.cols, 2, 1000) || 120;
     const rows = clampInt(spec.rows, 1, 500) || 30;
-    const env = { ...(spec.env || {}) };
+    const env = withPathEnv(spec.env || {});
     for (const k of Object.keys(env)) if (k.startsWith('NODE_CHANNEL_') || k === 'NODE_UNIQUE_ID') delete env[k];
 
     let file = spec.file;

package/neural-interface/lib/pty-host/manager.js

@@ -38,6 +38,7 @@ export function createPtyHostManager({
 } = {}) {
   const handlers = new Map();     // id → { onSpawned, onTap, onResized, onClients, onExit }
   const spawnWaiters = new Map(); // id → waiter
+  const preparing = new Map();   // id → operations queued while PATH is read
   const requests = new Map();     // reqId → { resolve, reject, timer }
   let reqSeq = 0;
   let child = null;
@@ -158,6 +159,7 @@ export function createPtyHostManager({
     heldSockets = [];
     queue = [];
     const lost = [...handlers.entries()];
+    preparing.clear();
     handlers.clear();
     for (const [id] of lost) settleSpawn(id, new Error('pty-host exited'));
     spawnWaiters.clear();
@@ -175,6 +177,13 @@ export function createPtyHostManager({
 
   // ── Main → host ──
   function sendOp(msg) {
+    if (preparing.has(msg.id) && msg.op !== OP.SPAWN) {
+      if (msg.op === OP.KILL) {
+        preparing.delete(msg.id);
+        dispatch({ t: EV.SPAWN_ERROR, id: msg.id, message: 'Terminal closed before it started' });
+      } else preparing.get(msg.id).push(msg);
+      return;
+    }
     if (mode === 'inproc') {
       if (!core || !ready) { queue.push(msg); return; }
       core.handleMessage(msg);
@@ -190,11 +199,23 @@ export function createPtyHostManager({
     for (const msg of q) sendOp(msg);
   }
 
-  function spawn(spec, h = {}) {
+  function spawn(spec, h = {}, prepare = null) {
     handlers.set(spec.id, h);
     const w = makeWaiter();
     spawnWaiters.set(spec.id, w);
-    sendOp({ op: OP.SPAWN, ...spec });
+    if (prepare) {
+      const pending = [];
+      preparing.set(spec.id, pending);
+      Promise.resolve().then(prepare).then(prepared => {
+        if (shuttingDown || !handlers.has(spec.id) || preparing.get(spec.id) !== pending) return;
+        preparing.delete(spec.id);
+        sendOp({ op: OP.SPAWN, ...spec, ...prepared });
+        for (const message of pending) sendOp(message);
+      }).catch(error => {
+        preparing.delete(spec.id);
+        dispatch({ t: EV.SPAWN_ERROR, id: spec.id, message: error.message });
+      });
+    } else sendOp({ op: OP.SPAWN, ...spec });
     return w.promise;
   }
 
@@ -315,6 +336,8 @@ export function createPtyHostManager({
 
   async function shutdown({ timeoutMs = 1500 } = {}) {
     shuttingDown = true;
+    for (const id of preparing.keys()) settleSpawn(id, new Error('Terminal host is shutting down'));
+    preparing.clear();
     if (restartTimer) { clearTimeout(restartTimer); restartTimer = null; }
     if (mode === 'inproc') {
       try { core?.shutdownAll(); } catch {}
@@ -332,6 +355,8 @@ export function createPtyHostManager({
 
   function killNow() {
     shuttingDown = true;
+    for (const id of preparing.keys()) settleSpawn(id, new Error('Terminal host is shutting down'));
+    preparing.clear();
     if (restartTimer) { clearTimeout(restartTimer); restartTimer = null; }
     try { child?.kill('SIGTERM'); } catch {}
     try { core?.shutdownAll(); } catch {}