synabun 2026.4.26-beta.4 → 2026.4.26-beta.6

package/neural-interface/public/shared/ui-update.js

@@ -160,7 +160,7 @@ function openUpdateModal() {
     return `
       <h3 class="update-modal-title">Run the Update</h3>
       <p style="font-size:12px;color:var(--t-muted);margin:4px 0 12px">
-        Run this command in your terminal to update SynaBun:
+        SynaBun will close and run this command in a new terminal window:
       </p>
       <div class="update-code-block">
         <code>${esc(installCmd)}</code>
@@ -168,19 +168,29 @@ function openUpdateModal() {
           <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
         </button>
       </div>
-      <p style="font-size:12px;color:var(--t-muted);margin:12px 0 8px">
-        Then restart the Neural Interface:
-      </p>
-      <div class="update-code-block">
-        <code>node neural-interface/server.js</code>
-        <button class="update-copy-btn" data-copy="node neural-interface/server.js" title="Copy">
-          <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
-        </button>
+
+      <label class="update-skip-label" style="margin:14px 0 8px;display:flex;align-items:center;gap:8px;cursor:pointer">
+        <input type="checkbox" id="update-auto-restart" checked>
+        <span>Relaunch SynaBun after update</span>
+      </label>
+
+      <div class="update-run-status" id="update-run-status" style="display:none;margin:10px 0 0">
+        <span class="update-backup-icon" id="update-run-icon"></span>
+        <span id="update-run-text"></span>
       </div>
-      <div class="tag-delete-modal-actions" style="margin-top:18px">
+
+      <div class="tag-delete-modal-actions" style="margin-top:14px;flex-wrap:wrap;gap:8px">
         <button class="action-btn action-btn--ghost" id="update-back">Back</button>
-        <button class="action-btn action-btn--primary" id="update-done">Done</button>
-      </div>`;
+        <button class="action-btn action-btn--ghost" id="update-manual" title="Run the command yourself in your own terminal">Manual</button>
+        <button class="action-btn action-btn--primary" id="update-run-now">
+          <svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:6px"><polyline points="8 17 12 21 16 17"/><line x1="12" y1="12" x2="12" y2="21"/><path d="M20.88 18.09A5 5 0 0 0 18 9h-1.26A8 8 0 1 0 3 16.29"/></svg>
+          Update Now
+        </button>
+      </div>
+
+      <p id="update-manual-note" style="display:none;font-size:11px;color:var(--t-muted);opacity:.75;margin:10px 0 0">
+        After running the command, restart SynaBun: <code>synabun</code>
+      </p>`;
   }
 
   function bindEvents() {
@@ -221,6 +231,16 @@ function openUpdateModal() {
     // Backup download
     overlay.querySelector('#update-backup-download')?.addEventListener('click', handleBackupDownload);
 
+    // Update Now — kick off click-to-update flow
+    overlay.querySelector('#update-run-now')?.addEventListener('click', handleRunUpdate);
+
+    // Manual — surface the command + relaunch hint, hide auto-update controls
+    overlay.querySelector('#update-manual')?.addEventListener('click', () => {
+      overlay.querySelector('#update-manual-note').style.display = '';
+      overlay.querySelector('#update-run-now').style.display = 'none';
+      overlay.querySelector('#update-auto-restart').closest('label').style.display = 'none';
+    });
+
     // Skip checkbox
     const skipCb = overlay.querySelector('#update-skip-backup');
     if (skipCb) {
@@ -232,6 +252,67 @@ function openUpdateModal() {
     }
   }
 
+  async function handleRunUpdate() {
+    // Resolve the same install tag the modal copy showed (channel-aware).
+    const target = _versionData?.latest || '';
+    const channel = _versionData?.installedChannel || 'stable';
+    const targetIsBeta = !!parseSemverPre(target);
+    const tag = (channel === 'prerelease' && targetIsBeta) ? 'beta' : 'latest';
+
+    const autoRestartCb = overlay.querySelector('#update-auto-restart');
+    const autoRestart = !!autoRestartCb?.checked;
+
+    const runBtn = overlay.querySelector('#update-run-now');
+    const backBtn = overlay.querySelector('#update-back');
+    const manualBtn = overlay.querySelector('#update-manual');
+    const status = overlay.querySelector('#update-run-status');
+    const icon = overlay.querySelector('#update-run-icon');
+    const text = overlay.querySelector('#update-run-text');
+
+    runBtn.disabled = true;
+    backBtn.disabled = true;
+    manualBtn.disabled = true;
+    runBtn.innerHTML = '<span class="update-spinner"></span> Launching updater...';
+    status.style.display = 'flex';
+    icon.className = 'update-backup-icon spin';
+    icon.textContent = '⟳';
+    text.textContent = 'Opening updater terminal and shutting down server...';
+
+    try {
+      const res = await fetch('/api/system/run-update', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ tag, autoRestart }),
+      });
+      if (!res.ok) {
+        let msg = `Updater failed (${res.status})`;
+        try { const b = await res.json(); msg = b.error || msg; } catch {}
+        throw new Error(msg);
+      }
+      const body = await res.json();
+
+      icon.className = 'update-backup-icon';
+      icon.textContent = '✓';
+      icon.style.color = '#34c759';
+      text.innerHTML = `Updater terminal launched. <strong>This window will go offline.</strong> Watch the new terminal for install progress${autoRestart ? ' — SynaBun relaunches when done.' : '. Run <code>synabun</code> after install completes.'}`;
+      runBtn.innerHTML = 'Updater running…';
+
+      // Server is shutting down. Optionally redirect to a friendly offline
+      // notice — for now leave the page; user already understands from copy.
+      // Re-enable Back so they can close the modal.
+      setTimeout(() => { backBtn.disabled = false; }, 2500);
+    } catch (err) {
+      icon.className = 'update-backup-icon';
+      icon.textContent = '✗';
+      icon.style.color = 'var(--accent-red)';
+      text.textContent = 'Failed to launch updater: ' + err.message;
+      runBtn.disabled = false;
+      backBtn.disabled = false;
+      manualBtn.disabled = false;
+      runBtn.innerHTML = `<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-2px;margin-right:6px"><polyline points="8 17 12 21 16 17"/><line x1="12" y1="12" x2="12" y2="21"/><path d="M20.88 18.09A5 5 0 0 0 18 9h-1.26A8 8 0 1 0 3 16.29"/></svg> Retry`;
+    }
+  }
+
   async function handleBackupDownload() {
     const btn = overlay.querySelector('#update-backup-download');
     const status = overlay.querySelector('#update-backup-status');

package/neural-interface/server.js

@@ -1546,14 +1546,264 @@ app.put('/api/settings', (req, res) => {
   }
 });
 
