synabun 1.3.0 → 2.0.0

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

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+/**
+ * SynaBun SubagentStart Hook for Claude Code
+ *
+ * Fires when a subagent (Task / AgentTool worker) begins. Mirrors the main
+ * session's UserPromptSubmit auto-recall: it searches SynaBun memory with the
+ * subagent's task text and injects the results into the subagent's context via
+ * `hookSpecificOutput.additionalContext`.
+ *
+ * Subagents never emit UserPromptSubmit, so without this hook they start with
+ * zero memory context. This works for ALL agent types — it only adds context
+ * and requires no tool access from the subagent.
+ *
+ * Finding the task text: SubagentStart carries only the base fields on CLI
+ * 2.1.281 (no prompt). pre-task.mjs stashes every Task/Agent dispatch by
+ * tool_use_id, and Claude Code writes
+ * <dirname(transcript_path)>/<session_id>/subagents/agent-<agent_id>.meta.json
+ * = {agentType, description, toolUseId, …}. In order:
+ *   1. a task field on the input (future hosts),
+ *   2. meta.json → toolUseId → the stash entry,
+ *   3. meta.json → toolUseId → that tool_use in the parent transcript,
+ *   4. exactly one unclaimed stash entry of the same agent type (last 60 s),
+ *   5. otherwise nothing: a guess could brief the worker with another's task.
+ *
+ * The recall is ranked (surface brief-rank) with the relevance floor. Gated by
+ * the hook feature `subagentRecall` (on when absent).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readStdin, detectProject, recallMemories, getHookFeatures, hookBudget, clipQuery, transcriptEntries, isTemporaryChat } from './shared.mjs';
+import { claimDispatch } from './task-gate.mjs';
+
+// Cross-platform safety: never break a subagent launch — always emit valid JSON.
+process.on('uncaughtException', () => { try { process.stdout.write('{}'); } catch {} process.exit(0); });
+process.on('unhandledRejection', () => { try { process.stdout.write('{}'); } catch {} process.exit(0); });
+
+const META_POLL_MS = 300;
+
+// The exact field carrying the subagent's task text isn't documented in the CC
+// binary, so probe the known candidates in priority order.
+function extractTaskText(input) {
+  const candidates = [
+    input?.prompt,
+    input?.task_prompt,
+    input?.agent_prompt,
+    input?.description,
+    input?.tool_input?.prompt,
+    input?.tool_input?.description,
+    input?.task?.prompt,
+    input?.task?.description,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.trim()) return c.trim();
+  }
+  return '';
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function readMeta(input) {
+  const { transcript_path: transcriptPath, session_id: sessionId, agent_id: agentId } = input || {};
+  if (typeof transcriptPath !== 'string' || !transcriptPath) return null;
+  if (!/^[a-zA-Z0-9_-]+$/.test(sessionId || '') || !/^[a-zA-Z0-9_-]+$/.test(agentId || '')) return null;
+  const path = join(dirname(transcriptPath), sessionId, 'subagents', `agent-${agentId}.meta.json`);
+  const until = Date.now() + META_POLL_MS;
+  for (;;) {
+    if (existsSync(path)) {
+      try {
+        const meta = JSON.parse(readFileSync(path, 'utf8'));
+        if (meta && typeof meta === 'object') return meta;
+      } catch { /* written but not complete yet: retry */ }
+    }
+    if (Date.now() >= until) return null;
+    await sleep(25);
+  }
+}
+
+function promptFromTranscript(transcriptPath, toolUseId) {
+  for (const entry of transcriptEntries(transcriptPath, 1024 * 1024).reverse()) {
+    if (entry.type !== 'assistant' || !Array.isArray(entry.message?.content)) continue;
+    for (const block of entry.message.content) {
+      if (block && block.type === 'tool_use' && block.id === toolUseId && typeof block.input?.prompt === 'string') {
+        return block.input.prompt;
+      }
+    }
+  }
+  return '';
+}
+
+async function resolveDispatch(input) {
+  const meta = await readMeta(input);
+  const toolUseId = typeof meta?.toolUseId === 'string' ? meta.toolUseId : '';
+  if (toolUseId) {
+    let entry = null;
+    try { entry = claimDispatch(input, { toolUseId }); } catch { /* lock contention: try the transcript */ }
+    if (entry?.prompt?.trim()) return entry.prompt.trim();
+    const fromTranscript = promptFromTranscript(input.transcript_path, toolUseId);
+    if (fromTranscript.trim()) return fromTranscript.trim();
+    return '';
+  }
+  try {
+    const entry = claimDispatch(input, { agentType: input.agent_type || meta?.agentType });
+    if (entry?.prompt?.trim()) return entry.prompt.trim();
+  } catch { /* best effort */ }
+  return '';
+}
+
+async function main() {
+  const budget = hookBudget(3000);
+  let input = {};
+  try {
+    input = JSON.parse(await readStdin());
+  } catch { /* proceed with empty */ }
+
+  // A temporary chat (see isTemporaryChat): no dispatch was stashed for its
+  // workers (pre-task.mjs), so there is no task text to brief them from.
+  if (isTemporaryChat()) { process.stdout.write('{}'); return; }
+
+  // Opt-in payload discovery for verification (SYNABUN_HOOK_DEBUG=1).
+  if (process.env.SYNABUN_HOOK_DEBUG) {
+    try { process.stderr.write(`[SubagentStart] ${JSON.stringify(input)}\n`); } catch { /* ok */ }
+  }
+
+  if (getHookFeatures().subagentRecall === false) { process.stdout.write('{}'); return; }
+
+  const taskText = extractTaskText(input) || await resolveDispatch(input);
+  if (!taskText) { process.stdout.write('{}'); return; }
+
+  const project = detectProject(input.cwd || '');
+  const callMs = Math.min(2000, budget.callTimeout(100));
+  const additionalContext = await recallMemories({
+    query: clipQuery(taskText), project, limit: 3, tokenBudget: 600,
+    timeoutMs: callMs, budgetMs: callMs,
+    // Attribution only: the worker's context holds none of the memories its
+    // parent was shown, so the parent's injection ledger must not filter them.
+    logSessionId: input.session_id,
+    rank: true, surface: 'brief-rank', floor: true,
+  });
+
+  if (additionalContext) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SubagentStart',
+        additionalContext,
+      },
+    }));
+  } else {
+    process.stdout.write('{}');
+  }
+}
+
+main().catch(() => { try { process.stdout.write('{}'); } catch {} process.exit(0); });

