synabun 2.0.9 → 2.1.0

package/neural-interface/lib/login-start.js

@@ -0,0 +1,524 @@
+// ═══════════════════════════════════════════
+// SynaBun — start at login, for an npm or Git install (Settings > App)
+// ═══════════════════════════════════════════
+//
+// The server starts in the background when the user logs in, with no window
+// and no terminal, through the same launcher the Start Server button uses
+// (launcher.mjs → lib/start-launcher.js runLauncher, in its background mode:
+// nothing happens when a server already answers or a start is under way, and
+// the server gets the login shell's environment, so an nvm or Homebrew Node
+// and the user's CLIs are found as in a terminal). Every path in the entry is
+// absolute: the PATH a login starts programs with is not the user's.
+//
+//   macOS    ~/Library/LaunchAgents/ai.synabun.server.plist (RunAtLoad; the
+//            launcher's process group is left alone when it exits)
+//   Windows  HKCU\...\Run "SynaBun Server": wscript.exe runs a small script of
+//            SynaBun's (DATA_HOME/runtime/login/synabun-hidden.vbs) that starts
+//            node with no window. A console program started from Run would
+//            show a console. A packaged entry (a GUI program) runs directly
+//   Linux    ~/.config/autostart/synabun-server.desktop (XDG autostart)
+//
+// The entry itself is the setting: on while it is there, off when it is gone.
+// It is read back from the system for every answer (inspect), and put back in
+// place on every start of the server while it is on (heal: another Node, a
+// moved install). One the user turned off in the system (disabled in Startup
+// apps, in Login Items, or in the desktop's autostart settings) stays off and
+// is reported as off.
+//
+// The SynaBun desktop app on the same data folder opens at login on its own
+// (packaging/desktop/src/login-item.mjs, which names both apps' entries the
+// same way: NPM_LOGIN, DESKTOP_LOGIN; a test keeps the two equal). Two starts
+// at login would start two servers on one data folder: while the app's entry is
+// there and on for this data folder (read from the system, desktopLoginOwner),
+// this one is refused ('desktop-app'); turning the app's on removes this one.
+//
+// Pure: the file calls and the programs it runs are handed in (tests/login-start.test.mjs).
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join as nativeJoin, posix, win32 } from 'node:path';
+import { desktopExecArg, launcherOverrides, winQuote } from '../../lib/start-launcher.js';
+
+/** The names of the entries (packaging/desktop/src/login-item.mjs NPM_LOGIN must be equal). */
+export const NPM_LOGIN = Object.freeze({
+  macLabel: 'ai.synabun.server',
+  winName: 'SynaBun Server',
+  linuxFile: 'synabun-server.desktop',
+});
+/** What the launcher is started with at login (lib/start-launcher.js parseLauncherArgs reads them). */
+export const LOGIN_ARGS = Object.freeze(['--via=login', '--background']);
+/**
+ * The desktop app's own login entries (packaging/desktop/src/login-item.mjs DESKTOP_LOGIN must be equal): read from
+ * the system to know whether the app opens at login on this data folder, never from the app's settings file.
+ */
+export const DESKTOP_LOGIN = Object.freeze({
+  macLabel: 'ai.synabun.app.login',
+  winName: 'ai.synabun.app',
+  linuxFile: 'synabun-app.desktop',
+  env: 'SYNABUN_DESKTOP_LOGIN',
+  flag: '--synabun-login',
+  dataFlag: '--synabun-data-home=',
+  portFlag: '--synabun-port=',
+});
+export const HIDDEN_SCRIPT = 'synabun-hidden.vbs';
+export const LINUX_MARKER = 'X-SynaBun-Login=server';
+
+const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
+const APPROVED_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\StartupApproved\\Run';
+
+/**
+ * Runs its arguments as one command line with no window. ASCII only, no path
+ * in it: what it starts comes in as its arguments, which the registry holds as
+ * Unicode (Windows Script Host reads the file itself in the ANSI code page).
+ */
+export const HIDDEN_SCRIPT_SOURCE = [
+  "' SynaBun: runs its arguments as one command, with no window (start at login).",
+  "' Generated by SynaBun. Do not edit.",
+  'Option Explicit',
+  'Dim shell, command, i, a, n',
+  'command = ""',
+  'For i = 0 To WScript.Arguments.Count - 1',
+  '  a = WScript.Arguments(i)',
+  "  ' Backslashes before the closing quote are doubled, or the last one would escape it.",
+  '  n = 0',
+  '  Do While n < Len(a)',
+  '    If Mid(a, Len(a) - n, 1) <> "\\" Then Exit Do',
+  '    n = n + 1',
+  '  Loop',
+  '  command = command & " """ & a & String(n, "\\") & """"',
+  'Next',
+  'Set shell = CreateObject("WScript.Shell")',
+  'shell.Run Trim(command), 0, False',
+  '',
+].join('\r\n');
+
+function defaultRun(file, args, { timeout = 5000 } = {}) {
+  return execFileSync(file, args, { encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+}
+
+const DEFAULT_FS = { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync };
+
+const failure = (code, message) => Object.assign(new Error(message || code), { code });
+
+function xmlEscape(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function systemTool(env, name) {
+  const root = env.SystemRoot || env.SYSTEMROOT || env.windir;
+  return root ? win32.join(root, 'System32', name) : name;
+}
+
+/**
+ * One REG_SZ value of a `reg export` file, or null. `reg query` prints in the console's code page, which turns a
+ * non-ASCII folder name (C:\Users\João) into other characters; the export (UTF-16) keeps it.
+ */
+export function parseRegExport(text, name) {
+  const quoted = `"${String(name).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"=`;
+  for (const line of String(text || '').replace(/^\uFEFF/, '').split(/\r?\n/)) {
+    if (!line.toLowerCase().startsWith(quoted.toLowerCase())) continue;
+    const rest = line.slice(quoted.length);
+    if (!rest.startsWith('"') || !rest.endsWith('"')) return null;
+    return rest.slice(1, -1).replace(/\\(["\\])/g, '$1');
+  }
+  return null;
+}
+
+function decodeRegFile(buffer) {
+  const bytes = Buffer.isBuffer(buffer) ? buffer : Buffer.from(String(buffer ?? ''), 'utf8');
+  return bytes[0] === 0xff && bytes[1] === 0xfe ? bytes.subarray(2).toString('utf16le') : bytes.toString('utf8');
+}
+
+/** One value of a registry key, read through `reg export` (Unicode-safe), or null. */
+export function readRegValue(key, name, { run = defaultRun, fs = DEFAULT_FS, env = process.env, tmp = tmpdir() } = {}) {
+  const file = nativeJoin(tmp, `synabun-login-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.reg`);
+  try {
+    run(systemTool(env, 'reg.exe'), ['export', key, file, '/y']);
+    return parseRegExport(decodeRegFile(fs.readFileSync(file)), name);
+  } catch {
+    return null;
+  } finally {
+    try { fs.rmSync(file, { force: true }); } catch {}
+  }
+}
+
+/** The data of one value in `reg query` output, or null. */
+export function parseRegQuery(output, name) {
+  for (const line of String(output || '').split(/\r?\n/)) {
+    const match = /^\s{2,}(.+?)\s{2,}(REG_[A-Z_]+)\s{2,}(.*)$/.exec(line) || /^\s{2,}(.+?)\s{2,}(REG_[A-Z_]+)\s*$/.exec(line);
+    if (match && match[1].toLowerCase() === String(name).toLowerCase()) return (match[3] ?? '').trim();
+  }
+  return null;
+}
+
+/** Windows' Startup apps switch, from its REG_BINARY: an odd first byte is "disabled". null when unknown. */
+export function startupApproved(hex) {
+  const first = /^[0-9a-f]{2}/i.exec(String(hex || '').trim());
+  if (!first) return null;
+  return (parseInt(first[0], 16) & 1) === 0;
+}
+
+/** The [Desktop Entry] keys of a .desktop file (the first value of a key counts). */
+function desktopEntryKeys(text) {
+  const out = {};
+  let inGroup = false;
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('[')) { inGroup = line === '[Desktop Entry]'; continue; }
+    const at = line.indexOf('=');
+    if (inGroup && at > 0 && !(line.slice(0, at).trim() in out)) out[line.slice(0, at).trim()] = line.slice(at + 1).trim();
+  }
+  return out;
+}
+
+/**
+ * The entry this install would write now, as data: no side effects.
+ *   { kind: 'launch-agent' | 'run-value' | 'autostart', path?, content?, key?, name?, value?, helper? }
+ * `entry` is a packaged build's entry executable (it brings its own Node): `<entry> launcher …`.
+ */
+export function buildLoginPlan({
+  platform = process.platform, nodePath = process.execPath, packageRoot, home = homedir(), env = process.env, dataHome, entry = null,
+} = {}) {
+  if (!packageRoot) throw new Error('packageRoot is required');
+  const overrides = launcherOverrides({ env, home, platform });
+  const args = [...LOGIN_ARGS, ...(overrides.dataHome ? ['--data-home', overrides.dataHome] : []), ...(overrides.port ? ['--port', String(overrides.port)] : [])];
+
+  if (platform === 'win32') {
+    const launcher = entry || win32.join(packageRoot, 'launcher.mjs');
+    const program = entry ? [entry, 'launcher', ...args] : [nodePath, launcher, ...args];
+    const mark = winQuote(launcher);
+    if (entry) return { kind: 'run-value', key: RUN_KEY, name: NPM_LOGIN.winName, value: program.map(winQuote).join(' '), helper: null, mark, refuse: null };
+    const helperPath = win32.join(dataHome, 'runtime', 'login', HIDDEN_SCRIPT);
+    // wscript's own options stay bare (//B: no message boxes); everything else is one quoted argument each.
+    const value = [winQuote(systemTool(env, 'wscript.exe')), '//B', '//NoLogo', ...[helperPath, ...program].map(winQuote)].join(' ');
+    // WshShell.Run expands %NAME% in what it runs, and nothing escapes it: such a path cannot be started this way.
+    const refuse = [helperPath, ...program].some(word => word.includes('%')) ? 'bad-path' : null;
+    return { kind: 'run-value', key: RUN_KEY, name: NPM_LOGIN.winName, value, helper: { path: helperPath, content: HIDDEN_SCRIPT_SOURCE }, mark, refuse };
+  }
+
+  const launcher = entry || posix.join(packageRoot, 'launcher.mjs');
+  const program = entry ? [entry, 'launcher', ...args] : [nodePath, launcher, ...args];
+  if (platform === 'darwin') {
+    const shell = /^\/[\w./-]+$/.test(String(env.SHELL || '')) ? env.SHELL : null;
+    const content = [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+      '<plist version="1.0">',
+      '<dict>',
+      `  <key>Label</key><string>${NPM_LOGIN.macLabel}</string>`,
+      '  <key>ProgramArguments</key>',
+      '  <array>',
+      ...program.map(word => `    <string>${xmlEscape(word)}</string>`),
+      '  </array>',
+      `  <key>WorkingDirectory</key><string>${xmlEscape(packageRoot)}</string>`,
+      // The launcher reads the login shell's environment (PATH, nvm): it is told which shell that is.
+      ...(shell ? ['  <key>EnvironmentVariables</key>', '  <dict>', `    <key>SHELL</key><string>${xmlEscape(shell)}</string>`, '  </dict>'] : []),
+      '  <key>RunAtLoad</key><true/>',
+      // The server outlives the launcher: launchd must not end it with the launcher's process group.
+      '  <key>AbandonProcessGroup</key><true/>',
+      '  <key>ProcessType</key><string>Interactive</string>',
+      '  <key>StandardOutPath</key><string>/dev/null</string>',
+      '  <key>StandardErrorPath</key><string>/dev/null</string>',
+      '</dict>',
+      '</plist>',
+      '',
+    ].join('\n');
+    return { kind: 'launch-agent', path: posix.join(home, 'Library', 'LaunchAgents', `${NPM_LOGIN.macLabel}.plist`), content, mark: `<string>${xmlEscape(launcher)}</string>` };
+  }
+
+  const config = String(env.XDG_CONFIG_HOME || '');
+  const dir = posix.join(config.startsWith('/') ? config : posix.join(home, '.config'), 'autostart');
+  const content = [
+    '[Desktop Entry]',
+    'Type=Application',
+    'Name=SynaBun server',
+    'Comment=Starts the SynaBun server in the background when you log in',
+    `Exec=${program.map(desktopExecArg).join(' ')}`,
+    'Terminal=false',
+    'NoDisplay=true',
+    'X-GNOME-Autostart-enabled=true',
+    LINUX_MARKER,
+    '',
+  ].join('\n');
+  return { kind: 'autostart', path: posix.join(dir, NPM_LOGIN.linuxFile), content, mark: desktopExecArg(launcher) };
+}
+
+/**
+ * The entry as the system has it: 'on' (in place), 'stale' (there, but it
+ * starts something else: another Node, a moved install), 'disabled' (turned
+ * off in the system) or 'off' (not there).
+ */
+export function inspectLoginEntry(plan, { env = process.env, fs = DEFAULT_FS, run = defaultRun, uid = typeof process.getuid === 'function' ? process.getuid() : null } = {}) {
+  if (plan.kind === 'run-value') {
+    const reg = systemTool(env, 'reg.exe');
+    const value = readRegValue(plan.key, plan.name, { run, fs, env });
+    if (value == null) return 'off';
+    let approved = null;
+    try { approved = startupApproved(parseRegQuery(run(reg, ['query', APPROVED_KEY, '/v', plan.name]), plan.name)); } catch {}
+    if (approved === false) return 'disabled';
+    const helperOk = !plan.helper || (() => { try { return fs.readFileSync(plan.helper.path, 'utf8') === plan.helper.content; } catch { return false; } })();
+    return value === plan.value && helperOk ? 'on' : 'stale';
+  }
+  let text = null;
+  try { text = fs.readFileSync(plan.path, 'utf8'); } catch { return 'off'; }
+  if (plan.kind === 'autostart') {
+    const keys = desktopEntryKeys(text);
+    if (/^true$/i.test(keys.Hidden || '') || /^false$/i.test(keys['X-GNOME-Autostart-enabled'] || 'true')) return 'disabled';
+  }
+  if (plan.kind === 'launch-agent' && uid != null) {
+    // Login Items > Allow in the Background, switched off, disables the job.
+    try {
+      const out = run('/bin/launchctl', ['print-disabled', `gui/${uid}`]);
+      if (new RegExp(`"${NPM_LOGIN.macLabel.replace(/\./g, '\\.')}"\\s*=>\\s*(?:true|disabled)`).test(String(out))) return 'disabled';
+    } catch {}
+  }
+  return text === plan.content ? 'on' : 'stale';
+}
+
+function writeAtomic(fs, path, content, mode) {
+  fs.mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, content, mode ? { mode } : undefined);
+  fs.renameSync(temp, path);
+}
+
+/**
+ * Put the entry in place. Throws { code: 'write-failed' | 'no-wscript' }. With `enable` (the user turned it on
+ * in Settings) a switch the system holds for it is turned on too: Windows' Startup apps, launchd's disabled list.
+ */
+export function applyLoginEntry(plan, { env = process.env, fs = DEFAULT_FS, run = defaultRun, uid = typeof process.getuid === 'function' ? process.getuid() : null, enable = false } = {}) {
+  if (plan.refuse) throw failure(plan.refuse, 'a path with % in it cannot be started at login on Windows');
+  try {
+    if (plan.kind === 'run-value') {
+      const wscript = systemTool(env, 'wscript.exe');
+      if (plan.helper && win32.isAbsolute(wscript) && !fs.existsSync(wscript)) throw failure('no-wscript', `${wscript} is missing`);
+      if (plan.helper) writeAtomic(fs, plan.helper.path, plan.helper.content);
+      run(systemTool(env, 'reg.exe'), ['add', plan.key, '/v', plan.name, '/t', 'REG_SZ', '/d', plan.value, '/f']);
+      // No Startup apps record: enabled.
+      if (enable) { try { run(systemTool(env, 'reg.exe'), ['delete', APPROVED_KEY, '/v', plan.name, '/f']); } catch {} }
+      return;
+    }
+    writeAtomic(fs, plan.path, plan.content, 0o644);
+    if (enable && plan.kind === 'launch-agent' && uid != null) { try { run('/bin/launchctl', ['enable', `gui/${uid}/${NPM_LOGIN.macLabel}`]); } catch {} }
+  } catch (error) {
+    if (error.code === 'no-wscript') throw error;
+    throw failure('write-failed', error.message);
+  }
+}
+
+/** The entry as it is written now (the file, or the Run value), or null. */
+export function readLoginEntry(plan, { env = process.env, fs = DEFAULT_FS, run = defaultRun } = {}) {
+  if (plan.kind === 'run-value') return readRegValue(plan.key, plan.name, { run, fs, env });
+  try { return fs.readFileSync(plan.path, 'utf8'); } catch { return null; }
+}
+
+/** Take the entry away. Throws { code: 'write-failed' } when it stays. */
+export function removeLoginEntry(plan, { env = process.env, fs = DEFAULT_FS, run = defaultRun, uid = typeof process.getuid === 'function' ? process.getuid() : null } = {}) {
+  try {
+    if (plan.kind === 'run-value') {
+      try { run(systemTool(env, 'reg.exe'), ['delete', plan.key, '/v', plan.name, '/f']); } catch (error) {
+        if (inspectLoginEntry(plan, { env, fs, run }) !== 'off') throw error;
+      }
+      if (plan.helper) fs.rmSync(plan.helper.path, { force: true });
+      return;
+    }
+    if (plan.kind === 'launch-agent' && uid != null) {
+      // Loaded since the last login (it ran once then): unload it too.
+      try { run('/bin/launchctl', ['bootout', `gui/${uid}/${NPM_LOGIN.macLabel}`]); } catch {}
+    }
+    fs.rmSync(plan.path, { force: true });
+  } catch (error) {
+    throw failure('write-failed', error.message);
+  }
+}
+
+// ── The desktop app's entry, as the system has it ──
+
+/** The strings of a plist's ProgramArguments array. */
+function plistArguments(text) {
+  const block = /<key>\s*ProgramArguments\s*<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(String(text || ''));
+  const unxml = (v) => v.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+  return block ? [...block[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map(m => unxml(m[1])) : [];
+}
+
+/** The words of a .desktop Exec value (its quoting and escapes undone). */
+function desktopExecWords(value) {
+  const text = String(value || '').replace(/\\\\/g, '\\').replace(/%%/g, '%');
+  const words = [];
+  let word = '';
+  let quoted = false;
+  let any = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch === '\\' && i + 1 < text.length) { word += text[++i]; continue; }
+      if (ch === '"') { quoted = false; continue; }
+      word += ch;
+    } else if (ch === '"') { quoted = true; any = true; } else if (/\s/.test(ch)) {
+      if (word || any) words.push(word);
+      word = ''; any = false;
+    } else word += ch;
+  }
+  if (word || any) words.push(word);
+  return words;
+}
+
+/** The words of a Windows command line (CommandLineToArgvW's quoting). */
+function windowsWords(line) {
+  const text = String(line || '');
+  const words = [];
+  let word = '';
+  let quoted = false;
+  let any = false;
+  let i = 0;
+  while (i < text.length) {
+    const ch = text[i];
+    if (ch === '\\') {
+      let slashes = 0;
+      while (text[i] === '\\') { slashes++; i++; }
+      if (text[i] === '"') {
+        word += '\\'.repeat(Math.floor(slashes / 2));
+        if (slashes % 2) { word += '"'; any = true; i++; }
+      } else word += '\\'.repeat(slashes);
+      continue;
+    }
+    i++;
+    if (ch === '"') { quoted = !quoted; any = true; continue; }
+    if (!quoted && /\s/.test(ch)) { if (word || any) words.push(word); word = ''; any = false; continue; }
+    word += ch;
+  }
+  if (word || any) words.push(word);
+  return words;
+}
+
+const samePath = (a, b, platform) => {
+  if (!a || !b) return false;
+  const norm = (value) => (platform === 'win32' ? win32.resolve(value) : posix.resolve(value)).replace(/[\\/]+$/, '');
+  return platform === 'linux' ? norm(a) === norm(b) : norm(a).toLowerCase() === norm(b).toLowerCase();
+};
+
+/**
+ * The desktop app's program when its login entry, as the system has it now (there, not switched off, its program
+ * still there), opens it on `dataHome`; otherwise null. The app's own settings file is not asked: an entry the user
+ * removed or switched off while the app was closed never blocks this install.
+ */
+export function desktopLoginOwner(dataHome, {
+  platform = process.platform, home = homedir(), env = process.env, fs = DEFAULT_FS, run = defaultRun,
+  uid = typeof process.getuid === 'function' ? process.getuid() : null,
+} = {}) {
+  const usual = platform === 'win32' ? (env.APPDATA ? win32.resolve(env.APPDATA, 'synabun') : null) : posix.join(home, '.synabun');
+  const owns = (program, folder) => (program && fs.existsSync(program) && samePath(folder || usual, dataHome, platform) ? program : null);
+  try {
+    if (platform === 'darwin') {
+      const text = fs.readFileSync(posix.join(home, 'Library', 'LaunchAgents', `${DESKTOP_LOGIN.macLabel}.plist`), 'utf8');
+      if (uid != null) {
+        try {
+          const out = run('/bin/launchctl', ['print-disabled', `gui/${uid}`]);
+          if (new RegExp(`"${DESKTOP_LOGIN.macLabel.replace(/\./g, '\\.')}"\\s*=>\\s*(?:true|disabled)`).test(String(out))) return null;
+        } catch {}
+      }
+      // `open -a <app> --env …`, or (a Mac whose `open` has no --env) the app's own program with its environment.
+      const words = plistArguments(text);
+      const unxml = (v) => v.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+      const direct = /^(.+\.app)\/Contents\/MacOS\/[^/]+$/.exec(words[0] || '');
+      const bundle = words.indexOf('-a') >= 0 ? words[words.indexOf('-a') + 1] : direct ? direct[1] : null;
+      const folder = words.find(w => w.startsWith('SYNABUN_DATA_HOME='))?.slice('SYNABUN_DATA_HOME='.length)
+        ?? (/<key>SYNABUN_DATA_HOME<\/key>\s*<string>([\s\S]*?)<\/string>/.exec(text)?.[1] ? unxml(/<key>SYNABUN_DATA_HOME<\/key>\s*<string>([\s\S]*?)<\/string>/.exec(text)[1]) : undefined);
+      return owns(bundle, folder);
+    }
+    if (platform === 'win32') {
+      const value = readRegValue(RUN_KEY, DESKTOP_LOGIN.winName, { run, fs, env });
+      if (value == null) return null;
+      let approved = null;
+      try { approved = startupApproved(parseRegQuery(run(systemTool(env, 'reg.exe'), ['query', APPROVED_KEY, '/v', DESKTOP_LOGIN.winName]), DESKTOP_LOGIN.winName)); } catch {}
+      if (approved === false) return null;
+      const words = windowsWords(value);
+      const data = words.find(w => w.startsWith(DESKTOP_LOGIN.dataFlag));
+      let folder = null;
+      if (data) { try { folder = Buffer.from(data.slice(DESKTOP_LOGIN.dataFlag.length), 'base64url').toString('utf8') || null; } catch {} }
+      return words.includes(DESKTOP_LOGIN.flag) ? owns(words[0], folder) : null;
+    }
+    const config = String(env.XDG_CONFIG_HOME || '');
+    const file = posix.join(config.startsWith('/') ? config : posix.join(home, '.config'), 'autostart', DESKTOP_LOGIN.linuxFile);
+    const keys = desktopEntryKeys(fs.readFileSync(file, 'utf8'));
+    if (/^true$/i.test(keys.Hidden || '') || /^false$/i.test(keys['X-GNOME-Autostart-enabled'] || 'true')) return null;
+    const words = desktopExecWords(keys.Exec);
+    const vars = words[0] === 'env' ? words.slice(1).filter(w => /^[A-Za-z_][A-Za-z0-9_]*=/.test(w)) : [];
+    const program = words[0] === 'env' ? words.slice(1).find(w => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w)) : words[0];
+    const folder = vars.find(w => w.startsWith('SYNABUN_DATA_HOME='))?.slice('SYNABUN_DATA_HOME='.length);
+    return owns(program, folder);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The start at login of this install.
+ *
+ *   status()       { supported, reason, enabled, state, owner }: reason 'desktop' (the desktop
+ *                  app has its own: Settings reads it from the app), 'not-here' (a test run or a
+ *                  throwaway data folder) or 'unsupported'; owner is the desktop app's program
+ *                  when it opens at login on this data folder
+ *   set(enabled)   turn it on or off; resolves to status(). Throws { code }: 'desktop-app', 'not-here',
+ *                  'write-failed', 'no-wscript', 'refused'
+ *   heal()         on a server start: this install's own entry, when stale, is put back in place; an entry that
+ *                  starts another install, or one the user turned off, is left as it is
+ */
+export function createLoginStart({
+  platform = process.platform, nodePath = process.execPath, packageRoot, home = homedir(), env = process.env, dataHome,
+  entry = null, desktopShell = false, allowed = () => true, fs = DEFAULT_FS, run = defaultRun, uid,
+  log = () => {},
+} = {}) {
+  const ops = { env, fs, run, ...(uid !== undefined ? { uid } : {}) };
+  const plan = () => buildLoginPlan({ platform, nodePath, packageRoot, home, env, dataHome, entry });
+  const support = () => {
+    if (desktopShell) return { supported: false, reason: 'desktop' };
+    if (!['darwin', 'win32', 'linux'].includes(platform)) return { supported: false, reason: 'unsupported' };
+    if (!allowed()) return { supported: false, reason: 'not-here' };
+    return { supported: true, reason: null };
+  };
+
+  function status() {
+    const { supported, reason } = support();
+    const owner = desktopLoginOwner(dataHome, { platform, home, env, ...ops });
+    if (!supported) return { supported, reason, enabled: false, state: 'off', owner };
+    let state = 'off';
+    try { state = inspectLoginEntry(plan(), ops); } catch {}
+    return { supported, reason, enabled: state === 'on' || state === 'stale', state, owner };
+  }
+
+  async function set(enabled) {
+    const { supported, reason } = support();
+    if (!supported) throw failure(reason, `start at login is not available here (${reason})`);
+    const target = plan();
+    if (enabled) {
+      const owner = desktopLoginOwner(dataHome, { platform, home, env, ...ops });
+      if (owner) throw failure('desktop-app', `the SynaBun app opens at login on this data folder (${owner})`);
+      applyLoginEntry(target, { ...ops, enable: true });
+    } else {
+      removeLoginEntry(target, ops);
+    }
+    const after = status();
+    log(`start at login ${enabled ? 'on' : 'off'}: ${after.state}`);
+    if (enabled ? after.state !== 'on' : after.enabled) throw failure('refused', after.state);
+    return after;
+  }
+
+  function heal() {
+    const { supported } = support();
+    if (!supported) return { changed: false, state: 'off' };
+    const target = plan();
+    const state = inspectLoginEntry(target, ops);
+    if (state !== 'stale') return { changed: false, state };
+    // Only this install's own entry (another Node, other pins): one that starts another install on this data folder
+    // (an npm install, a Git checkout run by hand) is that install's, and stays as it is.
+    if (!String(readLoginEntry(target, ops) || '').includes(target.mark)) return { changed: false, state };
+    applyLoginEntry(target, ops);
+    log('start at login: the entry now starts this install');
+    return { changed: true, state: inspectLoginEntry(target, ops) };
+  }
+
+  return { status, set, heal, plan };
+}

package/neural-interface/lib/mcp-agent-servers.js

@@ -0,0 +1,67 @@
+// Registry conversion is read-only. An explicit switch is authoritative; missing switches are on.
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+export function agentAccessFrom(registry) {
+  const reg = asObject(registry);
+  if (reg.agentAccess && typeof reg.agentAccess === 'object' && !Array.isArray(reg.agentAccess)) return { ...reg.agentAccess };
+  const profile = asObject(asObject(reg.profiles)[reg.activeProfile]);
+  if (!Array.isArray(profile.servers)) return {};
+  const granted = new Set(profile.servers);
+  // The old reconciliation marker distinguishes a de-selection from a genuinely new server.
+  const known = new Set(Array.isArray(reg.profileDefaults?.knownServers)
+    ? reg.profileDefaults.knownServers : Object.keys(asObject(reg.servers)));
+  return Object.fromEntries(Object.entries(asObject(reg.servers))
+    .filter(([name, entry]) => !entry?.builtin && known.has(name) && !granted.has(name))
+    .map(([name]) => [name, false]));
+}
+
+export function agentServerNames(registry) {
+  const reg = asObject(registry);
+  const access = agentAccessFrom(reg);
+  return Object.entries(asObject(reg.servers))
+    .filter(([name, entry]) => !entry?.builtin && access[name] !== false)
+    .map(([name]) => name);
+}
+
+/**
+ * Tools that mutate ad state or spend budget, keyed by MCP server name.
+ *
+ * FleetView agents run with `--permission-mode bypassPermissions`, so the read-only
+ * allowlist in .claude/settings.json does not apply to them. These are pushed as
+ * `--disallowedTools` instead: agents keep full read/reporting access, while anything
+ * that creates, edits, activates, or deletes stays with a human.
+ */
+export const MCP_SERVER_WRITE_TOOLS = {
+  'meta-ads': [
+    'ads_create_campaign', 'ads_create_ad_set', 'ads_create_ad', 'ads_create_creative',
+    'ads_update_entity', 'ads_activate_entity', 'ads_boost_ig_post',
+    'ads_create_custom_audience', 'ads_update_custom_audience',
+    'ads_update_custom_audience_users', 'ads_delete_custom_audience',
+    'ads_catalog_create', 'ads_catalog_update_catalog',
+    'ads_catalog_product_create', 'ads_catalog_update_product', 'ads_catalog_delete_product',
+    'ads_catalog_create_product_set', 'ads_catalog_update_product_set', 'ads_catalog_product_set_delete',
+    'ads_catalog_create_product_feed', 'ads_catalog_update_product_feed',
+    'ads_catalog_create_product_feed_upload_session', 'ads_catalog_product_feed_delete',
+    'ads_catalog_create_feed_rule', 'ads_catalog_product_feed_delete_rule',
+    'ads_catalog_event_source_connect', 'ads_catalog_event_source_disconnect',
+    'ads_pixel_event_create', 'ads_pixel_event_update', 'ads_pixel_event_delete',
+    'ads_pixel_parameter_create', 'ads_pixel_parameter_update', 'ads_pixel_parameter_delete',
+    'ads_experiment_abtest_create_test', 'ads_experiment_abtest_update_test',
+    'ads_experiment_lift_create_test',
+  ],
+};
+
+/** Fully-qualified deny list for whichever servers an agent's --mcp-config actually grants. */
+export function buildAgentDisallowedTools(mcpConfigJson) {
+  let serverNames = [];
+  try {
+    serverNames = Object.keys(asObject(JSON.parse(mcpConfigJson || '{}')).mcpServers || {});
+  } catch { return []; }
+  const deny = [];
+  for (const server of serverNames) {
+    for (const tool of MCP_SERVER_WRITE_TOOLS[server] || []) deny.push(`mcp__${server}__${tool}`);
+  }
+  return deny;
+}

package/neural-interface/lib/mcp-client-config.js

@@ -102,32 +102,3 @@ export function mergeGeminiMcpConfig(existing, definition) {
     },
   };
 }
-
-export function toOpenCodeMcpEntry(mcpConfig) {
-  const source = asObject(mcpConfig);
-  const { type: _type, command, args, env, environment, headers, oauth: _oauth, url, ...rest } = source;
-  if (isRemoteMcp(source)) {
-    // OpenCode names the URL-addressed transport "remote"; there is no http/sse split.
-    const entry = { type: 'remote', url, ...rest };
-    const hdrs = hasKeys(headers);
-    if (hdrs) entry.headers = { ...hdrs };
-    if (entry.enabled === undefined) entry.enabled = true;
-    return entry;
-  }
-  const entry = { type: 'local', ...rest };
-  if (command) entry.command = Array.isArray(command) ? [...command] : [command, ...(args || [])];
-  const envObj = environment || env;
-  if (envObj && Object.keys(envObj).length > 0) entry.environment = { ...envObj };
-  return entry;
-}
-
-export function mergeOpenCodeMcpConfig(existing, name, mcpConfig) {
-  const config = asObject(existing);
-  return {
-    ...config,
-    mcp: {
-      ...asObject(config.mcp),
-      [name]: toOpenCodeMcpEntry(mcpConfig),
-    },
-  };
-}