synabun 1.3.0 → 2.0.0

package/lib/desktop-pwa.js

@@ -0,0 +1,206 @@
+/** Browser-owned PWA shortcuts only. No browser databases and no --app= window. */
+import { createHash } from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, sep } from 'node:path';
+
+export function pwaAppId(url) {
+  return createHash('sha256').update(url).digest('hex').slice(0, 32)
+    .replace(/[0-9a-f]/g, c => String.fromCharCode(97 + parseInt(c, 16)));
+}
+
+export function pwaOrigins(port) {
+  return [`http://localhost:${port}/`, `http://127.0.0.1:${port}/`, `http://[::1]:${port}/`];
+}
+
+export function matchesPwaUrl(value, port, installRoute = false) {
+  try {
+    const url = new URL(value);
+    return !url.username && !url.password && url.protocol === 'http:'
+      && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)
+      && Number(url.port || 80) === Number(port)
+      && (url.pathname === '/' || (installRoute && url.pathname === '/install-app.html')) && !url.search && !url.hash;
+  } catch { return false; }
+}
+
+/** Conservative argument reader for browser-generated shortcuts, never a shell. */
+export function shortcutArgs(text) {
+  const args = [];
+  let token = '', quoted = false, active = false;
+  for (const c of String(text).trim()) {
+    if (c === '"') { quoted = !quoted; active = true; }
+    else if (/\s/.test(c) && !quoted) {
+      if (active) args.push(token);
+      token = ''; active = false;
+    } else { token += c; active = true; }
+  }
+  if (quoted) return [];
+  if (active) args.push(token);
+  return args;
+}
+
+/** Rebuild the launch arguments from an installed app identity; drop nothing silently. */
+export function chromiumShortcut(args, port) {
+  let id = null, profile = null;
+  for (const arg of args) {
+    if (/^--app-id=[a-p]{32}$/.test(arg) && !id) id = arg.slice(9);
+    else if (/^--profile-directory=[\w -]{1,80}$/.test(arg) && !profile) profile = arg.slice(20);
+    else if (/^--app-launch-source=\d+$/.test(arg)) continue;
+    else return null; // Includes --app=URL, shell syntax and additional browser switches.
+  }
+  if (!id || !pwaOrigins(port).some(url => pwaAppId(url) === id)) return null;
+  return [`--app-id=${id}`, ...(profile ? [`--profile-directory=${profile}`] : [])];
+}
+
+function list(folder) {
+  try { return readdirSync(folder).sort(); } catch { return []; }
+}
+function inside(file, folder) {
+  try { return realpathSync(file).startsWith(realpathSync(folder) + sep); } catch { return false; }
+}
+function smallFile(file) {
+  try { return statSync(file).size <= 1024 * 1024; } catch { return false; }
+}
+function appName(name) { return /^synabun(?:\.app|\.lnk)?$/i.test(String(name || '')); }
+
+function plistUrls(value) {
+  if (!value || typeof value !== 'object') return [];
+  return Object.entries(value).flatMap(([key, item]) =>
+    ['CrAppModeShortcutURL', 'LSWebApplicationURL', 'WebAppURL', 'WebsiteURL', 'URL', 'start_url', 'manifestId'].includes(key)
+      && typeof item === 'string' ? [item] : plistUrls(item));
+}
+
+export function macPwa(plist, file, port) {
+  if (!appName(plist.CFBundleDisplayName || plist.CFBundleName || basename(file))) return null;
+  const bundleId = String(plist.CFBundleIdentifier || '');
+  const safari = /^com\.apple\.Safari\.WebApp\./.test(bundleId);
+  const chrome = /^(com\.google\.Chrome|com\.microsoft\.edgemac)\.app\./.test(bundleId);
+  if (!(safari || chrome) || !plistUrls(plist).some(url => matchesPwaUrl(url, port, safari))) return null;
+  if (chrome && !/^[a-p]{32}$/.test(plist.CrAppModeShortcutID || bundleId.split('.').pop())) return null;
+  return { kind: safari ? 'Safari web app' : 'Chromium installed PWA', file: '/usr/bin/open', args: ['-a', file] };
+}
+
+function knownBrowsers(platform, env, home) {
+  if (platform === 'win32') {
+    return [env.PROGRAMFILES, env['PROGRAMFILES(X86)'], env.ProgramFiles, env['ProgramFiles(x86)'], env.LOCALAPPDATA]
+      .filter(Boolean).flatMap(root => ['Google/Chrome/Application/chrome', 'Microsoft/Edge/Application/msedge']
+        .flatMap(tail => [join(root, `${tail}.exe`), join(root, `${tail}_proxy.exe`)]));
+  }
+  return ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/opt/google/chrome/google-chrome',
+    '/opt/google/chrome/chrome', '/usr/bin/microsoft-edge', '/usr/bin/microsoft-edge-stable',
+    '/opt/microsoft/msedge/msedge'];
+}
+
+export function browserPwa({ name, target, args }, port, allowed) {
+  if (!appName(name) || !allowed.includes(target)) return null;
+  const safe = chromiumShortcut(Array.isArray(args) ? args : shortcutArgs(args), port);
+  return safe ? { kind: 'Chromium installed PWA', file: target, args: safe } : null;
+}
+
+export function linuxPwa(text, port, allowed) {
+  const section = String(text).split('[Desktop Entry]')[1]?.split(/\n\[/)[0];
+  if (!section) return null;
+  const values = Object.fromEntries(section.split(/\r?\n/).map(line => line.match(/^([\w-]+)=(.*)$/))
+    .filter(Boolean).map(match => [match[1], match[2]]));
+  if (values.Type !== 'Application' || values.Hidden === 'true' || values.Terminal === 'true') return null;
+  // Desktop-entry strings escape backslashes once before the Exec quoting layer.
+  const [target, ...args] = shortcutArgs(String(values.Exec || '').replace(/\\\\/g, '\\'));
+  return browserPwa({ name: values.Name, target, args }, port, allowed);
+}
+
+/** Scan only app bundles or browser-generated application shortcuts bearing SynaBun's name. */
+export function findInstalledPwa({ port, platform = process.platform, home = homedir(), env = process.env,
+  run = spawnSync } = {}) {
+  if (platform === 'darwin') {
+    const roots = [join(home, 'Applications'), join(home, 'Applications', 'Chrome Apps.localized'),
+      join(home, 'Applications', 'Edge Apps.localized'), '/Applications/Chrome Apps.localized', '/Applications/Edge Apps.localized'];
+    for (const root of roots) for (const name of list(root).filter(name => /^synabun\.app$/i.test(name))) {
+      const file = join(root, name), info = join(file, 'Contents', 'Info.plist');
+      if (!inside(file, root) || !smallFile(info)) continue;
+      const result = run('/usr/bin/plutil', ['-convert', 'json', '-o', '-', info], { encoding: 'utf8', timeout: 3000, maxBuffer: 1024 * 1024 });
+      try { const app = macPwa(JSON.parse(result.stdout), file, port); if (app) return app; } catch {}
+    }
+    return null;
+  }
+  const allowed = knownBrowsers(platform, env, home).filter(existsSync);
+  if (platform === 'linux') {
+    const roots = [join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'applications'), '/usr/share/applications'];
+    for (const root of roots) for (const name of list(root).filter(name => /^(?:chrome|msedge)-[a-p]{32}-.+\.desktop$/.test(name))) {
+      // Only the app IDs for this exact loopback origin, before reading any entry.
+      if (!pwaOrigins(port).some(url => name.includes(pwaAppId(url)))) continue;
+      const file = join(root, name);
+      if (!inside(file, root) || !smallFile(file)) continue;
+      try { const app = linuxPwa(readFileSync(file, 'utf8'), port, allowed); if (app) return app; } catch {}
+    }
+    return null;
+  }
+  if (platform === 'win32') {
+    // WScript reads only SynaBun.lnk in these application folders. It never executes a link.
+    const roots = [env.APPDATA && join(env.APPDATA, 'Microsoft', 'Windows', 'Start Menu', 'Programs'), join(home, 'Desktop')].filter(Boolean);
+    const links = roots.flatMap(root => [root, join(root, 'Chrome Apps'), join(root, 'Edge Apps')])
+      .flatMap(root => list(root).filter(name => /^synabun\.lnk$/i.test(name)).map(name => join(root, name)))
+      .filter(file => smallFile(file));
+    if (!links.length) return null;
+    const script = "$w=New-Object -ComObject WScript.Shell; $r=@(); foreach($p in (ConvertFrom-Json $env:SYNABUN_PWA_LINKS)) { $s=$w.CreateShortcut($p); $r+=@{name='SynaBun';target=$s.TargetPath;args=$s.Arguments} }; ConvertTo-Json -Compress -InputObject @($r)";
+    const result = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+      encoding: 'utf8', windowsHide: true, timeout: 10000, maxBuffer: 1024 * 1024,
+      env: { ...env, SYNABUN_PWA_LINKS: JSON.stringify(links) },
+    });
+    try {
+      for (const item of JSON.parse(result.stdout.replace(/^\uFEFF/, ''))) {
+        // Windows paths are case-insensitive, but must still be a known installed browser.
+        const target = allowed.find(path => path.toLowerCase() === String(item.target).toLowerCase());
+        const app = target && browserPwa({ ...item, target }, port, allowed);
+        if (app) return app;
+      }
+    } catch {}
+  }
+  return null;
+}
+
+export async function openDesktopPwa({ port, env = process.env, platform = process.platform,
+  find = findInstalledPwa, spawnImpl = spawn } = {}) {
+  if (env.SYNABUN_OPEN_BROWSER === '0') return { kind: 'suppressed' };
+  const installed = find({ port, env, platform });
+  const url = `http://localhost:${port}/install-app.html`;
+  const fallback = platform === 'win32'
+    ? { file: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] }
+    : platform === 'darwin' ? { file: '/usr/bin/open', args: [url] } : { file: 'xdg-open', args: [url] };
+  const launch = choice => new Promise((done, reject) => {
+    const child = spawnImpl(choice.file, choice.args, { env, stdio: 'ignore', detached: true, windowsHide: true });
+    child.once('error', reject);
+    child.once('spawn', () => { child.unref(); done(); });
+  });
+  if (installed) {
+    try { await launch(installed); return { kind: installed.kind }; } catch {}
+  }
+  await launch(fallback);
+  return { kind: 'one-time browser installation', url };
+}
+
+/** A re-executed AppImage owns a fresh mount for the entire supervisor lifetime. */
+export function backgroundCommand(runtime, env) {
+  if (!runtime?.entry) throw new Error('the installed launcher is missing');
+  const next = { ...env, SYNABUN_OPEN_BROWSER: '0', SYNABUN_LAUNCH_ENV: 'resolved' };
+  const image = runtime.artifact === 'linux-appdir' && env.APPIMAGE;
+  if (image) {
+    const mount = String(env.APPDIR || '').replace(/\/+$/, '');
+    if (mount && next.PATH) next.PATH = next.PATH.split(':').filter(path => path !== mount && !path.startsWith(`${mount}/`)).join(':');
+    for (const key of ['APPIMAGE', 'APPDIR', 'ARGV0', 'OWD']) delete next[key];
+  }
+  // The first image may unmount after handoff. No cwd or PATH of the fresh
+  // runtime may depend on it; the launcher has already created the data home.
+  return { file: runtime.entry, args: ['background-server'], env: next,
+    cwd: image ? (next.SYNABUN_DATA_HOME || dirname(runtime.entry)) : undefined };
+}
+
+/** A port occupant prevents duplicates; only SynaBun's healthy API permits a PWA handoff. */
+export async function pwaServerReady(port, { fetchImpl = globalThis.fetch } = {}) {
+  try {
+    const response = await fetchImpl(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(1500) });
+    if (!response.ok) return false;
+    const data = await response.json();
+    return data.ok === true && data.storage === 'sqlite' && typeof data.projectDir === 'string' && !!data.startLauncher;
+  } catch { return false; }
+}

