synabun 2.0.0 → 2.0.7

package/neural-interface/lib/mcp-installer.js

@@ -1,6 +1,7 @@
 import { spawn, spawnSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, chmodSync } from 'fs';
 import { join, resolve, isAbsolute } from 'path';
+import { withPackagedPathLast } from './augmented-path.js';
 
 const GITHUB_URL_RE = /^https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/i;
 
@@ -87,11 +88,22 @@ export function maskEnv(env) {
   return out;
 }
 
+/**
+ * The environment of a git / package-manager run: this process's, with a
+ * packaged application's runtime and npm's global bin after the user's own
+ * PATH (augmented-path.js withPackagedPathLast): a repository is installed
+ * with the user's npm, pnpm, yarn, uv or pip when they have one, SynaBun's
+ * bundled npm only when they have none. Unchanged for an npm or Git install.
+ */
+export function installEnv(extra = {}, base = process.env) {
+  return withPackagedPathLast({ ...base, ...extra });
+}
+
 async function runCommand(cmd, args, opts = {}) {
   return new Promise((resolvePromise) => {
     const child = spawn(cmd, args, {
       cwd: opts.cwd,
-      env: { ...process.env, ...(opts.env || {}) },
+      env: installEnv(opts.env || {}),
       stdio: ['ignore', 'pipe', 'pipe'],
       shell: false,
     });
@@ -466,7 +478,7 @@ export async function installDependencies({ dataHome, name, repoPath, onLine })
 
   if (hasPyproject || hasRequirements) {
     if (hasUvLock || hasPyproject) {
-      const uvExists = spawnSync('which', ['uv']).status === 0;
+      const uvExists = spawnSync('which', ['uv'], { env: installEnv() }).status === 0;
       if (uvExists) {
         logInstall(dataHome, name, 'running uv sync');
         const res = await runCommand('uv', ['sync'], { cwd: repoPath, onLine: (line) => { logInstall(dataHome, name, line); onLine?.(line); } });

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

@@ -99,6 +99,15 @@ export function filterInjected(results, { caller, session, generation } = {}, co
   if (seen.size > 500) seen.delete(seen.values().next().value);
   return fresh;
 }
+/**
+ * Record memories as already in an Assistant conversation's context (its user-context digest, a
+ * nudge or a cue: lib/assistant-user-context.js), in the same ledger automatic recall reads: they
+ * are not injected again in that context generation.
+ */
+export function markInjected(rows, { session, generation } = {}) {
+  const list = (Array.isArray(rows) ? rows : []).filter(r => r && r.id).map(r => ({ id: r.id, revision: r.revision }));
+  if (list.length) filterInjected(list, { caller: 'assistant', session, generation });
+}
 function input(body) {
   if (typeof body?.query !== 'string' || !body.query.trim() || body.query.length > 16000) throw new Error('query must be non-empty text of at most 16000 characters.');
   const out = {query:body.query};
@@ -316,9 +325,14 @@ async function planConflict(text, body, ctx, retrieve) {
 // The assistant passes { origin:'assistant', defer:true }: retrieval and ranking
 // run now, but nothing is rendered or committed to the injection ledger until
 // it calls finish(tier) with the size its prompt-urgency judgment chose;
-// finish(null) withholds the memories. The HTTP route never passes options.
-export async function hookRecall(body = {}, retrieve = retrieveMemory, { origin = null, defer = false } = {}) {
+// finish(null) withholds the memories. `divert` (category names; the assistant's
+// user-context engine) keeps those categories out of the rendered block: they
+// are searched and ranked with the rest, then returned apart as `diverted`
+// (never rendered, never committed here). The HTTP route never passes options.
+export async function hookRecall(body = {}, retrieve = retrieveMemory, { origin = null, defer = false, divert = null } = {}) {
   const opts=input(body);
+  const divertSet=Array.isArray(divert) && divert.length ? new Set(divert.map(String)) : null;
+  const isDiverted=r=>!!divertSet && divertSet.has(String(r.category));
   const ctx=origin ? {...hookContext(body),origin} : hookContext(body);
   const judgeOff=body.judge === false;
   // `surface` implies ranking; `rank:true` alone keeps meaning brief-rank.
@@ -332,7 +346,7 @@ export async function hookRecall(body = {}, retrieve = retrieveMemory, { origin
     return out;
   };
   const skipFollowup=()=>{
-    const out=withStale({results:[],context:'',already_present:false,skipped:'referential-followup',estimated_tokens:0,ranked:false,rank_surface:null,judged:0,dropped:[],floor:null});
+    const out=withStale({results:[],context:'',already_present:false,skipped:'referential-followup',estimated_tokens:0,ranked:false,rank_surface:null,judged:0,dropped:[],floor:null,diverted:[]});
     return defer ? {...out,deferred:true,candidates:0,finish:()=>out} : out;
   };
   // A judged ranking decides relevance for follow-ups too; the regex is the
@@ -347,7 +361,8 @@ export async function hookRecall(body = {}, retrieve = retrieveMemory, { origin
   const budget=Math.max(100,Math.min(2000,Number(body.token_budget)||600));
   const identity={caller:body.caller,session:body.claudeSessionId || body.session,generation:body.context_generation};
   let candidates=filterInjected(result.results,identity,false);
-  const alreadyPresent=result.results.length>0 && candidates.length===0;
+  // "Already supplied" is about the block: a diverted category never renders in it.
+  const alreadyPresent=result.results.some(r=>!isDiverted(r)) && !candidates.some(r=>!isDiverted(r));
   let ranked=false, scores=null, dropped=[], floor=null, logId=null;
   if (canRank && (candidates.length > 1 || (floorWanted && candidates.length === 1))) {
     const settings=surfaceConfig(surface);
@@ -370,6 +385,14 @@ export async function hookRecall(body = {}, retrieve = retrieveMemory, { origin
     }
     if (!ranked && isReferentialFollowup(opts.query)) return skipFollowup();
   }
+  // Diverted categories leave the candidates here, after the ranking and its floor judged them.
+  let diverted=[];
+  if (divertSet) {
+    diverted=candidates.filter(isDiverted).map(r=>({id:r.id,revision:r.revision,category:r.category,project:r.project,content:r.content,
+      subcategory:r.payload?.subcategory ?? null,importance:r.payload?.importance ?? null,created_at:r.created_at,updated_at:r.payload?.updated_at ?? r.created_at,
+      related_memory_ids:r.payload?.related_memory_ids ?? null,score:r.score,ranked:ranked && scores.has(r.id),relevance:ranked && scores.has(r.id) ? scores.get(r.id) : null}));
+    candidates=candidates.filter(r=>!isDiverted(r));
+  }
   // The first `lim` candidates that fit `tok` tokens (the classic path: limit / budget).
   const render=(lim,tok)=>{
     const pool=surface ? candidates.slice(0,lim) : candidates;
@@ -394,7 +417,7 @@ export async function hookRecall(body = {}, retrieve = retrieveMemory, { origin
   // `scores` null: the row is still annotated, with no candidates.
   const outcome=(extra)=>({surface,floor,
     candidates:scores ? [...scores].map(([id,relevance])=>({id,relevance,level:relevanceLevel(relevance)})) : [],
-    ...extra,dropped:dropped.map(d=>d.id)});
+    ...extra,dropped:dropped.map(d=>d.id),...(diverted.length ? {diverted:diverted.map(d=>d.id)} : {})});
   // Commit what was injected to the ledger, record it on the ranking's log row, shape the answer.
   const finalize=({results,context,delivered},extra={})=>{
     filterInjected(delivered,identity);
@@ -402,6 +425,7 @@ export async function hookRecall(body = {}, retrieve = retrieveMemory, { origin
     const out={results:results.filter(r=>delivered.some(h=>h.id===r.id)),context,already_present:alreadyPresent,
       estimated_tokens:estimateTokens(context),degraded:result.degraded,ranked,rank_surface:ranked ? surface : null,
       judged:scores?.size ?? 0,dropped,floor};
+    if (divertSet) out.diverted=diverted;
     if (ranked && !delivered.length && dropped.length) out.skipped='judged-irrelevant';
     return out;
   };
@@ -415,7 +439,7 @@ export async function hookRecall(body = {}, retrieve = retrieveMemory, { origin
     if (!tier) {
       if (logId) annotateTypeSafeLog(logId,outcome({injected:[],withheld:'prompt-urgency'}));
       settled={results:[],context:'',already_present:false,estimated_tokens:0,degraded:result.degraded,ranked,
-        rank_surface:ranked ? surface : null,judged:scores?.size ?? 0,dropped,floor,withheld:'prompt-urgency'};
+        rank_surface:ranked ? surface : null,judged:scores?.size ?? 0,dropped,floor,withheld:'prompt-urgency',...(divertSet ? {diverted:[]} : {})};
       return settled;
     }
     const lim=Math.max(1,Math.min(50,Math.floor(Number(tier.limit))||limit));
@@ -424,7 +448,7 @@ export async function hookRecall(body = {}, retrieve = retrieveMemory, { origin
     return settled;
   };
   return {deferred:true,ranked,rank_surface:ranked ? surface : null,judged:scores?.size ?? 0,dropped,floor,
-    already_present:alreadyPresent,degraded:result.degraded,candidates:candidates.length,finish};
+    already_present:alreadyPresent,degraded:result.degraded,candidates:candidates.length,...(divertSet ? {diverted} : {}),finish};
 }
 
 /**

package/neural-interface/lib/native-loop-providers.js

@@ -248,6 +248,9 @@ export async function createCodexNativeLoopAdapter(options = {}) {
     collectMedia = null,
     // Assistant task runs: the browser policy's hook and the run's notes (a function: never in the state file).
     runMode = 'loop', onNote = null, browserPolicyTrust = null,
+    // Inherited variables to remove before extraEnv applies (the Codex account's launch:
+    // lib/codex-accounts.js launchFor() — inherited OpenAI/Codex credentials never reach the run).
+    unsetEnv = [],
   } = options;
   const permissionPolicy = normalizePermissionPolicy(rawPolicy);
   const capability = normalizeCapability(rawCapability);
@@ -281,7 +284,9 @@ export async function createCodexNativeLoopAdapter(options = {}) {
     // Computer-use workers: the grant unlocks the `computer` group in the MCP child.
     SYNABUN_DESKTOP_GRANT: typeof desktopGrantProvider === 'function' ? desktopGrantProvider() || undefined : undefined,
   });
-  const env = stringEnv({ ...process.env, ...pins, CODEX_HOME: codexHome, ...(browserPolicy ? { SYNABUN_BROWSER_POLICY_CWD: cwd || process.cwd() } : {}), ...stringEnv(extraEnv) });
+  const inherited = { ...process.env };
+  for (const key of Array.isArray(unsetEnv) ? unsetEnv : []) delete inherited[key];
+  const env = stringEnv({ ...inherited, ...pins, CODEX_HOME: codexHome, ...(browserPolicy ? { SYNABUN_BROWSER_POLICY_CWD: cwd || process.cwd() } : {}), ...stringEnv(extraEnv) });
   const config = {};
   if (Object.keys(pins).length) config.mcp_servers = { SynaBun: { env: pins } };
   if (extended) config.model_context_window = Math.floor(Number(modelContextWindow));
@@ -423,6 +428,11 @@ export async function createClaudeNativeLoopAdapter(options = {}) {
     extraEnv = {}, permissionPolicy: rawPolicy = 'auto', permissionBroker = null,
     capability: rawCapability = 'full', maxBudgetUsd = null, outputSchema = null, runMode = 'loop',
     desktopGrantProvider = null,
+    // Inherited variables to remove before extraEnv applies (the Claude account's launch:
+    // credentials the server was started with never reach a worker).
+    unsetEnv = [],
+    // The host's last word on the environment: on Windows the Git Bash it names (lib/git-bash/).
+    childEnv = null,
   } = options;
   const permissionPolicy = normalizePermissionPolicy(rawPolicy);
   const capability = normalizeCapability(rawCapability);
@@ -432,8 +442,10 @@ export async function createClaudeNativeLoopAdapter(options = {}) {
   let alive = true;
   let sessionId = null;
   let activeTurn = null;
-  const env = stringEnv({
-    ...cleanClaudeEnvironment(),
+  const inherited = cleanClaudeEnvironment();
+  for (const key of Array.isArray(unsetEnv) ? unsetEnv : []) delete inherited[key];
+  const ownEnv = stringEnv({
+    ...inherited,
     SYNABUN_TERMINAL_SESSION: runId,
     SYNABUN_PROJECT: cwd ? memoryProject(cwd) : 'global',
     SYNABUN_PROFILE: 'full',
@@ -442,6 +454,7 @@ export async function createClaudeNativeLoopAdapter(options = {}) {
     SYNABUN_RUN_MODE: runMode === 'task' ? 'task' : undefined,
     ...stringEnv(extraEnv),
   });
+  const env = typeof childEnv === 'function' ? stringEnv(childEnv(ownEnv)) : ownEnv;
   const brokerRequest = async (request) => {
     try {
       const reply = await permissionBroker.request({
@@ -649,11 +662,16 @@ export async function createClaudeNativeLoopAdapter(options = {}) {
     }
     if (pumpError) throw pumpError;
   })();
-  pump.catch((error) => onEvent({
-    provider: 'claude-code',
-    runId,
-    event: { type: 'synabun.error', message: error?.message || String(error) },
-  }));
+  pump.catch((error) => {
+    // dispose() aborts the query when the run ends, however it ended, and the
+    // SDK throws "Claude Code process aborted by user" for it: not a failure.
+    if (abortController.signal.aborted) return;
+    onEvent({
+      provider: 'claude-code',
+      runId,
+      event: { type: 'synabun.error', message: error?.message || String(error) },
+    });
+  });
 
   return {
     identity: () => ({ providerSessionId: sessionId }),

package/neural-interface/lib/native-loop-runtime.js

@@ -373,9 +373,14 @@ export class NativeLoopRuntime {
     record.startupCancelPromise = new Promise((resolveCancel) => { record._cancelStartup = resolveCancel; });
     this.records.set(runId, record);
     this._emit('sidepanel:run-created', record);
-    const maxMs = Math.max(1, Number(nativeState.maxMinutes) || 30) * 60_000;
-    record.timer = setTimeout(() => { this.stop(runId, 'time_cap').catch(() => {}); }, maxMs);
-    record.timer.unref?.();
+    // A task run's (assistant dispatch) maxMinutes is work time, which its dispatcher counts and
+    // enforces (assistant-dispatch.js, the work clock): idle time between its turns does not count,
+    // so it gets no wall-clock cap here. A loop's maxMinutes stays the wall clock.
+    if (record.runMode !== 'task') {
+      const maxMs = Math.max(1, Number(nativeState.maxMinutes) || 30) * 60_000;
+      record.timer = setTimeout(() => { this.stop(runId, 'time_cap').catch(() => {}); }, maxMs);
+      record.timer.unref?.();
+    }
 
     const startupSignal = record.startupAbortController.signal;
     const factoryPromise = Promise.resolve().then(() => factory({
@@ -510,7 +515,7 @@ export class NativeLoopRuntime {
         return;
       }
       const elapsed = this.now() - new Date(state.startedAt || record.startedAt).getTime();
-      if (elapsed >= Math.max(1, Number(state.maxMinutes) || 30) * 60_000) {
+      if (record.runMode !== 'task' && elapsed >= Math.max(1, Number(state.maxMinutes) || 30) * 60_000) {
         await this.stop(record.runId, 'time_cap');
         return;
       }

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/plugin-installer.js

@@ -5,6 +5,7 @@ import {
 } from 'fs';
 import { join, resolve, dirname } from 'path';
 import os from 'node:os';
+import { runGitReadSync } from './git-read.js';
 
 const PLUGINS_ROOT = () => join(os.homedir(), '.claude', 'plugins');
 const INSTALLED_PLUGINS_FILE = () => join(PLUGINS_ROOT(), 'installed_plugins.json');
@@ -48,9 +49,10 @@ function claudeNotFoundErr() {
   return { ok: false, error: 'Claude Code CLI not found on PATH. Install `claude` to manage plugins.' };
 }
 
+// (git is asked as lib/git-read.js runs a read: the folder comes from a request, or from Claude Code's registry)
 function gitHeadSha(repoPath) {
   if (!repoPath || !existsSync(repoPath)) return 'unknown';
-  const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: repoPath, encoding: 'utf-8' });
+  const r = runGitReadSync(repoPath, ['rev-parse', 'HEAD'], { encoding: 'utf-8' });
   const out = (r.stdout || '').trim();
   return out || 'unknown';
 }
@@ -252,7 +254,7 @@ export function repairSynabunPlugins() {
     if (!meta.ok) { failed.push({ marketplaceName: name, error: meta.error }); continue; }
     let githubUrl = null;
     try {
-      const r = spawnSync('git', ['remote', 'get-url', 'origin'], { cwd: path, encoding: 'utf-8' });
+      const r = runGitReadSync(path, ['remote', 'get-url', 'origin'], { encoding: 'utf-8' });
       const u = (r.stdout || '').trim();
       if (/^https?:\/\//.test(u)) githubUrl = u.replace(/\.git$/, '');
     } catch {}

package/neural-interface/lib/project-storage.js

@@ -18,8 +18,8 @@ import {
   resolve,
   sep,
 } from 'node:path';
-import { spawnSync } from 'node:child_process';
 import { isMainThread, parentPort, Worker, workerData } from 'node:worker_threads';
+import { runGitReadSync } from './git-read.js';
 
 export const PROJECT_STORAGE_SAFE_CONFIRMATION = 'CLEAR SELECTED CACHES';
 export const PROJECT_STORAGE_DEPENDENCY_CONFIRMATION = 'DELETE DEPENDENCIES';
@@ -216,11 +216,11 @@ function measurePath(rootPath, { entryLimit = MEASURE_ENTRY_LIMIT } = {}) {
   return { bytes, fileCount, incomplete, containsRepository };
 }
 
+// Both questions are reads, run as lib/git-read.js runs one: a registered project is a folder like any other, and
+// listing its files starts nothing its own git configuration names (`git ls-files` asks the file system monitor).
 function gitInfoForProject(projectRoot) {
   const canonicalProjectRoot = canonicalExistingPath(projectRoot);
-  const probe = spawnSync('git', ['-C', projectRoot, 'rev-parse', '--show-toplevel'], {
-    encoding: 'utf8', timeout: 5_000, windowsHide: true,
-  });
+  const probe = runGitReadSync(projectRoot, ['rev-parse', '--show-toplevel'], { encoding: 'utf8', timeout: 5_000 });
   if (probe.status !== 0) {
     let current = canonicalProjectRoot;
     while (true) {
@@ -237,9 +237,7 @@ function gitInfoForProject(projectRoot) {
   if (!pathIsWithin(gitRoot, canonicalProjectRoot, { allowEqual: true })) {
     return { isRepository: false, verified: false, root: gitRoot, tracked: [] };
   }
-  const listed = spawnSync('git', ['-C', gitRoot, 'ls-files', '-z'], {
-    encoding: 'buffer', timeout: 20_000, maxBuffer: 64 * 1024 * 1024, windowsHide: true,
-  });
+  const listed = runGitReadSync(gitRoot, ['ls-files', '-z'], { encoding: 'buffer', timeout: 20_000, maxBuffer: 64 * 1024 * 1024 });
   if (listed.status !== 0 || listed.error) {
     return { isRepository: true, verified: false, root: gitRoot, tracked: [] };
   }