synabun 2.0.0-beta → 2.0.0

package/CHANGELOG.md

@@ -25,6 +25,8 @@ SynaBun 2.0 adds a central Assistant that plans work and hands it to Claude Code
 - **Recall before subagents** — In Claude Code, a Task or Agent dispatch now starts from a shared memory brief (5 memories, 1,200 tokens), so workers begin with the paths, earlier fixes and constraints the session already knows. On by default.
 - **Claude accounts** — Several Claude accounts can be signed in side by side and chosen per session, the way Codex accounts already could.
 - **A new workspace tour** — The **?** button opens a hand-drawn tour of memory and the map, the whiteboard, coding tools, browser and automations, and the Assistant. It resumes where you left off, in English and Brazilian Portuguese.
+- **Start Server button** — When the server is down, the offline page and the app's Server Offline overlay show a **Start Server** button. It works on macOS, Windows and Linux, for npm and GitHub installs, starts one server however often it is clicked, and the page reconnects by itself when the server answers. While a start runs, the page names each step the launcher reports (installing dependencies, the browser download, the build, the pre-update backup, the server starting) next to a clock of whole seconds; a failed start shows its reason, the log's path and **Try again**. The command under the button is one line that works in cmd.exe, PowerShell and POSIX shells. A page opened through a tunnel, an invite link or a LAN address shows the clock and general status only.
+- **Command Runner as a searchable library** — Saved commands can be searched by name, command, group or directory, filtered by group, and sorted by saved order or most recently run. Commands on a local workspace stay runnable without an internet connection.
 
 ## 🛠 Fixed
 
@@ -42,12 +44,18 @@ SynaBun 2.0 adds a central Assistant that plans work and hands it to Claude Code
 - **Two ways around the X publish gate** — On loop tabs, `Cmd+Enter` and a scripted click on the post button skipped the publish gate and the write queue. Both are refused.
 - **BlueSky schedules stopped on an expired token** — The token is renewed in place, and every automation runs in the default MoreLogin profile.
 - **Session pills vanished when the toolbar collapsed** — They stay visible.
+- **Saved commands started about 15 seconds late** — The Command Runner waited for a prompt it could recognise, and the default macOS zsh prompt (`%`) was not on its list, so the command was typed by a 15-second fallback. A shell tab now gets the command as soon as its prompt is ready, and the terminal says so when a command could not be delivered. Claude Code, Codex, Gemini and OpenCode tabs keep their timing.
+- **The Settings save bar drifted into the middle of the page** — On a page with a save bar (Settings → Browser) the bar stays on the bottom edge of its column whether sections are open or closed, and its buttons stack in a narrow panel instead of being cut off.
+- **The Assistant mascot covered your message after a send** — The character now moves at once into the Thinking row under the message.
+- **Codex approvals with a policy choice** — When an approval offers a policy change (for example allowing a command from now on), the Assistant sends back exactly the choice Codex offered instead of only its label.
 
 ## ⚙️ Changed
 
 - **Plain semantic versioning** — 2.0.0 replaces the date-style versions on npm and on GitHub. The update check treats every date-style release as older than any 2.x release.
 - **The Assistant and its workers look at pages only through the SynaBun browser** — Public pages and `localhost` alike; ad-hoc Playwright, Puppeteer or headless browsers started from a shell are refused outside a project's own test suite.
 - **Hide all toolbars** — The top-right chevron now hides every toolbar, with a rebindable shortcut.
