@crouton-kit/crouter 0.3.28 → 0.3.30

package/dist/core/runtime/spawn.js

@@ -2,31 +2,40 @@
 // a running pi process on the canvas. Composes canvas (birth + spine), persona
 // (resolve), launch (pi argv), and tmux (placement).
 //
-//   bootRoot   — the user-opened front door (bare `crtr`). Resident; runs pi
-//                inline, taking over the current terminal.
+//   bootRoot   — the user-opened front door (bare `crtr`). Resident; launches the
+//                root's broker engine, then execs `crtr attach` inline so THIS
+//                terminal becomes the broker's controller-viewer.
 //   spawnChild — a node spawned by a live node (`crtr node new`). A managed,
 //                terminal background worker by default; with `root`, an
 //                INDEPENDENT resident root (no subscription back to the spawner,
 //                provenance via spawned_by) brought forefront for direct driving.
 import { spawnSync } from 'node:child_process';
-import { join } from 'node:path';
-import { FRONT_DOOR_ENV } from './front-door.js';
-import { readConfig } from '../config.js';
-import { jobDir } from '../canvas/paths.js';
-import { spawnNode, currentNodeContext, resolveBirthSession, nodeSession, rootOfSpine } from './nodes.js';
+import { readdirSync, existsSync } from 'node:fs';
+import { isAbsolute, resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnNode, currentNodeContext, rootOfSpine } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
 import { installMenuBinding, installNavBindings, installViewNavBindings } from './tmux-chrome.js';
-import { setPresence, updateNode, getNode, fullName } from '../canvas/index.js';
-import { registerRootFocus, ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, focusWindow, waitForBrokerViewSocket, } from './placement.js';
+import { getNode, fullName } from '../canvas/index.js';
+import { registerViewerFocus, openViewerWindow, waitForBrokerViewSocket, viewerSplitEnv, windowOfPane, currentTmux, inTmux, focusWindow, } from './placement.js';
 import { transition } from './lifecycle.js';
 import { headlessBrokerHost } from './host.js';
 import { ensureDaemon } from '../../daemon/manage.js';
