synabun 2.0.9 → 2.1.0

package/lib/claude-hooks.js

@@ -1,6 +1,8 @@
-import { resolve } from 'node:path';
+import { accessSync, constants, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { isAbsolute, join, resolve, sep } from 'node:path';
 import { PACKAGE_ROOT } from './paths.js';
-import { durableEntry, packagedRuntime } from './packaged-runtime.js';
+import { durableEntry, isReadOnlyVolumePath, isTransientPath, packagedRuntime } from './packaged-runtime.js';
 
 // Handler identity must be byte-for-byte identical across settings scopes.
 // Claude Code deduplicates matching settings handlers before executing them.
@@ -27,10 +29,10 @@ export function hookDefinitionsForEvent(event) {
   return HOOK_SCRIPTS.filter(def => events.includes(def.event));
 }
 
-// No shell-specific environment expansion, install paths, or downloads. Walk
-// up from the project/cwd for checkout-only installs, then use the installed
-// root. Single quotes inside JS work inside the command's double quotes on
-// both cmd.exe and POSIX shells. Keep this versioned literal stable.
+// No install paths or downloads. Walk up from the project/cwd for checkout-only
+// installs, then use the installed root. Single quotes inside JS work inside
+// the command's double quotes on both cmd.exe and POSIX shells. Keep this
+// versioned literal stable.
 const BOOTSTRAP = "const f=require('node:fs'),p=require('node:path'),u=require('node:url'),s=process.argv[1];let r;const ok=d=>{try{return JSON.parse(f.readFileSync(p.join(d,'package.json'),'utf8')).name==='synabun'&&f.existsSync(p.join(d,'hooks','claude-code',s))}catch{return false}};for(let d=p.resolve(process.env.CLAUDE_PROJECT_DIR||process.cwd());;d=p.dirname(d)){if(ok(d)){r=d;break}if(d===p.dirname(d))break}if(!r&&process.env.SYNABUN_HOOK_ROOT&&ok(process.env.SYNABUN_HOOK_ROOT))r=process.env.SYNABUN_HOOK_ROOT;if(!r)throw Error('SynaBun hook root unavailable; repair the hook installation');import(u.pathToFileURL(p.join(r,'hooks','claude-code',s)).href)";
 
 /**
@@ -49,23 +51,48 @@ function quoteHookEntry(entry) {
   return `"${entry.replace(/[\\"$`]/g, '\\$&')}"`;
 }
 
+// Windows: cmd.exe, PowerShell and Git Bash all run this, and a Windows program
+// gets the user's PATH from the registry whoever starts it.
 const nodeHookCommand = scriptName => `node -e "${BOOTSTRAP}" ${scriptName}`;
 
+/**
+ * Where a hook started without the login PATH looks for Node after `node` on
+ * PATH: the official installer's and Homebrew's folders and Volta's shim (the
+ * Node a terminal finds, as a rule), then SYNABUN_NODE. The same names on every
+ * machine.
+ */
+export const HOOK_NODE_FOLDERS = Object.freeze(['/usr/local/bin/node', '/opt/homebrew/bin/node', '$HOME/.volta/bin/node']);
+
+// macOS and Linux: Claude Code runs a settings hook with /bin/sh in its own
+// environment. Started from a terminal that has the login PATH; started from
+// the Dock, Finder, a desktop app or launchd it is /usr/bin:/bin:/usr/sbin:/sbin,
+// where `node` is not found and every hook exits 127. So: `node` on PATH, as a
+// terminal finds it, then the usual folders, then the Node the installer named
+// in the user's settings (SYNABUN_NODE: nvm and the like have no usual folder).
+// Nothing in it names this machine, so the tracked template and the projects'
+// settings carry it as they are.
+const POSIX_NODE_FINDER = `n=$(command -v node) || for n in ${HOOK_NODE_FOLDERS.map(p => (p.startsWith('$') ? `"${p}"` : p)).join(' ')} "$SYNABUN_NODE"; do [ -f "$n" ] && [ -x "$n" ] && break; n=node; done; `;
+const posixHookCommand = scriptName => `${POSIX_NODE_FINDER}exec "$n" -e "${BOOTSTRAP}" ${scriptName}`;
+
 // Whatever entry wrote it: an application that moved must still find, and
 // repair, its own handlers.
 const PACKAGED_HOOK_COMMAND = new RegExp(`^"(?:[^"\\\\]|\\\\.)+"\\s+${PACKAGED_HOOK_MODE}\\s+(\\S+)$`);
 
-export function hookCommandString(scriptName, _targetProjectPath, runtime = packagedRuntime()) {
+export function hookCommandString(scriptName, _targetProjectPath, runtime = packagedRuntime(), platform = process.platform) {
   if (!HOOK_SCRIPTS.some(h => h.script === scriptName)) throw new Error('Unknown SynaBun hook');
   const entry = durableEntry(runtime);
-  return entry ? `${quoteHookEntry(entry)} ${PACKAGED_HOOK_MODE} ${scriptName}` : nodeHookCommand(scriptName);
+  if (entry) return `${quoteHookEntry(entry)} ${PACKAGED_HOOK_MODE} ${scriptName}`;
+  return platform === 'win32' ? nodeHookCommand(scriptName) : posixHookCommand(scriptName);
 }
 
 export function isSynaBunHookCommand(command, scriptName) {
   if (typeof command !== 'string') return false;
-  // Both canonical forms, whichever kind of install is reading: moving between
-  // an npm install and the application must not leave two handlers behind.
-  if (command === nodeHookCommand(scriptName)) return true;
+  // Every canonical form, whichever kind of install and system is reading:
+  // moving between an npm install and the application, or a settings file
+  // shared between Windows and macOS, must not leave two handlers behind.
+  if (command === nodeHookCommand(scriptName) || command === posixHookCommand(scriptName)) return true;
+  // Any version of the POSIX finder in front of the same bootstrap.
+  if (command.startsWith('n=$(command -v node)') && command.endsWith(` -e "${BOOTSTRAP}" ${scriptName}`)) return true;
   const packaged = command.trim().match(PACKAGED_HOOK_COMMAND);
   if (packaged) return packaged[1] === scriptName;
   // Recognize only the old direct-node path forms, including cross-OS installs.
@@ -98,25 +125,47 @@ export function hookInstallPlan({ target, registered = false, hook } = {}, runti
   return target === 'project' && !registered && !hook ? 'register-only' : 'refuse';
 }
 
-export function ensureHookRoot(settings, targetProjectPath, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime()) {
+/**
+ * The Node a hook falls back to when Claude Code was started without the login
+ * PATH (SYNABUN_NODE): the one running SynaBun, which is known to run its hooks,
+ * when its path outlives this run. null on Windows (its programs get the user's
+ * PATH) and for a Node in a temporary place.
+ */
+export function hookNodePin({ execPath = process.execPath, platform = process.platform, env = process.env, writable } = {}) {
+  if (platform === 'win32' || typeof execPath !== 'string' || !isAbsolute(execPath)) return null;
+  if (isTransientPath(execPath, env) || isReadOnlyVolumePath(execPath, { platform, writable })) return null;
+  const temporary = [tmpdir(), '/tmp', '/private/tmp', '/private/var/folders', '/var/folders'];
+  if (temporary.some(dir => resolve(execPath).startsWith(`${resolve(dir)}${sep}`))) return null;
+  return execPath;
+}
+
+export function ensureHookRoot(settings, targetProjectPath, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime(), { node = hookNodePin() } = {}) {
   // A packaged application's command finds its own handlers, and its package
   // root can be a mount that ends with the run.
   if (runtime) return false;
   // The checked-in template must not acquire a machine-specific env path.
   if (targetProjectPath && resolve(targetProjectPath) === resolve(packageRoot)) return false;
-  if (settings.env?.SYNABUN_HOOK_ROOT === resolve(packageRoot)) return false;
-  settings.env = { ...settings.env, SYNABUN_HOOK_ROOT: resolve(packageRoot) };
-  return true;
+  let changed = false;
+  if (settings.env?.SYNABUN_HOOK_ROOT !== resolve(packageRoot)) {
+    settings.env = { ...settings.env, SYNABUN_HOOK_ROOT: resolve(packageRoot) };
+    changed = true;
+  }
+  // The user's own settings only (this machine's file): every session gets its env.
+  if (!targetProjectPath && node && settings.env?.SYNABUN_NODE !== node) {
+    settings.env = { ...settings.env, SYNABUN_NODE: node };
+    changed = true;
+  }
+  return changed;
 }
 
-export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime()) {
+export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime(), { platform = process.platform, node = hookNodePin({ platform }) } = {}) {
   if (!settings?.hooks || hookInstallBlocker(runtime)) return false;
   let changed = false;
   let ownsHooks = false;
   for (const def of HOOK_SCRIPTS) {
     const entries = settings.hooks[def.event];
     if (!Array.isArray(entries)) continue;
-    const command = hookCommandString(def.script, targetProjectPath, runtime);
+    const command = hookCommandString(def.script, targetProjectPath, runtime, platform);
     const matches = entries.flatMap(e => (e.hooks || []).filter(h => isSynaBunHookCommand(h.command, def.script)).map(h => ({ entry: e, hook: h })));
     if (!matches.length) continue;
     ownsHooks = true;
@@ -133,6 +182,111 @@ export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, pack
     settings.hooks[def.event] = [...rest, { matcher: def.matcher || '', hooks: [{ type: 'command', command, timeout: def.timeout }] }];
     changed = true;
   }
-  if (ownsHooks && ensureHookRoot(settings, targetProjectPath, packageRoot, runtime)) changed = true;
+  if (ownsHooks && ensureHookRoot(settings, targetProjectPath, packageRoot, runtime, { node })) changed = true;
   return changed;
 }
+
+// ── What is really installed (Settings → Automations → Claude Code hooks) ────
+
+/**
+ * What one settings file holds of SynaBun's handlers. `handlers`: one per
+ * HOOK_SCRIPTS entry, with `copies` (SynaBun handlers for that script in any
+ * form) and `current` (one of them is this machine's command, matcher and
+ * timeout); `events`: every handler of the event present; `installed` /
+ * `current` / `total` count handlers, `duplicates` the extra copies (each runs).
+ */
+export function hookInstallState(settings, { targetProjectPath, runtime = packagedRuntime(), platform = process.platform } = {}) {
+  const handlers = HOOK_SCRIPTS.map((def) => {
+    const entries = Array.isArray(settings?.hooks?.[def.event]) ? settings.hooks[def.event] : [];
+    const owned = entries.flatMap(entry => (Array.isArray(entry?.hooks) ? entry.hooks : [])
+      .filter(hook => isSynaBunHookCommand(hook?.command, def.script)).map(hook => ({ entry, hook })));
+    const command = hookCommandString(def.script, targetProjectPath, runtime, platform);
+    const current = owned.some(({ entry, hook }) => hook.command === command && (entry.matcher || '') === (def.matcher || '') && hook.timeout === def.timeout);
+    return { event: def.event, script: def.script, copies: owned.length, current };
+  });
+  const events = {};
+  for (const h of handlers) events[h.event] = (events[h.event] ?? true) && h.copies > 0;
+  return {
+    handlers,
+    events,
+    installed: handlers.filter(h => h.copies > 0).length,
+    current: handlers.filter(h => h.current).length,
+    duplicates: handlers.reduce((sum, h) => sum + Math.max(0, h.copies - 1), 0),
+    total: handlers.length,
+  };
+}
+
+/** The commands of SynaBun's handlers in a settings file, script by script (to compare two scopes). */
+export function hookCommandsOf(settings) {
+  const out = {};
+  for (const def of HOOK_SCRIPTS) {
+    const entries = Array.isArray(settings?.hooks?.[def.event]) ? settings.hooks[def.event] : [];
+    const commands = entries.flatMap(entry => (Array.isArray(entry?.hooks) ? entry.hooks : []))
+      .map(hook => hook?.command).filter(command => isSynaBunHookCommand(command, def.script));
+    out[`${def.event}:${def.script}`] = [...new Set(commands)].sort();
+  }
+  return out;
+}
+
+/**
+ * Whether a project's SynaBun handlers run once next to the user's: Claude Code
+ * runs one copy of identical handlers from both files, and both of different
+ * ones. 'same' (nothing of SynaBun's there, or the same commands), 'different'.
+ */
+export function projectHooksAgree(userSettings, projectSettings) {
+  const user = hookCommandsOf(userSettings);
+  const project = hookCommandsOf(projectSettings);
+  for (const [key, commands] of Object.entries(project)) {
+    if (!commands.length) continue;
+    const mine = user[key] || [];
+    if (!mine.length) continue; // only the project runs it: once
+    if (commands.some(command => !mine.includes(command))) return 'different';
+  }
+  return 'same';
+}
+
+/** Claude Code's own switches that stop SynaBun's handlers, in one settings file: the first that applies, or null. */
+export function hooksSwitchedOff(settings, { managed = false } = {}) {
+  if (!settings || typeof settings !== 'object') return null;
+  if (settings.disableAllHooks === true) return 'disableAllHooks';
+  // Only managed settings can keep user and project hooks from running.
+  if (managed && settings.allowManagedHooksOnly === true) return 'allowManagedHooksOnly';
+  return null;
+}
+
+/** Where Claude Code reads managed (organization) settings on this system. */
+export function managedClaudeSettingsPath(platform = process.platform) {
+  if (platform === 'darwin') return '/Library/Application Support/ClaudeCode/managed-settings.json';
+  if (platform === 'win32') return 'C:\\Program Files\\ClaudeCode\\managed-settings.json';
+  return '/etc/claude-code/managed-settings.json';
+}
+
+/** The PATH macOS gives a program it starts from the Dock, Finder or launchd. */
+export const LAUNCHD_PATH = Object.freeze(['/usr/bin', '/bin', '/usr/sbin', '/sbin']);
+
+function runnableFile(path) {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * The Node a SynaBun hook would run with in a Claude Code started without the
+ * login PATH (the Dock, Finder, a desktop app, launchd): what the POSIX command
+ * tries after PATH, in its order. { path, via: 'SYNABUN_NODE' | 'folder' } or
+ * null (such a session would fail every hook). Windows: not asked (null).
+ */
+export function hookNodeWithoutPath({ env = {}, home = homedir(), platform = process.platform, runnable = runnableFile } = {}) {
+  if (platform === 'win32') return null;
+  // `command -v node` on the PATH such a launch has (a Linux distribution's own Node).
+  for (const dir of LAUNCHD_PATH) if (runnable(`${dir}/node`)) return { path: `${dir}/node`, via: 'PATH' };
+  for (const folder of HOOK_NODE_FOLDERS) {
+    const path = folder.startsWith('$HOME/') ? join(home, folder.slice('$HOME/'.length)) : folder;
+    if (runnable(path)) return { path, via: 'folder' };
+  }
+  const pinned = typeof env.SYNABUN_NODE === 'string' ? env.SYNABUN_NODE : '';
+  if (pinned && runnable(pinned)) return { path: pinned, via: 'SYNABUN_NODE' };
+  return null;
+}

package/lib/client-config-repair.js

@@ -16,11 +16,18 @@ import { dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import {
   mergeGeminiMcpConfig,
-  mergeOpenCodeMcpConfig,
 } from '../neural-interface/lib/mcp-client-config.js';
+import {
+  mcpServersOf,
+  opencodeConfigDir,
+  opencodeConfigFilePath,
+  opencodeMcpServerEntry,
+  setMcpServer,
+} from '../neural-interface/lib/opencode-config.js';
 import {
   inspectCodexConfig,
   upsertCodexMcpConfig,
+  upsertCodexMcpContent,
 } from '../mcp-server/dist/services/codex-config-heal.js';
 import { mcpStdioCommand } from './packaged-runtime.js';
 
@@ -60,11 +67,12 @@ export function auditAndRepairClientConfigs({
 } = {}) {
   if (!dataHome || !packageRoot) throw new Error('dataHome and packageRoot are required');
   const definition = buildCanonicalMcpDefinition({ dataHome, packageRoot });
+  // Codex loads every SynaBun tool (its deferred catalog); a Codex runtime's own list is only its focus.
   const codexDefinition = {
     ...definition,
     env: {
       ...definition.env,
-      SYNABUN_PROFILE: 'full',
+      SYNABUN_TOOLS: 'all',
       SYNABUN_TOOL_CATALOG_MODE: 'deferred',
     },
   };
@@ -105,11 +113,12 @@ export function auditAndRepairClientConfigs({
     results.gemini = { exists: existsSync(geminiPath), connected: false, changed: false, path: geminiPath };
   }
 
-  const xdgConfigHome = process.env.XDG_CONFIG_HOME || join(home, '.config');
-  const openCodePath = join(xdgConfigHome, 'opencode', 'config.json');
+  // OpenCode 2's global opencode.json (it never reads the config.json of OpenCode 1), its mcp.servers.SynaBun:
+  // the folder the rest of SynaBun writes (OPENCODE_CONFIG_DIR, else XDG_CONFIG_HOME's, else ~/.config/opencode).
+  const openCodePath = opencodeConfigFilePath(opencodeConfigDir({ home }));
   const openCode = readJson(openCodePath);
-  if (openCode?.mcp?.SynaBun) {
-    const next = mergeOpenCodeMcpConfig(openCode, 'SynaBun', definition);
+  if (mcpServersOf(openCode).SynaBun) {
+    const next = setMcpServer(structuredClone(openCode), 'SynaBun', opencodeMcpServerEntry(definition));
     const changed = jsonChanged(openCode, next);
     if (apply && changed) writeJsonAtomic(openCodePath, next);
     results.opencode = { exists: true, connected: true, changed, path: openCodePath };
@@ -126,9 +135,9 @@ export function auditAndRepairClientConfigs({
       upsertCodexMcpConfig(codexPath, codexDefinition);
       changed = before !== readFileSync(codexPath, 'utf-8');
     } else {
+      // What the repair would write, compared with what is there: a value like "all" is in most files anyway.
       const content = readFileSync(codexPath, 'utf-8');
-      changed = ![codexDefinition.command, ...codexDefinition.args].every(value => content.includes(value))
-        || !Object.values(codexDefinition.env).every(value => content.includes(value));
+      changed = upsertCodexMcpContent(content, codexDefinition) !== content;
     }
     results.codex = { exists: true, connected: true, changed, path: codexPath, health: codexHealth };
   } else {

package/lib/desktop-app.js

@@ -193,9 +193,15 @@ export async function runAppBackend({
   // 3. Start, through the launcher (lock, supervisor record, background start).
   let launcherPid = null;
   let lastPhase = null;
+  let lastStep = null;
+  // A phase is said when it begins; the snapshot also says how far it is (its step, the bytes done), for the
+  // window's progress bar.
   const reportPhase = (current) => {
-    if (!current?.phase || current.phase === lastPhase) return;
+    if (!current?.phase) return;
+    const step = current.phase === 'snapshot' ? `${current.detail?.step ?? ''}:${current.detail?.done ?? ''}:${current.detail?.state ?? ''}` : null;
+    if (current.phase === lastPhase && step === lastStep) return;
     lastPhase = current.phase;
+    lastStep = step;
     emit({ type: 'supervisor', phase: current.phase, detail: current.detail || null });
   };
   const reporter = () => ({

package/lib/external-tools.js

@@ -66,7 +66,7 @@ export const EXTERNAL_TOOLS = Object.freeze([
     label: 'OpenCode',
     command: 'opencode',
     packages: Object.freeze(['opencode-ai']),
-    // (@opencode-ai/sdk is the JavaScript client and is not matched.)
+    // (No OpenCode client package ships: SynaBun speaks to OpenCode 2's serve itself, neural-interface/lib/opencode2-client.js.)
     patterns: Object.freeze([new RegExp(`^opencode-${PLATFORMS}-`)]),
   }),
   Object.freeze({

package/lib/first-launch-protection.js

@@ -11,6 +11,16 @@
 // The launcher also leaves its stop message in the server's stderr log
 // (recordLauncherFailure), because a detached launch has no terminal: the
 // updater's relaunch reads it back to tell the user why SynaBun did not start.
+//
+// The snapshot is the backup service's upgrade snapshot (createUpgradeSnapshot):
+// a consistent copy of each database (a clone where the file system clones)
+// that passed SQLite's integrity check, stored uncompressed, checksummed as it
+// is written and read back once. The desktop app takes it itself before it
+// replaces its own files (lib/update-snapshot.js) and hands it over; this start
+// uses it only when the data home is still what it was taken from
+// (checkUpgradeSnapshotFreshness), whatever process wrote since: an AI tool's
+// own MCP server may have saved a memory while the app swapped itself. Then it
+// takes a new one, here, before the server and so any migration runs.
 
 import { appendFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
@@ -31,19 +41,41 @@ function readJson(path, fallback) {
 /**
  * Why the snapshot an in-app update handed over cannot stand in for a fresh
  * one, or null when it can. It can only when the updater recorded that it
- * installed exactly the version now launching, and the archive still passes
- * verification. A `prepared` update is not enough: its updater may never have
- * run while the old server went on changing data.
+ * installed exactly the version now launching, the archive passes verification
+ * and its database copy passed SQLite's integrity check, and (the desktop app's
+ * snapshot, which records what it was taken from) nothing it protects changed
+ * since it was taken. A `prepared` update is not enough: its updater may never
+ * have run while the old server went on changing data.
  */
-async function handoffSnapshotProblem({ handoff, version, backupService }) {
+async function handoffSnapshotProblem({ handoff, version, backupService, dataHome }) {
   if (handoff.status !== 'installed') return 'that update was prepared but never recorded as installed';
   if (typeof handoff.target !== 'string' || handoff.target !== version) return 'it belongs to an update to another version';
   if (typeof handoff.snapshotPath !== 'string' || !handoff.snapshotPath) return 'it names no snapshot';
   if (!existsSync(handoff.snapshotPath)) return 'its snapshot file is gone';
   try {
     const service = await backupService();
-    const archive = await service.verifyBackupArchive(handoff.snapshotPath);
-    if (archive?.kind !== 'pre-update') return 'its file is not a pre-update snapshot';
+    let manifest;
+    // The desktop app read its snapshot back once, right after writing it, and
+    // recorded which file that was. The very same file, untouched since (device,
+    // inode, size, modification time), is not read a second time: only its
+    // manifest. Any other file is read in full.
+    if (handoff.verifiedStamp && typeof service.sameBackupFile === 'function' && typeof service.readBackupArchiveManifest === 'function'
+      && service.sameBackupFile(handoff.snapshotPath, handoff.verifiedStamp)) {
+      manifest = await service.readBackupArchiveManifest(handoff.snapshotPath);
+      if (manifest?.verified !== true) return 'its file is not a verified snapshot';
+    } else {
+      manifest = await service.verifyBackupArchive(handoff.snapshotPath);
+    }
+    if (manifest?.kind !== 'pre-update') return 'its file is not a pre-update snapshot';
+    // The restore runs SQLite's integrity check on the database it puts back: a copy that never passed it is no copy.
+    if (manifest.database && manifest.database.integrity !== 'ok') return 'its database copy was not checked with SQLite\'s integrity check';
+    // The data as it is now, before anything of this version touches it. The desktop app's snapshot says what it was
+    // taken from; the npm updater's (taken by the old server right before it stopped) does not, and is used as before.
+    if (handoff.source === 'desktop' || manifest.inputs) {
+      if (typeof service.checkUpgradeSnapshotFreshness !== 'function') return 'this version cannot tell whether the data changed since';
+      const freshness = await service.checkUpgradeSnapshotFreshness({ dataHome, manifest, databasePath: resolve(dataHome, 'mcp-data', 'memory.db') });
+      if (!freshness?.fresh) return `the data changed after it was taken (${freshness?.reason || 'unknown'})`;
+    }
   } catch (error) {
     return `its snapshot did not pass verification (${error?.message || error})`;
   }
@@ -94,7 +126,10 @@ export async function protectFirstLaunchAfterUpdate({
   let snapshotPath = null;
   if (pendingHandoff) {
     info('Checking the snapshot taken by the updater...');
-    const problem = await handoffSnapshotProblem({ handoff, version, backupService });
+    // The desktop app's splash says it: the copy made before the update is compared with the data (supervisor phase
+    // `snapshot`, step `check`).
+    progress({ step: 'check' });
+    const problem = await handoffSnapshotProblem({ handoff, version, backupService, dataHome });
     if (problem) info(`The updater's snapshot is not used: ${problem}. Taking a new one.`);
     else {
       snapshotPath = handoff.snapshotPath;
@@ -106,11 +141,16 @@ export async function protectFirstLaunchAfterUpdate({
   if (!snapshotPath) {
     const folderPath = resolve(dataHome, 'backups', 'updates');
     let service;
+    let lastPhase = null;
     try {
       info(`Protecting user state before first launch of v${version}...`);
       progress({});
       service = await backupService();
-      const snapshot = await service.createVerifiedBackup({
+      // The upgrade snapshot where the service has it (every SynaBun since 2026-10-21); the full backup otherwise.
+      const takeSnapshot = typeof service.createUpgradeSnapshot === 'function'
+        ? options => service.createUpgradeSnapshot(options)
+        : options => service.createVerifiedBackup(options);
+      const snapshot = await takeSnapshot({
         dataHome,
         databasePath: resolve(dataHome, 'mcp-data', 'memory.db'),
         folderPath,
@@ -118,17 +158,22 @@ export async function protectFirstLaunchAfterUpdate({
         appVersion: manifest.lastAppVersion || null,
         // Without this the checksum and archive phases run silently for minutes
         // on a large data home, which users read as a hang and kill.
-        onProgress: ({ phase, files, bytes, skippedFiles, skippedBytes }) => {
-          progress({ step: phase, files, bytes, skippedFiles });
+        onProgress: ({ phase, files, bytes, skippedFiles, skippedBytes, done, total, method, state }) => {
+          progress({ step: phase, files, bytes, skippedFiles, done, total, ...(state ? { state } : {}) });
+          // Each phase is said once, when it begins; the steps within it only reach the progress bar.
+          if (phase === lastPhase) return;
+          lastPhase = phase;
           const size = bytes ? ` (${(bytes / 1024 / 1024).toFixed(0)} MB)` : '';
           if (phase === 'collect') {
             info(`  ${files} files to protect${size}`);
             if (skippedFiles) {
               info(`  Skipping ${skippedFiles} generated media files (${(skippedBytes / 1024 / 1024).toFixed(0)} MB) — an upgrade never touches them`);
             }
-          } else if (phase === 'checksum') info(`  Checksumming ${files} files...`);
-          else if (phase === 'archive') info(`  Compressing${size}...`);
+          } else if (phase === 'copy') info(`  Copying the databases${method === 'clone' ? ' (a file system clone)' : ''}...`);
+          else if (phase === 'checksum') info(`  Checksumming ${files} files...`);
+          else if (phase === 'archive') info(total ? `  Writing the archive (${(total / 1024 / 1024).toFixed(0)} MB)...` : `  Compressing${size}...`);
           else if (phase === 'verify') info('  Verifying archive integrity...');
+          else if (phase === 'integrity') info('  Finishing SQLite\'s integrity check of the database copies...');
         },
       });
       snapshotPath = snapshot.path;

package/lib/mcp-dist.js

@@ -0,0 +1,176 @@
+// What "the MCP server is built" means, in one place: mcp-server/dist/index.js and every module it imports by a
+// relative path, transitively, are on disk. mcp-server/dist/ is build output that git ignores, yet a checkout can
+// hold a tracked dist/index.js whose newer imports were never committed (they are ignored too): a server started
+// from it fails to load /mcp. postinstall.js and setup.js build when this says no; the Neural Interface's restore,
+// onboarding status and build route, the install details, the release and the packaged app's checks ask it too.
+//
+// The imports are read from the code itself, never from a comment or a string: a light tokenizer skips comments,
+// strings, template literals and regular expressions, so a word "import" in a text cannot ask for a module that is
+// not loaded (a packaged app has no compiler: a false "missing" there would stop it). Only plain fs and path:
+// postinstall.js and setup.js import this on any Node.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+const MAX_MODULES = 5000;
+const MAX_MODULE_BYTES = 8 * 1024 * 1024;
+const CODE_EXT = /\.(?:m?js|cjs)$/i;
+// After one of these a `/` starts a regular expression, after anything else it divides.
+const REGEX_AFTER_PUNCT = new Set(['(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '<', '>', '~', '^']);
+const REGEX_AFTER_WORD = new Set(['return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void', 'throw', 'case', 'do', 'else', 'yield', 'await']);
+
+/**
+ * The tokens of a module that matter for its imports: words, punctuation and string literals (their values), with
+ * comments, template literal text and regular expressions left out.
+ * @returns {{ t: 'word'|'punct'|'string', v: string }[]}
+ */
+export function codeTokens(text) {
+  const src = String(text ?? '');
+  const out = [];
+  const frames = [];   // one per open `${` of a template literal: the brace depth that closes it
+  let depth = 0;
+  let i = 0;
+  const last = () => out[out.length - 1];
+  const regexAllowed = () => {
+    const p = last();
+    if (!p) return true;
+    if (p.t === 'punct') return REGEX_AFTER_PUNCT.has(p.v);
+    if (p.t === 'word') return REGEX_AFTER_WORD.has(p.v);
+    return false;
+  };
+  const template = () => {
+    // From just after a backtick (or a closing `}` of a `${`): to the closing backtick or the next `${`.
+    while (i < src.length) {
+      const c = src[i];
+      if (c === '\\') { i += 2; continue; }
+      if (c === '`') { i += 1; out.push({ t: 'string', v: '' }); return; }
+      if (c === '$' && src[i + 1] === '{') { i += 2; frames.push(depth); depth += 1; return; }
+      i += 1;
+    }
+  };
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '/' && src[i + 1] === '/') { const nl = src.indexOf('\n', i); i = nl < 0 ? src.length : nl; continue; }
+    if (c === '/' && src[i + 1] === '*') { const end = src.indexOf('*/', i + 2); i = end < 0 ? src.length : end + 2; continue; }
+    if (c === '\'' || c === '"') {
+      let j = i + 1; let v = '';
+      while (j < src.length && src[j] !== c && src[j] !== '\n') { if (src[j] === '\\') { v += src[j + 1] ?? ''; j += 2; continue; } v += src[j]; j += 1; }
+      out.push({ t: 'string', v });
+      i = j + 1;
+      continue;
+    }
+    if (c === '`') { i += 1; template(); continue; }
+    if (c === '/' && regexAllowed()) {
+      let j = i + 1; let inClass = false;
+      while (j < src.length && src[j] !== '\n') {
+        const d = src[j];
+        if (d === '\\') { j += 2; continue; }
+        if (d === '[') inClass = true;
+        else if (d === ']') inClass = false;
+        else if (d === '/' && !inClass) break;
+        j += 1;
+      }
+      i = j + 1;
+      while (i < src.length && /[a-z]/i.test(src[i])) i += 1;
+      out.push({ t: 'punct', v: ')' });   // a value, as far as a following `/` is concerned
+      continue;
+    }
+    if (/[A-Za-z_$]/.test(c)) {
+      let j = i + 1;
+      while (j < src.length && /[\w$]/.test(src[j])) j += 1;
+      out.push({ t: 'word', v: src.slice(i, j) });
+      i = j;
+      continue;
+    }
+    if (/\s/.test(c)) { i += 1; continue; }
+    if (/[0-9]/.test(c)) { let j = i + 1; while (j < src.length && /[\w.]/.test(src[j])) j += 1; out.push({ t: 'word', v: src.slice(i, j) }); i = j; continue; }
+    if (c === '{') depth += 1;
+    if (c === '}') {
+      if (frames.length && depth - 1 === frames[frames.length - 1]) { depth -= 1; frames.pop(); i += 1; template(); continue; }
+      depth = Math.max(0, depth - 1);
+    }
+    out.push({ t: 'punct', v: c });
+    i += 1;
+  }
+  return out;
+}
+
+/** The module specifiers a module loads: static imports, `export … from`, side-effect imports, `import('…')`. */
+export function importSpecifiers(text) {
+  const tokens = codeTokens(text);
+  const found = [];
+  const at = (k) => tokens[k] || { t: 'end', v: '' };
+  for (let k = 0; k < tokens.length; k++) {
+    const tok = tokens[k];
+    if (tok.t !== 'word' || (tok.v !== 'import' && tok.v !== 'export')) continue;
+    if (k > 0 && at(k - 1).t === 'punct' && at(k - 1).v === '.') continue;   // obj.import
+    const next = at(k + 1);
+    if (tok.v === 'import') {
+      if (next.t === 'punct' && next.v === '.') continue;   // import.meta
+      if (next.t === 'punct' && next.v === '(') { if (at(k + 2).t === 'string' && at(k + 3).v === ')') found.push(at(k + 2).v); continue; }
+      if (next.t === 'string') { found.push(next.v); continue; }
+    }
+    // import a, { b as c } from '…'; import * as d from '…'; export { e } from '…'; export * from '…'
+    let j = k + 1;
+    while (j < tokens.length) {
+      const x = at(j);
+      if (x.t === 'word' && x.v === 'from') break;
+      if (x.t === 'word' || (x.t === 'punct' && (x.v === ',' || x.v === '{' || x.v === '}' || x.v === '*'))) { j += 1; continue; }
+      j = -1;
+      break;
+    }
+    if (j > k + 1 && at(j).v === 'from' && at(j + 1).t === 'string') {
+      if (tok.v === 'export' && !(next.v === '*' || next.v === '{')) continue;
+      found.push(at(j + 1).v);
+    }
+  }
+  return found;
+}
+
+const posix = (p) => p.split(sep).join('/');
+
+/**
+ * Every module dist/index.js needs that is not on disk (or cannot be read), as paths from the package root.
+ * Modules inside mcp-server/dist are followed; one outside it (the package's lib/) is only looked for.
+ * @param {string} packageRoot
+ * @param {{ exists?: (p: string) => boolean, readText?: (p: string) => string, entry?: string }} [o]
+ * @returns {{ complete: boolean, missing: string[], checked: number }}
+ */
+export function mcpDistMissing(packageRoot, { exists = existsSync, readText = null, entry = 'index.js' } = {}) {
+  const root = resolve(packageRoot);
+  const dist = join(root, 'mcp-server', 'dist');
+  const read = readText || ((p) => {
+    const st = statSync(p);
+    if (!st.isFile()) throw new Error('not a regular file');
+    if (st.size > MAX_MODULE_BYTES) return null;
+    return readFileSync(p, 'utf8');
+  });
+  const missing = new Set();
+  const seen = new Set();
+  const queue = [join(dist, entry)];
+  let checked = 0;
+  while (queue.length && checked < MAX_MODULES) {
+    const file = queue.shift();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    if (!exists(file)) { missing.add(posix(relative(root, file))); continue; }
+    const inside = file.startsWith(dist + sep);
+    if (!inside || !CODE_EXT.test(file)) continue;
+    let text;
+    try { text = read(file); } catch { missing.add(posix(relative(root, file))); continue; }
+    checked += 1;
+    if (text === null) continue;   // too large to read here: present, not followed
+    for (const spec of importSpecifiers(text)) {
+      if (!spec.startsWith('./') && !spec.startsWith('../')) continue;
+      const target = resolve(dirname(file), spec.split(/[?#]/)[0]);
+      if (!seen.has(target)) queue.push(target);
+    }
+  }
+  const list = [...missing].sort();
+  return { complete: list.length === 0, missing: list, checked };
+}
+
+/** Whether the MCP server is built: dist/index.js and everything it imports are there. */
+export function mcpDistBuilt(packageRoot, options) {
+  return mcpDistMissing(packageRoot, options).complete;
+}