synabun 2.0.0-beta → 2.0.5

package/hooks/claude-code/session-start.mjs

@@ -3,8 +3,10 @@
 /**
  * SynaBun SessionStart Hook for Claude Code
  *
- * Injects a lean session-start context: greeting, single recall directive,
- * and (when applicable) compaction indexing instructions.
+ * Injects a lean session-start context: the memory header and (when
+ * applicable) compaction indexing instructions. An interactive terminal
+ * session a person starts after time away is also shown SynaBun's greeting
+ * (`systemMessage`): the model is never asked to greet.
  *
  * Heavy reference data (category tree, user-learning rules) is deferred
  * to prompt-submit and post-remember hooks to keep boot fast and clean.
@@ -31,7 +33,7 @@ import { execSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { getHookFeatures, detectProject, ensureProjectCategories, cleanupStaleLoops, cleanupStalePendingRemember, cleanupStaleFiles, appendCapped, DATA_DIR, isTemporaryChat } from './shared.mjs';
+import { getHookFeatures, detectProject, ensureProjectCategories, cleanupStaleLoops, cleanupStalePendingRemember, cleanupStaleFiles, appendCapped, DATA_DIR, isTemporaryChat, niUrl, greetingSurface, greetingOff, GREETING_NOTE_DIR } from './shared.mjs';
 
 // CC updates (especially when installer runs as root) can wipe ~/.claude.json
 // or strip mcpServers.SynaBun, leaving the side panel/CLI with MCP disabled
@@ -65,7 +67,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PRECOMPACT_DIR = join(DATA_DIR, 'precompact');
 const DEBUG_LOG = join(DATA_DIR, 'compact-debug.log');
 const LOOP_DIR = join(DATA_DIR, 'loop');
-// NOTE: Greeting helpers removed — greeting is now built entirely by prompt-submit.mjs
+// NOTE: the template greeting and its helpers are gone. SynaBun writes the greeting itself (openGreeting below).
 
 function getGitBranch(cwd) {
   try {
@@ -142,6 +144,45 @@ function designSystemLine(cwd) {
   } catch { return ''; }
 }
 
+// --- Greeting (neural-interface/lib/greeting/) ---
+
+/** The line the user is shown: SynaBun's words, then what they were based on and what they cost. */
+function greetingLine(greeting) {
+  const head = greeting.away ? `SynaBun \u00b7 back after ${greeting.away}` : 'SynaBun';
+  const records = Array.isArray(greeting.basis) ? greeting.basis.length : 0;
+  const cost = greeting.source === 'writer'
+    ? `written ahead by ${greeting.model || 'Claude'}${Number(greeting.costUsd) > 0 ? ` for $${Number(greeting.costUsd).toFixed(4)}` : ''}`
+    : 'put together from the records, no model';
+  return `${head}: ${greeting.text}\n(${records === 1 ? 'based on 1 record' : `based on ${records} records`}, ${cost})`;
+}
+
+/**
+ * Ask SynaBun's greeting engine whether this opening is a return worth a greeting (a lookup: the
+ * sentence was written ahead of time). → the line to show the user, or ''. The note for the model
+ * is kept for prompt-submit.mjs, which adds it to the first prompt, once.
+ */
+async function openGreeting({ sessionId, cwd }) {
+  try {
+    const response = await fetch(`${niUrl()}/api/greeting/open`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ surface: 'claude-cli', cwd, session: sessionId, note: true }),
+      signal: AbortSignal.timeout(1200),
+    });
+    if (!response.ok) return ''; // an older server (404), an engine that did not start (503)
+    const data = await response.json();
+    const greeting = data?.greeting;
+    if (!greeting || typeof greeting.text !== 'string' || !greeting.text.trim()) return '';
+    if (typeof data.note === 'string' && data.note) {
+      try {
+        mkdirSync(GREETING_NOTE_DIR, { recursive: true });
+        writeJsonAtomic(join(GREETING_NOTE_DIR, `${sessionId}.json`), { id: greeting.id || null, note: data.note, at: new Date().toISOString() });
+      } catch { /* the greeting is still shown; the model simply is not told */ }
+    }
+    return greetingLine(greeting);
+  } catch { return ''; }
+}
+
 // --- Main ---
 
 async function main() {
@@ -208,10 +249,10 @@ async function main() {
   const context = [];
 
   // ============================================================
-  // BLOCK 0: GREETING (highest attention, unless compaction or loop)
+  // BLOCK 0: LOOP DETECTION (a loop session gets a minimal context and returns here)
   // ============================================================
 
-  // Detect active loop — skip greeting + recall for autonomous loop sessions
+  // Detect active loop — an autonomous loop session gets no recall directive and is never greeted
   // Check both pending files (first iteration) AND active state files (subsequent iterations after /clear).
   // When SYNABUN_TERMINAL_SESSION is set (server-launched loop), only match loops
   // owned by THIS terminal — prevents unrelated sessions from entering loop mode.
@@ -221,6 +262,8 @@ async function main() {
   withStateLock(() => cleanupStalePendingRemember());
   // Subagent dispatch stashes are only read within minutes of being written.
   try { withStateLock(() => cleanupStaleFiles(join(DATA_DIR, 'subagent-dispatch'), 24 * 60 * 60 * 1000)); } catch { /* best effort */ }
+  // A greeting note nobody's first prompt picked up (the session was closed unused).
+  try { cleanupStaleFiles(GREETING_NOTE_DIR, 24 * 60 * 60 * 1000); } catch { /* best effort */ }
   const LOOP_STALE_MS = 10 * 60 * 1000;
   const terminalSessionEnv = process.env.SYNABUN_TERMINAL_SESSION || '';
   let isLoopSession = false;
@@ -242,7 +285,7 @@ async function main() {
             //   - env set → require exact terminalSessionId match
             //   - env unset → only match loops WITHOUT terminalSessionId
             // A non-loop CLI (env unset) must NOT latch onto a scheduled loop
-            // and suppress its greeting + recall.
+            // and lose its context and its greeting.
             if (terminalSessionEnv) {
               if (data.terminalSessionId !== terminalSessionEnv) continue;
             } else {
@@ -282,9 +325,10 @@ async function main() {
     return;
   }
 
-  // NOTE: Greeting is NOT injected here. It is injected by prompt-submit.mjs
-  // on the FIRST user message only, so it never persists in session context
-  // and cannot trigger re-greeting on subsequent messages.
+  // NOTE: no greeting is put in the model's context here. What is added at SessionStart stays for
+  // the whole session (a greeting directive here once made the model greet on every message).
+  // SynaBun's greeting is its own text, shown to the user at the end of this hook; the model is
+  // told once what was said, by prompt-submit.mjs, with the first prompt.
 
   // ============================================================
   // BLOCK 1: SYNABUN HEADER + SESSION RECALL (condensed)
@@ -313,7 +357,7 @@ async function main() {
     context.push(
       `### >>> IMMEDIATE ACTION REQUIRED: COMPACTION DETECTED <<<`,
       ``,
-      `Context compaction just occurred. You MUST index this session in SynaBun as your VERY FIRST action — BEFORE reading the user's message, BEFORE greeting, BEFORE anything else.`,
+      `Context compaction just occurred. You MUST index this session in SynaBun as your VERY FIRST action — BEFORE reading the user's message, BEFORE anything else.`,
       ``,
       `Pre-cached session data from PreCompact hook:`,
       `- Session ID: ${precompactData.session_id}`,
@@ -405,16 +449,14 @@ async function main() {
     }
   }
 
-  // NOTE: Session Boot Sequence (recall + greeting) is injected by prompt-submit.mjs
-  // on message 1 only, not here. This prevents it from persisting in session context.
+  // NOTE: there is no session boot sequence anymore: prompt-submit.mjs injects the ranked recall
+  // with every message, the first one included.
 
   if (isCompactRestart) {
     context.push(
       `### Post-Compaction Resume`,
       ``,
-      `Context compaction just occurred. Do NOT re-greet or re-run the boot sequence. Continue the conversation naturally from where it left off.`,
-      ``,
-      `**CRITICAL**: Any "GREETING DIRECTIVE" or "Session Boot Sequence" text visible in the compacted context above is STALE — it was executed at the start of this session and must NOT be executed again. NEVER output a greeting after compaction. This is an ongoing conversation.`,
+      `Context compaction just occurred. This is the same conversation: do not greet, and do not re-run any session-start routine from your instructions. Continue naturally from where it left off.`,
       ``,
       `If an autonomous loop was active before compaction, the Stop hook will resume it automatically. Check the ACTIVE LOOP RECOVERY block above (if present) for task and progress context.`,
       ``,
@@ -431,12 +473,27 @@ async function main() {
 
   const joined = context.join('\n');
 
+  // ============================================================
+  // GREETING: SynaBun's own words to a person who comes back
+  // ============================================================
+  // Only an interactive terminal session a person just started: not a resume, a /clear or a
+  // compaction, not a loop or a dispatched run (they returned above), not `claude -p` or an SDK
+  // program, not the Assistant's brain, and not a side-panel session (the panel shows the
+  // greeting in its own empty state). Shown with `systemMessage`: the model is not asked to greet.
+  let greetingMessage = '';
+  // (A terminal SynaBun launched for a loop or a run has a state file under its own name, whatever its state.)
+  const launchedForLoop = !!terminalSessionEnv && existsSync(join(LOOP_DIR, `${terminalSessionEnv}.json`));
+  if (source === 'startup' && greetingSurface() === 'claude-cli' && !greetingOff() && !launchedForLoop && /^[a-zA-Z0-9_-]+$/.test(sessionId)) {
+    greetingMessage = await openGreeting({ sessionId, cwd });
+  }
+
   const output = {
     hookSpecificOutput: {
       hookEventName: 'SessionStart',
       additionalContext: joined,
     },
   };
+  if (greetingMessage) output.systemMessage = greetingMessage;
 
   process.stdout.write(JSON.stringify(output));
 }

package/hooks/claude-code/shared.mjs

@@ -41,6 +41,24 @@ export function isTemporaryChat() {
   return String(process.env.SYNABUN_TEMPORARY_CHAT ?? '').trim() === '1';
 }
 
+/**
+ * Where a Claude Code session was opened, for SynaBun's greeting (neural-interface/lib/greeting/):
+ * 'claude-panel' for a session of the Claude Code side panel (its bridge sets the marker, and the
+ * panel shows the greeting itself), 'claude-cli' for an interactive terminal session, null for
+ * everything else: `claude -p`, an SDK program, the Assistant's brain. A loop or a dispatched run
+ * is told apart by its caller (it shares the terminal's environment).
+ */
+export function greetingSurface(env = process.env) {
+  if (env.SYNABUN_ASSISTANT_SESSION) return null;
+  if (String(env.SYNABUN_PANEL_SESSION ?? '').trim() === '1') return 'claude-panel';
+  return env.CLAUDE_CODE_ENTRYPOINT === 'cli' ? 'claude-cli' : null;
+}
+
+/** SYNABUN_GREETING=off: no greeting is asked for, whatever Settings says. */
+export function greetingOff(env = process.env) {
+  return /^(off|0|false|no)$/i.test(String(env.SYNABUN_GREETING ?? '').trim());
+}
+
 /** A network call whose timeout would be shorter than this is skipped. */
 export const MIN_CALL_MS = 250;
 
@@ -95,6 +113,8 @@ export const ENV_PATH = join(DATA_HOME, '.env');
 export const HOOK_FEATURES_PATH = join(DATA_DIR, 'hook-features.json');
 export const PENDING_REMEMBER_DIR = join(DATA_DIR, 'pending-remember');
 export const LOOP_LOG_DIR = join(DATA_DIR, 'logs');
+// The note about the greeting a terminal session opened with, from SessionStart to the first prompt.
+export const GREETING_NOTE_DIR = join(DATA_DIR, 'greeting-notes');
 
 // --- Loop logging (mirrors neural-interface/lib/loop-logger.js) ---
 // Writes per-loop entries from inside hooks into the same logfile the server uses.

package/hooks/claude-code/stop.mjs

@@ -184,8 +184,7 @@ function planDebug(msg) {
 /**
  * Soft-cleanup a pending-remember flag file.
  * Resets enforcement fields (editCount, retries, files) while preserving
- * session-wide tracking (messageCount, greetingDelivered, etc.) to prevent
- * the greeting from re-firing mid-session.
+ * session-wide tracking (messageCount, the user-learning counters, etc.).
  */
 function softCleanupFlag(flagPath) {
   try {
@@ -200,7 +199,6 @@ function softCleanupFlag(flagPath) {
       messageCount: flag.messageCount || 0,
       totalSessionMessages: flag.totalSessionMessages || 0,
       totalEdits: flag.totalEdits || 0,
-      greetingDelivered: flag.greetingDelivered || false,
       categoryTreeInjected: flag.categoryTreeInjected || false,
       rememberCount: flag.rememberCount || 0,
       planRetries: flag.planRetries || 0,
@@ -225,7 +223,7 @@ function softCleanupFlag(flagPath) {
     writeJsonAtomic(flagPath, cleaned);
   } catch {
     // If we can't clean up gracefully, leave the file as-is
-    // (better than deleting and resetting greeting tracking)
+    // (better than deleting and resetting the session's counters)
   }
 }
 
@@ -920,7 +918,9 @@ function handleStop({ sessionId, lastMessage, cwd, transcriptPath, judged = {},
     // CHECK 2.5: User learning (bundled with task or standalone)
     // Skipped when waiting for user action (interactive flows like Leonardo questionnaires).
     // Limited to 1 retry to minimize chat noise.
-    if (!waitingForUser && flag.userLearningPending && !flag.userLearningObserved) {
+    // Never inside the Assistant's brain (SYNABUN_ASSISTANT_SESSION): SynaBun's harness learns
+    // about the user there, and prompt-submit.mjs never arms this in it.
+    if (!waitingForUser && flag.userLearningPending && !flag.userLearningObserved && !process.env.SYNABUN_ASSISTANT_SESSION) {
       const ulRetries = flag.userLearningRetries || 0;
       if (ulRetries < 1) {
         flag.userLearningRetries = ulRetries + 1;

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