-// POST /api/server/restart — Gracefully restart the server process
-app.post('/api/server/restart', (req, res) => {
-  console.log('[server] Restart requested — shutting down in 500ms...');
+// ── Graceful shutdown — kills all spawned children before exiting ──
+//
+// Background: the previous /api/server/restart only ran closeDb() + exit(0),
+// leaving spawned children orphaned (opencode sidecar, agents, _sidecarProcess
+// CLI links, pty terminals, cloudflare tunnel). On Windows those orphans
+// kept file handles inside neural-interface/ open, causing EBUSY errors when
+// `npm install -g synabun@latest` tried to rename the package directory.
+//
+// gracefulShutdown() centralizes shutdown so /api/server/restart,
+// /api/server/shutdown, and the new /api/system/run-update all release
+// children before exiting.
+
+let _shutdownInProgress = false;
+
+async function gracefulShutdown(reason = 'shutdown') {
+  if (_shutdownInProgress) return;
+  _shutdownInProgress = true;
+  console.log(`[server] gracefulShutdown(${reason}) — releasing children...`);
+
+  // 1. opencode sidecar — has its own teardown that handles managed PID + ollama.
+  try { stopOpencodeServer(); } catch (err) { console.warn('  opencode stop err:', err?.message); }
+
+  // 2. Agents in agentRegistry — use platform-native tree kill so descendants die too.
+  try {
+    const isWin = process.platform === 'win32';
+    for (const agent of agentRegistry.values()) {
+      const pid = agent?.process?.pid;
+      if (!pid || agent.status !== 'running') continue;
+      agent._stopped = true;
+      agent.status = 'stopped';
+      try {
+        if (isWin) {
+          spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { shell: true, windowsHide: true });
+        } else {
+          try { process.kill(-pid, 'SIGTERM'); } catch { try { agent.process.kill('SIGTERM'); } catch {} }
+        }
+      } catch {}
+    }
+  } catch (err) { console.warn('  agent kill err:', err?.message); }
+
+  // 3. Save snapshot + DB last so children release file handles before SQLite closes.
+  try { saveSessionSnapshot(); } catch {}
+
+  // 4. Brief grace period so SIGTERM'd children can flush.
+  await new Promise(r => setTimeout(r, 500));
+
+  try { closeDb(); } catch {}
+
+  // 5. Belt-and-suspenders: tree-kill THIS process's descendants on Windows.
+  // Synabun spawns CLI links, pty terminals, cloudflare tunnel etc. that may
+  // not be reachable through the registries above. The taskkill /T flag walks
+  // the process tree and terminates every descendant.
+  if (process.platform === 'win32') {
+    try {
+      // Use spawn(detached) so taskkill survives our own exit and finishes
+      // killing children even if we exit before it completes.
+      const tk = spawn('taskkill', ['/pid', String(process.pid), '/T'], {
+        shell: true, windowsHide: true, detached: true, stdio: 'ignore',
+      });
+      tk.unref();
+    } catch {}
+  }
+
+  console.log(`[server] gracefulShutdown(${reason}) complete — exiting.`);
+}
+
+// POST /api/server/restart — Gracefully restart the server process.
+// (Caller is expected to launch a new instance externally; we just exit.)
+app.post('/api/server/restart', async (req, res) => {
+  console.log('[server] Restart requested.');
   res.json({ ok: true, message: 'Server restarting...' });
-  setTimeout(() => {
-    closeDb();
+  // Defer so the response flushes before we start tearing down children.
+  setTimeout(async () => {
+    await gracefulShutdown('restart');
+    process.exit(0);
+  }, 200);
+});
+
+// POST /api/server/shutdown — Graceful shutdown without restart. Used by
+// `npm uninstall synabun` (preuninstall.js) and the in-app updater.
+app.post('/api/server/shutdown', async (req, res) => {
+  console.log('[server] Shutdown requested.');
+  res.json({ ok: true, message: 'Server shutting down...' });
+  setTimeout(async () => {
+    await gracefulShutdown('shutdown');
     process.exit(0);
-  }, 500);
+  }, 200);
+});
+
+// POST /api/system/run-update — Click-to-update flow for npm-installed users.
+//
+// Spawns the per-OS updater shim (updater.cmd on Windows, updater.sh on
+// macOS/Linux) in a NEW visible terminal window. Each shim invokes
+// updater.mjs and handles its own "press a key to close" lifecycle so we
+// don't have to thread cmd /k or bash -c quoting through node's spawn.
+//
+// The updater shim:
+//   1. Waits for the server PID to exit
+//   2. Runs `npm install -g synabun@<tag>`
+//   3. Optionally relaunches synabun
+//   4. Holds the terminal open so the user sees output / errors
+//
+// Right after spawning the detached updater, we run gracefulShutdown +
+// process.exit so file handles in neural-interface/ release and npm's
+// rename succeeds. The updater polls our PID and only starts npm after
+// we're gone.
+app.post('/api/system/run-update', async (req, res) => {
+  try {
+    const tag = String((req.body?.tag || 'latest')).replace(/[^a-zA-Z0-9_.-]/g, '');
+    const autoRestart = !!req.body?.autoRestart;
+    const allowedTags = new Set(['latest', 'beta', 'next', 'rc', 'alpha']);
+    if (!allowedTags.has(tag)) {
+      return res.status(400).json({ error: `tag must be one of: ${[...allowedTags].join(', ')}` });
+    }
+
+    const plat = process.platform;
+    const shimPath = plat === 'win32'
+      ? resolve(PACKAGE_ROOT, 'updater.cmd')
+      : resolve(PACKAGE_ROOT, 'updater.sh');
+    const updaterMjsPath = resolve(PACKAGE_ROOT, 'updater.mjs');
+
+    if (!existsSync(updaterMjsPath)) {
+      return res.status(500).json({ error: `updater.mjs not found at ${updaterMjsPath}. SynaBun install may be corrupt — reinstall: npm install -g synabun@${tag}` });
+    }
+    if (!existsSync(shimPath)) {
+      return res.status(500).json({ error: `${plat === 'win32' ? 'updater.cmd' : 'updater.sh'} not found at ${shimPath}. SynaBun install may be corrupt — reinstall: npm install -g synabun@${tag}` });
+    }
+
+    // On Unix, ensure the shim is executable. npm publish preserves the
+    // executable bit only if it was set when packed; defensive chmod here
+    // covers users whose tarball lost it (some Windows-staged pipelines do).
+    if (plat !== 'win32') {
+      try { chmodSync(shimPath, 0o755); } catch {}
+    }
+
+    const serverPid = process.pid;
+    const argsBase = ['--tag', tag, '--pid', String(serverPid)];
+    if (autoRestart) argsBase.push('--restart');
+
+    let spawned = null;
+    let launchError = null;
+
+    if (plat === 'win32') {
+      // Use shell:true so cmd parses our string directly — bypasses node's
+      // arg-escape algorithm that was mangling the title arg ("SynaBun
+      // Update" was being eaten by start's title slot, leaving Windows to
+      // try to launch "Update" as a program).
+      //
+      // `start "" "<shim>" args` — empty title (cmd's start ALWAYS treats
+      // the first quoted arg as a title), then runs the .cmd shim with
+      // args. The shim handles its own pause-before-close.
+      const argsLine = argsBase.map(a => `"${String(a).replace(/"/g, '""')}"`).join(' ');
+      const cmdLine = `start "" "${shimPath}" ${argsLine}`;
+      try {
+        spawned = spawn(cmdLine, {
+          shell: true,
+          detached: true,
+          stdio: 'ignore',
+          windowsHide: false,
+        });
+      } catch (err) { launchError = err; }
+    } else if (plat === 'darwin') {
+      // Drive Terminal.app via osascript. The shim path may contain spaces;
+      // wrap it in single quotes inside the AppleScript string. AppleScript
+      // string is wrapped in JS double-quote, so we escape JS backslashes
+      // and double-quotes after building the inner shell command.
+      const shellEscape = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+      const appleCmd = `${shellEscape(shimPath)} ${argsBase.map(shellEscape).join(' ')}`;
+      try {
+        spawned = spawn('osascript', [
+          '-e', 'tell application "Terminal" to activate',
+          '-e', `tell application "Terminal" to do script "${appleCmd.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`,
+        ], { detached: true, stdio: 'ignore' });
+      } catch (err) { launchError = err; }
+    } else {
+      // Linux/BSD/etc — try common terminal emulators in order. Each gets
+      // the shim path as the program to run; the shim itself is a bash
+      // script so we let the terminal exec it directly without bash -c.
+      const candidates = [
+        ['x-terminal-emulator', ['-e', shimPath, ...argsBase]],
+        ['gnome-terminal',      ['--', shimPath, ...argsBase]],
+        ['konsole',             ['-e', shimPath, ...argsBase]],
+        ['xfce4-terminal',      ['-e', `${shimPath} ${argsBase.map(a => `"${a}"`).join(' ')}`]],
+        ['mate-terminal',       ['-e', `${shimPath} ${argsBase.map(a => `"${a}"`).join(' ')}`]],
+        ['lxterminal',          ['-e', shimPath, ...argsBase]],
+        ['terminator',          ['-e', `${shimPath} ${argsBase.map(a => `"${a}"`).join(' ')}`]],
+        ['alacritty',           ['-e', shimPath, ...argsBase]],
+        ['kitty',               [shimPath, ...argsBase]],
+        ['wezterm',             ['start', '--', shimPath, ...argsBase]],
+        ['urxvt',               ['-e', shimPath, ...argsBase]],
+        ['xterm',               ['-e', shimPath, ...argsBase]],
+      ];
+      for (const [bin, args] of candidates) {
+        let child = null;
+        try {
+          child = spawn(bin, args, { detached: true, stdio: 'ignore' });
+        } catch {
+          continue;
+        }
+        // spawn() doesn't throw synchronously when bin is missing — it emits
+        // 'error' async (ENOENT). Probe briefly to detect that case before
+        // declaring success and unrefing.
+        const survived = await new Promise((resolveProbe) => {
+          let settled = false;
+          const onErr = () => {
+            if (settled) return;
+            settled = true;
+            child.removeAllListeners('error');
+            resolveProbe(false);
+          };
+          child.once('error', onErr);
+          setTimeout(() => {
+            if (settled) return;
+            settled = true;
+            child.removeAllListeners('error');
+            resolveProbe(true);
+          }, 150);
+        });
+        if (survived) { spawned = child; break; }
+      }
+      if (!spawned) {
+        launchError = new Error(
+          'No supported terminal emulator found (tried: x-terminal-emulator, gnome-terminal, konsole, xfce4-terminal, mate-terminal, lxterminal, terminator, alacritty, kitty, wezterm, urxvt, xterm). ' +
+          `Install one (e.g. \`apt install xterm\`) or run manually: npm install -g synabun@${tag}`
+        );
+      }
+    }
+
+    if (!spawned) {
+      const msg = launchError?.message || `Failed to launch updater terminal on ${plat}`;
+      console.error('[server] run-update launch failed:', msg);
+      return res.status(500).json({ error: msg });
+    }
+
+    // Don't tie our shutdown to the spawned process — it's a long-living
+    // terminal we don't want to wait on.
+    spawned.unref();
+    spawned.on('error', (err) => {
+      // Async ENOENT etc. — log but the response already went out.
+      console.error('[server] updater spawn async error:', err.message);
+    });
+
+    console.log(`[server] Updater terminal launched (tag=${tag}, autoRestart=${autoRestart}, shim=${shimPath}). Shutting down...`);
+    res.json({ ok: true, tag, autoRestart, shimPath, platform: plat });
+
+    // Give the spawned terminal time to fully launch before we tear down
+    // (on Windows `start` returns instantly but the new window takes a
+    // beat to init node; on macOS osascript dispatches AppleScript async).
+    // 1.2s is generous; updater polls our PID anyway so an extra second
+    // here is harmless.
+    setTimeout(async () => {
+      await gracefulShutdown('run-update');
+      process.exit(0);
+    }, 1200);
+  } catch (err) {
+    console.error('[server] run-update error:', err?.message);
+    if (!res.headersSent) res.status(500).json({ error: err.message });
+  }
 });
 
 // POST /api/settings/move-db — Move SQLite database to a new directory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synabun",
-  "version": "2026.4.26-beta.4",
+  "version": "2026.4.26-beta.6",
   "description": "Persistent vector memory for AI assistants",
   "license": "Apache-2.0",
   "author": "The SynaBun Authors",
@@ -17,6 +17,9 @@
     "setup.js",
     "postinstall.js",
     "preuninstall.js",
+    "updater.mjs",
+    "updater.cmd",
+    "updater.sh",
     "mcp-server/package.json",
     "mcp-server/dist/",
     "mcp-server/tsconfig.json",

package/postinstall.js

@@ -197,6 +197,25 @@ function registerProtocolHandler() {
   }
 }
 