-/** Create a root node and bring up its pi. Returns the node; for 'inline' this
- *  only returns after pi exits (it took over the terminal). */
+/** Create the front-door root: launch its broker engine, then exec `crtr attach`
+ *  inline so THIS terminal becomes the broker's controller-viewer. Does not
+ *  return — it process.exit()s when the inline attach exits (detach leaves the
+ *  resident broker running, to be reconnected later). */
 export function bootRoot(opts) {
+    // crtr is tmux-only: the front door execs `crtr attach` inline in THIS pane to
+    // become the root's controller-viewer, so there must be a tmux pane to anchor
+    // on. Outside tmux there is no viewer surface — throw with a friendly message
+    // rather than boot a root nobody can see.
+    if (!inTmux()) {
+        throw new Error('crtr must be started from inside a tmux session — start tmux first (e.g. `tmux new -s work`), then run `crtr` there.');
+    }
     // The thin supervisor must be up before any node exists, so a refresh-yield
     // or crash can be reaped/revived. Idempotent.
     try {
@@ -34,10 +43,6 @@ export function bootRoot(opts) {
     }
     catch { /* daemon is best-effort */ }
     const kind = opts.kind ?? 'general';
-    // Host precedence: explicit --headless/--no-headless flag > config `headless`
-    // default > tmux. Mirrors `crtr node new`'s resolution (commands/node.ts).
-    const headless = opts.headless ?? readConfig('user').headless === true;
-    const hostKind = headless ? 'broker' : 'tmux';
     // A born-resident root starts in base mode; it earns the orchestrator persona
     // the first time it delegates (or on promotion). Resident lifecycle either way.
     const { launch } = buildLaunchSpec(kind, 'base', { lifecycle: 'resident', hasManager: false });
@@ -52,135 +57,140 @@ export function bootRoot(opts) {
         cwd: opts.cwd,
         name: opts.name ?? kind,
         parent: null,
-        hostKind,
         launch,
     });
     // Persist the spawning prompt as the goal so a fresh revive can re-read its
     // mandate (bare `crtr` has none — writeGoal no-ops on empty).
     if (opts.prompt !== undefined)
         writeGoal(meta.node_id, opts.prompt);
-    // Every node window — root or child — lives in the one shared session.
-    const session = nodeSession();
-    ensureSession(session, opts.cwd);
     // Make the Alt+C action menu + Alt+] / Alt+[ node-nav keys + Alt+V then ]/[
-    // view-nav chord live on this server (idempotent, in-tmux only).
-    if (inTmux()) {
-        try {
-            installMenuBinding();
-        }
-        catch { /* best-effort */ }
-        try {
-            installNavBindings();
-        }
-        catch { /* best-effort */ }
-        try {
-            installViewNavBindings();
-        }
-        catch { /* best-effort */ }
+    // view-nav chord live on this server (idempotent; guaranteed in tmux above).
+    try {
+        installMenuBinding();
     }
-    // HEADLESS front door: a broker root has NO engine pane — headlessBrokerHost
-    // launches a DETACHED broker that hosts the single engine + binds view.sock,
-    // opening no tmux window. So instead of exec'ing pi inline we boot the broker,
-    // wait for its socket, and auto-attach a VIEWER into THIS pane (the same
-    // `crtr attach` viewer focusBroker splits beside a caller). Presence stays
-    // null and NO focus row is registered — the viewer pane self-tags @crtr_node
-    // on connect, the handle node cycle/close/lifecycle resolve a broker by.
-    if (meta.host_kind === 'broker')
-        return bootRootBroker(meta, session, opts);
-    // inline: the root's pi takes over THIS terminal, so its own window stays
-    // where the user is (its tmux_session tracks that real pane so supervision
-    // sees it alive). But its children spawn into the shared global session via
-    // CRTR_ROOT_SESSION — they never clutter the user's working session.
+    catch { /* best-effort */ }
+    try {
+        installNavBindings();
+    }
+    catch { /* best-effort */ }
+    try {
+        installViewNavBindings();
+    }
+    catch { /* best-effort */ }
+    // This terminal becomes the root's attach VIEWER in the user's CURRENT session,
+    // so its window stays where the user already is. The node row carries NO
+    // presence — a broker node's pane/window/tmux_session stay NULL; the viewer
+    // pane lives in the focuses table (below).
     const here = currentTmux();
-    const adopted = resolveBirthSession({ adoptCaller: true, here, rootSession: undefined });
-    setPresence(meta.node_id, { tmux_session: adopted, window: here?.window ?? null, pane: here?.pane ?? null });
-    // REVIVE-HOME: the inline root's durable revive target is the session it
-    // adopts (the caller's when inside tmux, else the shared backstage). Set once
-    // at birth, alongside the live LOCATION above.
-    updateNode(meta.node_id, { home_session: adopted });
-    // Root boot registers focus #1 (§2.6): the FOREGROUND inline root owns the
-    // user's viewport, so its OWN pane becomes a durable focus (remain-on-exit so
-    // a clean exit freezes rather than detaching the terminal). A background
-    // `--root` (spawnChild) does NOT — it stays a plain window until the user
-    // focuses it (§6). Only possible inside tmux (a pane to anchor on).
-    if (here) {
+    // The FOREGROUND front-door terminal is the root's one viewer: record its pane
+    // as the node's viewer focus row so focus/nav can find it. The `crtr attach`
+    // exec below makes the terminal a controller-viewer of the broker; detaching
+    // leaves the resident broker running.
+    if (here !== null) {
         try {
-            registerRootFocus(meta.node_id, here.pane, adopted, here.window);
+            registerViewerFocus(meta.node_id, here.pane, here.session, here.window);
         }
         catch { /* best-effort */ }
     }
-    const withSession = getNode(meta.node_id);
-    const inv = buildPiArgv(withSession, { prompt: opts.prompt });
-    const env = { ...process.env, ...inv.env, CRTR_ROOT_SESSION: session, CRTR_SUBTREE: rootOfSpine(meta.node_id), [FRONT_DOOR_ENV]: '1' };
-    const r = spawnSync('pi', inv.argv, { stdio: 'inherit', env });
+    const inv = buildPiArgv(meta, { prompt: opts.prompt });
+    // Broker is the only host: the root runs as a detached broker engine (so its
+    // first refresh/revive doesn't strand this terminal — the daemon revives the
+    // broker and the viewer reconnects), and THIS terminal execs `crtr attach`
+    // inline to become its controller-viewer. The host sets CRTR_FRONT_DOOR.
+    inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
+    const placed = headlessBrokerHost.launch(meta.node_id, inv, {
+        cwd: opts.cwd,
+        name: fullName(meta),
+        resuming: false,
+    });
+    // No broker pid ⇒ the root has no engine. Crash it (so the daemon won't watch a
+    // zombie 'active') and throw — there is nothing to attach to.
+    if (placed.pid === null) {
+        transition(meta.node_id, 'crash');
+        throw new Error(`failed to launch the broker engine for the front-door root ${meta.node_id} — nothing to attach to.`);
+    }
+    // The terminal has nothing to attach to until view.sock accepts. The root is
+    // useless without its engine, so a socket timeout IS fatal here (unlike a
+    // background child's optional viewer, which is skipped on timeout).
+    if (!waitForBrokerViewSocket(meta.node_id)) {
+        throw new Error(`the front-door root broker ${meta.node_id} never bound its view socket — cannot attach.`);
+    }
+    const attachEnv = { ...process.env, ...viewerSplitEnv() };
+    const r = spawnSync('crtr', ['attach', 'to', meta.node_id], { stdio: 'inherit', env: attachEnv });
     process.exit(r.status ?? 0);
 }
-/** The headless front door (host_kind==='broker'): launch a detached broker for
- *  this root, wait for its view.sock, then auto-attach a viewer INLINE in this
- *  pane. Mirrors placement.focusBroker (ensure-broker → wait-socket → viewer)
- *  but the viewer runs in the CURRENT pane (the front door owns it) rather than
- *  a split beside a caller. Never returns — it exits with the viewer's status. */
-function bootRootBroker(meta, session, opts) {
-    // The shared backstage this subtree's descendants flow into (CRTR_ROOT_SESSION
-    // below). Mirrors the inline path; for a broker it is also the (moot) revive
-    // home — broker revive launches a detached process, ignoring the session.
-    updateNode(meta.node_id, { home_session: session });
-    const withSession = getNode(meta.node_id);
-    const inv = buildPiArgv(withSession, { prompt: opts.prompt });
-    // Authoritative backstage routing on the ENGINE's env (the broker host merges
-    // inv.env into the detached broker process), mirroring the inline pi env.
-    inv.env = { ...inv.env, CRTR_ROOT_SESSION: session, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
-    // Launch the detached broker (it records its own pid as pi_pid via the
-    // stophook and binds view.sock). Returns placement all-null — no tmux window.
-    headlessBrokerHost.launch(meta.node_id, inv, { cwd: meta.cwd, name: fullName(meta), resuming: false });
-    // Close the cold-start race: the broker records its pid during extension bind,
-    // then opens view.sock LATER; attach connects once and exits "no broker" if we
-    // run it before listen(). Probe for an ACCEPTING socket before attaching. A
-    // timeout here does NOT mean the broker died — the engine is a resident root
-    // that keeps booting; we just can't attach yet, so point the user at re-focus.
-    if (!waitForBrokerViewSocket(meta.node_id)) {
-        process.stderr.write(`crtr: ${meta.node_id} is still starting its broker — it is running, but its viewer socket did not come up in time. ` +
-            `Re-focus the node to attach (\`crtr node focus ${meta.node_id}\`); see ${join(jobDir(meta.node_id), 'broker.log')} if it never appears.\n`);
-        process.exit(1);
+/** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
+ *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
+ *  deep-imported, and a ROOT import of `getAgentDir` would eager-load the entire
+ *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
+ *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
+ *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
+ *  the sessions dir — same vendoring rationale as pi-vendored.ts. */
+function piSessionsRoot() {
+    const env = process.env['PI_CODING_AGENT_DIR'];
+    const agentDir = env !== undefined && env !== '' ? env : join(homedir(), '.pi', 'agent');
+    return join(agentDir, 'sessions');
+}
+/** Resolve a bare/partial pi session uuid to its ABSOLUTE `.jsonl` path by
+ *  scanning pi's sessions store the way pi's own CLI does (exact id, else a
+ *  unique prefix). The broker fork seam (`SessionManager.forkFrom`) loads a FILE
+ *  and does NOT resolve a uuid, so a bare id must be resolved here or the fork
+ *  throws at boot. Session files are `<sessions>/<project>/<ts>_<id>.jsonl`. */
+function resolveSessionUuid(uuid) {
+    const sessionsRoot = piSessionsRoot();
+    if (!existsSync(sessionsRoot)) {
+        throw new Error(`--fork-from '${uuid}': no pi sessions store at ${sessionsRoot} to resolve it from — pass a node id or an absolute .jsonl path.`);
     }
-    // Auto-attach the VIEWER inline: re-invoke OUR OWN cli (process.execPath +
-    // its own execArgv + argv[1]) as `attach to <id>` so it needs no PATH `crtr`
-    // AND survives a loader-based launch (dev `tsx`/`--import` flags ride
-    // execArgv); stdio:'inherit' hands this pane to the viewer's raw-mode TUI.
-    // runAttach self-tags the pane @crtr_node on connect; ctrl+c/ctrl+d detaches
-    // and the broker engine runs on.
-    const entry = process.argv[1];
-    if (entry === undefined) {
-        process.stderr.write(`crtr: cannot resolve the crtr entrypoint to auto-attach; run \`crtr node focus ${meta.node_id}\`.\n`);
-        process.exit(1);
+    const matches = [];
+    for (const dir of readdirSync(sessionsRoot, { withFileTypes: true })) {
+        if (!dir.isDirectory())
+            continue;
+        const projDir = join(sessionsRoot, dir.name);
+        for (const f of readdirSync(projDir)) {
+            if (!f.endsWith('.jsonl'))
+                continue;
+            const stem = f.slice(0, -'.jsonl'.length);
+            const id = stem.slice(stem.lastIndexOf('_') + 1);
+            matches.push({ id, path: join(projDir, f) });
+        }
     }
-    const r = spawnSync(process.execPath, [...process.execArgv, entry, 'attach', 'to', meta.node_id], {
-        stdio: 'inherit',
-    });
-    process.exit(r.status ?? 0);
+    const exact = matches.filter((m) => m.id === uuid);
+    const hit = exact.length > 0 ? exact : matches.filter((m) => m.id.startsWith(uuid));
+    if (hit.length === 0)
+        throw new Error(`--fork-from '${uuid}': no pi session with that id found.`);
+    if (hit.length > 1) {
+        throw new Error(`--fork-from '${uuid}': ambiguous — ${hit.length} sessions match that id prefix; pass the full id or the .jsonl path.`);
+    }
+    return hit[0].path;
 }
-/** Resolve a `--fork-from` value to the source pi gets as `--fork <path|id>`.
- *  A live node id resolves to its captured session FILE (absolute, cwd-immune),
- *  falling back to its bare session id; a path or partial uuid passes straight
- *  through to pi. Throws when a known node has no session to fork yet. */
+/** Resolve a `--fork-from` value to an ABSOLUTE `.jsonl` source path for the
+ *  broker fork (`SessionManager.forkFrom`, which loads a file — never a bare id).
+ *  A live node id resolves to its captured session FILE (absolute, cwd-immune); a
+ *  relative path is made absolute; a bare/partial uuid is resolved against pi's
+ *  sessions store. Throws when a known node has no captured session file, or when
+ *  a uuid resolves to zero or multiple sessions. */
 export function resolveForkSource(value) {
     const v = value.trim();
     if (v === '')
         throw new Error('--fork-from requires a node id, session file, or session uuid.');
-    // A path (contains `/` or ends `.jsonl`) is a session file — hand it to pi as-is.
-    if (v.includes('/') || v.endsWith('.jsonl'))
-        return v;
-    // A live node id — fork from the conversation it has accumulated.
+    // A path (contains `/` or ends `.jsonl`) is a session file — ensure it is
+    // ABSOLUTE so the broker, launched in a different cwd, still resolves it.
+    if (v.includes('/') || v.endsWith('.jsonl')) {
+        return isAbsolute(v) ? v : resolve(process.cwd(), v);
+    }
+    // A live node id — fork from the conversation it has accumulated. Its captured
+    // session FILE is absolute; the broker cannot fork a bare session id.
     const n = getNode(v);
     if (n !== null) {
-        const src = n.pi_session_file ?? n.pi_session_id;
+        const src = n.pi_session_file;
         if (src === undefined || src === null || src === '') {
-            throw new Error(`node ${v} has no pi session yet — it has not started a conversation to fork from.`);
+            throw new Error(`node ${v} has no pi session yet — it has not captured a session FILE to fork from (the broker forks a .jsonl path, not a bare id).`);
         }
         return src;
     }
-    // Not a known node — treat as a bare/partial pi session id for pi to resolve.
-    return v;
+    // Not a known node — a bare/partial pi session uuid; resolve it to an absolute
+    // .jsonl (the broker fork won't resolve a uuid).
+    return resolveSessionUuid(v);
 }
 /** Resolve who a spawn is attributed to. A managed child needs a spine parent
  *  (explicit `--parent` or the calling node's CRTR_NODE_ID). A --root spawn
@@ -237,7 +247,6 @@ export function spawnChild(opts) {
         // the boot intro can detect this is a fork and re-assert the node's own
         // identity over the source's copied-in conversation.
         forkFrom: opts.forkFrom,
-        hostKind: opts.hostKind,
         modelOverride: opts.model,
         launch,
     });
@@ -271,90 +280,52 @@ export function spawnChild(opts) {
     }
     // (The three scoped long-term memory stores are seeded for EVERY node at birth
     // in spawnNode — no orchestrator-gated seeding needed here.)
-    // A managed CHILD lands in the shared global session: inherited from the
-    // parent's CRTR_ROOT_SESSION, else the default node session. A --root spawned
-    // from inside tmux instead opens its window in the CALLER'S CURRENT session,
-    // so it appears where the spawner is working rather than exiled to a separate
-    // crtr session. Either way the root's OWN descendants still flow to the shared
-    // session (childSession) via CRTR_ROOT_SESSION, to keep the subtree from
-    // cluttering the user's session.
-    const rootSessionEnv = process.env['CRTR_ROOT_SESSION'];
+    // A --root spawned from inside tmux opens its one viewer in the CALLER'S
+    // CURRENT session (below), so it appears where the spawner is working; a
+    // managed child is a headless broker with NO viewer at all.
     const here = root ? currentTmux() : null;
-    // The shared backstage the whole subtree flows into (this child's own
-    // CRTR_ROOT_SESSION): the inherited root session, else the default `crtr`.
-    const childSession = resolveBirthSession({ adoptCaller: false, here, rootSession: rootSessionEnv });
-    // Where THIS node's window opens — and its durable REVIVE-HOME. A managed
-    // child lands in the backstage; a --root adopts the caller's current session
-    // when inside tmux, so it appears where the spawner is working.
-    const session = resolveBirthSession({ adoptCaller: root, here, rootSession: rootSessionEnv });
-    ensureSession(session, opts.cwd);
-    // REVIVE-HOME set once at birth: a managed child's revive target is the
-    // backstage, never a user session — this is what keeps a background revive
-    // off the user's screen (the focus taint cannot reach it).
-    updateNode(meta.node_id, { home_session: session });
     const inv = buildPiArgv(meta, { prompt: kickoff, forkFrom });
-    // Belt-and-suspenders backstage routing emitted at EVERY launch site: the
-    // authoritative CRTR_ROOT_SESSION (this subtree's shared backstage) +
-    // CRTR_SUBTREE (this node's spine root). Hoisted ABOVE the host branch so the
-    // broker launch and the tmux command consume ONE authoritative env — the
-    // broker host merges inv.env, so a --headless --root broker would otherwise
-    // inherit the SPAWNER's subtree id via the lossy nodeEnv passthrough (review
-    // reuse MINOR-2). FRONT_DOOR is added per-consumer below (the broker host sets
-    // it itself; the tmux env const adds it).
-    inv.env = { ...inv.env, CRTR_ROOT_SESSION: childSession, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
-    // Birth LAUNCH branch on the PERSISTED host_kind (set at birth by spawnNode).
-    // A broker birth diverts AWAY from the tmux pane: the headless broker host
-    // launches a detached broker process (which records its own pid as pi_pid via
-    // the stophook) and returns placement fields all null — so we open NO tmux
-    // window and write NO tmux placement (presence stays null for a broker). The
-    // tmux path below is left completely UNCHANGED (byte-identical) for every
-    // non-broker spawn. Mirrors reviveNode's `hostFor(meta).launch(...)` shape.
-    if (meta.host_kind === 'broker') {
-        const placed = headlessBrokerHost.launch(meta.node_id, inv, {
-            cwd: meta.cwd,
-            name: fullName(meta),
-            resuming: false,
-        });
-        const saved = getNode(meta.node_id);
-        return { node: saved, window: placed.window, session: placed.session };
-    }
-    const env = { ...inv.env, [FRONT_DOOR_ENV]: '1' };
-    const command = piCommand(inv.argv);
-    // openNodeWindow now returns {window, pane}; pane is unused until the
-    // placement layer lands, so destructure the window and proceed unchanged.
-    const opened = openNodeWindow({
-        session,
+    // CRTR_SUBTREE (the spine root) rides the detached broker's env so it can group
+    // the subtree; the host sets CRTR_FRONT_DOOR itself.
+    inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
+    // Broker is the only host: launch the detached broker ENGINE. A managed child
+    // gets NO viewer — spawning it returns once the engine is launched and a human
+    // opens a viewer on demand via `crtr node focus` / `crtr attach`. A --root gets
+    // one foreground viewer below.
+    const placed = headlessBrokerHost.launch(meta.node_id, inv, {
+        cwd: meta.cwd,
         name: fullName(meta),
-        cwd: opts.cwd,
-        env,
-        command,
+        resuming: false,
     });
-    const window = opened?.window ?? null;
-    // Two-stage failure model. Opening the window is instant and definitive, so a
-    // failure here is reported SYNCHRONOUSLY: crash the node (so it isn't a zombie
-    // 'active' the daemon can't reap — it has no window to watch) and throw so
-    // `crtr node new` exits non-zero with a clear message for the caller. The node
-    // is still 'active' from spawnNode, so transition('crash') is a legal from-LIVE
-    // move — the last scattered node-status write, now through the lifecycle machine.
-    //
-    // pi BOOTING inside the window, by contrast, is inherently slow (and slower
-    // under load), so we stay optimistic and return status='active' the instant
-    // the window exists. A vehicle that then dies before its first session_start
-    // is caught by the daemon — it surfaces the boot failure up the spine rather
-    // than letting the node die silently (see crtrd.ts surfaceBootFailure).
-    if (window === null) {
+    // Definitive failure: no broker pid ⇒ the node has no engine. Crash it (so the
+    // daemon doesn't watch a zombie 'active') and throw so `crtr node new` exits
+    // non-zero. transition('crash') is a legal from-LIVE move (still 'active' from
+    // spawnNode). Mirrors the old window===null crash.
+    if (placed.pid === null) {
         transition(meta.node_id, 'crash');
-        throw new Error(`failed to open a tmux window for ${meta.node_id} (${meta.name}) in session '${session}' — the node was not started.`);
+        throw new Error(`failed to launch the broker engine for ${meta.node_id} (${meta.name}) — the node was not started.`);
     }
-    setPresence(meta.node_id, { tmux_session: session, window });
-    const saved = getNode(meta.node_id);
-    // A root is spawned to be driven directly — bring it forefront so whoever
-    // asked for it picks up the conversation. A child stays a background window.
-    if (root) {
-        try {
-            focusWindow(session, window);
+    // A --root is spawned to be DRIVEN directly: when the caller is inside tmux,
+    // open ONE foreground viewer in the caller's CURRENT session and bring it
+    // forefront so whoever asked for it picks up the conversation. Outside tmux a
+    // --root opens no viewer (an agent handing a root off) — never a throw. A
+    // managed child opens nothing. Non-fatal if tmux refuses (openViewerWindow
+    // returns null) or the socket never binds — `focus` opens a viewer later.
+    let window = null;
+    let session = null;
+    if (root && here !== null && waitForBrokerViewSocket(meta.node_id)) {
+        const viewer = openViewerWindow(meta.node_id, here.session, { name: fullName(meta), cwd: opts.cwd });
+        if (viewer !== null && viewer.pane !== null && viewer.pane !== '') {
+            session = here.session;
+            window = windowOfPane(viewer.pane);
+            if (window !== null) {
+                try {
+                    focusWindow(here.session, window);
+                }
+                catch { /* best-effort */ }
+            }
         }
-        catch { /* best-effort */ }
     }
+    const saved = getNode(meta.node_id);
     return { node: saved, window, session };
 }

package/dist/core/runtime/surface-bg.d.ts

@@ -0,0 +1,11 @@
+/** The SGR escape that turns ON the distinct-surface background (theme
+ *  `selectedBg`), e.g. `\x1b[48;2;58;58;74m`. Pair with `\x1b[49m` to reset just
+ *  the background. Throws if no process has initialized the theme — callers on a
+ *  render path (the attach overlay) always have, by construction. */
+export declare function surfaceBgAnsi(): string;
+/** tmux flags that frame a `display-menu` / `display-popup` on the distinct
+ *  surface background — a rounded border + the surface bg on the body and border.
+ *  Empty when the theme is unavailable in this process (chrome stays default; the
+ *  attach viewer re-installs the menu with these once it has themed). One knob:
+ *  every crtr tmux float shares this single definition. */
+export declare function surfaceTmuxStyleArgs(): string[];

package/dist/core/runtime/surface-bg.js

@@ -0,0 +1,68 @@
+// surface-bg.ts — the "distinct popup surface" background, theme-derived.
+//
+// crtr's overlays and popups must read as a SEPARATE surface from the normal one
+// (CTO ruling, taste/inline-ui-placement #11): a popup whose background matches
+// the surface has invisible edges, so you can't tell where the float begins. We
+// paint them with the active pi theme's `selectedBg` role — theme-derived, so it
+// adapts to light/dark and is ONE centralized knob, not a scattered hardcode.
+//
+// pi 0.79 does not re-export `selectedBg` through its public API (the `.` entry
+// omits `getResolvedThemeColors` and the live `theme` singleton). It DOES publish
+// the live `Theme` instance on a process-global symbol once `initTheme()` has run
+// — the same hook pi's own SDK reads (see broker.ts `ctx.ui.theme`). We read it
+// there and use the public `Theme.bg()` / `Theme.getBgAnsi()` methods.
+//
+// CRITICAL: this module must NOT statically import `@earendil-works/pi-coding-agent`
+// — that package costs ~400ms to load and would land on the cold `crtr` front
+// door (which never otherwise loads pi). We only READ the process-global symbol;
+// any process that needs styling (the attach viewer, a node's broker) has already
+// called `initTheme()` and populated it. Where the symbol is absent (the front
+// door, before it execs into the themed `crtr attach`), the tmux helpers return
+// no style args and the chrome stays at its default — the viewer re-themes it.
+const THEME_SYMBOL = Symbol.for('@earendil-works/pi-coding-agent:theme');
+/** The live pi Theme if a process has already run `initTheme()`, else undefined.
+ *  Read-only: never initializes (that would pull pi into the front door). */
+function liveTheme() {
+    const t = globalThis[THEME_SYMBOL];
+    return (t ?? undefined);
+}
+/** The SGR escape that turns ON the distinct-surface background (theme
+ *  `selectedBg`), e.g. `\x1b[48;2;58;58;74m`. Pair with `\x1b[49m` to reset just
+ *  the background. Throws if no process has initialized the theme — callers on a
+ *  render path (the attach overlay) always have, by construction. */
+export function surfaceBgAnsi() {
+    const t = liveTheme();
+    if (t === undefined)
+        throw new Error('surfaceBgAnsi: pi theme not initialized in this process');
+    return t.getBgAnsi('selectedBg');
+}
+/** The distinct-surface background as a tmux colour token (`#rrggbb` on a
+ *  truecolor theme, `colourN` on a 256-colour theme), or undefined when the theme
+ *  is not yet loaded in this process OR defines no selection background. tmux
+ *  cannot read pi's theme, so we translate the SGR pi resolved for us. */
+function surfaceBgTmux() {
+    const t = liveTheme();
+    if (t === undefined)
+        return undefined;
+    const ansi = t.getBgAnsi('selectedBg');
+    const tc = /48;2;(\d+);(\d+);(\d+)/.exec(ansi);
+    if (tc !== null) {
+        const hex = (n) => Number(n).toString(16).padStart(2, '0');
+        return `#${hex(tc[1])}${hex(tc[2])}${hex(tc[3])}`;
+    }
+    const c256 = /48;5;(\d+)/.exec(ansi);
+    if (c256 !== null)
+        return `colour${c256[1]}`;
+    return undefined; // empty/default selectedBg → nothing distinct to paint
+}
+/** tmux flags that frame a `display-menu` / `display-popup` on the distinct
+ *  surface background — a rounded border + the surface bg on the body and border.
+ *  Empty when the theme is unavailable in this process (chrome stays default; the
+ *  attach viewer re-installs the menu with these once it has themed). One knob:
+ *  every crtr tmux float shares this single definition. */
+export function surfaceTmuxStyleArgs() {
+    const bg = surfaceBgTmux();
+    if (bg === undefined)
+        return [];
+    return ['-b', 'rounded', '-s', `bg=${bg}`, '-S', `bg=${bg}`];
+}