package/hooks/claude-code/subagent-stop.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/**
+ * SynaBun SubagentStop Hook for Claude Code
+ *
+ * Fires when a subagent (Task / AgentTool worker) finishes. Mirrors the main
+ * session's Stop auto-remember obligation, but as a SOFT nudge: it injects
+ * `additionalContext` asking the subagent to persist its findings via the
+ * `remember` tool. Per the CC 2.1.177 spec, SubagentStop additionalContext is
+ * "non-error feedback delivered to the subagent; the subagent continues so it
+ * can act on it" — so the worker gets one more turn to call remember.
+ *
+ * Gated behind the `subagentRemember` hook feature (default off) so it's a
+ * deliberate opt-in via the SynaBun settings UI. One nudge per subagent
+ * (tracked by a marker file) to avoid SubagentStop → remember → SubagentStop
+ * loops. Harmless for agents without memory tools — the nudge says to ignore
+ * it when no remember tool is available or nothing substantive was produced.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { readStdin, getHookFeatures, DATA_DIR, isTemporaryChat } from './shared.mjs';
+
+process.on('uncaughtException', () => { try { process.stdout.write('{}'); } catch {} process.exit(0); });
+process.on('unhandledRejection', () => { try { process.stdout.write('{}'); } catch {} process.exit(0); });
+
+const MARKER_DIR = join(DATA_DIR, 'pending-subagent-remember');
+const MARKER_TTL_MS = 24 * 60 * 60 * 1000; // stale-marker cleanup horizon
+
+function sanitizeKey(s) {
+  return String(s || '').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120);
+}
+
+// Opportunistically delete markers older than the TTL so the dir can't grow
+// unbounded (one marker is written per nudged subagent and never re-cleared).
+function cleanupStaleMarkers() {
+  try {
+    const now = Date.now();
+    for (const name of readdirSync(MARKER_DIR)) {
+      const p = join(MARKER_DIR, name);
+      try { if (now - statSync(p).mtimeMs > MARKER_TTL_MS) unlinkSync(p); } catch { /* ok */ }
+    }
+  } catch { /* ok */ }
+}
+
+const NUDGE = [
+  '=== SynaBun: Persist your findings ===',
+  'Before you finish, if you produced findings worth keeping (a fix, a non-obvious',
+  'discovery, an architecture decision, a reusable pattern), call the `remember`',
+  'tool ONCE to store them: include what + why + how, set the project, 3-5 tags,',
+  'and an importance (5=routine, 6-7=significant, 8+=critical).',
+  'Skip this if you have no memory tool available, or did only trivial/read-only',
+  'work with nothing substantive to save.',
+  '=== End ===',
+].join('\n');
+
+async function main() {
+  // Opt-in only.
+  const features = getHookFeatures();
+  if (features.subagentRemember !== true) { process.stdout.write('{}'); return; }
+
+  let input = {};
+  try { input = JSON.parse(await readStdin()); } catch { /* empty */ }
+
+  // A temporary chat (see isTemporaryChat): a worker is not asked to store what it found.
+  if (isTemporaryChat()) { process.stdout.write('{}'); return; }
+
+  if (process.env.SYNABUN_HOOK_DEBUG) {
+    try { process.stderr.write(`[SubagentStop] ${JSON.stringify(input)}\n`); } catch { /* ok */ }
+  }
+
+  // One-shot per subagent: key by agent_id (fallback to session+agent_type).
+  // The marker persists so a worker that stops repeatedly (e.g. stops again
+  // right after acting on the nudge) is never re-nudged. Stale markers are
+  // swept by TTL so the dir can't grow unbounded.
+  const key = sanitizeKey(input.agent_id || `${input.session_id || 's'}-${input.agent_type || 'a'}`);
+  let markerPath = '';
+  try {
+    if (!existsSync(MARKER_DIR)) mkdirSync(MARKER_DIR, { recursive: true });
+    cleanupStaleMarkers();
+    markerPath = join(MARKER_DIR, key);
+  } catch { /* fs unavailable — proceed without loop protection */ }
+
+  if (markerPath && existsSync(markerPath)) {
+    // Already nudged this subagent — stay quiet so it can finish.
+    process.stdout.write('{}');
+    return;
+  }
+
+  if (markerPath) {
+    try { writeFileSync(markerPath, String(Date.now())); } catch { /* ok */ }
+  }
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStop',
+      additionalContext: NUDGE,
+    },
+  }));
+}
+
+main().catch(() => { try { process.stdout.write('{}'); } catch {} process.exit(0); });