+// ── Updater shim executable bit ──
+//
+// npm publish drops the executable bit on macOS/Linux when the tarball is
+// built on Windows (a common pipeline issue). The in-app updater needs
+// updater.sh to be executable so the per-OS terminal-launch path can
+// `exec()` it directly. Restore the bit defensively on every postinstall.
+
+function ensureUpdaterShExecutable() {
+  if (platform() === 'win32') return;
+  const shPath = resolve(__dirname, 'updater.sh');
+  if (!existsSync(shPath)) return;
+  try {
+    chmodSync(shPath, 0o755);
+    ok('updater.sh marked executable');
+  } catch (err) {
+    warn(`updater.sh chmod failed (${err.message}) — manual fix: chmod +x "${shPath}"`);
+  }
+}
+
 // ── Main ──
 
 function main() {
@@ -207,6 +226,7 @@ function main() {
   rebuildPty();
   buildMcpServer();
   registerProtocolHandler();
+  ensureUpdaterShExecutable();
 
   console.log(`\n  ${c.green}\u2713${c.reset} Setup complete. Run ${c.cyan}synabun${c.reset} to start.\n`);
 }

package/preuninstall.js

@@ -3,10 +3,18 @@
 /**
  * SynaBun — NPM preuninstall script
  *
- * Runs before `npm uninstall synabun`.
- * Removes nested node_modules that cause EPERM/deep-path errors on Windows.
- * Removes the synabun:// protocol handler registration.
- * Graceful — if cleanup fails, don't block the uninstall.
+ * Runs before `npm uninstall synabun` AND before `npm install -g synabun@x`
+ * overwrites the existing install.
+ *
+ *   1. Politely ask any running SynaBun server to shut down so its child
+ *      processes (opencode sidecar, agents, pty terminals) release file
+ *      handles inside neural-interface/. Without this step, npm's rename
+ *      step fails with EBUSY on Windows.
+ *   2. Remove nested node_modules that cause EPERM/deep-path errors on Windows.
+ *   3. Remove the synabun:// protocol handler registration.
+ *
+ * Graceful — if any step fails, don't block the uninstall. npm will handle
+ * the remainder; the user can always retry.
  */
 
 import { rmSync, existsSync } from 'node:fs';
@@ -17,7 +25,51 @@ import { homedir, platform } from 'node:os';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// ── Remove nested node_modules ──
+// ── Step 1: ask running SynaBun server to shut down cleanly ──
+// Default port 3344 (matches NEURAL_PORT default in server.js). If the user
+// changed NEURAL_PORT we miss them; that's acceptable since the next steps
+// degrade gracefully. We don't want to scan all ports — too invasive for a
+// preuninstall script.
+
+await tryGracefulServerShutdown();
+
+async function tryGracefulServerShutdown() {
+  const port = Number(process.env.NEURAL_PORT) || 3344;
+  const url = `http://127.0.0.1:${port}/api/server/shutdown`;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 2000);
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    if (!res.ok) return; // server returned but not OK — proceed anyway
+    // Wait for server to actually exit (poll with a HEAD request to /api/health
+    // or just sleep — sleep is simpler and uses no network).
+    for (let i = 0; i < 20; i++) {
+      await new Promise(r => setTimeout(r, 250));
+      try {
+        const ping = new AbortController();
+        const tt = setTimeout(() => ping.abort(), 500);
+        await fetch(`http://127.0.0.1:${port}/api/health`, { signal: ping.signal });
+        clearTimeout(tt);
+        // Still up — keep waiting.
+      } catch {
+        // Connection refused / aborted — server is gone.
+        break;
+      }
+    }
+    // Extra grace for child processes to release file handles on Windows.
+    await new Promise(r => setTimeout(r, 1500));
+  } catch {
+    // No server listening, fetch unavailable, etc. — just continue.
+  }
+}
+
+// ── Step 2: remove nested node_modules ──
 
 const dirs = [
   resolve(__dirname, 'neural-interface', 'node_modules'),
@@ -32,7 +84,7 @@ for (const dir of dirs) {
   }
 }
 