package/lib/external-tools.js

@@ -0,0 +1,221 @@
+/**
+ * SynaBun — external tools stay external
+ *
+ * Claude Code, Codex, OpenCode and Gemini CLI are programs of their own. The
+ * user installs them; SynaBun finds what is installed (PATH, Homebrew, npm, the
+ * native installers' folders) and talks to it, through a thin JavaScript SDK
+ * where there is one. It never installs, ships or runs a copy of its own.
+ *
+ * npm has no way to say "this SDK, without the program it carries": the Claude
+ * Agent SDK brings the Claude Code executable as a per-platform optional
+ * dependency, and @openai/codex-sdk depends on the whole Codex CLI. So the rule
+ * is kept in three places, all reading the one list below:
+ *
+ *   the lockfiles      hold none of these packages and no edge to one
+ *                      (scripts/strip-external-tools.mjs), so npm never
+ *                      downloads them
+ *   an install         removes any that came anyway (the neural-interface
+ *                      postinstall, the server at start)
+ *   a packaged build   removes them from what it stages and refuses a bundle
+ *                      that holds one (packaging/lib/stage.mjs, verify.mjs)
+ *
+ * The SDKs stay: every call hands them the user's executable
+ * (pathToClaudeCodeExecutable, codexPathOverride), so the payload they would
+ * otherwise look for is never needed.
+ *
+ * Only node:fs and node:path here: the install scripts import this on any
+ * Node, before a single dependency exists.
+ */
+
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PLATFORMS = '(?:darwin|linux|win32|windows|android)';
+
+/**
+ * Each tool: the command the user runs, the packages that ARE the tool (never
+ * a dependency of SynaBun), and how its per-platform payload packages are
+ * named. A name is what a package is installed as, under node_modules.
+ */
+export const EXTERNAL_TOOLS = Object.freeze([
+  Object.freeze({
+    id: 'claude-code',
+    label: 'Claude Code',
+    command: 'claude',
+    packages: Object.freeze(['@anthropic-ai/claude-code']),
+    // The CLI's own platform packages, and the same executable as the Agent SDK carries it.
+    patterns: Object.freeze([
+      new RegExp(`^@anthropic-ai/claude-code-${PLATFORMS}-`),
+      new RegExp(`^@anthropic-ai/claude-agent-sdk-${PLATFORMS}-`),
+    ]),
+  }),
+  Object.freeze({
+    id: 'codex',
+    label: 'Codex',
+    command: 'codex',
+    packages: Object.freeze(['@openai/codex']),
+    // (@openai/codex-sdk is the JavaScript client and is not matched.)
+    patterns: Object.freeze([new RegExp(`^@openai/codex-${PLATFORMS}-`)]),
+  }),
+  Object.freeze({
+    id: 'opencode',
+    label: 'OpenCode',
+    command: 'opencode',
+    packages: Object.freeze(['opencode-ai']),
+    // (@opencode-ai/sdk is the JavaScript client and is not matched.)
+    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']),
+    patterns: Object.freeze([]),
+  }),
+]);
+
+/** The file names a tool's command can have in a `.bin` folder or on disk. */
+const COMMAND_SUFFIXES = ['', '.cmd', '.ps1', '.bat', '.exe'];
+const COMMAND_FILES = new Map(EXTERNAL_TOOLS.flatMap(tool => COMMAND_SUFFIXES.map(suffix => [`${tool.command}${suffix}`, tool])));
+
+/** The tool a package name belongs to, or null: `@openai/codex` yes, `@openai/codex-sdk` no. */
+export function externalToolOf(packageName) {
+  const name = String(packageName || '');
+  if (!name) return null;
+  return EXTERNAL_TOOLS.find(tool => tool.packages.includes(name) || tool.patterns.some(pattern => pattern.test(name))) || null;
+}
+
+/** The package a lockfile path installs: what follows its last `node_modules/`. */
+export function packageNameOfLockPath(path) {
+  const value = String(path || '').replace(/\\/g, '/');
+  const at = value.lastIndexOf('node_modules/');
+  return at < 0 ? '' : value.slice(at + 'node_modules/'.length);
+}
+
+const EDGE_FIELDS = ['dependencies', 'optionalDependencies', 'peerDependencies', 'peerDependenciesMeta', 'devDependencies'];
+
+/**
+ * What a lockfile (package-lock.json, or the hidden node_modules/.package-lock.json)
+ * still holds of external tools: `packages` are the entries that would be
+ * installed, `edges` the dependencies other entries declare on one.
+ */
+export function externalToolsInLock(lock) {
+  const packages = [];
+  const edges = [];
+  for (const [path, entry] of Object.entries(lock?.packages || {})) {
+    const tool = externalToolOf(packageNameOfLockPath(path));
+    if (tool) { packages.push({ path, tool: tool.id, version: entry?.version || null }); continue; }
+    for (const field of EDGE_FIELDS) {
+      for (const name of Object.keys(entry?.[field] || {})) {
+        const wanted = externalToolOf(name);
+        if (wanted) edges.push({ from: path || '(root)', field, name, tool: wanted.id });
+      }
+    }
+  }
+  return { packages, edges };
+}
+
+/**
+ * Take every external tool out of a lockfile object, in place: its entries, and
+ * the edges that would make npm fetch them again. Returns what was removed.
+ * A lockfile left this way installs the SDKs and nothing they would carry.
+ */
+export function stripExternalToolsFromLock(lock) {
+  const found = externalToolsInLock(lock);
+  for (const item of found.packages) delete lock.packages[item.path];
+  for (const edge of found.edges) {
+    const entry = lock.packages[edge.from === '(root)' ? '' : edge.from];
+    if (!entry?.[edge.field]) continue;
+    delete entry[edge.field][edge.name];
+    if (!Object.keys(entry[edge.field]).length) delete entry[edge.field];
+  }
+  return found;
+}
+
+const list = (folder) => { try { return readdirSync(folder, { withFileTypes: true }); } catch { return []; } };
+
+/**
+ * Every external-tool package and command installed under one node_modules
+ * folder, nested trees included: [{ kind: 'package' | 'command', name, tool, path }].
+ */
+export function externalToolsInstalledIn(nodeModules, { depth = 6 } = {}) {
+  const found = [];
+  const visitModules = (folder, left) => {
+    for (const entry of list(folder)) {
+      if (entry.name === '.bin') {
+        for (const file of list(join(folder, '.bin'))) {
+          const tool = COMMAND_FILES.get(file.name);
+          if (tool) found.push({ kind: 'command', name: file.name, tool: tool.id, path: join(folder, '.bin', file.name) });
+        }
+        continue;
+      }
+      if (entry.name.startsWith('.') || !(entry.isDirectory() || entry.isSymbolicLink())) continue;
+      const names = entry.name.startsWith('@')
+        ? list(join(folder, entry.name)).filter(scoped => scoped.isDirectory() || scoped.isSymbolicLink()).map(scoped => `${entry.name}/${scoped.name}`)
+        : [entry.name];
+      for (const name of names) {
+        const path = join(folder, ...name.split('/'));
+        const tool = externalToolOf(name);
+        if (tool) { found.push({ kind: 'package', name, tool: tool.id, path }); continue; }
+        if (left > 0 && existsSync(join(path, 'node_modules'))) visitModules(join(path, 'node_modules'), left - 1);
+      }
+    }
+  };
+  visitModules(nodeModules, depth);
+  return found;
+}
+
+/**
+ * Remove what externalToolsInstalledIn() finds, and the same entries from npm's
+ * hidden lockfile, so that npm's own record matches the folder. Never throws:
+ * `failed` lists what could not be removed (a read-only install, a file in use).
+ * Does nothing, and writes nothing, when there is nothing to remove.
+ */
+export function pruneExternalTools(nodeModules, { log = null } = {}) {
+  const result = { removed: [], failed: [] };
+  for (const item of externalToolsInstalledIn(nodeModules)) {
+    try {
+      rmSync(item.path, { recursive: true, force: true });
+      result.removed.push(item);
+      if (log) log(`removed ${item.kind} ${item.name} (${item.tool} is installed separately): ${item.path}`);
+    } catch (error) {
+      result.failed.push({ ...item, error: error?.message || String(error) });
+      if (log) log(`could not remove ${item.path}: ${error?.message || error}`);
+    }
+  }
+  if (!result.removed.length) return result;
+  const hidden = join(nodeModules, '.package-lock.json');
+  try {
+    const lock = JSON.parse(readFileSync(hidden, 'utf8'));
+    const stripped = stripExternalToolsFromLock(lock);
+    if (stripped.packages.length || stripped.edges.length) writeFileSync(hidden, JSON.stringify(lock, null, 2) + '\n');
+  } catch { /* no hidden lockfile, or not ours to repair */ }
+  return result;
+}
+
+/**
+ * Why a file of a packaged application is an external tool's, or null. By path
+ * alone, forward or back slashes: a package folder, or a command in a `.bin`
+ * folder. `native` says the file is a native executable; then the tool's own
+ * file name anywhere is one too (`claude`, `codex.exe` ...).
+ */
+export function externalToolPayloadReason(relativePath, { native = false } = {}) {
+  const path = String(relativePath || '').replace(/\\/g, '/');
+  const parts = path.split('/');
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (parts[i] !== 'node_modules') continue;
+    if (parts[i + 1] === '.bin') {
+      const tool = i + 2 === parts.length - 1 ? COMMAND_FILES.get(parts[i + 2]) : null;
+      if (tool) return `the ${tool.label} command (${parts[i + 2]})`;
+      continue;
+    }
+    const name = parts[i + 1].startsWith('@') ? `${parts[i + 1]}/${parts[i + 2] || ''}` : parts[i + 1];
+    const tool = externalToolOf(name);
+    if (tool) return `the package ${name} (${tool.label})`;
+  }
+  if (native) {
+    const tool = COMMAND_FILES.get(parts[parts.length - 1]);
+    if (tool) return `the ${tool.label} executable`;
+  }
+  return null;
+}

