synabun 2026.4.26-beta.3 → 2026.4.26-beta.5

package/neural-interface/public/shared/styles.css

@@ -24369,3 +24369,19 @@
 .update-check-toast .utc-sub  { color: var(--t-muted); }
 .update-check-toast .utc-hint { color: var(--t-muted); opacity: 0.7; margin-top: 6px; font-size: 11px; }
 
+.update-channel-pill {
+  display: inline-block;
+  padding: 2px 8px;
+  margin-left: 8px;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  border-radius: 6px;
+  vertical-align: middle;
+  background: rgba(255, 159, 10, 0.18);
+  color: #ff9f0a;
+}
+.update-channel-pill--beta { background: rgba(255, 159, 10, 0.18); color: #ff9f0a; }
+
+

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

@@ -88,24 +88,36 @@ function openUpdateModal() {
 
   function renderStep1() {
     const src = _versionData.source;
+    const channel = _versionData.installedChannel || 'stable';
+    const channelTag = channel === 'prerelease'
+      ? '<span class="update-channel-pill update-channel-pill--beta">beta</span>'
+      : '';
+
     const srcCopy = src === 'both'
       ? 'A new version of SynaBun is available on npm and GitHub.'
       : src === 'github'
         ? 'A new SynaBun release is tagged on GitHub. The npm publish may still be in progress.'
         : 'A new version of SynaBun has been published to npm.';
 
-    const npmBit  = _versionData.npmLatest ? `npm v${esc(_versionData.npmLatest)}` : 'npm —';
-    const gitBit  = _versionData.gitLatest ? `GitHub v${esc(_versionData.gitLatest)}` : 'GitHub —';
+    const npmStable = _versionData.npmLatestStable
+      ? `npm latest v${esc(_versionData.npmLatestStable)}`
+      : 'npm latest —';
+    const npmBeta = _versionData.npmLatestBeta
+      ? ` · npm beta v${esc(_versionData.npmLatestBeta)}`
+      : '';
+    const gitBit = _versionData.gitLatest
+      ? ` · GitHub v${esc(_versionData.gitLatest)}`
+      : ' · GitHub —';
 
     return `
-      <h3 class="update-modal-title">Update Available</h3>
+      <h3 class="update-modal-title">Update Available ${channelTag}</h3>
       <div class="update-version-diff">
         <span class="update-ver update-ver--old">v${esc(_versionData.current)}</span>
         <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14"/><path d="m12 5 7 7-7 7"/></svg>
         <span class="update-ver update-ver--new">v${esc(_versionData.latest)}</span>
       </div>
       <p style="font-size:12px;color:var(--t-muted);margin:12px 0 6px">${srcCopy}</p>
-      <p style="font-size:11px;color:var(--t-muted);opacity:.75;margin:0 0 18px">${npmBit} · ${gitBit}</p>
+      <p style="font-size:11px;color:var(--t-muted);opacity:.75;margin:0 0 18px">${npmStable}${npmBeta}${gitBit}</p>
       <div class="tag-delete-modal-actions">
         <button class="action-btn action-btn--ghost" id="update-cancel">Cancel</button>
         <button class="action-btn action-btn--primary" id="update-next">Next</button>
@@ -137,30 +149,48 @@ function openUpdateModal() {
   }
 
   function renderStep3() {
+    // Channel-aware install command. Beta users staying on beta keep the
+    // @beta tag; both targets exist on stable so we surface a single line.
+    const channel = _versionData.installedChannel || 'stable';
+    const target = _versionData.latest || '';
+    const targetLooksBeta = parseSemverPre(target);
+    const installTag = (channel === 'prerelease' && targetLooksBeta) ? 'beta' : 'latest';
+    const installCmd = `npm install -g synabun@${installTag}`;
+
     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>npm install -g synabun@latest</code>
-        <button class="update-copy-btn" data-copy="npm install -g synabun@latest" title="Copy">
+        <code>${esc(installCmd)}</code>
+        <button class="update-copy-btn" data-copy="${esc(installCmd)}" 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>
       </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() {
@@ -201,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) {
@@ -212,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');
@@ -279,3 +380,12 @@ function esc(str) {
   d.textContent = str || '';
   return d.innerHTML;
 }
+
+// Returns the prerelease tag from a semver-ish string ("2026.4.26-beta.3"
+// -> "beta.3"), or null. Used to pick install command target.
+function parseSemverPre(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim().replace(/^v\.?/, '');
+  const m = s.match(/^\d+\.\d+\.\d+(?:-([0-9A-Za-z.-]+))?/);
+  return m && m[1] ? m[1] : null;
+}

package/neural-interface/server.js

@@ -1546,14 +1546,186 @@ 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 updater.mjs in a NEW visible terminal window (cmd on Windows,
+// Terminal.app on macOS, x-terminal-emulator/gnome-terminal/konsole/xterm
+// fallback on Linux). The updater:
+//   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 handles waiting on us — it only starts npm
+// after our PID is 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 updaterPath = resolve(PACKAGE_ROOT, 'updater.mjs');
+    if (!existsSync(updaterPath)) {
+      return res.status(500).json({ error: `updater.mjs not found at ${updaterPath}. SynaBun install may be corrupt.` });
+    }
+
+    const serverPid = process.pid;
+    const argsBase = ['--tag', tag, '--pid', String(serverPid)];
+    if (autoRestart) argsBase.push('--restart');
+
+    const plat = process.platform;
+    let spawned = null;
+
+    if (plat === 'win32') {
+      // `cmd /c start "<title>" cmd /k "node <updater> ..."` opens a new
+      // visible cmd window that stays open after the script finishes (/k).
+      const nodeExe = process.execPath;
+      const cmdLine = `"${nodeExe}" "${updaterPath}" ${argsBase.map(a => `"${a}"`).join(' ')}`;
+      spawned = spawn('cmd', ['/c', 'start', '"SynaBun Update"', 'cmd', '/k', cmdLine], {
+        detached: true, stdio: 'ignore', windowsHide: false, shell: false,
+      });
+    } else if (plat === 'darwin') {
+      // Use osascript to drive Terminal.app — opens a visible window the
+      // user can watch. Escape internal quotes for AppleScript string.
+      const nodeExe = process.execPath;
+      const cmd = `${JSON.stringify(nodeExe)} ${JSON.stringify(updaterPath)} ${argsBase.map(a => JSON.stringify(a)).join(' ')}`;
+      const escaped = cmd.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+      spawned = spawn('osascript', [
+        '-e', `tell application "Terminal" to activate`,
+        '-e', `tell application "Terminal" to do script "${escaped}"`,
+      ], { detached: true, stdio: 'ignore' });
+    } else {
+      // Linux — try common terminal emulators in order, fall back to xterm.
+      const nodeExe = process.execPath;
+      const inner = `${nodeExe} ${updaterPath} ${argsBase.join(' ')}; echo; echo '[Press Enter to close]'; read`;
+      const candidates = [
+        ['x-terminal-emulator', ['-e', `bash -c "${inner.replace(/"/g, '\\"')}"`]],
+        ['gnome-terminal', ['--', 'bash', '-c', inner]],
+        ['konsole', ['-e', 'bash', '-c', inner]],
+        ['xfce4-terminal', ['-e', `bash -c "${inner.replace(/"/g, '\\"')}"`]],
+        ['xterm', ['-e', 'bash', '-c', inner]],
+      ];
+      for (const [bin, args] of candidates) {
+        try {
+          spawned = spawn(bin, args, { detached: true, stdio: 'ignore' });
+          break;
+        } catch {}
+      }
+      if (!spawned) {
+        return res.status(500).json({ error: 'No supported terminal emulator found. Install xterm or run `npm install -g synabun@' + tag + '` manually.' });
+      }
+    }
+
+    spawned.unref();
+    console.log(`[server] Updater terminal launched (tag=${tag}, autoRestart=${autoRestart}). Shutting down...`);
+    res.json({ ok: true, tag, autoRestart, updaterPath });
+
+    // 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 actually init node). 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);
+    res.status(500).json({ error: err.message });
+  }
 });
 
 // POST /api/settings/move-db — Move SQLite database to a new directory
