@crouton-kit/crouter 0.3.27 → 0.3.29

package/dist/core/runtime/spawn.js

@@ -2,28 +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 { FRONT_DOOR_ENV } from './front-door.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, } 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 {
@@ -51,75 +63,134 @@ export function bootRoot(opts) {
     // 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();
+    }
+    catch { /* best-effort */ }
+    try {
+        installNavBindings();
     }
-    // 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 {
+        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);
 }
-/** 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. */
+/** 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.`);
+    }
+    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 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 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
@@ -176,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,
     });
@@ -210,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}`];
+}

package/dist/core/runtime/tmux.d.ts

@@ -46,6 +46,12 @@ export interface SplitWindowOpts {
     command: string;
     /** Stack the new pane below instead of beside (default: beside, `-h`). */
     vertical?: boolean;
+    /** Place the new pane BEFORE the target (left for `-h`, above for `-v`) via
+     *  `-b`, instead of after it (default: after — right/below). */
+    before?: boolean;
+    /** Fixed size of the new pane in the split axis' cells (columns for `-h`, rows
+     *  for `-v`) via `-l`. Omit ⇒ tmux's default even split. */
+    size?: number;
 }
 /** Split `targetPane`'s window, opening a NEW pane beside it running `command`,
  *  and return the new pane id (the durable `%id`). The ONLY new-pane-beside verb
@@ -62,6 +68,10 @@ export declare function splitWindow(targetPane: string, opts: SplitWindowOpts):
 export declare function focusWindow(session: string, window: string): boolean;
 /** Close a node's window (drop it from the UI). */
 export declare function closeWindow(window: string): boolean;
+/** Rename a window (`tmux rename-window -t <window> <name>`). Used by the
+ *  root relaunch to re-title the viewer window when its pane is re-pointed at
+ *  the freshly-minted node. Best-effort; false if tmux fails. */
+export declare function renameWindow(window: string, name: string): boolean;
 /** Close a single PANE. Its window closes automatically once this was the last
  *  pane, but sibling panes survive — so co-located nodes (several agents sharing
  *  one window via swap-pane focus) are torn down one at a time instead of all
@@ -96,6 +106,11 @@ export declare function paneLocation(pane: string): {
  *  liveness. We therefore require the echoed `#{pane_id}` to equal the requested
  *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
 export declare function paneExists(pane: string): boolean;
+/** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
+ *  Distinguishes a pane genuinely hosting a live process from a remain-on-exit
+ *  corpse frozen after exit (`pane_dead` = 1). Node viewer panes run `crtr attach`
+ *  as the pane command, so pane-running ⟹ a live viewer occupies it. */
+export declare function paneRunning(pane: string): boolean;
 /** Every live pane id on the server (`list-panes -a`), as a Set for membership
  *  probes. Returns null when tmux is unreachable (no server / transient failure)
  *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,
@@ -116,21 +131,6 @@ export declare function setPaneOption(pane: string, name: string, value: string)
  *  <name>`): `-v` prints only the value, `-q` suppresses the unknown-option
  *  error so an unset option yields an empty string. undefined if tmux fails. */
 export declare function getPaneOption(pane: string, name: string): string | undefined;
-/** Relocate a pane into another session as its own window WITHOUT killing the
- *  process in it — `break-pane -d` moves the pane out of its current window (the
- *  pi keeps generating) into a fresh window in `session`; `-d` leaves the caller's
- *  client where it is rather than following the pane to the background, and `-a`
- *  allocates the next free window index (same dodge as openNodeWindow). The
- *  "detach to background" driver behind `node lifecycle --detach`. Best-effort;
- *  false if tmux refuses (e.g. the pane is gone). The caller reconciles presence
- *  so the canvas follows the move. */
-export declare function breakPaneToSession(pane: string, session: string): boolean;
-/** Swap `targetPane` into `callerPane`'s layout slot, IN PLACE. `-d` keeps the
- *  caller's window active, so the target's pane appears where the caller is
- *  rather than navigating the client off to the target's window. The caller's
- *  old pane lives on in the target's former window — the move is reversible
- *  (focusing back swaps it in again). Best-effort; never throws. */
-export declare function swapPaneInPlace(targetPane: string, callerPane: string): boolean;
 export interface RespawnPaneOpts {
     /** Target pane id (e.g. `%3`) — the pane to re-exec in place. */
     pane: string;
@@ -139,21 +139,11 @@ export interface RespawnPaneOpts {
     /** The full command to run in the pane (already a shell string). */
     command: string;
 }
-/** Re-exec a command in an EXISTING pane, in place — DETACHED. Spawned in its own
- *  process group (unref'd) so the request reaches the tmux server even though
- *  `-k` tears down the caller's own pi mid-flight. Used when a node respawns ITS
- *  OWN pane (refresh-yield): the dispatch can't be awaited because it kills the
- *  awaiter. Returns true once the request was dispatched. */
-export declare function respawnPaneDetached(opts: RespawnPaneOpts): boolean;
 /** Re-exec a command in an EXISTING pane, in place — SYNCHRONOUS. Runs the
  *  `respawn-pane` to completion and reports the real exit status. Used when the
  *  caller is NOT the pane being respawned (e.g. the daemon resuming a frozen
  *  focus pane), so it can confirm the respawn landed. Returns true on success. */
 export declare function respawnPaneSync(opts: RespawnPaneOpts): boolean;
-/** @deprecated Use respawnPaneDetached. Retained so existing refresh-yield
- *  callers stay green while the placement layer migrates onto the explicit
- *  sync/detached split. */
-export declare function respawnPane(opts: RespawnPaneOpts): boolean;
 /** Turn a pi argv array into a single shell command string.
  *
  *  The binary defaults to `CRTR_PI_BINARY` when that env var is set, else the
@@ -183,24 +173,6 @@ export declare function selectWindow(session: string, window: string): boolean;
  *  `tmux switch-client -t <session>`. Best-effort; never throws. The caller is
  *  responsible for following up with selectWindow to land on the right window. */
 export declare function switchClient(session: string): boolean;
-/** Move a source pane into a destination window (`tmux join-pane`). The source
- *  pane's running process (e.g. a child's live pi) is preserved; its now-empty
- *  source window auto-closes. Best-effort; false if tmux fails. */
-export declare function joinPane(srcPane: string, dstWindow: string): boolean;
-/** Apply a named tmux layout to a window (`tmux select-layout`). Use
- *  `main-vertical` for one wide pane on the left + the rest stacked right.
- *  Best-effort; never throws. */
-export declare function selectLayout(window: string, layout: string): boolean;
-/** Set a tmux window option (`tmux set-window-option`). Used to size the main
- *  pane (`main-pane-width`) before a main-vertical layout. Best-effort. */
-export declare function setWindowOption(window: string, name: string, value: string): boolean;
-/** Toggle `remain-on-exit` on a window (§1.5 F3). `on` keeps a focus pane on
- *  screen after its pi exits — the viewport survives (F1), the final transcript
- *  is preserved, and `respawn-pane -k` can resurrect the node into the SAME pane
- *  id. NOTE (§1.5/§2.5, spike-confirmed): a dead/frozen pane is reaped only by
- *  `kill-pane`/`respawn-pane`, NEVER by toggling this off — the toggle does not
- *  reap an already-dead pane. Best-effort; never throws. */
-export declare function setRemainOnExit(window: string, on: boolean): boolean;
 /** Type a literal (e.g. a `/graph` slash command) into a pane and press Enter
  *  (`tmux send-keys -t <pane> '<text>' Enter`). Requires the pane's editor be
  *  empty, same limitation as the menu's `/promote` item. Best-effort. */