package/hooks/claude-code/task-gate.mjs

@@ -0,0 +1,150 @@
+/** Shared, short transactions for the orchestrator's per-prompt recall gate. */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDataHome } from '../../lib/paths.js';
+import { updateJsonState, withStateLock, writeJsonAtomic } from './state.mjs';
+
+export const TASK_TOOLS = new Set(['Task', 'Agent']);
+export const RECALL_TOOL = /(?:^|__)Syna[Bb]un_+recall$/;
+const LOCK_OPTIONS = { timeoutMs: 100 };
+
+// --- Subagent dispatch stash ---
+// SubagentStart carries no task text (CLI 2.1.281), so pre-task.mjs records
+// every Task/Agent dispatch here, keyed by tool_use_id, and subagent-start.mjs
+// finds its own through subagents/agent-<id>.meta.json → toolUseId. An
+// ephemeral cache: corrupt content is replaced, entries expire after 10 min.
+const DISPATCH_TTL_MS = 10 * 60 * 1000;
+const DISPATCH_MAX = 50;
+
+function dispatchPath(sessionId) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(typeof sessionId === 'string' ? sessionId : '')) return null;
+  return join(getDataHome(), 'data', 'subagent-dispatch', `${sessionId}.json`);
+}
+
+function readStash(file) {
+  try {
+    const value = JSON.parse(readFileSync(file, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch { return {}; }
+}
+
+const agentType = (value) => (typeof value === 'string' && value.trim() ? value.trim() : 'general-purpose');
+
+/** Record one PreToolUse Task/Agent dispatch. Idempotent per tool_use_id. */
+export function stashDispatch(input) {
+  if (!TASK_TOOLS.has(input?.tool_name) || typeof input.tool_use_id !== 'string' || !input.tool_use_id) return;
+  const file = dispatchPath(input.session_id);
+  if (!file) return;
+  const toolInput = input.tool_input && typeof input.tool_input === 'object' ? input.tool_input : {};
+  const prompt = typeof toolInput.prompt === 'string' ? toolInput.prompt.slice(0, 16000) : '';
+  const description = typeof toolInput.description === 'string' ? toolInput.description.slice(0, 500) : '';
+  if (!prompt.trim() && !description.trim()) return;
+  withStateLock(() => {
+    const now = Date.now();
+    const stash = readStash(file);
+    if (stash[input.tool_use_id]) return;
+    const kept = Object.entries(stash)
+      .filter(([, entry]) => entry && typeof entry === 'object' && now - (Number(entry.at) || 0) < DISPATCH_TTL_MS);
+    kept.push([input.tool_use_id, { prompt, description, subagent_type: agentType(toolInput.subagent_type), at: now }]);
+    kept.sort((a, b) => a[1].at - b[1].at);
+    writeJsonAtomic(file, Object.fromEntries(kept.slice(-DISPATCH_MAX)));
+  }, LOCK_OPTIONS);
+}
+
+/**
+ * Claim the dispatch a subagent was started from. With `toolUseId` (from the
+ * subagent's meta.json) the lookup is exact. Without it, only an unambiguous
+ * guess is made: exactly one unclaimed entry of the same agent type stashed in
+ * the last `windowMs`. Returns {tool_use_id, prompt, description, subagent_type, at} or null.
+ */
+export function claimDispatch(input, { toolUseId, agentType: type, windowMs = 60 * 1000 } = {}) {
+  const file = dispatchPath(input?.session_id);
+  if (!file) return null;
+  let claimed = null;
+  withStateLock(() => {
+    const stash = readStash(file);
+    const now = Date.now();
+    let id = null;
+    if (typeof toolUseId === 'string' && toolUseId) {
+      if (stash[toolUseId] && typeof stash[toolUseId] === 'object') id = toolUseId;
+    } else if (type !== undefined) {
+      const wanted = agentType(type);
+      const matches = Object.entries(stash).filter(([, entry]) => entry && typeof entry === 'object' && !entry.claimed
+        && agentType(entry.subagent_type) === wanted && now - (Number(entry.at) || 0) <= windowMs);
+      if (matches.length === 1) id = matches[0][0];
+    }
+    if (!id) return;
+    const entry = stash[id];
+    claimed = { tool_use_id: id, prompt: String(entry.prompt || ''), description: String(entry.description || ''),
+      subagent_type: agentType(entry.subagent_type), at: Number(entry.at) || 0 };
+    if (!entry.claimed) {
+      stash[id] = { ...entry, claimed: true, claimedBy: typeof input.agent_id === 'string' ? input.agent_id : null, claimedAt: now };
+      writeJsonAtomic(file, stash);
+    }
+  }, LOCK_OPTIONS);
+  return claimed;
+}
+
+function statePath(input) {
+  if (input?.agent_id || !/^[a-zA-Z0-9_-]+$/.test(input?.session_id || '')) return null;
+  return join(getDataHome(), 'data', 'task-gate', `${input.session_id}.json`);
+}
+
+export function startTaskTurn(input) {
+  const file = statePath(input);
+  if (!file || typeof input.prompt !== 'string') return;
+  return updateJsonState(file, state => {
+    // Canonical handlers are deduplicated by Claude; tolerate a duplicate
+    // delivery too, without erasing the receipts from an already-started turn.
+    if (input.prompt_id && state?.promptId === input.prompt_id) return;
+    return {
+      turn: (Number.isSafeInteger(state?.turn) ? state.turn : 0) + 1,
+      promptId: input.prompt_id || null,
+      prompt: input.prompt.trim().slice(0, 16000),
+      completedRecalls: [],
+      blockedToolUseIds: [],
+    };
+  }, undefined, LOCK_OPTIONS);
+}
+
+export function updateTaskTurn(input, update, expectedTurn) {
+  const file = statePath(input);
+  // Old hosts without prompt_id cannot safely attribute a late completion.
+  // Fail open rather than releasing another user prompt's gate.
+  if (!file || typeof input.prompt_id !== 'string' || !input.prompt_id) return;
+  return updateJsonState(file, state => {
+    if (!Number.isSafeInteger(state?.turn) || state.turn < 1
+      || state.promptId !== input.prompt_id
+      || (expectedTurn !== undefined && state.turn !== expectedTurn)) return;
+    return update(state);
+  }, undefined, LOCK_OPTIONS);
+}
+
+export function recordTaskRecall(input) {
+  if (!RECALL_TOOL.test(input.tool_name || '') || !input.tool_use_id) return;
+  return updateTaskTurn(input, state => {
+    if (state.recalledTurn === state.turn || state.releasedTurn === state.turn) return;
+    const ids = state.completedRecalls || [];
+    if (ids.includes(input.tool_use_id)) return;
+    state.completedRecalls = [...ids, input.tool_use_id].slice(-256);
+    return state;
+  });
+}
+
+export function completeTaskBatch(input) {
+  if (!Array.isArray(input.tool_calls)) return;
+  const ids = new Set(input.tool_calls.map(call => call?.tool_use_id).filter(Boolean));
+  if (!ids.size) return;
+  return updateTaskTurn(input, state => {
+    const recalled = (state.completedRecalls || []).some(id => ids.has(id));
+    const blocked = state.blockedTurn === state.turn
+      && (state.blockedToolUseIds || []).some(id => ids.has(id));
+    if (!recalled && !blocked) return;
+    if (recalled) state.recalledTurn = state.turn;
+    if (blocked) state.releasedTurn = state.turn;
+    state.completedRecalls = (state.completedRecalls || []).filter(id => !ids.has(id));
+    delete state.claim;
+    delete state.brief;
+    return state;
+  });
+}

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

@@ -0,0 +1,137 @@
+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.
+export const HOOK_SCRIPTS = Object.freeze([
+  { event: 'SessionStart', script: 'session-start.mjs', timeout: 5 },
+  { event: 'UserPromptSubmit', script: 'prompt-submit.mjs', timeout: 3 },
+  { event: 'PreCompact', script: 'pre-compact.mjs', timeout: 10 },
+  { event: 'Stop', script: 'stop.mjs', timeout: 3 },
+  { event: 'PreToolUse', script: 'pre-websearch.mjs', timeout: 3, matcher: '^WebSearch$|^WebFetch$' },
+  { event: 'PreToolUse', script: 'pre-task.mjs', timeout: 5, matcher: '^Task$|^Agent$' },
+  { event: 'PostToolBatch', script: 'pre-task.mjs', timeout: 3 },
+  { event: 'PostToolUse', script: 'post-remember.mjs', timeout: 3, matcher: '^Edit$|^Write$|^NotebookEdit$|Syna[Bb]un_+(remember|reflect|recall)$' },
+  { event: 'PostToolUse', script: 'post-plan.mjs', timeout: 15, matcher: '^(Enter|Exit)PlanMode$' },
+  { event: 'SubagentStart', script: 'subagent-start.mjs', timeout: 3 },
+  { event: 'SubagentStop', script: 'subagent-stop.mjs', timeout: 3 },
+].map(Object.freeze));
+
+// The batch-completion handler is an installation dependency of the guards.
+// Treat either event as the same group, including direct API callers.
+export function hookDefinitionsForEvent(event) {
+  if (!event) return HOOK_SCRIPTS;
+  const events = ['PreToolUse', 'PostToolBatch'].includes(event)
+    ? ['PreToolUse', 'PostToolBatch'] : [event];
+  return HOOK_SCRIPTS.filter(def => events.includes(def.event));
+}
+
+// No shell-specific environment expansion, install paths, or downloads. Walk
+// up from the project/cwd for checkout-only installs, then use the installed
+// root. Single quotes inside JS work inside the command's double quotes on
+// 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)";
+
+/**
+ * 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');
+  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;
+  // 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;
+  const script = (match[1] || match[2] || match[3]).replace(/\\/g, '/');
+  return script === `hooks/claude-code/${scriptName}` || script.endsWith(`/hooks/claude-code/${scriptName}`);
+}
+
+/**
+ * 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;
+  settings.env = { ...settings.env, SYNABUN_HOOK_ROOT: resolve(packageRoot) };
+  return true;
+}
+
+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, 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;
+    const canonical = matches.find(({ hook }) => hook.command === command);
+    const matcherOk = canonical && (canonical.entry.matcher || '') === (def.matcher || '');
+    if (matches.length === 1 && matcherOk && canonical.hook.timeout === def.timeout && canonical.hook.type === 'command') continue;
+    stats.removed = (stats.removed || 0) + matches.length - 1;
+    if (!canonical) stats.repaired = (stats.repaired || 0) + 1;
+    else if (!matcherOk) stats.matchers = (stats.matchers || 0) + 1;
+    const rest = entries.flatMap(entry => {
+      const hooks = (entry.hooks || []).filter(h => !isSynaBunHookCommand(h.command, def.script));
+      return hooks.length ? [{ ...entry, hooks }] : [];
+    });
+    settings.hooks[def.event] = [...rest, { matcher: def.matcher || '', hooks: [{ type: 'command', command, timeout: def.timeout }] }];
+    changed = true;
+  }
+  if (ownsHooks && ensureHookRoot(settings, targetProjectPath, packageRoot, runtime)) changed = true;
+  return changed;
+}