synabun 2.0.10 → 2.2.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

@@ -15,12 +15,20 @@ import {
 import { dirname, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import {
-  mergeGeminiMcpConfig,
-  mergeOpenCodeMcpConfig,
+  mergeAntigravityMcpConfig,
+  parseAntigravityMcpConfig,
 } 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 +68,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',
     },
   };
@@ -94,22 +103,26 @@ export function auditAndRepairClientConfigs({
     results.claude = { exists: existsSync(claudePath), connected: false, changed: false, path: claudePath };
   }
 
-  const geminiPath = join(home, '.gemini', 'settings.json');
-  const gemini = readJson(geminiPath);
-  if (gemini?.mcpServers?.SynaBun) {
-    const next = mergeGeminiMcpConfig(gemini, definition);
-    const changed = jsonChanged(gemini, next);
-    if (apply && changed) writeJsonAtomic(geminiPath, next);
-    results.gemini = { exists: true, connected: true, changed, path: geminiPath };
+  // Google Antigravity (the `agy` CLI and the app share it): ~/.gemini/config/mcp_config.json, mcpServers.SynaBun.
+  // The file Antigravity creates is empty until a server is added; one that is not JSON is left alone.
+  const antigravityPath = join(home, '.gemini', 'config', 'mcp_config.json');
+  let antigravity = null;
+  try { antigravity = parseAntigravityMcpConfig(readFileSync(antigravityPath, 'utf-8')); } catch { antigravity = null; }
+  if (antigravity?.mcpServers?.SynaBun) {
+    const next = mergeAntigravityMcpConfig(antigravity, definition);
+    const changed = jsonChanged(antigravity, next);
+    if (apply && changed) writeJsonAtomic(antigravityPath, next);
+    results.antigravity = { exists: true, connected: true, changed, path: antigravityPath };
   } else {
-    results.gemini = { exists: existsSync(geminiPath), connected: false, changed: false, path: geminiPath };
+    results.antigravity = { exists: existsSync(antigravityPath), connected: false, changed: false, path: antigravityPath };
   }
 
-  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 +139,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

@@ -1,7 +1,7 @@
 /**
  * SynaBun — external tools stay external
  *
- * Claude Code, Codex, OpenCode and Gemini CLI are programs of their own. The
+ * Claude Code, Codex, OpenCode and the Antigravity CLI are programs of their own. The
  * user installs them; SynaBun finds what is installed (Settings, PATH and the
  * OS PATH, the folders of every install method:
  * neural-interface/lib/cli-resolver.js) and talks to it, through a thin
@@ -66,14 +66,15 @@ 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({
-    id: 'gemini',
-    label: 'Gemini CLI',
-    command: 'gemini',
-    packages: Object.freeze(['@google/gemini-cli', '@google/gemini-cli-core']),
+    // Google ships the Antigravity CLI as a signed binary (no npm package): only its command is matched.
+    id: 'antigravity',
+    label: 'Antigravity CLI',
+    command: 'agy',
+    packages: Object.freeze([]),
     patterns: 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;