-// ── Remove protocol handler ──
+// ── Step 3: remove protocol handler ──
 
 const plat = platform();
 

package/updater.cmd

@@ -0,0 +1,31 @@
+@echo off
+setlocal enableextensions
+title SynaBun Updater
+
+rem ───────────────────────────────────────────────────────
+rem Windows shim for the cross-platform updater (updater.mjs).
+rem Invoked by the running SynaBun server via:
+rem   start "" "<install>\updater.cmd" --tag X --pid Y [--restart]
+rem
+rem We use a shim instead of spawning node directly so cmd's
+rem quoting rules don't mangle the command line, and so the
+rem window stays open for the user to read npm output even
+rem if node exits unexpectedly.
+rem ───────────────────────────────────────────────────────
+
+set "SCRIPT_DIR=%~dp0"
+set "EXIT_CODE=0"
+
+rem %~dp0 ends with backslash. updater.mjs lives next to this file.
+node "%SCRIPT_DIR%updater.mjs" %*
+set EXIT_CODE=%ERRORLEVEL%
+
+echo.
+if %EXIT_CODE%==0 (
+  echo [Update finished. Press any key to close this window.]
+) else (
+  echo [Update exited with code %EXIT_CODE%. Press any key to close this window.]
+)
+pause >nul
+
+endlocal ^& exit /b %EXIT_CODE%

