synabun 2.0.0-beta → 2.0.5

package/neural-interface/templates/rulesets/README.md

@@ -5,5 +5,5 @@ One source, rendered per host by `neural-interface/lib/rulesets/render.js`.
 - `core.md` is the text every host gets. A line ending in `<!-- except: codex -->` is dropped for the hosts it names; the line `<!-- host -->` is where the host's own file goes.
 - `claude.md`, `codex.md`, `opencode.md`, `gemini.md`, `cursor.md` hold at most two bullets each.
 - `coexistence.md` is a snippet people copy by hand. It is never installed.
-- `manifest.json` carries the version and one hash per host. A text change without a new version and new hashes fails `tests/rulesets-render.test.mjs`, which prints the hashes to paste.
+- `manifest.json` carries the version and one hash per host. A text change needs a new version and new hashes; the render test (not published with this repository) fails without them and prints the hashes to paste.
 - `legacy-hashes.json` lists every ruleset SynaBun ever served, so the installer can recognise a copy someone pasted. `node scripts/gen-ruleset-legacy-hashes.mjs` adds to it and never drops an entry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synabun",
-  "version": "2.0.0-beta",
+  "version": "2.0.5",
   "description": "Local-first persistent vector memory, MCP tooling, and multi-agent workflows for AI assistants",
   "license": "Apache-2.0",
   "author": "The SynaBun Authors",
@@ -19,6 +19,7 @@
     "postinstall.js",
     "preuninstall.js",
     "updater.mjs",
+    "launcher.mjs",
     "updater.cmd",
     "updater.sh",
     "NOTICE",
@@ -56,6 +57,10 @@
     "hooks/claude-code/task-gate.mjs",
     "skills/",
     "lib/paths.js",
+    "lib/start-launcher.js",
+    "lib/packaged-runtime.js",
+    "lib/desktop-pwa.js",
+    "lib/external-tools.js",
     "lib/paths.d.ts",
     "lib/data-home-migration.js",
     "lib/first-launch-protection.js",
@@ -72,8 +77,6 @@
     "docs/judgments.md",
     "docs/style-guide.md",
     "docs/whatsapp.md",
-    "benchmarks/browser-v2-results.json",
-    "benchmarks/browser-live-results.json",
     "benchmarks/fixtures/browser/",
     "benchmarks/fixtures/desktop/",
     "README.md",
@@ -83,13 +86,16 @@
     "start": "node --disable-warning=ExperimentalWarning setup.js",
     "server": "node --disable-warning=ExperimentalWarning neural-interface/server.js",
     "mcp:build": "npm --prefix mcp-server run build",
-    "test": "npm run test:mcp && npm run test:neural",
-    "test:mcp": "npm --prefix mcp-server test",
-    "test:neural": "npm --prefix neural-interface test",
     "pack:check": "npm pack --dry-run --json --ignore-scripts",
+    "build:targets": "node packaging/build.mjs targets",
+    "build:mac:arm": "node packaging/build.mjs build --target macos-arm64",
+    "build:mac:intel": "node packaging/build.mjs build --target macos-x64",
+    "build:linux:x64": "node packaging/build.mjs build --target linux-x64",
+    "build:windows:x64": "node packaging/build.mjs build --target windows-x64",
+    "build:windows:x86": "node packaging/build.mjs build --target windows-x86",
     "postinstall": "node postinstall.js",
     "preuninstall": "node preuninstall.js",