+- **Onboarding installs the rules** — Step 6 of the setup wizard is **Install SynaBun Rules**: **Install for all**, or **Install**, **Update** or **Replace** per tool, with the file each tool reads. Copying by hand remains only where SynaBun cannot write (Cursor's User Rules and the optional coexistence snippet), under **Manual setup**.
+- **Style Guide panel** — The header has a close button and wraps in a narrow panel, and each section is labelled for screen readers.
 - **Dependencies** — `@anthropic-ai/claude-agent-sdk` 0.3.258 → 0.3.288, `@openai/codex-sdk` 0.121 → 0.160, `@opencode-ai/sdk` 1.14 → 1.18.34 (pinned); `@xterm/headless` and `@xterm/addon-serialize` are new.
 - **Removed** — The legacy OpenCode sidepanel, the standalone Claude chat page, the 3D graphics presets, and `CLAUDE-template.md` (replaced by the installed rulesets).
 

package/THIRD-PARTY-LICENSES.md

@@ -129,3 +129,8 @@ information is in [NOTICE](./NOTICE). The
 `@anthropic-ai/claude-agent-sdk` lockfile metadata declares
 `SEE LICENSE IN README.md`; review the dependency's distributed README and
 license materials for its authoritative package-specific terms.
+
+Claude Code, Codex, OpenCode and Gemini CLI are not dependencies of SynaBun and
+are not distributed with it: the user installs them separately, under their
+publishers' terms. The agent SDKs listed above are installed without the
+executables they would otherwise carry (`lib/external-tools.js`).

package/launcher.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+/**
+ * SynaBun — start launcher
+ *
+ * What the operating system runs for a synabun://start link (the Start Server
+ * button on the offline page). Starts the server through the normal supervisor
+ * (setup.js) unless it already answers or a start is under way, then exits.
+ *
+ * Registered by lib/start-launcher.js; can also be run by hand:
+ *   node launcher.mjs
+ */
+
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BEACON_LINGER_MS, runLauncher } from './lib/start-launcher.js';
+
+const packageRoot = dirname(fileURLToPath(import.meta.url));
+
+try {
+  // The page that asked is offline and cannot ask a server how the start is
+  // going: the launch reports itself on its beacon, and keeps a failure
+  // readable there for a moment.
+  const result = await runLauncher({ argv: process.argv.slice(2), packageRoot, beacon: true, lingerMs: BEACON_LINGER_MS });
+  if (process.stdout.isTTY) {
+    const said = {
+      ignored: 'Nothing to do for that link.',
+      'already-running': `SynaBun is already running on port ${result.port}.`,
+      'already-starting': 'SynaBun is already starting.',
+      started: `SynaBun is running on port ${result.port}.`,
+      spawned: 'SynaBun is starting; it has not answered yet.',
+      failed: 'SynaBun could not be started. Run "npm start" in its folder to see why.',
+    }[result.outcome];
+    if (said) console.log(said);
+  }
+  process.exit(result.code);
+} catch (error) {
+  console.error(`SynaBun launcher: ${error.message}`);
+  process.exit(1);
+}

package/lib/claude-hooks.js

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 import { PACKAGE_ROOT } from './paths.js';
+import { durableEntry, packagedRuntime } from './packaged-runtime.js';
 
 // Handler identity must be byte-for-byte identical across settings scopes.
 // Claude Code deduplicates matching settings handlers before executing them.