package/updater.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+// ═══════════════════════════════════════════
+// SynaBun NPM Updater
+// ═══════════════════════════════════════════
+//
+// Runs in a detached terminal window spawned by the running SynaBun server
+// when the user clicks "Update Now" in the in-app update modal.
+//
+// Sequence:
+//   1. Wait for the SynaBun server PID to fully exit (so file handles inside
+//      neural-interface/ are released — required to avoid EBUSY on Windows
+//      during `npm install -g`).
+//   2. As a last-ditch belt-and-suspenders kill any lingering descendants of
+//      the server PID (taskkill /T /F on Windows, pkill -P on Unix).
+//   3. Run `npm install -g synabun@<tag>`. Output streams to the terminal
+//      so the user sees install progress and any failures.
+//   4. (Optional) Relaunch SynaBun via `synabun` if --restart was passed.
+//   5. Hold the terminal open until the user presses Enter.
+//
+// CLI args:
+//   --tag <latest|beta|next|rc|alpha>    npm dist-tag to install (default: latest)
+//   --pid <serverPid>                    Server PID to wait on (optional but recommended)
+//   --restart                            After install, exec `synabun` to relaunch
+
+import { spawn, spawnSync } from 'node:child_process';
+
+const args = parseArgs(process.argv.slice(2));
+const tag = sanitizeTag(args.tag || 'latest');
+const serverPid = args.pid ? Number(args.pid) : null;
+const autoRestart = !!args.restart;
+
+const isWin = process.platform === 'win32';
+const NPM_BIN = isWin ? 'npm.cmd' : 'npm';
+
+const HR = '═'.repeat(56);
+
+// Ignore Ctrl+C during the npm install phase so the user doesn't accidentally
+// abort halfway. On Windows this avoids an immediate window close on misclick.
+process.on('SIGINT', () => {});
+
+console.log(`\n${HR}`);
+console.log(`  SynaBun Updater — installing synabun@${tag}`);
+console.log(`${HR}\n`);
+
+// ── Step 1: wait for server to exit ───────────────────────────────
+if (serverPid && Number.isFinite(serverPid)) {
+  console.log(`→ Waiting for SynaBun server (PID ${serverPid}) to exit...`);
+  const deadline = Date.now() + 30000;
+  let exited = false;
+  while (Date.now() < deadline) {
+    if (!isPidAlive(serverPid)) { exited = true; break; }
+    await sleep(250);
+  }
+  if (exited) {
+    console.log('  ✓ Server exited.\n');
+  } else {
+    console.warn(`  ⚠ Server still alive after 30s — forcing kill.\n`);
+    forceKillTree(serverPid);
+    await sleep(1500);
+  }
+} else {
+  console.log('→ No server PID provided — assuming already stopped.\n');
+}
+
+// ── Step 2: extra grace window for AV / Windows file-locks ────────
+// Windows Defender + indexing services hold file handles briefly after
+// process exit. 1.5s is empirically enough on most Win10/11 boxes.
+await sleep(1500);
+
+// Belt-and-suspenders: tree-kill any leftover descendants by PID.
+if (isWin && serverPid) forceKillTree(serverPid);
+
+// ── Step 3: run npm install -g synabun@<tag> ──────────────────────
+console.log(`→ Running: ${NPM_BIN} install -g synabun@${tag}\n`);
+console.log(HR);
+const installRes = spawnSync(NPM_BIN, ['install', '-g', `synabun@${tag}`], {
+  stdio: 'inherit',
+  shell: isWin, // npm.cmd on Windows requires shell to resolve via PATHEXT
+});
+console.log(HR);
+
+if (installRes.status !== 0) {
+  console.error(`\n✗ npm install failed with exit code ${installRes.status}.\n`);
+  console.error(`Common fixes:`);
+  if (isWin) {
+    console.error(`  • EBUSY/EPERM:  close other SynaBun terminals/windows, then retry.`);
+    console.error(`  • Run as admin: right-click cmd → "Run as administrator", then retry.`);
+    console.error(`  • Force kill:   taskkill /F /IM node.exe   (warning: kills ALL node)`);
+  } else {
+    console.error(`  • EACCES: re-run with sudo, or fix global npm prefix permissions.`);
+    console.error(`  • Stale lock: rm -rf ~/.npm/_locks/*`);
+  }
+  console.error(`  • Cache:        npm cache clean --force`);
+  console.error(`\nManual retry:    npm install -g synabun@${tag}`);
+  await holdOpen();
+  process.exit(installRes.status || 1);
+}
+
+console.log(`\n✓ SynaBun updated to ${tag}!\n`);
+
+// ── Step 4: optional auto-restart ────────────────────────────────
+if (autoRestart) {
+  console.log(`→ Relaunching SynaBun...\n`);
+  // Detached so this updater terminal can close without killing the new
+  // server. stdio:'ignore' so synabun doesn't tie its lifetime to ours.
+  const child = spawn(isWin ? 'synabun.cmd' : 'synabun', [], {
+    detached: true,
+    stdio: 'ignore',
+    shell: isWin,
+  });
+  child.unref();
+  console.log(`  ✓ synabun launched (detached).\n`);
+} else {
+  console.log(`Run "synabun" to start the new version.\n`);
+}
+
+await holdOpen();
+process.exit(0);
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next == null || next.startsWith('--')) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i++;
+    }
+  }
+  return out;
+}
+
+function sanitizeTag(raw) {
+  const allowed = new Set(['latest', 'beta', 'next', 'rc', 'alpha']);
+  const t = String(raw).replace(/[^a-zA-Z0-9_.-]/g, '');
+  return allowed.has(t) ? t : 'latest';
+}
+
+function isPidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === 'EPERM'; } // EPERM = exists but we lack rights
+}
+
+function forceKillTree(pid) {
+  try {
+    if (isWin) {
+      spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], {
+        shell: true, windowsHide: true, stdio: 'ignore',
+      });
+    } else {
+      try { spawnSync('pkill', ['-P', String(pid)], { stdio: 'ignore' }); } catch {}
+      try { process.kill(pid, 'SIGKILL'); } catch {}
+    }
+  } catch {}
+}
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+function holdOpen() {
+  return new Promise(resolve => {
+    console.log(`\n[Press Enter to close this window]`);
+    try {
+      process.stdin.setEncoding('utf8');
+      process.stdin.resume();
+      process.stdin.once('data', () => resolve());
+    } catch {
+      // stdin not available — auto-close after 30s
+      setTimeout(resolve, 30000);
+    }
+  });
+}

package/updater.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# ───────────────────────────────────────────────────────
+# Unix shim for the cross-platform updater (updater.mjs).
+# Invoked by the running SynaBun server inside a fresh
+# terminal window — keeps the terminal open after node
+# exits so the user can read npm output and any errors.
+# ───────────────────────────────────────────────────────
+
+set +e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+NODE_BIN="${SYNABUN_NODE_BIN:-node}"
+
+# Pretty terminal title (no-op in some terminals).
+printf '\033]0;SynaBun Updater\007' 2>/dev/null || true
+
+"$NODE_BIN" "$SCRIPT_DIR/updater.mjs" "$@"
+EXIT_CODE=$?
+
+echo
+if [ "$EXIT_CODE" = "0" ]; then
+  echo "[Update finished. Press Enter to close this window.]"
+else
+  echo "[Update exited with code $EXIT_CODE. Press Enter to close this window.]"
+fi
+# Read one line. If stdin is closed (e.g. piped run), fall through immediately.
+read -r _ || true
+
+exit $EXIT_CODE