-    "prepublishOnly": "npm --prefix mcp-server ci --ignore-scripts && npm --prefix neural-interface ci --ignore-scripts && npm run mcp:build && npm test && node -e \"const fs = require('node:fs'); for (const path of ['mcp-server/dist/index.js', 'NOTICE', 'THIRD-PARTY-LICENSES.md']) fs.accessSync(path)\" && npm run pack:check"
+    "prepublishOnly": "npm --prefix mcp-server ci --ignore-scripts && npm --prefix neural-interface ci --ignore-scripts && npm run mcp:build && node -e \"const fs = require('node:fs'); for (const path of ['mcp-server/dist/index.js', 'NOTICE', 'THIRD-PARTY-LICENSES.md']) fs.accessSync(path)\" && npm run pack:check"
   },
   "keywords": [
     "ai-agents",

package/postinstall.js

@@ -9,10 +9,11 @@
  */
 
 import { execSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs';
+import { existsSync, chmodSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir, platform } from 'node:os';
+import { platform } from 'node:os';
+import { registerStartLauncher } from './lib/start-launcher.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -114,87 +115,16 @@ function buildMcpServer() {
 }
 
 // ── Protocol handler registration ──
+//
+// The synabun:// handler behind the offline page's Start Server button. The
+// same registration runs on every start (setup.js), so this only makes the
+// button work before the first one.
 
 function registerProtocolHandler() {
-  const nodeBin = process.execPath;
-  const setupJs = resolve(__dirname, 'setup.js');
-  const plat = platform();
-
-  if (plat === 'win32') {
-    // Windows — HKCU registry (no admin required)
-    try {
-      const cmd = `"${nodeBin}" "${setupJs}" "%1"`;
-      execSync(`reg add "HKCU\\Software\\Classes\\synabun" /ve /d "URL:SynaBun Protocol" /f`, { stdio: 'pipe' });
-      execSync(`reg add "HKCU\\Software\\Classes\\synabun" /v "URL Protocol" /d "" /f`, { stdio: 'pipe' });
-      execSync(`reg add "HKCU\\Software\\Classes\\synabun\\shell\\open\\command" /ve /d "${cmd}" /f`, { stdio: 'pipe' });
-      ok('Registered synabun:// protocol handler');
-    } catch {
-      warn('Could not register synabun:// protocol handler');
-    }
-  } else if (plat === 'darwin') {
-    // macOS — minimal .app bundle in ~/.synabun/
-    try {
-      const appDir = resolve(homedir(), '.synabun', 'SynaBun.app', 'Contents');
-      const macosDir = resolve(appDir, 'MacOS');
-      mkdirSync(macosDir, { recursive: true });
-
-      writeFileSync(resolve(appDir, 'Info.plist'), [
-        '<?xml version="1.0" encoding="UTF-8"?>',
-        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
-        '<plist version="1.0">',
-        '<dict>',
-        '  <key>CFBundleIdentifier</key><string>ai.synabun.launcher</string>',
-        '  <key>CFBundleName</key><string>SynaBun</string>',
-        '  <key>CFBundleExecutable</key><string>synabun-launcher</string>',
-        '  <key>CFBundleVersion</key><string>1.0</string>',
-        '  <key>CFBundleURLTypes</key>',
-        '  <array><dict>',
-        '    <key>CFBundleURLName</key><string>SynaBun Protocol</string>',
-        '    <key>CFBundleURLSchemes</key><array><string>synabun</string></array>',
-        '  </dict></array>',
-        '</dict>',
-        '</plist>',
-      ].join('\n'));
-
-      const launcherPath = resolve(macosDir, 'synabun-launcher');
-      writeFileSync(launcherPath, `#!/bin/sh\nexec "${nodeBin}" "${setupJs}" "$@"\n`);
-      chmodSync(launcherPath, 0o755);
-
-      // Register with LaunchServices
-      try {
-        execSync(`/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -R "${resolve(homedir(), '.synabun', 'SynaBun.app')}"`, { stdio: 'pipe' });
-      } catch {
-        try { execSync(`open "${resolve(homedir(), '.synabun', 'SynaBun.app')}"`, { stdio: 'pipe' }); } catch {}
-      }
-
-      ok('Registered synabun:// protocol handler');
-    } catch {
-      warn('Could not register synabun:// protocol handler');
-    }
-  } else {
-    // Linux — .desktop file
-    try {
-      const appsDir = resolve(homedir(), '.local', 'share', 'applications');
-      mkdirSync(appsDir, { recursive: true });
-
-      writeFileSync(resolve(appsDir, 'synabun.desktop'), [
-        '[Desktop Entry]',
-        'Type=Application',
-        'Name=SynaBun',
-        `Exec="${nodeBin}" "${setupJs}" %u`,
-        'MimeType=x-scheme-handler/synabun;',
-        'NoDisplay=true',
-        'Terminal=true',
-        '',
-      ].join('\n'));
-
-      try { execSync('xdg-mime default synabun.desktop x-scheme-handler/synabun', { stdio: 'pipe' }); } catch {}
-
-      ok('Registered synabun:// protocol handler');
-    } catch {
-      warn('Could not register synabun:// protocol handler');
-    }
-  }
+  const result = registerStartLauncher({ packageRoot: __dirname });
+  if (result.state === 'skipped') return;
+  if (result.ok) ok('Registered synabun:// protocol handler');
+  else warn(`Could not register synabun:// protocol handler (${result.errors[0]})`);
 }
 
 // ── Updater shim executable bit ──

package/setup.js

@@ -44,6 +44,10 @@ import {
   protectFirstLaunchAfterUpdate,
   recordLauncherFailure,
 } from './lib/first-launch-protection.js';
+import {
+  RESTART_REPORT_ENV, noteSupervisorFailure, openRestartReport, openSupervisorRecord, registerStartLauncher, resolvePort,
+} from './lib/start-launcher.js';
+import { packagedRuntime } from './lib/packaged-runtime.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -76,6 +80,25 @@ const DATA_HOME = REQUESTED_DATA_HOME_DIAGNOSTICS.dataHomeInsidePackage
 process.env.SYNABUN_DATA_HOME = DATA_HOME;
 process.env.MEMORY_DATA_DIR = resolve(DATA_HOME, 'mcp-data');
 
+// What this start is doing, written where the Start Server launcher reads it
+// (DATA_HOME/data/supervisor.json): the offline page that asked for the start
+// has no server to ask, and shows these phases instead of a guess. Each phase
+// is noted when it begins. Opened in main(), once the data home is settled.
+let supervisor = null;
+// A restart reports the same phases on the start beacon while the server is
+// away (lib/start-launcher.js openRestartReport): the page that asked for it
+// is waiting, with no server to ask. Open only while a restart lasts.
+let restartReport = null;
+// Set by a server that had no supervisor, on the one it starts to take its
+// place after a restart. This process only: nothing it starts inherits it.
+const STARTED_FOR_RESTART = !!process.env[RESTART_REPORT_ENV];
+delete process.env[RESTART_REPORT_ENV];
+const startPhase = (name, detail) => {
+  try { supervisor?.phase(name, detail); } catch {}
+  try { restartReport?.phase(); } catch {}
+};
+const startFailed = (code, message, extra = {}) => { try { supervisor?.fail({ code, message, ...extra }); } catch {} };
+
 // ── Migration: move legacy in-repository state to the platform data home ──
 
 function looksLikeSynabunCheckout(root) {
@@ -235,6 +258,16 @@ function handleDoctorCommand() {
   console.log('');
 }
 
+// The offline page's Start Server button hands the OS a synabun:// link. Keep
+// the handler pointing at this install: a GitHub checkout never ran the npm
+// postinstall, and node or the package may have moved since it did.
+function ensureStartLauncher() {
+  const result = registerStartLauncher({ packageRoot: PACKAGE_ROOT });
+  if (result.state === 'skipped') return;
+  if (!result.ok) warn(`Could not register the Start Server launcher: ${result.errors[0]}`);
+  else if (result.changed) ok('Start Server launcher registered (synabun://)');
+}
+
 function repairClientConfigs() {
   try {
     const result = auditAndRepairClientConfigs({ dataHome: DATA_HOME, packageRoot: PACKAGE_ROOT, apply: true });
@@ -279,6 +312,7 @@ function installDeps(name, dir, { includeDev = false } = {}) {
   }
 
   info(`Installing ${name} dependencies...`);
+  startPhase('dependencies', { name });
   try {
     const omitFlag = includeDev ? '' : ' --omit=dev';
     execSync(`npm install${omitFlag} --ignore-scripts`, {
@@ -290,6 +324,7 @@ function installDeps(name, dir, { includeDev = false } = {}) {
   } catch (err) {
     fail(`Failed to install ${name} dependencies`);
     console.error(err.stderr?.toString() || err.message);
+    startFailed('DEPENDENCIES_FAILED', `npm could not install the ${name} dependencies`);
     process.exit(1);
   }
 }
@@ -309,6 +344,7 @@ function installPlaywrightChromium() {
   } catch { /* not installed */ }
 
   info('Installing Playwright Chromium (for browser automation)...');
+  startPhase('browser');
   try {
     execSync('npx playwright install chromium', {
       cwd: niDir,
@@ -335,10 +371,12 @@ function buildMcpServer() {
   }
 
   info('Building MCP server from source...');
+  startPhase('build');
   try {
     execSync('npx tsc', {
       cwd: resolve(PACKAGE_ROOT, 'mcp-server'),
       stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: !!packagedRuntime(),
       timeout: 120_000,
     });
     ok('MCP server built');
@@ -445,14 +483,25 @@ function startServer() {
   let firstLaunch = true;
   let currentChild = null;
   let shuttingDown = false;
+  // The port the server last said it listens on: where a restart's report is read.
+  let listenPort = null;
   const restartLog = [];
   const CRASH_WINDOW_MS = 60_000;
   const CRASH_LIMIT = 5;
 
+  // A restart that ends without a server keeps saying why until the page that
+  // waits for it has read it (a moment; 20 s at the most when nobody reads).
+  const exitAfterReport = (code, error) => {
+    const report = restartReport;
+    if (!report?.open) { process.exit(code); return; }
+    report.failed(error).finally(() => process.exit(code));
+  };
+
   function spawnOnce() {
-    const child = spawn('node', ['--disable-warning=ExperimentalWarning', '--max-old-space-size=6144', serverPath], {
+    const child = spawn(process.execPath, ['--disable-warning=ExperimentalWarning', '--max-old-space-size=6144', serverPath], {
       cwd: niDir,
       stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: !!packagedRuntime(),
       env: {
         ...process.env,
         SYNABUN_DATA_HOME: DATA_HOME,
@@ -461,17 +510,32 @@ function startServer() {
       },
     });
     currentChild = child;
+    startPhase('server', { pid: child.pid });
+    child.on('error', (error) => {
+      fail(`Could not start the server: ${error.message}`);
+      startFailed('SERVER_SPAWN_FAILED', `the server could not be started: ${error.message}`);
+      exitAfterReport(1, { code: 'SERVER_SPAWN_FAILED', message: `the server could not be started: ${error.message}` });
+    });
 
     let opened = !firstLaunch;
+    let announced = false;
     child.stdout.on('data', (data) => {
       const s = data.toString();
       process.stdout.write(s);
       try { outLog?.write(s); } catch {}
+      // The server prints its address from its listen callback: it is up.
+      if (!announced && s.includes('Server:')) {
+        announced = true;
+        const port = Number(s.match(/Server:\s+http:\/\/localhost:(\d+)/)?.[1]) || undefined;
+        if (port) listenPort = port;
+        startPhase('listening', { port });
+      }
       if (!opened && s.includes('Server:')) {
         opened = true;
         const port = s.match(/Server:\s+http:\/\/localhost:(\d+)/)?.[1] || '3344';
         const url = `http://localhost:${port}${setupComplete ? '/' : '/onboarding.html'}`;
-        setTimeout(() => openBrowser(url), 1500);
+        // The Start Server button already has a tab waiting for the server.
+        if (process.env.SYNABUN_OPEN_BROWSER !== '0') setTimeout(() => openBrowser(url), 1500);
       }
     });
     child.stderr.on('data', (data) => {
@@ -499,9 +563,16 @@ function startServer() {
         const now = Date.now();
         restartLog.push(now);
         while (restartLog.length && now - restartLog[0] > CRASH_WINDOW_MS) restartLog.shift();
+        // The page that asked for this has no server to ask now: from here
+        // until the new one is listening, this supervisor says what happens.
+        try { restartReport?.close(); } catch {}
+        restartReport = openRestartReport({ port: listenPort || resolvePort({ dataHome: DATA_HOME }), dataHome: DATA_HOME, exited: true });
         if (restartLog.length > CRASH_LIMIT) {
+          const message = `the server restarted ${restartLog.length} times in ${Math.round(CRASH_WINDOW_MS / 1000)} s`;
           fail(`Server restarted ${restartLog.length} times in ${Math.round(CRASH_WINDOW_MS / 1000)}s — aborting supervisor.`);
-          process.exit(1);
+          startFailed('RESTART_LOOP', message);
+          exitAfterReport(1, { code: 'RESTART_LOOP', message });
+          return;
         }
         firstLaunch = false;
         setTimeout(spawnOnce, 250);
@@ -510,7 +581,9 @@ function startServer() {
 
       if (code !== 0 && code !== null) {
         fail(`Server exited with code ${code}`);
-        process.exit(code);
+        startFailed('SERVER_EXITED', `the server exited with code ${code}`, { exitCode: code });
+        exitAfterReport(code, { code: 'SERVER_EXITED', message: `the server exited with code ${code}`, exitCode: code });
+        return;
       }
       process.exit(0);
     });
@@ -740,32 +813,60 @@ async function main() {
   // Inspect and migrate before creating empty destination directories. A
   // divergent pair stops normal launch without overwriting either root.
   const preflight = preflightDataHome();
-  if (preflight.status === 'conflict') process.exit(2);
+  if (preflight.status === 'conflict') {
+    noteSupervisorFailure(DATA_HOME, {
+      code: 'DATA_HOME_CONFLICT',
+      message: 'SynaBun found different user state in two locations and stopped before changing either. Run "synabun doctor".',
+      exitCode: 2,
+    });
+    process.exit(2);
+  }
 
   // Ensure data directories
   ensureDataDirs(DATA_HOME);
 
+  // From here until this process exits a start is under way: the Start Server
+  // launcher reads this record so a second click never starts a second one,
+  // and passes what it says on to the page that is waiting.
+  supervisor = openSupervisorRecord(DATA_HOME);
+  process.on('exit', supervisor.release);
+  // Taking the place of a server that restarted without a supervisor: the
+  // pages that asked are waiting, so this start says what it is doing.
+  if (STARTED_FOR_RESTART) {
+    restartReport = openRestartReport({ port: resolvePort({ dataHome: DATA_HOME }), dataHome: DATA_HOME });
+  }
+
   // Prerequisites
   checkNodeVersion();
   console.log('');
 
   // Dependencies (installed in global package location)
+  // A slow step names itself when it begins (startPhase inside each); between
+  // them the record goes back to 'checking', so it never names a finished one.
   installDeps('Neural Interface', resolve(PACKAGE_ROOT, 'neural-interface'));
   installDeps('MCP Server', resolve(PACKAGE_ROOT, 'mcp-server'), { includeDev: needsBuild() });
+  startPhase('checking');
   console.log('');
 
   // Playwright browser
   installPlaywrightChromium();
+  startPhase('checking');
   console.log('');
 
   // Build
   buildMcpServer();
+  startPhase('checking');
   console.log('');
 
   // A new version never runs on user state that has no verified snapshot. When
   // the snapshot cannot be created the launch stops here, before the server
   // (and any data migration) starts. There is no flag to launch anyway.
-  const protection = await protectFirstLaunchAfterUpdate({ dataHome: DATA_HOME, version, log: { info, ok, warn } });
+  const protection = await protectFirstLaunchAfterUpdate({
+    dataHome: DATA_HOME,
+    version,
+    log: { info, ok, warn },
+    onProgress: (detail) => startPhase('snapshot', { version, ...detail }),
+  });
   if (protection.status === 'failed') {
     const failure = describeSnapshotFailure({ ...protection, dataHome: DATA_HOME, version });
     // Server logging has not begun, and a detached launch (the updater's
@@ -776,13 +877,16 @@ async function main() {
     for (const line of failure.lines) info(line);
     if (logPath) info(`This message is also in: ${logPath}`);
     console.log('');
+    startFailed('SNAPSHOT_FAILED', failure.headline, { exitCode: SNAPSHOT_FAILED_EXIT_CODE });
     process.exit(SNAPSHOT_FAILED_EXIT_CODE);
   }
+  startPhase('checking');
   console.log('');
 
   // Existing registrations can carry checkout-local DOTENV_PATH and data-home
   // overrides. Rewrite only their SynaBun entry after the new MCP build exists.
   repairClientConfigs();
+  ensureStartLauncher();
   console.log('');
 
   // State
@@ -800,5 +904,6 @@ async function main() {
 main().catch(error => {
   fail(error.message);
   recordLauncherFailure({ dataHome: DATA_HOME, exitCode: 1, headline: `SynaBun did not start: ${error.message}` });
+  startFailed('SETUP_FAILED', error.message);
   process.exit(1);
 });

package/benchmarks/browser-live-results.json

@@ -1,79 +0,0 @@
-{
-  "generatedAt": "2026-09-08T03:59:21.092Z",
-  "transport": "configured SynaBun browser HTTP engine",
-  "scope": "Updated snapshot/content/extraction algorithms over SynaBun engine adapter; read-only live pages. New route wiring covered separately by local Express tests.",
-  "results": [
-    {
-      "group": "general",
-      "url": "https://example.com/",
-      "status": "passed",
-      "finalUrl": "https://example.com/",
-      "title": "Example Domain",
-      "snapshotChars": 298,
-      "captures": 1,
-      "scopedHtmlChars": 220,
-      "extractedLinks": 1,
-      "durationMs": 8361
-    },
-    {
-      "group": "general",
-      "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array",
-      "status": "passed",
-      "finalUrl": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array",
-      "title": "Array - JavaScript | MDN",
-      "snapshotChars": 5965,
-      "captures": 2,
-      "scopedHtmlChars": 91581,
-      "extractedLinks": 10,
-      "durationMs": 8384
-    },
-    {
-      "group": "general",
-      "url": "https://en.wikipedia.org/wiki/Web_browser",
-      "status": "passed",
-      "finalUrl": "https://en.wikipedia.org/wiki/Web_browser",
-      "title": "Web browser - Wikipedia",
-      "snapshotChars": 5982,
-      "captures": 2,
-      "scopedHtmlChars": 403828,
-      "extractedLinks": 10,
-      "durationMs": 3207
-    },
-    {
-      "group": "social",
-      "url": "https://bsky.app/",
-      "status": "passed",
-      "finalUrl": "https://bsky.app/",
-      "title": "Discover — Bluesky",
-      "snapshotChars": 1823,
-      "captures": 1,
-      "scopedHtmlChars": 87619,
-      "extractedLinks": 10,
-      "durationMs": 2596
-    },
-    {
-      "group": "social",
-      "url": "https://www.youtube.com/",
-      "status": "passed",
-      "finalUrl": "https://www.youtube.com/",
-      "title": "YouTube",
-      "snapshotChars": 5999,
-      "captures": 2,
-      "scopedHtmlChars": 576986,
-      "extractedLinks": 10,
-      "durationMs": 4583
-    },
-    {
-      "group": "social",
-      "url": "https://x.com/explore",
-      "status": "passed",
-      "finalUrl": "https://x.com/explore",
-      "title": "Explorar / X",
-      "snapshotChars": 318,
-      "captures": 1,
-      "scopedHtmlChars": 4936,
-      "extractedLinks": 1,
-      "durationMs": 1802
-    }
-  ]
-}