@@ -32,14 +33,41 @@ export function hookDefinitionsForEvent(event) {
 // both cmd.exe and POSIX shells. Keep this versioned literal stable.
 const BOOTSTRAP = "const f=require('node:fs'),p=require('node:path'),u=require('node:url'),s=process.argv[1];let r;const ok=d=>{try{return JSON.parse(f.readFileSync(p.join(d,'package.json'),'utf8')).name==='synabun'&&f.existsSync(p.join(d,'hooks','claude-code',s))}catch{return false}};for(let d=p.resolve(process.env.CLAUDE_PROJECT_DIR||process.cwd());;d=p.dirname(d)){if(ok(d)){r=d;break}if(d===p.dirname(d))break}if(!r&&process.env.SYNABUN_HOOK_ROOT&&ok(process.env.SYNABUN_HOOK_ROOT))r=process.env.SYNABUN_HOOK_ROOT;if(!r)throw Error('SynaBun hook root unavailable; repair the hook installation');import(u.pathToFileURL(p.join(r,'hooks','claude-code',s)).href)";
 
-export function hookCommandString(scriptName) {
+/**
+ * A packaged application registers its own entry executable instead: the
+ * person has no Node of their own, and an IDE started by itself never sees the
+ * application's PATH. `<entry> claude-hook <script>` runs the handler with the
+ * Node that came with the application (packaging/runtime/bootstrap.mjs).
+ */
+export const PACKAGED_HOOK_MODE = 'claude-hook';
+
+// The entry inside the command's double quotes. A POSIX shell still reads
+// \ " $ ` there. A Windows path has no quote in it, and forward slashes keep
+// it one argument for cmd.exe and Git Bash alike.
+function quoteHookEntry(entry) {
+  if (/^[A-Za-z]:[\\/]|^\\\\/.test(entry)) return `"${entry.replace(/\\/g, '/')}"`;
+  return `"${entry.replace(/[\\"$`]/g, '\\$&')}"`;
+}
+
+const nodeHookCommand = scriptName => `node -e "${BOOTSTRAP}" ${scriptName}`;
+
+// Whatever entry wrote it: an application that moved must still find, and
+// repair, its own handlers.
+const PACKAGED_HOOK_COMMAND = new RegExp(`^"(?:[^"\\\\]|\\\\.)+"\\s+${PACKAGED_HOOK_MODE}\\s+(\\S+)$`);
+
+export function hookCommandString(scriptName, _targetProjectPath, runtime = packagedRuntime()) {
   if (!HOOK_SCRIPTS.some(h => h.script === scriptName)) throw new Error('Unknown SynaBun hook');
-  return `node -e "${BOOTSTRAP}" ${scriptName}`;
+  const entry = durableEntry(runtime);
+  return entry ? `${quoteHookEntry(entry)} ${PACKAGED_HOOK_MODE} ${scriptName}` : nodeHookCommand(scriptName);
 }
 
 export function isSynaBunHookCommand(command, scriptName) {
   if (typeof command !== 'string') return false;
-  if (command === hookCommandString(scriptName)) return true;
+  // Both canonical forms, whichever kind of install is reading: moving between
+  // an npm install and the application must not leave two handlers behind.
+  if (command === nodeHookCommand(scriptName)) return true;
+  const packaged = command.trim().match(PACKAGED_HOOK_COMMAND);
+  if (packaged) return packaged[1] === scriptName;
   // Recognize only the old direct-node path forms, including cross-OS installs.
   const match = command.trim().match(/^node\s+(?:"([^"]+)"|'([^']+)'|([^\s]+))\s*$/);
   if (!match) return false;
@@ -47,7 +75,32 @@ export function isSynaBunHookCommand(command, scriptName) {
   return script === `hooks/claude-code/${scriptName}` || script.endsWith(`/hooks/claude-code/${scriptName}`);
 }
 
-export function ensureHookRoot(settings, targetProjectPath, packageRoot = PACKAGE_ROOT) {
+/**
+ * Why this run must not write hook commands, or null when it may. A packaged
+ * application with no path that outlives the run (macOS started it from a
+ * temporary copy) would leave every handler pointing at nothing.
+ */
+export function hookInstallBlocker(runtime = packagedRuntime()) {
+  if (!runtime || durableEntry(runtime)) return null;
+  return 'SynaBun is running from a temporary location, so its hooks would stop working when it closes. Move SynaBun to its permanent place (Applications on macOS), open it again, then turn the hooks on.';
+}
+
+/**
+ * What a request to enable hooks may do in this run: 'write' them, 'refuse'
+ * it, or 'register-only'. Adding a project is more than its hooks, so a run
+ * that cannot write them still registers a new project; a request that asks
+ * for nothing but hooks (all of them globally, one event, or a project that
+ * is already registered) is refused with the blocker's sentence.
+ */
+export function hookInstallPlan({ target, registered = false, hook } = {}, runtime = packagedRuntime()) {
+  if (!hookInstallBlocker(runtime)) return 'write';
+  return target === 'project' && !registered && !hook ? 'register-only' : 'refuse';
+}
+
+export function ensureHookRoot(settings, targetProjectPath, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime()) {
+  // A packaged application's command finds its own handlers, and its package
+  // root can be a mount that ends with the run.
+  if (runtime) return false;
   // The checked-in template must not acquire a machine-specific env path.
   if (targetProjectPath && resolve(targetProjectPath) === resolve(packageRoot)) return false;
   if (settings.env?.SYNABUN_HOOK_ROOT === resolve(packageRoot)) return false;
@@ -55,14 +108,14 @@ export function ensureHookRoot(settings, targetProjectPath, packageRoot = PACKAG
   return true;
 }
 
-export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, packageRoot = PACKAGE_ROOT) {
-  if (!settings?.hooks) return false;
+export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, packageRoot = PACKAGE_ROOT, runtime = packagedRuntime()) {
+  if (!settings?.hooks || hookInstallBlocker(runtime)) return false;
   let changed = false;
   let ownsHooks = false;
   for (const def of HOOK_SCRIPTS) {
     const entries = settings.hooks[def.event];
     if (!Array.isArray(entries)) continue;
-    const command = hookCommandString(def.script);
+    const command = hookCommandString(def.script, targetProjectPath, runtime);
     const matches = entries.flatMap(e => (e.hooks || []).filter(h => isSynaBunHookCommand(h.command, def.script)).map(h => ({ entry: e, hook: h })));
     if (!matches.length) continue;
     ownsHooks = true;
@@ -79,6 +132,6 @@ export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, pack
     settings.hooks[def.event] = [...rest, { matcher: def.matcher || '', hooks: [{ type: 'command', command, timeout: def.timeout }] }];
     changed = true;
   }
-  if (ownsHooks && ensureHookRoot(settings, targetProjectPath, packageRoot)) changed = true;
+  if (ownsHooks && ensureHookRoot(settings, targetProjectPath, packageRoot, runtime)) changed = true;
   return changed;
 }

package/lib/client-config-repair.js

@@ -22,6 +22,7 @@ import {
   inspectCodexConfig,
   upsertCodexMcpConfig,
 } from '../mcp-server/dist/services/codex-config-heal.js';
+import { mcpStdioCommand } from './packaged-runtime.js';
 
 function readJson(path) {
   try { return JSON.parse(readFileSync(path, 'utf-8')); } catch { return null; }
@@ -41,8 +42,8 @@ function jsonChanged(before, after) {
 export function buildCanonicalMcpDefinition({ dataHome, packageRoot }) {
   const canonicalDataHome = resolve(dataHome);
   return {
-    command: 'node',
-    args: [resolve(packageRoot, 'mcp-server', 'dist', 'preload.js').replace(/\\/g, '/')],
+    // `node <preload.js>`, or the entry executable of a packaged application.
+    ...mcpStdioCommand(resolve(packageRoot, 'mcp-server', 'dist', 'preload.js').replace(/\\/g, '/'), { packageRoot }),
     env: {
       DOTENV_PATH: resolve(canonicalDataHome, '.env').replace(/\\/g, '/'),
       SYNABUN_DATA_HOME: canonicalDataHome,
@@ -126,7 +127,7 @@ export function auditAndRepairClientConfigs({
       changed = before !== readFileSync(codexPath, 'utf-8');
     } else {
       const content = readFileSync(codexPath, 'utf-8');
-      changed = !codexDefinition.args.every(value => content.includes(value))
+      changed = ![codexDefinition.command, ...codexDefinition.args].every(value => content.includes(value))
         || !Object.values(codexDefinition.env).every(value => content.includes(value));
     }
     results.codex = { exists: true, connected: true, changed, path: codexPath, health: codexHealth };

package/lib/data-home-migration.js

@@ -32,6 +32,10 @@ const MIGRATION_RUNTIME_ONLY_FILES = new Set([
   'data/active-profile.json',
   'mcp-data/active-profile.json',
   'mcp-data/tool-usage.json',
+  // The Start Server launcher and the supervisor write these on every start.
+  'data/supervisor.json',
+  'data/start-launcher.lock',
+  'data/launcher.log',
 ]);
 
 function normalize(path) {

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; }
+}