@crouton-kit/crouter 0.3.26 → 0.3.28

package/dist/core/runtime/broker.js

@@ -310,7 +310,7 @@ export async function runBroker(nodeId) {
         broadcast({ type: 'control_changed', controller_id: controllerId });
     };
     const buildSnapshot = () => ({
-        messages: session.messages,
+        messages: snapshotMessages(session),
         stats: session.getSessionStats(),
         state: {
             sessionId: session.sessionId,
@@ -907,6 +907,31 @@ export async function runBroker(nodeId) {
     }
 }
 // ---------------------------------------------------------------------------
+// snapshotMessages — the catch-up snapshot's ordered message history.
+//
+// The broker is the SOLE writer of the node's session `.jsonl`, so the session
+// manager's persisted tree (`buildSessionContext`) is the canonical, complete,
+// ordered history — byte-identical to what a dormant reader (crouter-web's static
+// normalizer) reconstructs from the same file. We serve THAT, NOT the agent's
+// live `session.messages` (`agent.state.messages`), because pi's recovery paths
+// mutate the live array away from the persisted history: auto-retry, context-
+// overflow recovery, and compaction each SLICE the errored/superseded assistant
+// message out of `state.messages` while DELIBERATELY keeping it on disk ("keep in
+// session for history", agent-session.js). So `session.messages` can OMIT — or, via
+// branch/compaction reshaping, reorder — a turn the `.jsonl` still holds. Pre-
+// close that drift is invisible (the live stream and the live array agree); after
+// a revive the welcome snapshot built from the reloaded array would diverge from
+// the on-disk history a dormant viewer just saw. Reconstructing from the session
+// manager makes the live snapshot == the persisted history (single source of
+// truth); the relayed live stream then continues from there.
+//
+// `AgentSession.sessionManager` is a public readonly field of the real pi SDK; the
+// fake-engine test fixture mirrors the same `sessionManager.buildSessionContext()`
+// surface, so this is a single path with no engine-capability fallback.
+export function snapshotMessages(session) {
+    return session.sessionManager.buildSessionContext().messages;
+}
+// ---------------------------------------------------------------------------
 // buildBrokerSession (plan T4 steps 2–4) — turn the launch recipe into a live
 // engine session via the pi SDK SERVICES path. Exported so the C3/C4 real-SDK
 // regression tests can drive the EXACT production wiring (not the mock).

package/dist/core/runtime/front-door.js

@@ -21,12 +21,19 @@ function isDir(p) {
         return false;
     }
 }
-/** Parse `[dir] [prompt]` positionals + `--name`/`--kind` flags out of the
- *  leftover tokens after the bare `crtr`. */
+/** The `--`flags the front door OWNS (everything else after a bare `crtr` is a
+ *  positional dir/prompt). A leading token in this set still boots a root —
+ *  without it, `crtr --headless` / `crtr --name X` would fall through to the
+ *  dispatcher and error as an unknown subcommand. */
+const FRONT_DOOR_FLAGS = new Set(['--name', '--kind', '--headless', '--no-headless']);
+/** Parse `[dir] [prompt]` positionals + the front-door flags out of the leftover
+ *  tokens after the bare `crtr`. `headless` is tri-state: `true`/`false` from an
+ *  explicit `--headless`/`--no-headless`, `undefined` to defer to the config. */
 function parseRootArgs(tokens) {
     let cwd = process.cwd();
     let name;
     let kind;
+    let headless;
     const positionals = [];
     for (let i = 0; i < tokens.length; i++) {
         const t = tokens[i];
@@ -36,6 +43,12 @@ function parseRootArgs(tokens) {
         else if (t === '--kind') {
             kind = tokens[++i];
         }
+        else if (t === '--headless') {
+            headless = true;
+        }
+        else if (t === '--no-headless') {
+            headless = false;
+        }
         else if (t.startsWith('--')) {
             // ignore unknown flags for the front door
         }
@@ -48,7 +61,7 @@ function parseRootArgs(tokens) {
         cwd = resolvePath(positionals.shift());
     }
     const prompt = positionals.length > 0 ? positionals.join(' ') : undefined;
-    return { cwd, prompt, name, kind };
+    return { cwd, prompt, name, kind, headless };
 }
 /** Env marker set on every pi the front door boots. Its presence means we are
  *  already inside a front-door-booted root, so a nested front-door launch must
@@ -79,14 +92,16 @@ export function maybeBootRoot(root, argv) {
     //   • bare `crtr`                  (no tokens)
     //   • `crtr <dir> [prompt]`        (first positional is an existing dir)
     //   • `crtr "multi word prompt"`   (first token contains whitespace)
-    // Anything else — a bare word like `job`, or a leading flag — is treated as a
-    // mistyped/removed subcommand and handed to the dispatcher, which errors with
-    // "unknown subcommand: <token>". Booting pi for such tokens is what let the
-    // renamed `agent`/`job` subcommands fork-bomb the front door.
+    //   • `crtr --headless` / `crtr --name X`  (a leading front-door flag)
+    // Anything else — a bare word like `job`, or an UNKNOWN leading flag — is
+    // treated as a mistyped/removed subcommand and handed to the dispatcher, which
+    // errors with "unknown subcommand: <token>". Booting pi for such tokens is what
+    // let the renamed `agent`/`job` subcommands fork-bomb the front door.
     if (first !== undefined) {
         const looksLikePrompt = /\s/.test(first);
         const looksLikeDir = !first.startsWith('-') && isDir(resolvePath(first));
-        if (!looksLikePrompt && !looksLikeDir)
+        const looksLikeFrontDoorFlag = FRONT_DOOR_FLAGS.has(first);
+        if (!looksLikePrompt && !looksLikeDir && !looksLikeFrontDoorFlag)
             return false;
     }
     // Unambiguous front-door launch → boot a resident root inline (exec pi in

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

@@ -6,17 +6,13 @@ export declare function sanitizeSessionName(raw: string): string;
 /** Local fallback: derive a name straight from the prompt (no pi call). Drops
  *  stop-words, takes the first few content words. */
 export declare function slugFromPrompt(prompt: string): string;
-/** Synchronously ask pi for a 3-8 word kebab name for `prompt`. Blocks up to
- *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
- *  output) falls back to a local slug. Returns '' only for an empty prompt. */
-export declare function generateSessionName(prompt: string): string;
 /** Asynchronously generate a name for `prompt` and persist it to the node's
  *  meta as `description` — only if the node has none yet (so a later message
  *  never clobbers it). Non-blocking: safe to call from inside a live pi event
  *  loop. Best-effort; swallows all errors.
  *
  *  `onNamed` (optional) fires with the freshly-persisted meta the moment the
- *  name lands — the bare-root path passes a callback that calls
+ *  name lands — the canvas-goal-capture naming hook passes a callback that calls
  *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
  *  same session, instead of waiting for the next revive/cycle. */
 export declare function generateAndPersistName(nodeId: string, prompt: string, onNamed?: (meta: NodeMeta) => void): void;

package/dist/core/runtime/naming.js

@@ -6,19 +6,16 @@
 // the first prompt by asking pi headlessly (`pi -p`), persisted on the node's
 // meta so it survives revives and shows in every cycle.
 //
-// Two entry points:
-//   • generateSessionName  — synchronous (spawnSync). For the CLI spawn paths
-//     (spawnChild / bootRoot) that run outside any pi event loop, where a brief
-//     block before launching the worker is fine and lets the FIRST pi session
-//     already carry the name.
-//   • generateAndPersistName — async (execFile, non-blocking). For the bare-root
-//     case where the prompt only arrives as the first interactive message inside
-//     a live pi process; it must never block the event loop. Persists the name
-//     to meta so the label picks it up on the next cycle.
+// One entry point: generateAndPersistName — async (execFile, non-blocking).
+// Naming happens INSIDE the named node's own pi process, off the first real
+// message (the kickoff task or a human's first line), never on the spawn path:
+// blocking spawn on an LLM round-trip used to freeze the caller's terminal for
+// 2-3s on every `crtr node new`. The headless namer runs with --no-extensions,
+// so it loads no canvas hooks and can never recurse into another spawn/name.
 //
-// Both are best-effort: a failed/slow/garbled pi call falls back to a local slug
-// of the prompt, so a node always gets a sane name.
-import { spawnSync, execFile } from 'node:child_process';
+// Best-effort: a failed/slow/garbled pi call falls back to a local slug of the
+// prompt, so a node always gets a sane name.
+import { execFile } from 'node:child_process';
 import { getNode, updateNode } from '../canvas/index.js';
 /** Cap on prompt text fed to the namer — a name needs only the gist. */
 const PROMPT_CAP = 2000;
@@ -97,30 +94,27 @@ function nameArgs(prompt) {
     argv.push(nameUserPrompt(prompt));
     return argv;
 }
-/** Synchronously ask pi for a 3-8 word kebab name for `prompt`. Blocks up to
- *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
- *  output) falls back to a local slug. Returns '' only for an empty prompt. */
-export function generateSessionName(prompt) {
-    const body = (prompt ?? '').trim();
-    if (body === '')
-        return '';
-    try {
-        const r = spawnSync('pi', nameArgs(body), {
-            encoding: 'utf8',
-            timeout: NAME_TIMEOUT_MS,
-            // Don't inherit a TUI; capture stdout only.
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
-        if (r.status === 0 && typeof r.stdout === 'string') {
-            const name = sanitizeSessionName(r.stdout);
-            if (name !== '')
-                return name;
+/** Ask pi headlessly for a kebab-case name for `body`, async. Resolves to the
+ *  sanitized name, or '' on any failure (non-zero exit, timeout, empty/garbled
+ *  output) so the caller can fall back to a local slug. Owns the subprocess
+ *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads
+ *  stdin, and execFile's default stdin is an OPEN pipe that never closes, so
+ *  without this pi blocks waiting for EOF and the call exits non-zero (the
+ *  regression that silently lost every LLM name to the slug fallback). */
+function headlessName(body) {
+    return new Promise((resolve) => {
+        try {
+            const child = execFile('pi', nameArgs(body), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
+                if (err || typeof stdout !== 'string')
+                    return resolve('');
+                resolve(sanitizeSessionName(stdout));
+            });
+            child.stdin?.end(); // immediate EOF — see the doc above
         }
-    }
-    catch {
-        // fall through to slug
-    }
-    return slugFromPrompt(body);
+        catch {
+            resolve('');
+        }
+    });
 }
 /** Asynchronously generate a name for `prompt` and persist it to the node's
  *  meta as `description` — only if the node has none yet (so a later message
@@ -128,7 +122,7 @@ export function generateSessionName(prompt) {
  *  loop. Best-effort; swallows all errors.
  *
  *  `onNamed` (optional) fires with the freshly-persisted meta the moment the
- *  name lands — the bare-root path passes a callback that calls
+ *  name lands — the canvas-goal-capture naming hook passes a callback that calls
  *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
  *  same session, instead of waiting for the next revive/cycle. */
 export function generateAndPersistName(nodeId, prompt, onNamed) {
@@ -150,17 +144,7 @@ export function generateAndPersistName(nodeId, prompt, onNamed) {
             // best-effort
         }
     };
-    try {
-        execFile('pi', nameArgs(body), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
-            if (err || typeof stdout !== 'string') {
-                persist(slugFromPrompt(body));
-                return;
-            }
-            const name = sanitizeSessionName(stdout);
-            persist(name !== '' ? name : slugFromPrompt(body));
-        });
-    }
-    catch {
-        persist(slugFromPrompt(body));
-    }
+    void headlessName(body).then((name) => {
+        persist(name !== '' ? name : slugFromPrompt(body));
+    });
 }

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

@@ -308,12 +308,13 @@ export declare function recycleFocusPane(nodeId: string, pane: string, launch: R
  *      manager that is NOT idle-release (done/dead/canceled, or idle with another
  *      intent) is one the daemon will NEVER revive, so this returns false WITHOUT
  *      repointing — the caller then disarms the freeze (see below).
- *    - LIVE manager (pi alive in the backstage, the normal multi-child state):
- *      the daemon never revives it (it only respawns dead-pi nodes), so we must
- *      bring it into the viewport SYNCHRONOUSLY here — swap its backstage pane
- *      into the focus slot (MAJOR 1). Otherwise the manager runs off-screen
- *      forever while %m sits orphaned in the viewport and the focus row lies
- *      about LOCATION.
+ *    - RUNNING backstage pane (a live pi — the normal multi-child state — OR a
+ *      pi still BOOTING because the daemon already revived the manager off the
+ *      `push final` before this handoff ran): the daemon never (re)revives it,
+ *      so we must bring it into the viewport SYNCHRONOUSLY here — swap its
+ *      backstage pane into the focus slot (MAJOR 1). Otherwise the manager runs
+ *      off-screen forever while %m sits orphaned in the viewport and the focus
+ *      row lies about LOCATION.
  *  Returns false — the caller closes the focus (Q1: closeFocusToShell disarms
  *  remain-on-exit so the pane REAPS on exit) — whenever NO successor will claim
  *  the frozen pane: no manager, the manager IS this node, the manager already

package/dist/core/runtime/placement.js

@@ -28,7 +28,7 @@
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path';
 import { getRow, getRowByPane, getNode, setPresence, openDb, openFocusRow, setFocusOccupant, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, setFocusPane, listFocuses as listFocusRows, view, } from '../canvas/index.js';
-import { paneExists, paneLocation, paneOfWindow, windowAlive, windowOfPane, ensureSession, openNodeWindow, respawnPaneSync, respawnPaneDetached, breakPaneToSession, splitWindow, swapPaneInPlace, setRemainOnExit, closePane, currentTmux, joinPane, selectLayout, setWindowOption, switchClient, selectWindow, } from './tmux.js';
+import { paneExists, paneRunning, paneLocation, paneOfWindow, windowAlive, windowOfPane, ensureSession, openNodeWindow, respawnPaneSync, respawnPaneDetached, breakPaneToSession, splitWindow, swapPaneInPlace, setRemainOnExit, closePane, currentTmux, joinPane, selectLayout, setWindowOption, switchClient, selectWindow, } from './tmux.js';
 import { homeSessionOf, childBackstageOf, nodeSession, newNodeId, rootOfSpine } from './nodes.js';
 import { nodeDir } from '../canvas/paths.js';
 import { isBusy } from './busy.js';
@@ -808,12 +808,13 @@ export function recycleFocusPane(nodeId, pane, launch) {
  *      manager that is NOT idle-release (done/dead/canceled, or idle with another
  *      intent) is one the daemon will NEVER revive, so this returns false WITHOUT
  *      repointing — the caller then disarms the freeze (see below).
- *    - LIVE manager (pi alive in the backstage, the normal multi-child state):
- *      the daemon never revives it (it only respawns dead-pi nodes), so we must
- *      bring it into the viewport SYNCHRONOUSLY here — swap its backstage pane
- *      into the focus slot (MAJOR 1). Otherwise the manager runs off-screen
- *      forever while %m sits orphaned in the viewport and the focus row lies
- *      about LOCATION.
+ *    - RUNNING backstage pane (a live pi — the normal multi-child state — OR a
+ *      pi still BOOTING because the daemon already revived the manager off the
+ *      `push final` before this handoff ran): the daemon never (re)revives it,
+ *      so we must bring it into the viewport SYNCHRONOUSLY here — swap its
+ *      backstage pane into the focus slot (MAJOR 1). Otherwise the manager runs
+ *      off-screen forever while %m sits orphaned in the viewport and the focus
+ *      row lies about LOCATION.
  *  Returns false — the caller closes the focus (Q1: closeFocusToShell disarms
  *  remain-on-exit so the pane REAPS on exit) — whenever NO successor will claim
  *  the frozen pane: no manager, the manager IS this node, the manager already
@@ -840,11 +841,22 @@ export function handFocusToManager(focusId, managerId) {
     const mgr = getRow(managerId);
     if (mgr === null)
         return false; // no row to hand to
-    // MAJOR 1 — LIVE backstage manager → swap it into the focus slot NOW. The
-    // daemon never revives a live node (it only respawns dead-pi nodes), so this
-    // synchronous swap is the ONLY way a live manager claims the frozen %m. Commit
-    // the occupant repoint only here, on a path that genuinely takes the pane.
-    if (mgr.pane != null && isNodePaneAlive(mgr) && isPidAlive(mgr.pi_pid) && f.pane != null) {
+    // MAJOR 1 — manager with a RUNNING backstage pane → swap it into the focus
+    // slot NOW. The daemon never revives a live node (it only respawns dead-pi
+    // nodes), so this synchronous swap is the ONLY way it claims the frozen %m.
+    // Commit the occupant repoint only here, on a path that genuinely takes the
+    // pane. The gate is the PANE (`paneRunning`: exists + command running, i.e.
+    // not a remain-on-exit corpse), NOT `isPidAlive(mgr.pi_pid)` — the recorded
+    // pid is a STALE proxy in the lost-pane race: the finishing child's `push
+    // final` seeds the manager's inbox mid-turn, the daemon's second pass revives
+    // the still-unfocused manager BACKSTAGE before this agent_end runs, and the
+    // fresh pi records its pid only at session_start, seconds into boot. Gating on
+    // the old dead pid made this branch miss the booting manager, the dormant
+    // branch miss it too (revive already flipped it active), and the caller reap
+    // the user's viewport while the manager ran on invisibly backstage. A booting
+    // pane is as swappable as a live one — swap it in; only a frozen corpse
+    // (pane_dead=1) is excluded, preserving the dead-focus-pane guarantees.
+    if (mgr.pane != null && paneRunning(mgr.pane) && f.pane != null) {
         setFocusOccupant(focusId, managerId);
         const focusLoc = paneLocation(f.pane); // F2's window/session — the slot mgr swaps INTO (%m is currently there)
         if (swapPaneInPlace(mgr.pane, f.pane) && focusLoc !== null) {

package/dist/core/runtime/revive.js

@@ -23,6 +23,7 @@ import { reconcile, piCommand, respawnPane, } from './placement.js';
 import { hostFor } from './host.js';
 import { nodeSession, childBackstageOf, rootOfSpine } from './nodes.js';
 import { isPidAlive } from '../canvas/pid.js';
+import { clearInjectedDocs } from '../substrate/injected-store.js';
 // ---------------------------------------------------------------------------
 // resumeArgs — which session source a revive resumes from
 // ---------------------------------------------------------------------------
@@ -93,6 +94,10 @@ export function reviveNode(nodeId, opts) {
         // woke you"); every other reviveNode caller passes nothing → no block.
         const bearings = drainBearings(meta);
         inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings, opts.wakeReason) });
+        // Fresh (no-resume) revive starts a NEW transcript — reset the on-read doc
+        // dedup so the new conversation surfaces docs from scratch (a resume below
+        // would instead KEEP the persisted set, continuing the same transcript).
+        clearInjectedDocs(nodeId);
     }
     // Placement owns WHERE this revive lands (§1.4): resume into a live focus pane
     // if the node occupies one, else a fresh window in its home_session (the
@@ -140,6 +145,8 @@ export function reviveInPlace(nodeId, pane, respawn = respawnPane) {
     // A refresh-yield is a cycle too — advance the label's trailing N.
     meta.cycles = (meta.cycles ?? 0) + 1;
     updateNode(nodeId, { cycles: meta.cycles });
+    // Fresh re-exec → new transcript: reset the on-read doc dedup.
+    clearInjectedDocs(nodeId);
     // The node's LOCATION — the session its pane physically lives in. The re-exec
     // is IN PLACE (the pane never moves), so this is preserved unchanged below.
     const session = meta.tmux_session ?? nodeSession();
@@ -198,6 +205,8 @@ export function relaunchRootInPane(nodeId, pane) {
         throw new Error(`relaunchRootInPane: unknown node ${nodeId}`);
     }
     // No prompt, no resume → a brand-new root conversation at cycle 0.
+    // Brand-new transcript: reset the on-read doc dedup.
+    clearInjectedDocs(nodeId);
     const inv = buildPiArgv(meta, {});
     // Source CRTR_ROOT_SESSION from childBackstageOf, the same backstage rule as
     // reviveInPlace. relaunchRootInPane runs only on a root, whose children must

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

@@ -6,6 +6,11 @@ export interface BootRootOpts {
     name?: string;
     /** Optional starter prompt (bare `crtr` requires none). */
     prompt?: string;
+    /** Tri-state host selection: `true`/`false` from an explicit
+     *  `--headless`/`--no-headless`, `undefined` to defer to the `headless`
+     *  config default. When it resolves to broker, the front door boots a
+     *  DETACHED broker root and auto-attaches a viewer inline in this pane. */
+    headless?: boolean;
 }
 /** 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). */

package/dist/core/runtime/spawn.js

@@ -9,16 +9,18 @@
 //                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 { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
-import { generateSessionName } from './naming.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 { registerRootFocus, ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, focusWindow, waitForBrokerViewSocket, } from './placement.js';
 import { transition } from './lifecycle.js';
 import { headlessBrokerHost } from './host.js';
 import { ensureDaemon } from '../../daemon/manage.js';
@@ -32,23 +34,25 @@ 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 });
-    // A root opened WITH a prompt gets its editor name now (so the first pi
-    // session already carries it). A bare root has no prompt yet — the
-    // goal-capture extension names it from the first message (async, next cycle).
-    const description = opts.prompt !== undefined && opts.prompt.trim() !== ''
-        ? generateSessionName(opts.prompt)
-        : undefined;
+    // Born WITHOUT a name. Naming is async + event-driven: the canvas-goal-capture
+    // extension names the node from its FIRST real message (the kickoff prompt or
+    // a human's first line) inside its own pi process, via a headless `pi -p`.
+    // Never block the front door on an LLM round-trip.
     const meta = spawnNode({
         kind,
         mode: 'base',
         lifecycle: 'resident',
         cwd: opts.cwd,
         name: opts.name ?? kind,
-        description,
         parent: null,
+        hostKind,
         launch,
     });
     // Persist the spawning prompt as the goal so a fresh revive can re-read its
@@ -74,6 +78,15 @@ export function bootRoot(opts) {
         }
         catch { /* best-effort */ }
     }
+    // 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
@@ -102,6 +115,50 @@ export function bootRoot(opts) {
     const r = spawnSync('pi', inv.argv, { stdio: 'inherit', env });
     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);
+    }
+    // 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 r = spawnSync(process.execPath, [...process.execArgv, entry, 'attach', 'to', meta.node_id], {
+        stdio: 'inherit',
+    });
+    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
@@ -162,14 +219,15 @@ export function spawnChild(opts) {
     // independent root sits top-of-spine with nobody to push to. Mirrors the
     // `parent` set below (root ? null : spawner), so hasManager === parent!==null.
     const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model });
-    // Name the worker from its task now, so its first editor label carries it.
+    // Born WITHOUT a name — the canvas-goal-capture extension names it async from
+    // its first message (the kickoff task) inside its own pi process, so spawn
+    // never blocks on the LLM naming round-trip (the 2-3s freeze it used to cost).
     const meta = spawnNode({
         kind: opts.kind,
         mode,
         lifecycle,
         cwd: opts.cwd,
         name: opts.name ?? opts.kind,
-        description: generateSessionName(opts.prompt),
         // A root has no spine parent (top-level, nobody subscribes); it still
         // records spawned_by=spawner when a node (not a human shell) spawned it.
         // A child's parent IS its manager.

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

@@ -96,6 +96,15 @@ 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 process — a live pi, or a pi still
+ *  BOOTING whose pid hasn't been recorded yet — from a remain-on-exit corpse
+ *  frozen after exit (`pane_dead` = 1). Node panes run pi as the pane command
+ *  (openNodeWindow / respawn-pane), never a shell, so pane-running ⟹ a pi (or
+ *  its respawn) occupies it. The probe handFocusToManager's live-swap gates on:
+ *  the recorded `pi_pid` is a stale proxy in the just-revived window (the new pi
+ *  records its pid only at session_start), but the pane itself never lies. */
+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,

package/dist/core/runtime/tmux.js

@@ -191,6 +191,18 @@ export function paneExists(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}']);
     return r.ok && r.stdout === pane;
 }
+/** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
+ *  Distinguishes a pane genuinely hosting a process — a live pi, or a pi still
+ *  BOOTING whose pid hasn't been recorded yet — from a remain-on-exit corpse
+ *  frozen after exit (`pane_dead` = 1). Node panes run pi as the pane command
+ *  (openNodeWindow / respawn-pane), never a shell, so pane-running ⟹ a pi (or
+ *  its respawn) occupies it. The probe handFocusToManager's live-swap gates on:
+ *  the recorded `pi_pid` is a stale proxy in the just-revived window (the new pi
+ *  records its pid only at session_start), but the pane itself never lies. */
+export function paneRunning(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}\t#{pane_dead}']);
+    return r.ok && r.stdout === `${pane}\t0`;
+}
 /** 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,

package/dist/core/spawn.d.ts

@@ -1,4 +1,18 @@
+/** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
+ *  gate for the human surface — see tmuxServerReachable. A headless-broker child
+ *  strips TMUX/TMUX_PANE (broker.ts, anti-stophook-hijack) yet can still drive
+ *  the canvas tmux server, so gating the surface on this wrongly starves broker
+ *  nodes of human-in-the-loop. */
 export declare function isInTmux(): boolean;
+/** Is the canvas tmux SERVER reachable? The canvas runs on the DEFAULT tmux
+ *  socket (no -L/-S in core/runtime/tmux.ts), so any `crtr` child — including a
+ *  headless-broker child that has deleted its own $TMUX — can split panes into
+ *  it. The human surface gates on THIS (can I reach the server to open a pane
+ *  the user is watching?), not on the caller's $TMUX. `list-clients` exits 0
+ *  whenever a server is up (even with zero attached clients) and non-zero when
+ *  no server is running — the true "no tmux to surface into" case that should
+ *  degrade to the inbox-drain follow-up. */
+export declare function tmuxServerReachable(): boolean;
 export declare function shellQuote(s: string): string;
 /** Count panes in a tmux window (0 outside tmux / on error). With `targetPane`,
  *  counts the window THAT pane lives in (the placement decision must reflect the