beehaven 0.8.16

package/dist/daemon-omni.js

@@ -0,0 +1,1442 @@
+/**
+ * Daemon-side Omni — Claude Agent SDK integration. Wraps SDK `query()`
+ * calls into a streaming event loop that local IPC callers (FAB via DO
+ * relay, mwah CLI, beehaven CLI) can drive.
+ *
+ *   IPC call: `omni:prompt` { prompt, sessionId?, model?, compositionId?, ... }
+ *   Stream:   subscribers see `agent:text-delta` / `agent:tool-call` /
+ *             `agent:tool-result` / `agent:turn-complete` / `agent:done`
+ *             events on the same channel mwah's CloudBridge listens for.
+ *
+ * Why a daemon module (not workspace.ts)?
+ *   The DO runtime can't fork subprocesses; the SDK spawns Claude Code
+ *   under the hood (Bash/Read/Edit are executed by a child process,
+ *   even via `query()`). So the SDK fundamentally needs Node, and the
+ *   daemon is the natural place.
+ *
+ * ⚠⚠ LOCAL IPC ONLY — AND THIS HEADER USED TO DOCUMENT THE OPPOSITE.
+ *
+ *   It said: "The Workspace DO acts as a routing layer: forwards FAB prompts
+ *   via `omni:prompt` over the relay, re-broadcasts the resulting `omni:event`
+ *   envelopes as agent:* messages back to the web client."
+ *
+ *   That path does not exist and must not be built. `daemon.ts` (at the
+ *   registration of these very verbs) states it as a COMPLIANCE BOUNDARY, not
+ *   a shortcut: "Cloud→daemon Claude orchestration is deliberately disabled
+ *   (see relay.ts 'Anthropic credential use policy'). The IPC socket is chmod
+ *   0600, so the kernel guarantees the caller is this UNIX user driving their
+ *   own subscription. Do NOT bridge these onto `relay.onDaemonRpcRequest` or
+ *   any other inbound relay path — that is precisely the shape that was
+ *   switched off."
+ *
+ *   ⚠ So a reader who trusted this header was being pointed at the one
+ *   integration the adjacent file forbids by name, with a policy reason. A
+ *   stale comment is ordinarily documentation debt; a stale comment that
+ *   describes a forbidden path as the design is an instruction to violate it.
+ *
+ *   Callers reach these verbs over the LOCAL IPC socket only: the FAB through
+ *   the desktop app's own IPC client, plus `mwah` and `beehaven` on this
+ *   machine. Nothing inbound from the relay.
+ *
+ * Session model — one-shot-per-turn (#48):
+ *   Earlier versions kept one persistent `query({prompt:AsyncIterable})`
+ *   alive per session and pushed messages into it. That mode silently
+ *   broke the SDK's `resume` option — every turn forked a new
+ *   session_id. Switching to one `query()` per turn with explicit
+ *   `resume: <sdkSessionId>` made cross-restart persistence work.
+ *
+ *   Each prompt opens a fresh `query()`. The SDK's session_id from
+ *   the init message is captured into OmniSession.sdkSessionId so
+ *   subsequent turns thread it as `resume:` — same JSONL file is
+ *   appended to, conversation persists across daemon restarts. On a
+ *   fresh process, findLatestSdkSessionId() scans the composition's
+ *   project dir on disk and primes the in-memory session with the
+ *   latest session_id.
+ *
+ *   Concurrency: one turn in flight per session. Subsequent calls to
+ *   promptOmni queue FIFO via OmniSession.queuedPrompts and drain in
+ *   the runTurn finally block.
+ *
+ * Auth:
+ *   The SDK reads ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN from
+ *   process env. We pass them through from the daemon's process.env —
+ *   no separate token plumbing. If the user has Claude Code installed
+ *   and logged in (subscription token), it Just Works.
+ *
+ * Nesting guard:
+ *   The SDK refuses to start when CLAUDECODE=1 is set (it's how
+ *   Claude Code detects "I'm being nested in another Claude Code
+ *   session" and bails). We delete it from our env passthrough so the
+ *   daemon-spawned SDK isn't blocked when the user happened to start
+ *   the daemon from inside a Claude Code session.
+ */
+import { query, SYSTEM_PROMPT_DYNAMIC_BOUNDARY } from '@anthropic-ai/claude-agent-sdk';
+import { buildToolGate } from './daemon-omni-tool-gate.js';
+import { COMPANY_ADDON, companyModeEnabled, workContextBlock } from './daemon-omni-company.js';
+import { ensureDefaultPoliciesRegistered } from './daemon-omni-policies.js';
+import { getDefaultHooks, setCompactionEmitter } from './daemon-omni-hooks.js';
+import { findClaudeBinary } from './claude-credential-store.js';
+import { resolveBoundRepo } from './composition-repos.js';
+import { createClearlyMcpServer } from './daemon-mcp-clearly.js';
+import { createPrincipalMcpServer, clearPrincipalContext, } from './daemon-omni-principal.js';
+// Cached path to the `claude` CLI binary. The Anthropic Agent SDK
+// normally resolves this from its own platform-specific package
+// (@anthropic-ai/claude-agent-sdk-{platform}-{arch}/claude), but when
+// the Mac app's npm install ran with --omit=optional that package
+// isn't present and the SDK errors with "Native CLI binary for
+// {platform}-{arch} not found." `findClaudeBinary()` falls back to
+// the user's own `claude login`-authed install at ~/.local/bin/claude,
+// which inherits the same Keychain auth the SDK would have used
+// anyway — so this resolves both the bundling and the auth issue in
+// one step. Resolved once on first turn, cached for the daemon's
+// lifetime (the path doesn't change between turns).
+let _cachedClaudeBinary = undefined;
+async function getClaudeBinary() {
+    if (_cachedClaudeBinary !== undefined)
+        return _cachedClaudeBinary;
+    _cachedClaudeBinary = await findClaudeBinary();
+    return _cachedClaudeBinary;
+}
+let _compactionEmitterWired = false;
+function ensureCompactionEmitterWired() {
+    if (_compactionEmitterWired)
+        return;
+    _compactionEmitterWired = true;
+    setCompactionEmitter((event) => {
+        emit({
+            type: 'agent:compacting',
+            sessionId: event.sessionId,
+            kind: event.kind,
+            ...(event.messageCount != null ? { messageCount: event.messageCount } : {}),
+            ...(event.reason ? { reason: event.reason } : {}),
+        });
+    });
+}
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync, chmodSync, } from 'fs';
+import { join, dirname, resolve as resolvePath } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+/**
+ * Decode the `text` property of an MCP tool argument while Claude is still
+ * producing the JSON. `JSON.parse` cannot help until the closing brace arrives,
+ * and emitting raw fragments would briefly show escaped characters (or a
+ * half-written unicode escape) in the chat. Keep the tiny decoder here beside
+ * the SDK stream adapter so principal-facing text has a real live path all the
+ * way to the desktop window.
+ */
+class PrincipalTextReader {
+    buffer = '';
+    start = -1;
+    emitted = 0;
+    push(fragment) {
+        this.buffer += fragment;
+        if (this.start < 0) {
+            const match = /"text"\s*:\s*"/.exec(this.buffer);
+            if (!match)
+                return '';
+            this.start = match.index + match[0].length;
+        }
+        let decoded = '';
+        let index = this.start;
+        while (index < this.buffer.length) {
+            const ch = this.buffer[index];
+            if (ch === '"')
+                break;
+            if (ch === '\\') {
+                if (index + 1 >= this.buffer.length)
+                    break;
+                const escape = this.buffer[index + 1];
+                if (escape === 'u') {
+                    if (index + 6 > this.buffer.length)
+                        break;
+                    decoded += String.fromCharCode(parseInt(this.buffer.slice(index + 2, index + 6), 16));
+                    index += 6;
+                    continue;
+                }
+                decoded += { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', '"': '"', '\\': '\\', '/': '/' }[escape] ?? escape;
+                index += 2;
+                continue;
+            }
+            decoded += ch;
+            index += 1;
+        }
+        const fresh = decoded.slice(this.emitted);
+        this.emitted = decoded.length;
+        return fresh;
+    }
+}
+const sessions = new Map();
+const subscribers = new Set();
+// ── First-party beehaven tools ───────────────────────────────────────
+//
+// The whole beehaven surface — canvas, compositions, the avatar, brand —
+// mounted as NATIVE MCP tools inside every daemon-claude session, not as
+// shell-outs it has to discover.
+//
+// `daemon-mcp-clearly.ts` has always described this wiring in its own header
+// and nothing ever performed it: `createClearlyMcpServer` was exported and
+// called from nowhere, so the tools existed only as a design. That is the gap
+// this closes. Before, reaching the canvas meant Claude writing
+// `beehaven call canvas-act '<json>'` into Bash — a ~50-100ms node bootstrap
+// per call, a shell-injection surface, and a permission gate that had to
+// REGEX A COMMAND STRING to work out what was being attempted. Now it is
+// `mcp__clearly__canvas_add_text` with a Zod-checked signature, in-process,
+// and gate-able by name.
+//
+// Registered rather than imported-and-constructed because the context it needs
+// (the relay socket, the local app manager) lives in daemon.ts's closure. Same
+// shape as `setTierResolver` — daemon.ts owns the wiring, this module owns the
+// use. Left unregistered (a CLI-hosted session, a unit test), the session is
+// simply plain Claude Code, which is the correct degradation.
+let _clearlyMcpServer = null;
+/** Wire the first-party beehaven tool surface. Call once from the daemon. */
+export function setClearlyTools(ctx) {
+    _clearlyMcpServer = ctx ? createClearlyMcpServer(ctx) : null;
+}
+/**
+ * OMNI'S OWN TOOLS — reply, ask, the board, design docs, the principal's screen.
+ *
+ * ⚠ SEPARATE FROM `clearly`, and deliberately so. The `clearly` surface is the
+ * WORKSPACE (canvas, compositions, images, vectors) and is useful to any agent.
+ * This one is the PRINCIPAL — a conversation, a question that blocks, a card, a
+ * window on someone's screen — and it only means anything when something is
+ * attached to render it. Mounting them as one server would make an unattended
+ * session (a cron, a CLI one-shot) advertise `reply_to_principal` to a model with
+ * nobody on the other end.
+ *
+ * Registered rather than constructed here for the same reason as `clearly`: the
+ * context it needs (the emit channel, the ask round-trip) lives in the caller's
+ * closure. Left unregistered, Omni is simply Claude Code with the beehaven
+ * tools — which is the correct degradation for a headless session.
+ */
+let _principalMcpServer = null;
+/**
+ * The session whose turn is running right now, for tagging principal events.
+ * Set by `runTurn`, and NOT cleared when it finishes — a tool result can arrive
+ * a tick after the turn's `finally`, and clearing would tag it with nothing.
+ * One turn runs at a time per daemon, so the last writer is always correct.
+ */
+let _activeTurnSessionId = 'default';
+export const activeTurnSessionId = () => _activeTurnSessionId;
+/**
+ * Does a WINDOWING surface currently have the conversation — the Mac app, as
+ * opposed to a terminal?
+ *
+ * ⚠ SET BY THE SURFACE, NOT INFERRED. The daemon cannot tell a Mac-app client
+ * from a CLI one by looking at the socket, and guessing wrong in the permissive
+ * direction is the bad one: Omni would report "opened the board" to someone
+ * staring at a terminal. Declared explicitly, defaulting to FALSE, so a surface
+ * that never claims the capability never gets credited with it.
+ */
+let _windowSurfaces = 0;
+export function declareWindowSurface() {
+    _windowSurfaces++;
+    let released = false;
+    return () => {
+        // Idempotent — a double release must not drive the count negative and
+        // silently disable windows for a surface that is still attached.
+        if (released)
+            return;
+        released = true;
+        _windowSurfaces = Math.max(0, _windowSurfaces - 1);
+    };
+}
+export const hasWindowSurface = () => _windowSurfaces > 0;
+export function setPrincipalTools(ctx) {
+    _principalMcpServer = ctx ? createPrincipalMcpServer(ctx) : null;
+    // Unmounting must also drop the context the GATE reads, or a daemon that has
+    // detached its principal would keep refusing edits against a board nothing can
+    // reach any more.
+    if (!ctx)
+        clearPrincipalContext();
+}
+export function principalToolsMounted() {
+    return !!_principalMcpServer;
+}
+/**
+ * OMNI'S IDENTITY — the standing prompt that makes this session Omni rather than
+ * a generic Claude Code.
+ *
+ * ⚠ A DAEMON-LEVEL DEFAULT, NOT A PER-CALL ARGUMENT, and that is the point. The
+ * identity used to be assembled inside the Mac app and handed to the session
+ * Electron spawned, so it reached exactly one caller: `beehaven agent`, the
+ * avatar panel and any CLI got an anonymous Claude with the same tools and none
+ * of the instructions for using them. Registered here, every entry point gets
+ * the same agent.
+ *
+ * ⚠ IT IS THE SYSTEM INSTRUCTION, NOT AN APPEND TO ONE. It used to ride in as
+ * `{preset:'claude_code', append}`, so the prompt the model actually read opened
+ * with Claude Code's own preset and Omni arrived underneath it as a footnote —
+ * the identity was a modifier on someone else's agent rather than the agent.
+ * Passed as a bare string (the SDK's custom-prompt form) it IS the prompt, which
+ * is what this file has claimed all along. The TOOL preset is unaffected and
+ * still `claude_code`: the tools were never the problem.
+ *
+ * A per-call `appendSystemPrompt` LAYERS ON TOP of it — see `resolveSystemPrompt`.
+ */
+let _omniIdentity = '';
+export function setOmniIdentity(prompt) {
+    _omniIdentity = String(prompt ?? '');
+}
+export const omniIdentitySet = () => !!_omniIdentity;
+/**
+ * The registered identity text, for diagnostics.
+ *
+ * ⚠ THE TEXT, NOT A BOOLEAN. `omniIdentitySet()` answers "is one registered"; the company-mode
+ * diagnostic also reports PROMPT WEIGHT, and a boolean cannot be measured. Read-only — the setter
+ * above stays the only way to change it.
+ */
+export const omniIdentityText = () => _omniIdentity;
+/**
+ * ⚠ A PER-CALL PROMPT IS A MODIFIER, AND MUST NOT REPLACE THE IDENTITY.
+ *
+ * It used to replace it, on the premise that the one caller passing a prompt had
+ * assembled a full one (the Mac app's). That caller is gone — `ea-chat.ts` sends
+ * no prompt and relies on this default. The two callers that DO pass one send a
+ * fragment: `beehaven claude` sends dev mode, and a pipeline/tree/consensus stage
+ * sends its role ("You are the DRAFTER"). Both were silently running as an
+ * anonymous Claude Code holding Omni's tools — precisely the failure registering
+ * the identity here was meant to end.
+ *
+ * The identity leads and the modifier follows, split on the SDK's cache boundary
+ * so the ~20 KB identity is a cacheable prefix shared across every session while
+ * the per-call half stays session-local. A caller that genuinely carries the
+ * identity already is passed through untouched, which is the doubling the old
+ * replace-semantics existed to prevent.
+ *
+ * With no identity registered there is nothing to be, so the preset stays — a
+ * bare stage fragment as the whole system prompt would be worse than either.
+ */
+export function resolveSystemPrompt(callerPrompt) {
+    const caller = String(callerPrompt ?? '').trim();
+    /**
+     * ⚠⚠ COMPANY MODE JOINS THE IDENTITY, BEFORE THE BOUNDARY — it is static per build, so it
+     * belongs in the CACHEABLE prefix. Appending it as a per-call modifier would push ~6 KB across
+     * the boundary on every turn, which is the exact cost this function was split to avoid.
+     *
+     * ⚠ AND IT FOLLOWS THE IDENTITY, NEVER REPLACES IT. Every safety property — what may be run, the
+     * git rules, what must never be done unasked, when to stop and ask — lives in the identity. A
+     * mode that swapped it out would trade all of that for a role-play.
+     */
+    const base = _omniIdentity && companyModeEnabled()
+        ? `${_omniIdentity}\n\n${COMPANY_ADDON}`
+        : _omniIdentity;
+    if (!base) {
+        /**
+         * ⚠ NO IDENTITY REGISTERED. The preset stays, and company mode still applies as an append —
+         * a bare operating manual as the WHOLE system prompt would be worse than either, but silently
+         * dropping the mode the operator switched on would be worse still.
+         */
+        const append = [companyModeEnabled() ? COMPANY_ADDON : '', caller].filter(Boolean).join('\n\n');
+        return { type: 'preset', preset: 'claude_code', ...(append ? { append } : {}) };
+    }
+    if (!caller)
+        return base;
+    if (caller.includes(base))
+        return caller;
+    return [base, SYSTEM_PROMPT_DYNAMIC_BOUNDARY, caller];
+}
+const pendingAsks = new Map();
+/**
+ * ⚠ A TIMEOUT IS NOT AN ANSWER. It resolves with `outcome:'timeout'` so the
+ * agent can tell "they said no" from "they never saw it" — opposite situations,
+ * and collapsing them is how an agent decides silence means consent.
+ */
+const ASK_TIMEOUT_MS = 10 * 60_000;
+/** Answer a pending ask. Safe to call twice or with an unknown id — a late click
+ *  after a timeout and a double tap both land here and must be no-ops. */
+export function answerOmniAsk(askId, value, outcome = 'answered') {
+    const p = pendingAsks.get(askId);
+    if (!p)
+        return false;
+    clearTimeout(p.timer);
+    pendingAsks.delete(askId);
+    p.resolve({ value, outcome });
+    return true;
+}
+/** Settle every open ask. Called on session teardown, or the turn's await is
+ *  orphaned inside a query that is being disposed. */
+export function dismissOmniAsks() {
+    for (const id of [...pendingAsks.keys()])
+        answerOmniAsk(id, '', 'dismissed');
+}
+/**
+ * Build the principal context for a session and mount it.
+ *
+ * ⚠ ONE CALL, because the three halves must agree on the sessionId: `emit` tags
+ * events with it, `ask` tags questions with it, and a subscriber filters on it.
+ * Wiring them separately is how a two-conversation daemon starts rendering one
+ * session's questions into the other's panel.
+ */
+export function mountPrincipalTools(opts) {
+    setPrincipalTools({
+        invokeRpc: opts.invokeRpc,
+        cwd: opts.cwd,
+        canOpenWindows: opts.canOpenWindows,
+        emit: (event) => {
+            emit({ type: 'agent:principal', sessionId: opts.sessionId(), event });
+        },
+        ask: (ask) => new Promise((resolve) => {
+            const askId = `ask_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+            const timer = setTimeout(() => {
+                pendingAsks.delete(askId);
+                resolve({ value: '', outcome: 'timeout' });
+            }, ASK_TIMEOUT_MS);
+            // Never hold the daemon open for a question nobody is going to answer.
+            timer.unref?.();
+            pendingAsks.set(askId, { resolve, timer });
+            emit({ type: 'agent:ask', sessionId: opts.sessionId(), askId, ask });
+        }),
+    });
+}
+/** Whether the beehaven tools are mounted — for `omni:sessions` / diagnostics. */
+export function clearlyToolsMounted() {
+    return !!_clearlyMcpServer;
+}
+// ── Idle session cleanup (#49) ───────────────────────────────────────
+//
+// Each composition opens an SDK session that lives in memory until the
+// daemon process ends. Without cleanup, a user who opens 50 compositions
+// over a day accumulates 50 warm SDK loops in the daemon — eats memory
+// + risks file-descriptor exhaustion.
+//
+// Strategy: every minute, walk the session Map. Anything idle longer
+// than IDLE_TIMEOUT_MS gets endSession()'d. The SDK's JSONL on disk
+// survives — so when the user comes back to that composition, the
+// next promptOmni call re-primes from disk via findLatestSdkSessionId.
+// User-invisible reuse vs cold-start: a cold start costs one round-trip
+// to read the JSONL (~30ms) on the first prompt.
+//
+// Disabling: set BEEHAVEN_OMNI_IDLE_TIMEOUT_MS=0 to keep all sessions
+// alive forever (useful when debugging concurrency / cross-session
+// pollution issues; never set in production).
+const IDLE_TIMEOUT_MS = (() => {
+    const env = process.env.BEEHAVEN_OMNI_IDLE_TIMEOUT_MS;
+    if (env != null) {
+        const n = Number(env);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    return 30 * 60_000; // 30 min default
+})();
+const CLEANUP_INTERVAL_MS = 60_000;
+let cleanupTimer = null;
+function reapIdleSessions() {
+    if (IDLE_TIMEOUT_MS === 0)
+        return 0;
+    const now = Date.now();
+    let reaped = 0;
+    for (const [id, sess] of sessions) {
+        if (sess.turnInFlight)
+            continue; // never reap a session mid-turn
+        if (sess.queuedPrompts.length > 0)
+            continue; // pending work pending
+        if (now - sess.lastActivityAt > IDLE_TIMEOUT_MS) {
+            endSession(id);
+            reaped++;
+        }
+    }
+    return reaped;
+}
+function ensureCleanupTimer() {
+    if (cleanupTimer)
+        return;
+    if (IDLE_TIMEOUT_MS === 0)
+        return; // cleanup disabled
+    cleanupTimer = setInterval(() => {
+        const reaped = reapIdleSessions();
+        if (reaped > 0) {
+            // eslint-disable-next-line no-console
+            console.log(`[omni] reaped ${reaped} idle session(s); ${sessions.size} remain`);
+        }
+    }, CLEANUP_INTERVAL_MS);
+    // Don't keep the daemon process alive just for the sweep timer.
+    if (typeof cleanupTimer?.unref === 'function')
+        cleanupTimer.unref();
+}
+// ── Subscriber registration ─────────────────────────────────────────
+export function subscribe(fn) {
+    subscribers.add(fn);
+    return () => subscribers.delete(fn);
+}
+function emit(event) {
+    for (const fn of subscribers) {
+        try {
+            fn(event);
+        }
+        catch {
+            /* subscriber errors don't sink the loop */
+        }
+    }
+}
+// ── Composition cwd resolution (#47) ────────────────────────────────
+/**
+ * Resolve + initialize a composition-scoped working directory.
+ *
+ *   ~/.clearly/compositions/<compositionId>/
+ *     ├── CLAUDE.md                  ← auto-seeded; tells Claude where it is
+ *     └── .clearly-composition.json  ← machine-readable metadata
+ *
+ * Idempotent. Creates the dir + seeds files only on first call for a
+ * given compositionId. Subsequent sessions for the same composition
+ * reuse what's already there.
+ *
+ * The seeded CLAUDE.md is loaded automatically by the SDK because we
+ * set `settingSources: ['user','project','local']` in the session
+ * options — that includes `project` which triggers CLAUDE.md discovery
+ * from the cwd upward. So Claude opens the session already knowing
+ * which composition it's in, no per-turn prompt overhead.
+ */
+function resolveCompositionCwd(opts) {
+    const home = homedir();
+    // A composition bound to a real local repo wins: use it as the cwd
+    // verbatim and leave its CLAUDE.md untouched (the repo owns its own
+    // context). This is what makes a board 1:1 with the Claude Code project
+    // for that repo — the SDK runs in `<repo>` and its conversation lands in
+    // `~/.claude/projects/<encoded-repo-path>/`. Read fresh each call, so a
+    // new binding takes effect on the next session without a daemon restart.
+    // Unbound compositions fall through to the scratch-dir behavior below.
+    const boundRepo = resolveBoundRepo(opts.compositionId);
+    if (boundRepo)
+        return boundRepo;
+    const compDir = join(home, '.clearly', 'compositions', opts.compositionId);
+    try {
+        if (!existsSync(compDir)) {
+            mkdirSync(compDir, { recursive: true });
+        }
+        // Seed CLAUDE.md once. User edits OUTSIDE the AUTO-CONTEXT block
+        // are preserved — refresh only swaps the marker-delimited section.
+        const claudeMd = join(compDir, 'CLAUDE.md');
+        if (!existsSync(claudeMd)) {
+            writeFileSync(claudeMd, buildSeedClaudeMd(opts), 'utf8');
+        }
+        else if (opts.refresh) {
+            const current = (() => {
+                try {
+                    return readFileSync(claudeMd, 'utf8');
+                }
+                catch {
+                    return '';
+                }
+            })();
+            const updated = updateAutoContextBlock(current, opts);
+            if (updated !== current)
+                writeFileSync(claudeMd, updated, 'utf8');
+        }
+        // Refresh the metadata file every time — composition title can change,
+        // and consumers should see the latest. Small payload, safe to rewrite.
+        const meta = {
+            compositionId: opts.compositionId,
+            compositionTitle: opts.compositionTitle ?? null,
+            brand: opts.brand ?? null,
+            kind: 'clearly.composition',
+            version: 1,
+            updatedAt: new Date().toISOString(),
+        };
+        writeFileSync(join(compDir, '.clearly-composition.json'), JSON.stringify(meta, null, 2), 'utf8');
+    }
+    catch (err) {
+        // Don't fail the session if seeding fails — fall through to using
+        // the dir as-is or the default cwd. Worst case: Claude is missing
+        // the seeded CLAUDE.md but the session still works.
+        // eslint-disable-next-line no-console
+        console.warn(`[omni] composition cwd seed failed for ${opts.compositionId}: ${err?.message ?? err}`);
+    }
+    return compDir;
+}
+/**
+ * Refresh the per-composition CLAUDE.md from outside the session
+ * spawn path (#114). Called by the daemon when:
+ *   • the worker broadcasts a brand-update for this composition
+ *   • the user opens / focuses the composition (canvas-open IPC)
+ *
+ * Idempotent: noop when the AUTO-CONTEXT block matches what we'd write.
+ * Safe to call before the composition's cwd exists — `mkdirSync` is
+ * recursive.
+ */
+export function refreshCompositionClaudeMd(opts) {
+    return resolveCompositionCwd({ ...opts, refresh: true });
+}
+const AUTO_CONTEXT_BEGIN = '<!-- BEGIN CLEARLY AUTO-CONTEXT -->';
+const AUTO_CONTEXT_END = '<!-- END CLEARLY AUTO-CONTEXT -->';
+/** Replace the AUTO-CONTEXT block in an existing CLAUDE.md. Preserves
+ *  everything outside the markers. If the markers are missing (legacy
+ *  seed format), prepend the block above the existing content. */
+function updateAutoContextBlock(current, opts) {
+    const block = `${AUTO_CONTEXT_BEGIN}\n${buildAutoContext(opts)}\n${AUTO_CONTEXT_END}`;
+    const beginIdx = current.indexOf(AUTO_CONTEXT_BEGIN);
+    const endIdx = current.indexOf(AUTO_CONTEXT_END);
+    if (beginIdx >= 0 && endIdx > beginIdx) {
+        const before = current.slice(0, beginIdx);
+        const after = current.slice(endIdx + AUTO_CONTEXT_END.length);
+        return `${before}${block}${after}`;
+    }
+    return `${block}\n\n${current}`;
+}
+/**
+ * Find the most recent SDK conversation file for a given cwd.
+ *
+ * Claude Code's SDK writes session state to:
+ *   ~/.claude/projects/<encoded-cwd>/<session-uuid>.jsonl
+ *
+ * The encoding strategy: replace each `/` in the absolute cwd with `-`.
+ * `/Users/gemini/.clearly/compositions/abc/` → `-Users-gemini--clearly-compositions-abc`
+ *
+ * We use this to explicitly `resume` the latest session on subsequent
+ * daemon starts. The SDK's `continue: true` is supposed to do this
+ * automatically, but in our AsyncIterable input-stream mode it
+ * inconsistently forks new sessions instead of resuming — passing an
+ * explicit `resume: <session-id>` is reliable.
+ *
+ * Returns the session UUID (filename without .jsonl extension) of the
+ * most recently modified JSONL in the project dir, or null if none.
+ */
+function findLatestSdkSessionId(cwd) {
+    // Encode the cwd the same way Claude Code does: EVERY non-alphanumeric
+    // char becomes `-`, substituted independently (no collapsing of runs).
+    // Verified against ~/.claude/projects/:
+    //   /Users/gemini/.clearly/compositions/abc → -Users-gemini--clearly-compositions-abc
+    //   /Users/gemini/projects/motion_studio    → -Users-gemini-projects-motion-studio
+    // NB: the earlier `/[\/.]/g` only mapped `/` and `.`, so it left `_`
+    // (and spaces, etc.) intact — for a repo path like `…/motion_studio`
+    // it computed `…-motion_studio` and never found the real `…-motion-studio`
+    // project dir, silently starting a fresh session instead of resuming.
+    // Broadening to all non-alphanumerics makes resume work for bound repos
+    // whose paths contain `_` and other special chars (#47b).
+    const encoded = cwd.replace(/[^a-zA-Z0-9]/g, '-');
+    const projectDir = join(homedir(), '.claude', 'projects', encoded);
+    if (!existsSync(projectDir))
+        return null;
+    try {
+        const jsonls = readdirSync(projectDir)
+            .filter((f) => f.endsWith('.jsonl'))
+            .map((f) => {
+            const full = join(projectDir, f);
+            try {
+                return { id: f.replace(/\.jsonl$/, ''), mtime: statSync(full).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((x) => x !== null)
+            .sort((a, b) => b.mtime - a.mtime);
+        return jsonls[0]?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Build the AUTO-CONTEXT block content — the part of CLAUDE.md the
+ *  daemon refreshes on brand-update + composition-open. User-edited
+ *  content outside the markers is preserved. */
+function buildAutoContext(opts) {
+    const titleLine = opts.compositionTitle
+        ? `# ${opts.compositionTitle}\n\nComposition id: \`${opts.compositionId}\``
+        : `# Composition \`${opts.compositionId}\``;
+    const brandSection = (() => {
+        if (!opts.brand)
+            return '';
+        const lines = ['\n**Active brand**'];
+        if (opts.brand.name)
+            lines.push(`- Name: ${opts.brand.name}`);
+        if (opts.brand.palette?.length)
+            lines.push(`- Palette: ${opts.brand.palette.slice(0, 8).join(' · ')}`);
+        if (opts.brand.typography?.heading || opts.brand.typography?.body) {
+            const parts = [];
+            if (opts.brand.typography.heading)
+                parts.push(`heading "${opts.brand.typography.heading}"`);
+            if (opts.brand.typography.body)
+                parts.push(`body "${opts.brand.typography.body}"`);
+            lines.push(`- Typography: ${parts.join(', ')}`);
+        }
+        if (opts.brand.voice)
+            lines.push(`- Voice: ${opts.brand.voice}`);
+        lines.push(`- Apply these to anything you produce (canvas blocks, exports, Remotion components).`);
+        return lines.join('\n') + '\n';
+    })();
+    const updatedAt = new Date().toISOString();
+    return `${titleLine}
+
+You are inside a Clearly composition. This directory is the scratch
+workspace for this composition only — files you Read/Write here persist
+with it, separately from your other compositions.
+
+**Where you are**
+- This dir: \`~/.clearly/compositions/${opts.compositionId}/\`
+- The user's other projects live elsewhere (typically \`~/projects/\`).
+  cd into them with Bash when the user references a specific project;
+  this composition's CLAUDE.md chain doesn't include those projects'
+  CLAUDE.mds unless you've cd'd there.
+
+**The canvas**
+The user is looking at a spatial editor canvas. Use the canvas RPCs
+(canvas-add-text, canvas-add-document, canvas-add-album, etc.) via
+\`beehaven call <action> '<json>'\` to add blocks, documents, and
+albums that show up immediately for them.
+${brandSection}
+**Persistence**
+Your conversation persists across daemon restarts via the SDK's session
+JSONL. Continuing a conversation: open this composition again — same
+cwd, same session.
+
+_Auto-context refreshed at ${updatedAt}. Anything you write OUTSIDE the
+\`BEGIN/END CLEARLY AUTO-CONTEXT\` markers is preserved across refreshes._`;
+}
+/** Build the seed CLAUDE.md content for a fresh composition directory.
+ *  Kept terse — the user's `~/.claude/CLAUDE.md` carries their global
+ *  preferences; this file only adds composition-specific framing. The
+ *  auto-context block lives between markers so daemon-side refreshes
+ *  (brand-update, canvas-open) can swap it in place without clobbering
+ *  user edits below. */
+function buildSeedClaudeMd(opts) {
+    return `${AUTO_CONTEXT_BEGIN}
+${buildAutoContext(opts)}
+${AUTO_CONTEXT_END}
+
+<!-- Your additions go below this line — they're preserved across
+     auto-context refreshes. -->
+`;
+}
+/** Default max prompts queued per session before promptOmni rejects new
+ *  prompts. Configurable per-session via StartOmniSessionOptions.maxQueuedPrompts. */
+const DEFAULT_MAX_QUEUED_PROMPTS = 20;
+/** Default max Claude<>tool turn-cycles per prompt. The SDK's own knob;
+ *  we set a sane upper bound so a buggy tool loop doesn't burn budget. */
+const DEFAULT_MAX_TURNS = 30;
+/**
+ * Look up or create an Omni session. **Doesn't start the SDK** — that
+ * happens per-turn now. This function just sets up the per-session
+ * state (resolved cwd, captured config, turn counter). The actual
+ * SDK calls happen inside `runTurn()` below.
+ *
+ * If we're resuming a composition that has prior JSONL session files,
+ * the session's `sdkSessionId` is primed from the latest JSONL so the
+ * first turn after a daemon restart resumes the right conversation.
+ */
+function getOrCreateSession(opts) {
+    const existing = sessions.get(opts.sessionId);
+    if (existing)
+        return existing;
+    // Cwd resolution order (#47):
+    //   1. compositionId → ~/.clearly/compositions/<id>/ (auto-seeded)
+    //   2. explicit opts.cwd
+    //   3. $HOME (default for non-composition sessions)
+    //   4. process.cwd() (only when HOME is unset — Windows/weird envs)
+    const cwd = opts.compositionId
+        ? resolveCompositionCwd({
+            compositionId: opts.compositionId,
+            compositionTitle: opts.compositionTitle,
+        })
+        : (opts.cwd ?? process.env.HOME ?? process.cwd());
+    // Resume the latest JSONL session for this cwd if one exists (#48).
+    // Survives daemon restarts: even though our in-memory `sessions`
+    // Map is empty after restart, the SDK's project dir on disk still
+    // holds the conversation. We pick up the most-recently-modified
+    // JSONL and thread its session_id as `resume:` on every turn.
+    let primedSdkSessionId = null;
+    if (opts.resumeSessionId) {
+        primedSdkSessionId = opts.resumeSessionId;
+    }
+    else if (opts.continueSession !== false && opts.compositionId) {
+        primedSdkSessionId = findLatestSdkSessionId(cwd);
+    }
+    const session = {
+        sessionId: opts.sessionId,
+        userId: opts.userId,
+        config: opts,
+        cwd,
+        sdkSessionId: primedSdkSessionId,
+        ended: false,
+        turnInFlight: false,
+        queuedPrompts: [],
+        currentText: '',
+        principalStreamIdx: null,
+        principalTextReader: null,
+        turnIndex: 0,
+        startedAt: Date.now(),
+        lastActivityAt: Date.now(),
+    };
+    sessions.set(opts.sessionId, session);
+    // First-session lazy-start of the idle-cleanup sweeper. Idempotent —
+    // subsequent calls no-op. The timer is `unref()`d so it doesn't
+    // pin the event loop.
+    ensureCleanupTimer();
+    // Auto-register default tool-gate policies (#60) on first session.
+    // Idempotent. New policies plug in here.
+    //
+    // (#62 "sandbox-write" is NOT among them. A `daemon-write-sandbox.ts`
+    // existed for months describing itself as the guard that stops a buggy
+    // agent trashing the user's filesystem — and nothing ever imported it.
+    // It was removed rather than left looking wired; recover it with
+    // `git show db8580c:packages/cli/src/daemon-write-sandbox.ts` if the
+    // sandbox-then-commit flow gets built for real. Note the open design
+    // problem it left: writes land in a sandbox and only reach disk on
+    // commit, so an un-wired commit path silently loses the user's work —
+    // which is why it needs the approval UI, not just this registration.)
+    ensureDefaultPoliciesRegistered();
+    // Wire compaction observability (#99). Idempotent.
+    ensureCompactionEmitterWired();
+    return session;
+}
+/**
+ * Build the SDK Options for a single turn. Called once per turn so
+ * the `resume` option reflects the LATEST captured sdkSessionId.
+ * Everything else (model, cwd, tools, settingSources, etc.) is static
+ * per session and just re-passed each call.
+ */
+// Resolve once: write a `beehaven` shim into ~/.beehaven/bin and return that
+// dir. Spawned Claude Code sessions can then run `beehaven …` from Bash even
+// when the daemon's own PATH (a Finder-launched Mac app) doesn't include the
+// npm-linked wrapper. The shim just execs the daemon's own cli.js with node.
+let _beehavenBinDir;
+function ensureBeehavenOnPath() {
+    if (_beehavenBinDir !== undefined)
+        return _beehavenBinDir;
+    try {
+        const cliJs = join(dirname(fileURLToPath(import.meta.url)), 'cli.js');
+        if (!existsSync(cliJs)) {
+            _beehavenBinDir = null;
+            return null;
+        }
+        const binDir = join(homedir(), '.beehaven', 'bin');
+        mkdirSync(binDir, { recursive: true });
+        const wrapper = join(binDir, 'beehaven');
+        writeFileSync(wrapper, `#!/usr/bin/env bash\nexec "${process.execPath}" "${cliJs}" "$@"\n`, {
+            mode: 0o755,
+        });
+        try {
+            chmodSync(wrapper, 0o755);
+        }
+        catch {
+            /* write mode usually suffices */
+        }
+        _beehavenBinDir = binDir;
+        return binDir;
+    }
+    catch {
+        _beehavenBinDir = null;
+        return null;
+    }
+}
+/**
+ * ⚠ `turnContext` IS PER TURN, EVERYTHING ELSE IS PER SESSION. Where the work stands changes
+ * between turns — somebody moves the card, a gate gets met — so it cannot be baked into the
+ * session's `appendSystemPrompt` at creation. It is passed in and composed after the identity.
+ */
+function buildSdkOptions(session, claudeBinary, turnContext) {
+    const opts = session.config;
+    // Strip the nesting guard from env. The SDK refuses to spawn when
+    // CLAUDECODE=1 is set (its way of refusing to recurse). Daemon may
+    // have inherited it from whoever launched it.
+    const env = { ...process.env };
+    delete env.CLAUDECODE;
+    // Sign the spawned session in as this avatar's agent identity so its
+    // `beehaven speak` (and every `beehaven` call) runs AS that agent — which
+    // is what makes speak use the avatar's configured voice. Also ensure
+    // `beehaven` resolves on the child's PATH.
+    if (opts.agentName) {
+        env.BEEHAVEN_AGENT = opts.agentName;
+        const binDir = ensureBeehavenOnPath();
+        if (binDir)
+            env.PATH = `${binDir}:${env.PATH ?? ''}`;
+    }
+    return {
+        model: opts.model ?? 'claude-sonnet-4-6',
+        cwd: session.cwd,
+        env,
+        // Use the user's installed `claude` binary when available. Avoids
+        // the "Native CLI binary for {platform}-{arch} not found" error
+        // that fires when the bundled @anthropic-ai/claude-agent-sdk-*
+        // platform package isn't shipped with the Mac app, AND lets the
+        // SDK inherit the user's `claude login` auth from macOS Keychain
+        // automatically. When null (no local claude install), the SDK
+        // falls back to its own resolution and will error if the native
+        // package is also missing — that's the surface the caller needs
+        // to fix (install Claude Code, or set ANTHROPIC_API_KEY env var).
+        ...(claudeBinary ? { pathToClaudeCodeExecutable: claudeBinary } : {}),
+        tools: { type: 'preset', preset: 'claude_code' },
+        settingSources: ['user', 'project', 'local'],
+        skills: 'all',
+        // Omni's registered identity AS the system instruction, with the caller's
+        // per-call prompt layered after it. See `resolveSystemPrompt`.
+        // ⚠ The per-turn block follows the session's own modifier; both sit after the cache boundary,
+        //   which is where volatile text belongs.
+        systemPrompt: resolveSystemPrompt([opts.appendSystemPrompt, turnContext].filter(Boolean).join('\n\n')),
+        ...(opts.allowedTools ? { allowedTools: opts.allowedTools } : {}),
+        ...(opts.additionalDirectories?.length
+            ? { additionalDirectories: opts.additionalDirectories }
+            : {}),
+        // First-party beehaven tools, then anything the caller layered on. The
+        // caller wins on a key collision so a session can still substitute its own
+        // `clearly` server (tests, a scoped surface) without editing this.
+        ...(() => {
+            const servers = {
+                ...(_clearlyMcpServer ? { clearly: _clearlyMcpServer } : {}),
+                // Omni's own surface, mounted when something is attached to render it.
+                ...(_principalMcpServer ? { principal: _principalMcpServer } : {}),
+                ...(opts.mcpServers ?? {}),
+            };
+            return Object.keys(servers).length ? { mcpServers: servers } : {};
+        })(),
+        // Resume / fork resolution:
+        //   • forkFromSdkSessionId set → resume that id with forkSession:true
+        //     so the SDK clones the prefix into a new session id. Used by
+        //     branchSession (#79). After the first turn captures the fork's
+        //     new session_id into sdkSessionId, the flag is cleared.
+        //   • sdkSessionId set (no fork pending) → normal resume (#48).
+        //   • neither → fresh session, SDK starts a new JSONL.
+        ...(session.forkFromSdkSessionId
+            ? { resume: session.forkFromSdkSessionId, forkSession: true }
+            : session.sdkSessionId
+                ? { resume: session.sdkSessionId }
+                : {}),
+        // canUseTool framework (#58). The SDK calls this before every tool
+        // execution. Our gate composes N policies (cost gates, tier checks,
+        // path transforms, FAB approval cards, …) — see daemon-omni-tool-
+        // gate.ts. Default policy set is empty; sibling modules register
+        // policies they care about (e.g. #60-63 plug in here).
+        //
+        // Note: when permissionMode is 'bypassPermissions', the SDK
+        // SHORT-CIRCUITS canUseTool calls — we still pass it through so the
+        // gate runs when callers switch to 'default' or 'dontAsk' mode.
+        canUseTool: buildToolGate({ sessionId: session.sessionId, userId: session.userId }),
+        // Default SDK hooks (#84 + future #83/#85). PostToolUse fires
+        // after each tool call; our hook sniffs Bash output for known
+        // error patterns and injects a remediation hint into Claude's
+        // next-turn context. See daemon-omni-hooks.ts.
+        hooks: getDefaultHooks(),
+        includePartialMessages: true,
+        // Permission mode + maxTurns are now caller-configurable (see
+        // StartOmniSessionOptions). Defaults:
+        //   - permissionMode: 'default' (was 'bypassPermissions') — the SDK's
+        //     built-in safety prompts run AND our canUseTool gate runs.
+        //     bypassPermissions short-circuits the gate, so changing the
+        //     default fixes the "no safety surface" concern raised in audit
+        //     task #63.
+        //   - maxTurns: 30 — prevents runaway tool-call loops billing the
+        //     user without bound. Disable explicitly by passing 0.
+        permissionMode: opts.permissionMode ?? 'default',
+        ...(opts.permissionMode === 'bypassPermissions'
+            ? { allowDangerouslySkipPermissions: true }
+            : {}),
+        ...((opts.maxTurns ?? DEFAULT_MAX_TURNS) > 0
+            ? { maxTurns: opts.maxTurns ?? DEFAULT_MAX_TURNS }
+            : {}),
+        ...(opts.abortController ? { abortController: opts.abortController } : {}),
+    };
+}
+/**
+ * Run a single Claude turn. One-shot string prompt → one `query()`
+ * call → consume messages until `result`. Captures the SDK's
+ * session_id from the init message so subsequent turns can resume the
+ * same JSONL.
+ *
+ * Architectural note: we previously used the SDK's AsyncIterable input
+ * mode (`query({ prompt: asyncIterable })`) to keep one query() alive
+ * across turns. That mode silently broke `resume` — the SDK forked a
+ * new session_id on every turn. Switching to one query() per turn
+ * with explicit `resume: sdkSessionId` made cross-restart persistence
+ * work reliably. See #48.
+ */
+async function runTurn(session, prompt) {
+    if (session.ended)
+        return;
+    session.turnInFlight = true;
+    session.currentText = '';
+    session.principalStreamIdx = null;
+    session.principalTextReader = null;
+    const turnStart = Date.now();
+    /**
+     * ⚠ ONE CONTROLLER PER TURN, held on the session so `interruptSession` can
+     * reach it.
+     *
+     * `abortController` was already an OPTION on the session config and nothing
+     * ever created one, so there was no way to stop a turn in flight — the only
+     * interrupt available was ending the session, which loses the conversation.
+     * A per-turn controller is the right lifetime: aborting turn 3 must not leave
+     * a tripped signal that kills turn 4 the moment it starts.
+     */
+    const abort = new AbortController();
+    session.abort = abort;
+    /**
+     * ⚠ WHICH SESSION THE PRINCIPAL TOOLS ARE SPEAKING FOR.
+     *
+     * A tool handler gets its arguments and nothing else — no session, no caller.
+     * So `reply_to_principal` cannot know which conversation it belongs to, and
+     * every principal event has to be tagged from here.
+     *
+     * The first version hardcoded `'omni'` at mount time. Sessions are keyed by
+     * the caller (`'default'` unless named), so every reply was broadcast under a
+     * session id no subscriber was listening for: the tool call succeeded, the
+     * event went out, and the chat showed nothing. Found by calling it.
+     */
+    _activeTurnSessionId = session.sessionId;
+    try {
+        const claudeBinary = await getClaudeBinary();
+        /**
+         * ⚠⚠ REFUSE HERE, IN WORDS SOMEBODY CAN ACT ON.
+         *
+         * The native binary is NOT bundled — the SDK's eight optional platform packages are not
+         * installed in this monorepo and no build copies one, because each is ~200 MB against a
+         * 561 MB app. So on a machine that has never installed Claude Code, `findClaudeBinary()`
+         * legitimately returns null and this is the normal, expected state — not a fault.
+         *
+         * ⚠ HANDING `null` TO THE SDK produces *"Native CLI binary for darwin-arm64 not found"*, which
+         * names an internal package and no action. The person reading it has done nothing wrong and
+         * cannot tell whether the product is broken or whether they are missing a prerequisite.
+         * A one-line install command is the whole difference.
+         */
+        if (!claudeBinary) {
+            emit({
+                type: 'agent:error',
+                sessionId: session.sessionId,
+                error: 'Claude Code is not installed on this machine, so there is nothing to run this turn. '
+                    + 'Install it from https://claude.com/claude-code (or `npm i -g @anthropic-ai/claude-code`), '
+                    + 'then run `claude login` once. Clearly uses your own Claude subscription or API key — '
+                    + 'it does not ship a copy.',
+            });
+            return;
+        }
+        /**
+         * ⚠⚠ READ THE BOARD, DO NOT ASSERT A STAGE. This is the pre-turn injection: where the active
+         * card stands and what its next gate is, derived from `work-status`. A block that asserted a
+         * stage could contradict the card the moment somebody moved it in the UI, and a model given
+         * two contradictory inventories follows whichever it read last.
+         *
+         * ⚠ NON-FATAL AND SILENT ON FAILURE. No active card, an older worker without `work-status`, an
+         * unreachable workspace — all produce no block rather than a wrong one. A turn with no work in
+         * front of it is a conversation.
+         */
+        let turnContext = '';
+        if (companyModeEnabled()) {
+            try {
+                const { activeWorkStatus } = await import('./daemon-omni-principal.js');
+                turnContext = workContextBlock(await activeWorkStatus());
+            }
+            catch {
+                turnContext = '';
+            }
+        }
+        const sdkOptions = buildSdkOptions(session, claudeBinary, turnContext || undefined);
+        const q = query({ prompt, options: { ...sdkOptions, abortController: abort } });
+        for await (const message of q) {
+            if (session.ended) {
+                try {
+                    q.interrupt?.();
+                }
+                catch { }
+                // ⚠ Breaking here ALWAYS leaks one unhandled rejection, and it cannot
+                // be caught at this layer. The implicit `iterator.return()` runs the
+                // SDK's cleanup from inside an async generator's `finally`
+                // (`Query closed before response received`), by which point nothing is
+                // awaiting it — so the surrounding try/catch never sees it.
+                //
+                // Measured, not assumed: pre-disposing with
+                // `Promise.resolve(q.return()).catch(()=>{})` before the break was
+                // tried and made NO difference — one rejection either way (A/B, same
+                // cancel, count before vs after). It was removed rather than left in
+                // as a comment claiming a fix it doesn't perform.
+                //
+                // The daemon's `unhandledRejection` handler is what actually keeps the
+                // process alive through a cancel. That is the fix; this is the note
+                // that stops the next person re-attempting this one.
+                break;
+            }
+            // Capture the SDK's session_id from the init message. The same id
+            // names the JSONL file in `~/.claude/projects/<encoded-cwd>/`.
+            // We thread it as `resume` on the next turn. When this turn was
+            // a fork (#79), the new id is the fork's id — clear the pending
+            // forkFromSdkSessionId so subsequent turns just resume normally.
+            if (message?.type === 'system' && message.session_id) {
+                session.sdkSessionId = message.session_id;
+                if (session.forkFromSdkSessionId) {
+                    session.forkFromSdkSessionId = undefined;
+                }
+            }
+            handleSdkMessage(session, message);
+            if (message?.type === 'result')
+                break;
+        }
+    }
+    catch (err) {
+        emit({
+            type: 'agent:error',
+            sessionId: session.sessionId,
+            error: err?.message ?? String(err),
+        });
+    }
+    finally {
+        session.turnInFlight = false;
+        // Cleared so a later interrupt cannot abort a turn that is not running.
+        if (session.abort === abort)
+            session.abort = undefined;
+        session.lastActivityAt = Date.now();
+        const durationMs = Date.now() - turnStart;
+        // The result event already fires inside handleSdkMessage but we
+        // also emit done here for the turnIndex/durationMs accounting,
+        // mirroring the old flow's per-turn summary.
+        // (handleSdkMessage's done handler is the authoritative one when
+        // a result message arrives; this branch only catches the path
+        // where the loop exits without a result, e.g. interrupted turn.)
+        if (durationMs > 0 && !session.ended && session.queuedPrompts.length === 0) {
+            // turnIndex was bumped by handleSdkMessage's result handler.
+            // Nothing extra to emit here for the happy path.
+        }
+        // Drain any queued prompts. Concurrent calls to promptOmni while
+        // a turn was running get processed FIFO here.
+        const next = session.queuedPrompts.shift();
+        if (next && !session.ended) {
+            void runTurn(session, next).catch((e) => {
+                emit({
+                    type: 'agent:error',
+                    sessionId: session.sessionId,
+                    error: e?.message ?? String(e),
+                });
+            });
+        }
+    }
+}
+function handleSdkMessage(session, message) {
+    /**
+     * Stream-partial. Ordinary assistant text is private model output and keeps
+     * its historical `agent:text-delta` channel. A `reply_to_principal` call is
+     * different: its `text` argument is what the person is waiting to read, so
+     * decode that argument and send a principal-scoped delta as soon as it is
+     * available. The completed MCP tool still emits the authoritative `prose`
+     * event below; the desktop adapter reconciles the two without duplicating it.
+     */
+    if (message?.type === 'stream_event') {
+        const event = message.event;
+        if (event?.type === 'content_block_start' && event.content_block?.type === 'tool_use') {
+            const name = String(event.content_block.name ?? '');
+            if (name.endsWith('reply_to_principal')) {
+                session.principalStreamIdx = Number(event.index);
+                session.principalTextReader = new PrincipalTextReader();
+            }
+        }
+        else if (event?.type === 'content_block_delta') {
+            const delta = event.delta;
+            if (delta?.type === 'text_delta' && typeof delta.text === 'string') {
+                session.currentText += delta.text;
+                emit({ type: 'agent:text-delta', sessionId: session.sessionId, text: delta.text });
+            }
+            else if (delta?.type === 'input_json_delta'
+                && Number(event.index) === session.principalStreamIdx
+                && session.principalTextReader) {
+                const text = session.principalTextReader.push(String(delta.partial_json ?? ''));
+                if (text) {
+                    emit({
+                        type: 'agent:principal',
+                        sessionId: session.sessionId,
+                        event: { kind: 'prose-delta', text },
+                    });
+                }
+            }
+        }
+        else if (event?.type === 'content_block_stop' && Number(event.index) === session.principalStreamIdx) {
+            session.principalStreamIdx = null;
+            session.principalTextReader = null;
+        }
+        return;
+    }
+    // Assistant message — full turn body (text + tool_use blocks).
+    // Tool calls fire here, before they execute. We mirror them as
+    // tool-call events so the FAB can show "Claude is using Bash...".
+    if (message?.type === 'assistant') {
+        const content = message?.message?.content;
+        if (Array.isArray(content)) {
+            for (const block of content) {
+                if (block?.type === 'tool_use') {
+                    emit({
+                        type: 'agent:tool-call',
+                        sessionId: session.sessionId,
+                        callId: block.id ?? `tool-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+                        tool: block.name ?? 'unknown',
+                        input: block.input ?? {},
+                    });
+                }
+            }
+        }
+        return;
+    }
+    // Tool result — the SDK already ran the tool. We surface a small
+    // preview (first 200 chars) so the FAB can show "ran successfully"
+    // / "errored" without dumping the full output back through.
+    if (message?.type === 'user') {
+        const content = message?.message?.content;
+        if (Array.isArray(content)) {
+            for (const block of content) {
+                if (block?.type === 'tool_result') {
+                    const raw = typeof block.content === 'string'
+                        ? block.content
+                        : Array.isArray(block.content)
+                            ? block.content.map((p) => p?.text ?? '').join('')
+                            : '';
+                    emit({
+                        type: 'agent:tool-result',
+                        sessionId: session.sessionId,
+                        callId: block.tool_use_id ?? 'unknown',
+                        tool: '', // ← human-readable name lives on the matching tool-call event
+                        ok: !block.is_error,
+                        preview: raw ? raw.slice(0, 200) : undefined,
+                    });
+                }
+            }
+        }
+        return;
+    }
+    // Result — the SDK's per-turn completion marker. We use it to:
+    //   (a) bump the turn counter
+    //   (b) emit the aggregated text for telemetry/transcript
+    //   (c) reset session.currentText for the next turn
+    if (message?.type === 'result') {
+        session.turnIndex += 1;
+        const result = message?.result;
+        emit({
+            type: 'agent:turn-complete',
+            sessionId: session.sessionId,
+            turnIndex: session.turnIndex,
+        });
+        emit({
+            type: 'agent:done',
+            sessionId: session.sessionId,
+            result: {
+                text: session.currentText || (typeof result === 'string' ? result : undefined),
+                turns: session.turnIndex,
+                durationMs: Date.now() - session.startedAt,
+            },
+        });
+        session.currentText = '';
+        return;
+    }
+    // System messages (init, models, etc.) — emitted by SDK at startup.
+    // We don't surface them; they're noise for the FAB.
+}
+/**
+ * Push a user message into an Omni session. If the session doesn't
+ * exist it's created and the SDK starts immediately. Resolves when
+ * the SDK has consumed the message (not when the response completes —
+ * subscribers see streaming events for that). Use this to drive a
+ * multi-turn chat: call once per user message; each call reuses the
+ * same SDK process if the sessionId is the same.
+ */
+export async function promptOmni(input) {
+    const session = getOrCreateSession({
+        sessionId: input.sessionId,
+        userId: input.userId,
+        agentName: input.agentName,
+        model: input.model,
+        appendSystemPrompt: input.appendSystemPrompt,
+        cwd: input.cwd,
+        compositionId: input.compositionId,
+        compositionTitle: input.compositionTitle,
+        allowedTools: input.allowedTools,
+        continueSession: input.continueSession,
+        resumeSessionId: input.resumeSessionId,
+        additionalDirectories: input.additionalDirectories,
+        mcpServers: input.mcpServers,
+    });
+    if (session.ended) {
+        throw new Error(`Omni session ${input.sessionId} has ended; start a new one.`);
+    }
+    // Concurrency model: one turn per session at a time. Subsequent
+    // calls during an in-flight turn queue FIFO and drain when the
+    // active turn finishes (see runTurn's finally block).
+    if (session.turnInFlight) {
+        // Queue cap (audit task #65). Without this, a client flooding the
+        // daemon with prompts grows the queue without bound — OOM under
+        // buggy clients or abuse.
+        const maxQueued = session.config.maxQueuedPrompts ?? DEFAULT_MAX_QUEUED_PROMPTS;
+        if (session.queuedPrompts.length >= maxQueued) {
+            throw new Error(`QUEUE_FULL: session ${input.sessionId} has ${session.queuedPrompts.length} prompts queued (max ${maxQueued}). ` +
+                `Wait for the current turn to finish or end this session.`);
+        }
+        session.queuedPrompts.push(input.prompt);
+    }
+    else {
+        // Fire-and-forget — subscribers see streaming events. promptOmni
+        // resolves immediately, the SDK runs in the background.
+        void runTurn(session, input.prompt).catch((err) => {
+            emit({
+                type: 'agent:error',
+                sessionId: session.sessionId,
+                error: err?.message ?? String(err),
+            });
+        });
+    }
+    return { sessionId: input.sessionId };
+}
+/** Terminate a session — drops in-memory state. The SDK's JSONL on
+ *  disk survives, so the same compositionId can be reopened later
+ *  and the conversation picks up via findLatestSdkSessionId. */
+/**
+ * Stop the turn in flight WITHOUT ending the session.
+ *
+ * ⚠ THE DISTINCTION FROM `endSession` IS THE WHOLE POINT. Ending a session drops
+ * the conversation; this is the Esc key — the user changed their mind about what
+ * they asked for, not about talking. It also settles any question the turn was
+ * parked on, or the tool call awaiting an answer is orphaned inside a query that
+ * is being torn down.
+ */
+export async function interruptSession(sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session?.turnInFlight || !session.abort)
+        return false;
+    dismissOmniAsks();
+    try {
+        session.abort.abort();
+    }
+    catch { /* already aborted */ }
+    return true;
+}
+export function endSession(sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session)
+        return;
+    session.ended = true;
+    session.queuedPrompts.length = 0;
+    sessions.delete(sessionId);
+}
+/**
+ * Branch a session (#79). Forks the JSONL conversation at the most
+ * recent turn — caller gets a new sessionId that starts from the
+ * same history but diverges from here. The SDK's `forkSession: true`
+ * (paired with `resume`) does the work — we just mint a new
+ * omniSessionId, find the latest JSONL for the source session's cwd,
+ * and start an SDK query() with both options.
+ *
+ * The first prompt to the new branch creates a fresh JSONL on disk.
+ * Subsequent prompts to the same branch resume normally.
+ *
+ * v1 forks at the LATEST turn (SDK's native fork semantic). Mid-
+ * conversation forking (at a specific turn N) requires JSONL
+ * truncation — added later when the use case demands it.
+ */
+export function branchSession(opts) {
+    const source = sessions.get(opts.sourceSessionId);
+    // Source session may not exist in-memory (daemon restart). We can
+    // still branch by looking up the latest JSONL on disk if compositionId
+    // is provided — the cwd derives the JSONL location.
+    let sourceSdkSessionId = source?.sdkSessionId ?? null;
+    if (!sourceSdkSessionId && opts.compositionId) {
+        const cwd = resolveCompositionCwd({ compositionId: opts.compositionId });
+        sourceSdkSessionId = findLatestSdkSessionId(cwd);
+    }
+    const newSessionId = `${opts.sourceSessionId}-branch-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    if (sourceSdkSessionId) {
+        // Pre-register the new session with forkFromSdkSessionId set. Next
+        // promptOmni({sessionId: newSessionId}) call: buildSdkOptions sees
+        // the flag and emits resume+forkSession to the SDK. The fork's new
+        // session_id is captured back into sdkSessionId on first response,
+        // and the flag is cleared. Subsequent turns resume normally.
+        const baseConfig = source?.config ?? {
+            sessionId: newSessionId,
+            userId: source?.userId ?? 'local',
+            compositionId: opts.compositionId,
+        };
+        sessions.set(newSessionId, {
+            sessionId: newSessionId,
+            userId: source?.userId ?? 'local',
+            config: { ...baseConfig, sessionId: newSessionId },
+            cwd: source?.cwd ??
+                (opts.compositionId
+                    ? resolveCompositionCwd({ compositionId: opts.compositionId })
+                    : (process.env.HOME ?? process.cwd())),
+            sdkSessionId: null, // populated by fork response
+            forkFromSdkSessionId: sourceSdkSessionId,
+            ended: false,
+            turnInFlight: false,
+            queuedPrompts: [],
+            currentText: '',
+            principalStreamIdx: null,
+            principalTextReader: null,
+            turnIndex: 0,
+            startedAt: Date.now(),
+            lastActivityAt: Date.now(),
+        });
+    }
+    return { newSessionId, sourceSdkSessionId };
+}
+/** Diagnostics — list active sessions for the daemon status menu. */
+export function listSessions() {
+    const now = Date.now();
+    return Array.from(sessions.values()).map((s) => ({
+        sessionId: s.sessionId,
+        userId: s.userId,
+        turns: s.turnIndex,
+        ageMs: now - s.startedAt,
+        idleMs: now - s.lastActivityAt,
+        sdkSessionId: s.sdkSessionId,
+        cwd: s.cwd,
+        turnInFlight: s.turnInFlight,
+    }));
+}
+/**
+ * Turn what a person typed into an absolute directory, or say why it is not one.
+ *
+ * ⚠ PURE AND EXPORTED SO IT CAN BE TESTED. Every trap in changing a cwd lives here — `~` that
+ * nothing downstream expands, a path that does not exist, a path that is a FILE — and none of them
+ * can be exercised through `setSessionCwd` without a live SDK session, which needs a real Claude
+ * binary. Untestable validation is validation nobody checks.
+ *
+ * ⚠ IT VALIDATES UP FRONT rather than letting the SDK discover it. A typo'd cwd is otherwise not
+ * caught until the next turn spawns, where it surfaces as an opaque tool failure far from the
+ * moment somebody set it.
+ */
+export function resolveCwdInput(cwd) {
+    const next = String(cwd ?? '').trim();
+    if (!next)
+        return { ok: false, code: 'no-cwd', error: 'cwd is required' };
+    // ⚠ `~` is not expanded by anything downstream; expanding it here is the difference between a
+    //   path a person can type and one only a shell can produce.
+    const resolved = next === '~' || next.startsWith('~/')
+        ? join(process.env.HOME ?? '', next.slice(1))
+        : resolvePath(next);
+    let stat;
+    try {
+        stat = statSync(resolved);
+    }
+    catch {
+        return { ok: false, code: 'not-found', error: `no such directory: ${resolved}` };
+    }
+    if (!stat.isDirectory())
+        return { ok: false, code: 'not-a-directory', error: `not a directory: ${resolved}` };
+    return { ok: true, cwd: resolved };
+}
+/**
+ * Move a session's working directory.
+ *
+ * ⚠⚠ THE SDK CONVERSATION DOES NOT COME WITH IT, AND SAYING SO IS THE POINT. Claude Code stores a
+ * session's JSONL under a project directory derived from the cwd, and `findLatestSdkSessionId`
+ * resolves the thread to resume BY cwd. Carrying `sdkSessionId` into a new directory either fails
+ * or silently resumes a thread that belongs somewhere else — so it is CLEARED, the next turn starts
+ * fresh in the new directory, and the caller is told (`threadReset: true`) so it can say so rather
+ * than letting someone discover it by finding an agent with no memory of the last five minutes.
+ *
+ * ⚠ REFUSED MID-TURN. Changing the ground under a running turn means the tools it already decided
+ * to call resolve against a directory it never saw. Refusing is recoverable; a half-moved turn is
+ * not.
+ *
+ * ⚠ THE DIRECTORY MUST EXIST. A typo'd cwd is not caught until the SDK spawns, and then it fails
+ * as an opaque tool error on the next turn rather than at the moment somebody set it.
+ */
+export function setSessionCwd(sessionId, cwd) {
+    const s = sessions.get(String(sessionId ?? ''));
+    if (!s)
+        return { ok: false, code: 'no-session', error: `no session ${sessionId}` };
+    if (s.ended)
+        return { ok: false, code: 'ended', error: 'session has ended' };
+    if (s.turnInFlight)
+        return { ok: false, code: 'busy', error: 'a turn is running — interrupt it or wait' };
+    const r = resolveCwdInput(cwd);
+    if (!r.ok)
+        return r;
+    const resolved = r.cwd;
+    const previous = s.cwd;
+    if (previous === resolved)
+        return { ok: true, cwd: resolved, previous, threadReset: false };
+    s.cwd = resolved;
+    s.sdkSessionId = null;
+    return { ok: true, cwd: resolved, previous, threadReset: true };
+}