synabun 2.0.0-beta → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synabun",
-  "version": "2.0.0-beta",
+  "version": "2.0.0",
   "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",
@@ -87,6 +92,13 @@
     "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",
+    "test:packaging": "node --test packaging/tests/*.test.mjs",
     "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"

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,8 @@ import {
   protectFirstLaunchAfterUpdate,
   recordLauncherFailure,
 } from './lib/first-launch-protection.js';
+import { noteSupervisorFailure, openSupervisorRecord, registerStartLauncher } from './lib/start-launcher.js';
+import { packagedRuntime } from './lib/packaged-runtime.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -76,6 +78,14 @@ 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;
+const startPhase = (name, detail) => { try { supervisor?.phase(name, detail); } 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 +245,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 +299,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 +311,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 +331,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 +358,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');
@@ -450,9 +475,10 @@ function startServer() {
   const CRASH_LIMIT = 5;
 
   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 +487,30 @@ 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}`);
+      process.exit(1);
+    });
 
     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;
+        startPhase('listening', { port: Number(s.match(/Server:\s+http:\/\/localhost:(\d+)/)?.[1]) || undefined });
+      }
       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) => {
@@ -501,6 +540,7 @@ function startServer() {
         while (restartLog.length && now - restartLog[0] > CRASH_WINDOW_MS) restartLog.shift();
         if (restartLog.length > CRASH_LIMIT) {
           fail(`Server restarted ${restartLog.length} times in ${Math.round(CRASH_WINDOW_MS / 1000)}s — aborting supervisor.`);
+          startFailed('RESTART_LOOP', `the server restarted ${restartLog.length} times in ${Math.round(CRASH_WINDOW_MS / 1000)} s`);
           process.exit(1);
         }
         firstLaunch = false;
@@ -510,6 +550,7 @@ function startServer() {
 
       if (code !== 0 && code !== null) {
         fail(`Server exited with code ${code}`);
+        startFailed('SERVER_EXITED', `the server exited with code ${code}`, { exitCode: code });
         process.exit(code);
       }
       process.exit(0);
@@ -740,32 +781,55 @@ 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);
+
   // 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 +840,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 +867,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/docs/browser-v2.md

@@ -1,109 +0,0 @@
-# Browser execution and efficiency
-
-SynaBun still uses its configured browser and the existing MCP tools. This change fixes action correctness and enables the faster browser path by default in version **2.0.0**, for general browsing and social automations.
-
-## Rollout
-
-Correctness fixes apply after the updated Neural Interface and MCP processes restart: compatible delivered snapshot baselines, cancellation/deadline handling, ref-aware publishing guards, caller/tab ownership checks, and protection against selectors changing targets during pacing.
-
-Performance changes are **on by default**; no opt-in variable is needed. After the updated Neural Interface and MCP processes restart, this enables bounded automatic snapshot capture, cached session routing, server-side paged extraction, omission of non-writing think pauses, and registration of `browser_batch`. Leave existing `SYNABUN_BROWSER_FAST`, `SYNABUN_BROWSER_COMPACT` and `SYNABUN_BROWSER_AUTOSNAPSHOT` settings as they are.
-
-For rollback, set `SYNABUN_BROWSER_V2=0` in the environment used by **both Neural Interface and its MCP processes**, then restart them normally. Remove that override to return to the new default. Correctness fixes remain enabled. No database migration or saved automation rewrite is required. This implementation does not change the running service's environment or restart active automations.
-
-Social engagement writes retain the existing randomized 30–90-second spacing, serialized within each browser session. It applies to the resolved target whether the caller uses refs or selectors. A blocked preflight does not consume a write slot; an attempted write with an uncertain outcome does. Typing cadence is preserved.
-
-## Interfaces and workflow
-
-- `browser_snapshot` accepts optional `baselineId` and returns a compact snapshot ID. A diff requires a compatible delivered observation from the same caller, page generation, scope, depth settings and budget. Removals are explicit. `force:true` requests a full view. Aborted requests never establish a baseline.
-- Navigation, click and scroll observations use the same budget at capture and formatting. Click defaults to 6,000 characters; navigation and scroll use 12,000; explicit snapshots retain 30,000. Truncation ends at complete lines. V2 automatic captures start at depth 12 and make at most one shallower retry; callers can override depth or scope to inspect deeper controls.
-- Playwright refs identify elements in its latest captured scope. A scoped snapshot can remove previously observed refs from that map. Re-snapshot when a ref is stale; do not assume every previously returned ref remains usable after another capture.
-- Paged `browser_extract_*` tools accept optional `fields` and `maxChars`. Identity deduplication occurs before projection; repeated identities update their fields. Results report stopping reasons and partial failures. Known loading states must finish before newly discovered items are accepted. FB group classification occurs before field projection.
-- `browser_content` accepts `selector` for one element's subtree with plain text or Markdown. Existing offsets and budgets remain supported. Missing/ambiguous scopes return an error. Relative source links are made absolute, and extraction does not modify the live DOM.
-- `browser_batch` accepts 1–10 `{tool,args,observe?}` steps, one `sessionId`/`tabId`, and final `snapshot:full|diff|none` (default `full`). It invokes the existing guarded tool handlers sequentially, validates every step before acting, and returns completed outcomes if a later step fails. Steps cannot change routing or use arbitrary evaluation.
-
-### MoreLogin as the default browser
-
-While Browser Settings name MoreLogin as the default (`connectMode: "morelogin"`), every loop, schedule, dispatched run, recovery and interactive acquisition drives the default MoreLogin profile (`moreloginEnvId`). Reuse and a caller-requested session count only when the session is MoreLogin on that exact env. If MoreLogin cannot be reached after the auto-launch wait, the run fails and its log, `lastRunResult` and the `schedule:failed` toast carry the reason (`Could not start the shared browser session: MoreLogin connect failed: …`). Nothing falls back to Chrome.
-
-The server decides which session may carry pages. `GET /api/browser/sessions` reports `servesDefault` per session and `defaultBrowser` for the list: with MoreLogin as the default only a MoreLogin session on the default env serves it; in managed and real-Chrome setups every session does, so nothing changes there. The MCP requires `servesDefault` for every page tool (navigations, localhost included, platform tools, screenshots, snapshots, content, console, clicks, typing, batches) and a run's pinned browser. A pinned session that does not serve the default fails the call with the reason. Navigations and platform tools drop an explicit id that does not serve it, then resolve the default browser; any other page tool refuses it (`Browser session <id> is not the default browser (…), so SynaBun's browser tools do not act on it`), since the page it names is in the other browser. The server holds the same line at its REST boundary: an agent request (one that carries `X-Synabun-Terminal`, as every MCP call does) on a session that does not serve the default is refused with 409 `NOT_DEFAULT_BROWSER` before anything runs, for any page action, a new tab or CDP; closing the session or a tab and listing its tabs stay allowed, and the Neural Interface's own UI (no header) keeps working with any session. Every `/api/browser` response names the default browser in `X-Synabun-Browser-Default` (`morelogin:<env>`, `other:<mode>`, or `unreadable`), and the MCP keys its route caches on it, so a change of connect mode or MoreLogin env drops every cached route; the in-process MCP is told the moment the settings are saved, and a `NOT_DEFAULT_BROWSER` refusal also forgets the caller's cached route and tab. Affinity, auto-selection and adoption skip it. When Browser V2 recovery of a cached route fails, the action returns the recovery's own reason (for example `MoreLogin connect failed: …`) with `recoveryFailed: true`, not a bare "Session not found".
-
-`bluesky_*` tools renew an expired access token themselves. They wait for bsky.app to refresh it (a freshly initialized tab is still booting), then reload the assigned bsky.app tab at most once. "Not logged in" is reported only when the page holds no session. A token the server still rejects gets one renewal and one re-run, and only when nothing was written yet. The whole call has one 48 s deadline, under the roughly 60 s tool limit of OpenCode and Codex. Finding and opening the tab, the token checks, the reload and image uploads must end 12 s before it, so the request itself always has time. A step that runs out of time returns a clear error. A request that doesn't answer in time is reported as possibly finished (check before repeating) and is never retried.
-
-#### Localhost in MoreLogin
-
-Localhost pages open in the MoreLogin profile like any other page; nothing reroutes them to another browser. MoreLogin's per-profile **Port scan protection** decides which local ports load: a port listed under Edit profile → Advanced settings → Port scan protection (allowed ports, read when the profile starts) loads normally, and any other local port is redirected to `getip.morelogin.com/black_whiteList_stop_page_v2.html?blockedUrl=<url>`. Keep protection on and list the dev-server ports (P-1 allows 3344, 3100, 3210, 3917, 9003 and 9017), then restart the profile. A blocked navigation, back, forward or click fails with `moreLoginBlocked: true` and the stop page's URL, and, for a local port, the error is `MoreLogin blocked localhost:<port>. Most likely the profile's Port scan protection: add <port> to its Advanced settings → Port scan protection allowed ports in MoreLogin. If a URL Access Restriction in MoreLogin's Security Center blocks localhost, remove localhost from that block policy. Then restart the profile.` (other hosts keep the website-whitelist message). A session created at a blocked URL is still created and says so (`moreLoginBlocked`, `notice`). `/api/morelogin/status` counts observed blocks (`blockedNavigations`, `lastBlockedUrl`). The earlier loopback sidecar (system Google Chrome on the leftover `userDataDir`), its page-level handoff and `LOOPBACK_ONLY_SESSION` are gone.
-
-#### Screenshots for visual QA
-
-`browser_screenshot` (`GET /api/browser/sessions/:id/screenshot-base64`, `lib/browser-screenshot.js`) returns the tab as an image, localhost included. Without options it is the viewport as JPEG (quality 60), downscaled to `maxWidth` (default 1024 px of real pixels; `0` = native resolution). Options:
-
-- `width` / `height` (100–4096 CSS px): the viewport for this capture only, as a CDP `Emulation.setDeviceMetricsOverride` (`deviceScaleFactor: 1`, `mobile` below 768 px) sent from a CDP session opened for the capture. Chromium keeps one override per page and a detach alone leaves it in place, so it is always cleared with `Emulation.clearDeviceMetricsOverride`, on errors and timeouts too, and then confirmed: the tab's `innerWidth` and `devicePixelRatio` must equal what they were before the capture. A clear that fails, hangs (2 s) or does not take is sent once more from a fresh CDP session, which first sets an empty override (0 width, height and scale), because Chromium ignores a clear from a session that never set one. A tab still not confirmed is closed (its session's other tabs stay; the only tab's page is closed and the next call opens a fresh one) and the result says so (`tabClosed: true` and a `notice`, or the notice appended to the error), so a MoreLogin tab never keeps a window size, DPR or mobile flag its profile does not have.
-- `fullPage`: the whole document (`captureBeyondViewport`, up to 16384 px; longer pages report `truncated`).
-- `format` (`png` | `jpeg`): the returned image is a JPEG unless PNG is asked for; a saved file is a PNG unless JPEG is asked for (saved JPEG quality 90).
-- `save` / `path`: also write the full-resolution image and return `savedPath`. The default file is `~/.synabun/data/media/screenshots/<yyyy-mm-dd>/<host>-<width>x<height>-<hhmmss>.png` (never an existing file). An explicit `path` must be absolute, end in .png, .jpg or .jpeg, and lie inside a registered project (`claude-code-projects.json`, never one at or above the home folder) or the screenshots folder, resolved through symlinks; parent folders are created, and only an existing PNG or JPEG is ever replaced. The file is checked again as it is written (a capture can take up to a minute): the parent's real path must still lie inside those folders, a symlink or a non-image at the name is refused, the bytes go to a temp file created `O_CREAT | O_EXCL | O_NOFOLLOW` in that real folder, the folder's real path is read again, and a rename puts it in place (a rename replaces a symlink, it never follows one). `savedPath` is the real path written.
-
-The returned image never exceeds 7900 px on a side. Its size is measured from a small capture of the same CDP session, not taken from the page's `devicePixelRatio` (a fingerprint value in MoreLogin). The MCP client waits the long timeout (30 s) for it. A saving screenshot is not a read-only call for plan mode and remote read-only sessions (`lib/assistant-plan-permissions.js`).
-
-#### Console and page errors
-
-`browser_console` (`GET /api/browser/sessions/:id/console?tabId=&level=&since=&limit=&clear=`, `lib/browser-console.js`) reads a per-page ring buffer of the last 200 console messages (`{ kind: "console", level, type, text, location, at }`, network errors such as a 404 script included) and uncaught page errors (`{ kind: "pageerror", level: "error", message, stack, at }`). The buffer is attached before the first navigation of every tab SynaBun registers (a new session, MoreLogin attach included, a new tab, a recovered tab) and follows their popups; attaching twice is a no-op. A popup is not a tab of its session, so its entries come back with the tab that opened it, each with `popup: <the popup's URL at the time>` and in the order they happened (the last 5 popups of a tab, popups of popups too; `popups` counts them, and `clear` empties them with the tab). The MCP shows them as `[popup <url>]`. `level` (`all` | `error` | `warning` | `info` | `log`) keeps that level and the more severe ones; `since` (ISO or epoch ms, e.g. the `latest` of the previous read) keeps newer entries; `limit` (1–200, default 50) returns the newest matches; `clear` empties the buffer after reading. The console arguments' JS handles are released as each message arrives, so a chatty page pins nothing. A tab registered before the buffer existed starts recording on its first read (`attached: false`).
-
-#### Browser settings file
-
-`browser-config.json` is written atomically (a temp file renamed over it). `loadBrowserConfig()` keeps the text of the last good read or write: when the file is torn, unparsable or not a JSON object it returns that config (logging a warning once per failure streak, then at most once a minute) instead of `{}`, which used to switch MoreLogin mode off for whatever read it at that moment. A missing file is `{}` (the defaults). A file that exists but has never been read well (no earlier good config) is not treated as unconfigured: `loadBrowserConfig()` returns `{}` marked unreadable, `createBrowserSession` refuses with `browser-config.json is unreadable; fix it in Settings → Browser (<reason>)` instead of taking the Chrome path, `GET /api/browser/config` adds `configError`, and saving the settings in Settings → Browser replaces the file.
-
-### Jev assistance (advisory)
-
-Three TypeSafe surfaces (`browser-page-state`, `browser-target`, `browser-social`; full contract in `docs/judgments.md`) add a typed reading of the page to the tools above. It is text only, bounded, and never part of the control flow: with TypeSafe off, a surface off, a timeout or a rate limit, every tool answers exactly as it did before.
-
-- `browser_navigate` accepts optional `intent`. One line may follow the snapshot: `Jev assessment: authentication_required (94%) — pause for human sign-in`. A blocker (`authentication_required`, `verification_required`, `consent_blocker`) means stop and hand over to the human; `loading` means wait and inspect again; a consent dialog is never dismissed automatically. With an `intent`, the line also says whether the page already satisfies it.
-- `browser_snapshot` accepts optional `intent` in AI mode and may append `Jev target: ref e12 "Account settings" (choice 91%, match 96%); alternatives: e15, e31`, or `no candidate qualified`. The refs come from the same capture that was delivered, so the recommendation is a fresh ref. It never executes.
-- A failed or ambiguous `browser_click`, `browser_fill`, `browser_type`, `browser_hover`, `browser_select` or `browser_upload` (the last two now accept `textHint`) returns its usual hints, reordered and annotated with each candidate's risk class when Jev found a confident match. Shadow mode sends no second request: the caller decides and acts with a new call.
-- An empty social extractor keeps its message verbatim as the first line and appends a diagnosis: genuinely empty, still loading, wrong surface, sign-in, verification, consent, or a rendered error. Populated output is byte-identical.
-- `browser_fb_composer_state` and `browser_x_compose_state` add a `judgment` key only when the probe itself is ambiguous. `recommendedAction`, `boostRisk` and the locale lists stay authoritative; a suggested control is a suggestion, and Boost / Promote controls are removed before Jev sees the options.
-- Inside `browser_batch` there is no assistance at all. A batch that navigated gets one `assessment` of its final page after it ends; steps are never added, replaced or replayed.
-
-**The one-retry invariant.** Safe auto-heal is off and locked until the browser benchmark passes for the exact running configuration (Settings → AI decisions → Browser assistance). When armed it permits exactly one retry, only for `browser_click`, only when the selector matched nothing or failed to parse, and only onto a plain same-origin navigation link that the server re-verifies on the element it is about to click. It never follows `actionStarted:true`, an uncertain outcome, a transport error, a cancellation or a guard; it never types, submits, publishes, likes, follows, pays, uploads or changes a toggle; a refused, failed or uncertain heal is final. A healed click says so in its result, `(auto-healed via Jev to "Pricing": choice 93%, match 97%; selector … matched nothing)`, and the route's body carries `autoHealed:true`.
-
-Page text is adversarial data. It reaches Jev only as `state`, never inside an instruction, and a control whose label addresses the agent disqualifies the whole page from healing.
-
-Use extraction for data and scoped snapshots for interaction. Choose fields needed by the task instead of returning avatars/media URLs by default. Use a batch only when the selectors and sequence are already known; otherwise inspect between actions. A local form example, after observing its selectors:
-
-```json
-{
-  "steps": [
-    {"tool":"browser_fill","args":{"selector":"#email","value":"fixture@example.invalid"}},
-    {"tool":"browser_click","args":{"selector":"#save"}}
-  ]
-}
-```
-
-Tool names inside batches are the unprefixed names shown above. Call the batch itself using the exact host-provided MCP name. Host cancellation stops pending HTTP calls and prevents subsequent batch steps. Never replay a whole batch or an uncertain click; inspect the current state first.
-
-## Metrics and measurements
-
-Set `SYNABUN_BROWSER_METRICS=1` on the same processes for diagnostic JSON on stderr. Client and server correlate with `X-Synabun-Request-Id` and share an absolute `X-Synabun-Deadline`. Records contain timings, operation names, response sizes and estimated tokens, without URLs, page text, selectors, scripts, form values or credentials. Intentional pacing is reported separately from processing. Metrics are disabled by default.
-
-The local benchmark behind these numbers uses isolated Chromium fixtures, no user profiles or external requests, alternates variant order, and runs at least 20 samples per variant for articles, search, dynamic forms, feeds, composers and virtualized extraction. Its report holds cold startup and per-scenario median/p95 processing time, required-data assertions, captures, response bytes and text-token estimates: [browser-v2-results.json](../benchmarks/browser-v2-results.json).
-
-The final measured run reduced the sum of scenario median processing times by about **78%**, and estimated output text tokens by **23%**. The largest change was virtualized extraction (about 1.8 seconds to 0.2 seconds for three items). Dense snapshots went from four captures to two. All required fixture data was retained. Optional field projection accounts for the measured output-token saving; it is not an automatic saving on every call.
-
-Deferred full-profile server instructions use concise capability summaries instead of repeating the entire tool catalog: **5,289 → 3,219 characters**, approximately **39% less instruction text** (~1,323 → ~805 estimated tokens). Legacy profiled-host instructions remain identical. This separate instruction measurement is not included in the 23% response-token result, and does not measure provider billing or how frequently a particular host injects instructions.
-
-These are component measurements, not full MCP/provider automation measurements. HTTP call counts in this fixture report are derived from the implementation, not network instrumentation. Deliberate social write delays and model reasoning time are excluded. Estimates are not provider-billed tokens. The provisional 30% output-token target remains an optimization goal rather than a release blocker. The measured processing and instruction reductions, full automated suites, and read-only real-page checks support the default rollout with an explicit rollback switch. Live checks exercise the updated algorithms through an adapter to the configured SynaBun browser; changed route wiring and mutating actions are verified separately using local Express/Chromium fixtures. They do not establish real-site publishing success, and no live posting is used for validation.
-
-## Validation
-
-The figures below are from the validation run of this change in September 2026. The suites that ship with 2.0.0 are larger.
-
-- Complete Node suite: **520 passed, 0 failed, 1 Windows-only skip**; includes four live Claude bridge scenarios.
-- Complete MCP suite: **130 passed, 0 failed**, including compiled Codex discovery of `browser_batch` with no opt-in.
-- All five local browser/UI suites: **19 passed**, including memory maintenance and sidepanel windows.
-- The MCP test command invokes Vitest through Node, so a launcher file that is not executable does not break it.
-- Real-page checks use a new test tab for each site, scoped snapshots/content and projected extraction without posting. Results and their transport limitations are recorded in [browser-live-results.json](../benchmarks/browser-live-results.json).
-
-
-- Node tests exercise cancellation, actual write spacing, selector ambiguity/identity, snapshot delivery and diffs, extraction completeness, browser recovery and policy contracts.
-- MCP Vitest tests exercise routing isolation, one safe pre-execution recovery, no ambiguous replay, cancellation, batch validation/partial outcomes, extraction projection and snapshot formatting.
-- Browser-driven suites, which are not part of this package, exercise the installed Playwright/Chromium against local fixtures and real Express route handlers. They cover live refs, deletions, reloads, truncation, background-frame deadlines, foreign-tab rejection, guarded publishing, cancelled clicks, replaced targets and hydration before extraction. macOS sandboxed runners may need permission to launch Chromium and bind loopback.
-- `npm run build` in `mcp-server` compiles the implementation and its generated runtime files.

package/docs/hook-integrity.md

@@ -1,89 +0,0 @@
-# Hook identity, state, and measurement
-
-SynaBun has 10 executable hook scripts with 11 registrations covering nine Claude Code events. The canonical
-definitions live in `lib/claude-hooks.js`. Every settings scope gets the same
-handler command, matcher, and timeout. Claude Code can therefore deduplicate
-the handler for each event even when both project and global hooks are installed.
-
-The command resolves a SynaBun checkout from the current project (including
-subdirectories), then falls back to the installer-managed `SYNABUN_HOOK_ROOT`.
-The tracked template contains no machine-specific root. Server startup repairs
-recognized old commands in global settings and registered projects' settings
-and local settings. Other handlers, including plugins, retain their own behavior.
-Repairing one settings file without the other can temporarily retain duplicate
-execution; no event is suppressed by a guessed identity or a marker file.
-
-## State integrity
-
-- `post-plan` and MCP `remember` use the same transactional writer. A plan's
-  retry key includes its project, canonical source path, and content hash.
-  Concurrent retries return the same UUID. An edited plan gets a new entry.
-- A verified old plan receipt can acquire a retry key without copying its row.
-  Stop records a retry count, never a successful receipt before storage succeeds.
-- Short JSON read–modify–write operations are serialized with SQLite's writer
-  lock in `data/hook-state-lock.sqlite`. JSON replacement is atomic. The
-  coordination database contains no memories; process death releases its lock.
-- Compaction flags carry a session ID and generation. The matching conversation
-  remember must carry `source_ref: synabun-compaction:<session>:<generation>`.
-  Hook instructions supply this value. Legacy generationless flags can only be
-  cleared by their own session. An old completion cannot clear a new generation.
-
-Runtime state resides under `SYNABUN_DATA_HOME` (normally `~/.synabun`). Existing
-memory rows are not deleted by this repair.
-
-## Recall admission
-
-Hybrid `score` remains a ranking value, preserving compatibility. Retrieval also
-exposes `semantic_score`, `passage_score`, `keyword_coverage`, and `fusion_score`.
-An absent channel value means that channel was not measured or did not qualify;
-it is not a zero or a probability.
-
-Automatic injection requires document or passage similarity of at least 0.4.
-Explicit recall can still retrieve keyword-only evidence such as error codes.
-Short referential questions such as “is there a better setting for that?” do not
-start another automatic search. Repeatedly supplied evidence produces no new
-context. MiniLM and its existing vectors are retained.
-
-## Reproducible accounting
-
-From the repository root:
-
-```sh
-node scripts/audit-claude-hook-usage.mjs --since 2026-09-14T06:27:59.243Z --until 2026-09-15T06:27:59.243Z --output benchmarks/hook-repair-usage-24h.json
-node scripts/audit-memory-duplicates.mjs --output benchmarks/hook-repair-duplicate-candidates.json
-```
-
-Usage records are deduplicated by API message ID. Uncached input, cache writes,
-cache reads, and output remain separate. Payloads retain request provenance,
-Unicode character counts, UTF-8 byte counts, image counts, and hashes. The join
-to the next recorded request does not prove subsequent retention or billing.
-Unknown component token counts are `null`, never character-based estimates.
-
-The duplicate audit is read-only. Exact hashes and near-duplicate candidates
-include UUIDs and metadata for review; they are not deletion instructions.
-
-For an isolated provider measurement, supply a transcript containing an exact
-duplicate SynaBun SessionStart block:
-
-```sh
-node scripts/measure-claude-hook-overhead.mjs --run --transcript /path/to/session.jsonl --output benchmarks/hook-repair-provider-measurement.json
-```
-
-This runs four short Claude requests: two reversed-order pairs with identical
-system/user text and the recorded context. Only temporary fixture hooks run;
-tools and MCP servers are disabled. It also checks native handler multiplicity.
-
-The September 15, 2026 probe used `claude-sonnet-5` and a 525-character recorded
-startup block. Legacy registrations ran SessionStart, UserPromptSubmit, and Stop
-twice each; canonical registrations ran them once each. Both pairs measured
-**940 versus 748 input tokens: 192 tokens removed per startup fixture**. This is
-not an attribution of historical account-wide usage or every hook's token cost.
-
-## Watchdogs and rollout
-
-Both sidepanel engines use `high: 120s`, `xhigh: 300s`, `max: 300s`. Lower efforts
-retain the engine's existing default. Legacy retries retain their budget across
-respawns.
-
-After changing MCP code, build with `npm run mcp:build` and restart the Neural
-Interface server. A build alone leaves the running server's ESM imports cached.