@@ -10082,8 +10254,11 @@ app.post('/api/search/memories', async (req, res) => {
 
 let _synabunUpdateCache = {
   current: null,
-  npmLatest: null,
-  gitLatest: null,
+  installedChannel: 'stable',    // 'stable' | 'prerelease'
+  npmLatestStable: null,         // dist-tags.latest
+  npmLatestBeta: null,           // dist-tags.beta (or null if absent)
+  npmLatest: null,               // chosen target for installed channel
+  gitLatest: null,               // tag_name from GitHub release matching channel
   latest: null,                  // newer of (npmLatest, gitLatest) — legacy field
   npmUpdateAvailable: false,
   gitUpdateAvailable: false,
@@ -10101,6 +10276,9 @@ async function checkSynabunUpdate() {
     current = pkg.version;
   } catch { /* keep prior current if package.json read fails */ }
 
+  const curParsed = parseSemver(current);
+  const installedChannel = curParsed?.pre ? 'prerelease' : 'stable';
+
   const fetchJsonWithTimeout = async (url, ms = 5000) => {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), ms);
@@ -10116,40 +10294,83 @@ async function checkSynabunUpdate() {
     }
   };
 
-  // Run both fetches in parallel — one failing must not block the other.
+  // npm: fetch the FULL registry document so we can read every dist-tag
+  // (latest + beta + any future channel). The /latest shorthand only
+  // surfaces dist-tags.latest, which made beta installs invisible.
+  // github: when installed is a prerelease, /releases/latest is wrong
+  // because it skips prereleases — fetch the full list and pick newest.
+  const npmUrl = 'https://registry.npmjs.org/synabun';
+  const githubUrl = installedChannel === 'prerelease'
+    ? 'https://api.github.com/repos/danilokhury/Synabun/releases?per_page=20'
+    : 'https://api.github.com/repos/danilokhury/Synabun/releases/latest';
+
   const [npmRes, gitRes] = await Promise.allSettled([
-    fetchJsonWithTimeout('https://registry.npmjs.org/synabun/latest'),
-    fetchJsonWithTimeout('https://api.github.com/repos/danilokhury/Synabun/releases/latest'),
+    fetchJsonWithTimeout(npmUrl),
+    fetchJsonWithTimeout(githubUrl),
   ]);
 
-  let npmLatest = null, gitLatest = null;
+  let npmLatestStable = null, npmLatestBeta = null;
+  let gitLatest = null;
   let npmError = null, gitError = null;
 
   if (npmRes.status === 'fulfilled') {
-    npmLatest = npmRes.value?.version || null;
+    const tags = npmRes.value?.['dist-tags'] || {};
+    npmLatestStable = tags.latest || null;
+    npmLatestBeta = tags.beta || tags.next || tags.rc || null;
   } else {
     npmError = npmRes.reason?.message || 'npm fetch failed';
   }
 
   if (gitRes.status === 'fulfilled') {
-    const tag = gitRes.value?.tag_name || gitRes.value?.name || '';
-    gitLatest = parseVersion(tag) || (tag ? tag.replace(/^v/i, '') : null);
+    if (Array.isArray(gitRes.value)) {
+      // /releases — pick newest non-draft entry whose tag parses as semver.
+      // For stable channel users we'd skip prereleases, but this branch only
+      // runs for prerelease users (per githubUrl above), so include both.
+      let best = null;
+      for (const r of gitRes.value) {
+        if (r?.draft) continue;
+        const tag = r?.tag_name || r?.name || '';
+        const parsed = parseSemver(tag);
+        if (!parsed) continue;
+        if (!best || compareSemver(parsed, best.parsed) > 0) {
+          best = { tag, parsed };
+        }
+      }
+      gitLatest = best?.tag.replace(/^v\.?/, '') || null;
+    } else {
+      // /releases/latest — single object
+      const tag = gitRes.value?.tag_name || gitRes.value?.name || '';
+      gitLatest = tag ? tag.replace(/^v\.?/, '') : null;
+    }
   } else {
     gitError = gitRes.reason?.message || 'github fetch failed';
   }
 
-  const cleanCur = parseVersion(current) || current;
-  const cleanNpm = npmLatest ? (parseVersion(npmLatest) || npmLatest) : null;
-  const cleanGit = gitLatest ? (parseVersion(gitLatest) || gitLatest) : null;
+  // Channel-aware npm target:
+  //  - prerelease user: pick whichever of (stable, beta) is newest. Either
+  //    is genuinely "newer than current"; surfacing stable when on beta is
+  //    intentional (some users manually flip back to stable).
+  //  - stable user: only stable. Beta on a stable install would look like
+  //    a downgrade ("2026.4.26 → 2026.4.26-beta.3" via semver = older).
+  let npmLatest = null;
+  if (installedChannel === 'prerelease') {
+    if (npmLatestStable && npmLatestBeta) {
+      npmLatest = compareSemver(npmLatestBeta, npmLatestStable) > 0 ? npmLatestBeta : npmLatestStable;
+    } else {
+      npmLatest = npmLatestStable || npmLatestBeta;
+    }
+  } else {
+    npmLatest = npmLatestStable;
+  }
 
-  const npmUpdateAvailable = !!(cleanNpm && semverNewer(cleanCur, cleanNpm));
-  const gitUpdateAvailable = !!(cleanGit && semverNewer(cleanCur, cleanGit));
+  const npmUpdateAvailable = !!(npmLatest && semverNewer(current, npmLatest));
+  const gitUpdateAvailable = !!(gitLatest && semverNewer(current, gitLatest));
   const updateAvailable = npmUpdateAvailable || gitUpdateAvailable;
 
-  // Pick the newer of the two as the canonical "latest" for legacy UI.
+  // Newer of the two (npm vs github) for legacy "latest" display.
   let latest = null;
-  if (cleanNpm && cleanGit) {
-    latest = semverNewer(cleanNpm, cleanGit) ? gitLatest : npmLatest;
+  if (npmLatest && gitLatest) {
+    latest = compareSemver(npmLatest, gitLatest) >= 0 ? npmLatest : gitLatest;
   } else {
     latest = npmLatest || gitLatest;
   }
@@ -10160,14 +10381,24 @@ async function checkSynabunUpdate() {
   else if (gitUpdateAvailable)                   source = 'github';
 
   _synabunUpdateCache = {
-    current, npmLatest, gitLatest, latest,
-    npmUpdateAvailable, gitUpdateAvailable, updateAvailable, source,
+    current,
+    installedChannel,
+    npmLatestStable,
+    npmLatestBeta,
+    npmLatest,
+    gitLatest,
+    latest,
+    npmUpdateAvailable,
+    gitUpdateAvailable,
+    updateAvailable,
+    source,
     checkedAt: new Date().toISOString(),
-    npmError, gitError,
+    npmError,
+    gitError,
   };
 
   if (updateAvailable) {
-    console.log(`  Updates:   v${current} → v${latest} (${source})`);
+    console.log(`  Updates:   v${current} → v${latest} (${source}; channel: ${installedChannel})`);
   } else if (npmError && gitError) {
     console.log(`  Updates:   check failed (npm: ${npmError}; github: ${gitError})`);
   } else if (npmError) {
@@ -10175,7 +10406,7 @@ async function checkSynabunUpdate() {
   } else if (gitError) {
     console.log(`  Updates:   up to date (v${current}; github check failed: ${gitError})`);
   } else {
-    console.log(`  Updates:   up to date (v${current})`);
+    console.log(`  Updates:   up to date (v${current}; channel: ${installedChannel})`);
   }
 }
 
@@ -10205,17 +10436,80 @@ const TOOL_DEFS = [
 
 let _toolVersionCache = { checkedAt: null, tools: {} };
 
+// Backwards-compat helper — returns a "MAJOR.MINOR.PATCH" string (no pre).
+// Kept because legacy callers expect a string for display purposes only.
+// Comparison logic must use parseSemver/compareSemver below to handle
+// prerelease/iteration suffixes correctly.
 function parseVersion(raw) {
-  const m = raw.match(/(\d+\.\d+\.\d+)/);
-  return m ? m[1] : null;
+  const m = String(raw ?? '').match(/(\d+)\.(\d+)\.(\d+)/);
+  return m ? `${m[1]}.${m[2]}.${m[3]}` : null;
+}
+
+// Structured semver parse — handles calver bumps and prerelease tags:
+//   "2026.4.26"          -> { major:2026, minor:4, patch:26, pre:null }
+//   "2026.4.20-2"        -> { major:2026, minor:4, patch:20, pre:"2" }
+//   "2026.4.26-beta.3"   -> { major:2026, minor:4, patch:26, pre:"beta.3" }
+//   "v1.2.3-rc.1"        -> { major:1, minor:2, patch:3, pre:"rc.1" }
+function parseSemver(raw) {
+  if (raw == null) return null;
+  const s = String(raw).trim().replace(/^v\.?/, '');
+  const m = s.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+  if (!m) return null;
+  return {
+    major: +m[1],
+    minor: +m[2],
+    patch: +m[3],
+    pre: m[4] || null,
+  };
+}
+
+// Semver-spec precedence including prerelease handling:
+//   1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0
+// Returns negative if a<b, positive if a>b, 0 if equal. Accepts strings or
+// parsed objects.
+function compareSemver(a, b) {
+  const pa = (a && typeof a === 'object' && 'major' in a) ? a : parseSemver(a);
+  const pb = (b && typeof b === 'object' && 'major' in b) ? b : parseSemver(b);
+  if (!pa && !pb) return 0;
+  if (!pa) return -1;
+  if (!pb) return 1;
+  if (pa.major !== pb.major) return pa.major - pb.major;
+  if (pa.minor !== pb.minor) return pa.minor - pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch - pb.patch;
+  // Equal x.y.z. Prerelease vs none: a release without prerelease is GREATER.
+  if (!pa.pre && !pb.pre) return 0;
+  if (!pa.pre &&  pb.pre) return  1;
+  if ( pa.pre && !pb.pre) return -1;
+  // Both have prerelease — compare identifiers per semver §11.4.
+  const ia = pa.pre.split('.');
+  const ib = pb.pre.split('.');
+  const len = Math.max(ia.length, ib.length);
+  for (let i = 0; i < len; i++) {
+    if (i >= ia.length) return -1; // shorter set has lower precedence
+    if (i >= ib.length) return  1;
+    const xa = ia[i], xb = ib[i];
+    const na = /^\d+$/.test(xa), nb = /^\d+$/.test(xb);
+    if (na && nb) {
+      const da = +xa, db = +xb;
+      if (da !== db) return da - db;
+    } else if (na && !nb) {
+      return -1; // numeric < alphanumeric
+    } else if (!na && nb) {
+      return  1;
+    } else {
+      if (xa !== xb) return xa < xb ? -1 : 1;
+    }
+  }
+  return 0;
 }
 
 function semverNewer(a, b) {
-  if (!a || !b) return false;
-  const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
-  return pb[0] > pa[0]
-    || (pb[0] === pa[0] && pb[1] > pa[1])
-    || (pb[0] === pa[0] && pb[1] === pa[1] && pb[2] > pa[2]);
+  // True iff b is strictly newer than a. Falls back to false if either side
+  // can't be parsed — same defensive contract as the prior implementation.
+  if (a == null || b == null) return false;
+  const pa = parseSemver(a), pb = parseSemver(b);
+  if (!pa || !pb) return false;
+  return compareSemver(pa, pb) < 0;
 }
 
 function resolveBinPath(cmd, env) {

package/package.json

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

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.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);
+    }
+  });
+}