package/lib/first-launch-protection.js

@@ -0,0 +1,245 @@
+// The protection user state gets before a new SynaBun version runs for the
+// first time: a verified snapshot of the data home, taken by setup.js before
+// the server (and so any data migration) starts.
+//
+// The snapshot is a promise, so its failure stops the launch. setup.js exits
+// with SNAPSHOT_FAILED_EXIT_CODE and the message from describeSnapshotFailure();
+// there is no flag or environment variable to launch anyway. A fresh install
+// with no user state, and a launch of the version that already ran, need no
+// snapshot and are not affected.
+//
+// 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.
+
+import { appendFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { DATA_HOME_MANIFEST, dataHomeHasState } from './data-home-migration.js';
+
+/** setup.js exits with this when the pre-update snapshot could not be created. */
+export const SNAPSHOT_FAILED_EXIT_CODE = 3;
+
+/** First line of a launcher stop record. updater.mjs looks for the same text. */
+export const LAUNCHER_STOP_MARKER = '===== launcher stopped ';
+
+const noop = () => {};
+
+function readJson(path, fallback) {
+  try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return 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.
+ */
+async function handoffSnapshotProblem({ handoff, version, backupService }) {
+  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';
+  } catch (error) {
+    return `its snapshot did not pass verification (${error?.message || error})`;
+  }
+  return null;
+}
+
+/**
+ * Makes sure a verified snapshot exists before `version` runs on a data home
+ * that last ran another version (or that an in-app update just handed over).
+ *
+ * @param {object} input
+ * @param {string} input.dataHome
+ * @param {string} input.version  the version about to launch
+ * @param {() => Promise<{createVerifiedBackup: Function, verifyBackupArchive: Function, applyBackupRetention: Function}>} [input.loadBackupService]
+ * @param {{info?: Function, ok?: Function, warn?: Function}} [input.log]
+ * @param {(detail: {step?: string, files?: number, bytes?: number, skippedFiles?: number}) => void} [input.onProgress]  called when a snapshot starts and at each of its steps
+ * @returns {Promise<
+ *   {status: 'not-due', reason: 'current-version' | 'no-state'} |
+ *   {status: 'protected', snapshotPath: string, created: boolean, recorded: boolean} |
+ *   {status: 'failed', error: Error, previousVersion: string|null, backupFolder: string}
+ * >} `failed` means no snapshot exists: the caller must not start the server.
+ */
+export async function protectFirstLaunchAfterUpdate({
+  dataHome,
+  version,
+  loadBackupService = () => import('../neural-interface/lib/backup-service.js'),
+  log = {},
+  onProgress = noop,
+} = {}) {
+  const info = log.info || noop;
+  const ok = log.ok || noop;
+  const warn = log.warn || noop;
+  const progress = (detail) => { try { onProgress(detail); } catch { /* reporting never stops a snapshot */ } };
+
+  const manifestPath = resolve(dataHome, DATA_HOME_MANIFEST);
+  const handoffPath = resolve(dataHome, 'data', 'update-handoff.json');
+  const manifest = readJson(manifestPath, {}) || {};
+  const handoff = readJson(handoffPath, null);
+  const pendingHandoff = !!handoff && ['prepared', 'installed'].includes(handoff.status);
+  if (manifest.lastAppVersion === version && !pendingHandoff) return { status: 'not-due', reason: 'current-version' };
+  if (!dataHomeHasState(dataHome)) return { status: 'not-due', reason: 'no-state' };
+
+  let loaded = null;
+  const backupService = async () => (loaded ||= await loadBackupService());
+
+  // An in-app update takes the snapshot before it replaces the code. It is
+  // reused only when it is provably the snapshot for this launch.
+  let snapshotPath = null;
+  if (pendingHandoff) {
+    info('Checking the snapshot taken by the updater...');
+    const problem = await handoffSnapshotProblem({ handoff, version, backupService });
+    if (problem) info(`The updater's snapshot is not used: ${problem}. Taking a new one.`);
+    else {
+      snapshotPath = handoff.snapshotPath;
+      ok('Verified the snapshot taken by the updater');
+    }
+  }
+  const created = !snapshotPath;
+
+  if (!snapshotPath) {
+    const folderPath = resolve(dataHome, 'backups', 'updates');
+    let service;
+    try {
+      info(`Protecting user state before first launch of v${version}...`);
+      progress({});
+      service = await backupService();
+      const snapshot = await service.createVerifiedBackup({
+        dataHome,
+        databasePath: resolve(dataHome, 'mcp-data', 'memory.db'),
+        folderPath,
+        kind: 'pre-update',
+        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 });
+          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 === 'verify') info('  Verifying archive integrity...');
+        },
+      });
+      snapshotPath = snapshot.path;
+      ok(`Verified upgrade snapshot: ${snapshot.name}`);
+    } catch (error) {
+      return {
+        status: 'failed',
+        error: error instanceof Error ? error : new Error(String(error)),
+        // The version to go back to: what the in-app update replaced, else what
+        // last ran on this data home. Never the version being launched.
+        previousVersion: [pendingHandoff ? handoff.current : null, manifest.lastAppVersion]
+          .find(value => typeof value === 'string' && value && value !== version) || null,
+        backupFolder: folderPath,
+      };
+    }
+    // The snapshot exists and is verified. Pruning older ones is housekeeping.
+    try { service.applyBackupRetention({ folderPath }); } catch (error) {
+      warn(`Could not prune older upgrade snapshots: ${error.message}`);
+    }
+  }
+
+  // Record the protected launch. The snapshot is already safe, so a failure
+  // here does not stop the launch: the next one takes a snapshot again.
+  try {
+    const nextManifest = {
+      version: 1,
+      installationId: manifest.installationId || `${Date.now()}-${process.pid}`,
+      dataSchemaVersion: manifest.dataSchemaVersion || 1,
+      ...manifest,
+      lastAppVersion: version,
+      lastUpgradeVerifiedAt: new Date().toISOString(),
+      lastUpgradeSnapshot: snapshotPath,
+    };
+    const manifestTemp = `${manifestPath}.${process.pid}.tmp`;
+    writeFileSync(manifestTemp, JSON.stringify(nextManifest, null, 2) + '\n', 'utf-8');
+    renameSync(manifestTemp, manifestPath);
+
+    if (pendingHandoff) {
+      // Closed either way: a handoff whose snapshot was not used is superseded
+      // by the one taken here.
+      writeFileSync(handoffPath, JSON.stringify({
+        ...handoff,
+        status: 'verified',
+        verifiedAt: new Date().toISOString(),
+        launchedVersion: version,
+        snapshotPath,
+        snapshotReused: !created,
+      }, null, 2) + '\n', 'utf-8');
+    }
+  } catch (error) {
+    warn(`The upgrade snapshot is safe at ${snapshotPath}, but recording it failed: ${error.message}`);
+    info('A new snapshot will be taken at the next launch.');
+    return { status: 'protected', snapshotPath, created, recorded: false };
+  }
+  return { status: 'protected', snapshotPath, created, recorded: true };
+}
+
+/**
+ * What to tell the user when the snapshot failed: what failed, what state the
+ * data is in, where it is, and the two ways forward.
+ * @returns {{headline: string, lines: string[]}}
+ */
+export function describeSnapshotFailure({ error, dataHome, version, previousVersion = null, backupFolder = null } = {}) {
+  const folder = backupFolder || resolve(dataHome, 'backups', 'updates');
+  // Without a recorded previous version (a data home older than the record, or
+  // one this version has not recorded yet) there may be nothing to go back to.
+  const goBack = previousVersion
+    ? `Or go back to the version you had: npm i -g synabun@${previousVersion}`
+    : 'Or, if you just updated, go back to the version you had: npm i -g synabun@<that version>';
+  return {
+    headline: `SynaBun v${version} did not start: the snapshot that protects your data before this version runs on it for the first time could not be created.`,
+    lines: [
+      `What failed: ${error?.message || 'unknown error'}`,
+      // Only what is true of the whole launch: an earlier step may have copied
+      // data from an old checkout into the data home (a verified copy; the
+      // source is kept), so "nothing was changed" would say too much.
+      `The server was not started, so v${version} has not converted or deleted any of your memories or settings.`,
+      `Data home: ${dataHome}`,
+      `Snapshot folder: ${folder}`,
+      `To continue: free disk space or fix the permissions of the snapshot folder, then run "synabun" again.`,
+      goBack,
+      'Run "synabun doctor" to inspect the data home.',
+    ],
+  };
+}
+
+/** Where the launcher leaves its stop message: the log the server's stderr goes to. */
+export function launcherLogPath(dataHome) {
+  return resolve(dataHome, 'data', 'server-stderr.log');
+}
+
+/**
+ * Appends why the launcher stopped to launcherLogPath(). Best effort and never
+ * throws: the disk may be the reason for the stop. It creates no folder, so a
+ * data home that does not exist yet stays that way.
+ * @returns {string|null} the log path when the record was written
+ */
+export function recordLauncherFailure({ dataHome, exitCode, headline, lines = [], now = () => new Date() } = {}) {
+  try {
+    if (!dataHome || !existsSync(resolve(dataHome, 'data'))) return null;
+    const path = launcherLogPath(dataHome);
+    const record = [
+      '',
+      `${LAUNCHER_STOP_MARKER}${now().toISOString()} (pid ${process.pid}, exit ${exitCode}) =====`,
+      headline,
+      ...lines,
+      '',
+    ].join('\n');
+    appendFileSync(path, record, 'utf-8');
+    return path;
+  } catch {
+    return null;
+  }
+}