@crouton-kit/crouter 0.3.32 → 0.3.33

package/dist/core/runtime/naming.js

@@ -1,10 +1,10 @@
 // Session naming — turn a node's first prompt into a short, human-readable
 // handle for the editor label.
 //
-// A node's editor label is `<kind> (<mode>) <name> <cycle>` (see editorLabel in
-// launch.ts). The `<name>` is a 3-8 word kebab-case "description" derived from
+// A node's editor label is `<name> <kind> (<mode>)` (see editorLabel in
+// labels.ts). The `<name>` is a 3-8 word kebab-case "description" derived from
 // the first prompt by asking pi headlessly (`pi -p`), persisted on the node's
-// meta so it survives revives and shows in every cycle.
+// meta so it survives revives and updates the live session name.
 //
 // One entry point: generateAndPersistName — async (execFile, non-blocking).
 // Naming happens INSIDE the named node's own pi process, off the first real
@@ -73,10 +73,10 @@ const DEFAULT_NAME_MODEL = 'anthropic/claude-haiku-4-5';
  *  side-effect free. Pinned to Haiku with thinking off — naming is a trivial
  *  classification that never needs a reasoning budget. Override the model with
  *  CRTR_NAME_MODEL. */
-function nameArgs(prompt) {
+function piTextArgs(systemPrompt, userPrompt) {
     const override = process.env['CRTR_NAME_MODEL'];
     const model = override !== undefined && override.trim() !== '' ? override.trim() : DEFAULT_NAME_MODEL;
-    const argv = [
+    return [
         '-p',
         '--no-session',
         '--no-context-files',
@@ -86,13 +86,15 @@ function nameArgs(prompt) {
         '--no-themes',
         '--no-tools',
         '--mode', 'text',
-        // Naming is a trivial one-line classification — no thinking budget, ever.
+        // A trivial one-line classification — no thinking budget, ever.
         '--thinking', 'off',
         '--model', model,
+        '--system-prompt', systemPrompt,
+        userPrompt,
     ];
-    argv.push('--system-prompt', NAME_SYSTEM_PROMPT);
-    argv.push(nameUserPrompt(prompt));
-    return argv;
+}
+function nameArgs(prompt) {
+    return piTextArgs(NAME_SYSTEM_PROMPT, nameUserPrompt(prompt));
 }
 /** 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
@@ -148,3 +150,53 @@ export function generateAndPersistName(nodeId, prompt, onNamed) {
         persist(name !== '' ? name : slugFromPrompt(body));
     });
 }
+// ---------------------------------------------------------------------------
+// Issue titles — turn a free-text todo/idea/bug note into a short, human-readable
+// GitHub-issue title (sentence case, NOT kebab). Used by `crtr canvas issue new`.
+// ---------------------------------------------------------------------------
+const TITLE_SYSTEM_PROMPT = 'You write GitHub issue titles. Given a free-text note (a todo, idea, or bug ' +
+    'report), reply with ONLY a concise issue title: sentence case, 4-10 words, no ' +
+    'trailing period, no quotes, no prefix like "Bug:" or "Idea:", no markdown. ' +
+    'Capture the gist as an actionable title. Output JUST the title, nothing else.';
+function titleUserPrompt(note) {
+    return `<note>\n${note.slice(0, PROMPT_CAP)}\n</note>\n\nWrite a concise GitHub issue title for the note above. Output JUST the title, nothing else.`;
+}
+/** First non-empty line of `note`, trimmed and clamped to ~80 chars — the local
+ *  fallback title when the headless call fails. */
+function firstLineTitle(note) {
+    const line = (note ?? '').split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+    const clamped = line.length > 80 ? `${line.slice(0, 77).trimEnd()}…` : line;
+    return clamped !== '' ? clamped : 'untitled';
+}
+/** A filesystem-safe slug for the `.todos/<slug>.md` fallback path: lowercase,
+ *  [a-z0-9] kept, everything else → single hyphen, clamped to 8 words. */
+export function titleSlug(title) {
+    const words = (title ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .split('-')
+        .filter((w) => w !== '');
+    return words.slice(0, 8).join('-') || 'untitled';
+}
+/** Ask pi headlessly for a one-line issue title for `note`. Resolves to the
+ *  generated title, or a local first-line fallback on any failure (non-zero
+ *  exit, timeout, empty output). Async; never throws. */
+export function generateIssueTitle(note) {
+    const body = (note ?? '').trim();
+    if (body === '')
+        return Promise.resolve('untitled');
+    return new Promise((resolve) => {
+        try {
+            const child = execFile('pi', piTextArgs(TITLE_SYSTEM_PROMPT, titleUserPrompt(body)), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
+                if (err || typeof stdout !== 'string')
+                    return resolve(firstLineTitle(body));
+                const t = stdout.trim().split('\n').map((l) => l.trim()).find((l) => l !== '') ?? '';
+                resolve(t !== '' ? t.replace(/^["']|["']$/g, '').replace(/\.$/, '') : firstLineTitle(body));
+            });
+            child.stdin?.end(); // immediate EOF — pi -p reads stdin (see headlessName)
+        }
+        catch {
+            resolve(firstLineTitle(body));
+        }
+    });
+}

package/dist/core/runtime/nodes.js

@@ -14,7 +14,7 @@
 //             is also recorded.
 import { randomBytes } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
-import { createNode, getNode, getRow, subscribe, recordSpawn, } from '../canvas/index.js';
+import { createNode, getNode, getRow, subscribe, recordSpawn, contextDir, } from '../canvas/index.js';
 import { memoryDir } from './memory.js';
 /** Generate a node id in the same shape as job ids (time-sortable + random). */
 export function newNodeId() {
@@ -59,6 +59,11 @@ export function nodeEnv(meta) {
         CRTR_MODE: meta.mode,
         CRTR_LIFECYCLE: meta.lifecycle,
         CRTR_NODE_CWD: meta.cwd,
+        // The node's own context dir (canvas home), as an ABSOLUTE path. The engine
+        // runs with cwd = CRTR_NODE_CWD (the project), so a relative `context/`
+        // resolves into the REPO, not here — agents must address artifacts via this.
+        CRTR_CONTEXT_DIR: contextDir(meta.node_id),
+        CRTR_CYCLES: (meta.cycles ?? 0).toString(),
     };
     if (meta.parent)
         env['CRTR_PARENT_NODE_ID'] = meta.parent;

package/dist/core/runtime/persona.js

@@ -28,11 +28,10 @@ import { orchestratorContextNote } from './bearings.js';
 // base→orchestrator guidance (the roadmap-shaping dump) — MOVED here from
 // promote.ts so the injector is the one place that builds it.
 // ---------------------------------------------------------------------------
-/** Coerce a frontmatter scalar to its string form, matching the legacy
- *  hand-rolled parser. Strings pass through; number/boolean coerce via
- *  String(); null/undefined and non-scalars are dropped (→ null). Without this,
- *  the `yaml` package's native scalar types would let a numeric/boolean
- *  `roadmapSkill` be silently dropped by a `typeof === 'string'` guard. */
+/** Coerce a frontmatter scalar to its string form. Strings pass through;
+ *  number/boolean coerce via String(); null/undefined and non-scalars are
+ *  dropped (→ null). This lets numeric/boolean `roadmapKnowledge` knowledge-doc
+ *  pointers resolve the same way string pointers do. */
 function scalarToString(v) {
     if (typeof v === 'string')
         return v;
@@ -40,10 +39,10 @@ function scalarToString(v) {
         return String(v);
     return null;
 }
-/** Load a substrate doc's body text by name, or null if it can't be resolved.
- *  Used to inline a kind's roadmap-shaping skill into the orchestration
- *  guidance — the skill now lives as a substrate memory doc. */
-function loadSkillBody(name) {
+/** Load a knowledge doc's body text by name, or null if it can't be resolved.
+ *  Used to inline a kind's roadmap-shaping knowledge doc into the orchestration
+ *  guidance. */
+function loadRoadmapKnowledgeBody(name) {
     try {
         return resolveMemoryDoc(name).body.trim();
     }
@@ -52,8 +51,8 @@ function loadSkillBody(name) {
     }
 }
 /** The base→orchestrator guidance dump, specialized to the node's kind: the
- *  shared kernel + that kind's roadmap-shaping skill + the roadmap scaffold the
- *  node must author + the orchestrator context-dir framing + a short pointer at
+ *  shared kernel + that kind's roadmap-shaping memory doc + the roadmap scaffold
+ *  the node must author + the orchestrator context-dir framing + a short pointer at
  *  the substrate memory flow (promotion re-informs of nothing about the stores,
  *  it only adds the across-cycles relevance). The node is now a delegator whose
  *  scarce resource is its own context window. (Lifecycle is left to its own
@@ -61,8 +60,8 @@ function loadSkillBody(name) {
 function orchestrationGuidance(nodeId, kind) {
     const kernel = loadKernel();
     const orch = loadPersona(kind, 'orchestrator');
-    const roadmapSkill = scalarToString(orch?.frontmatter?.['roadmapSkill']) ?? undefined;
-    const skillBody = roadmapSkill ? loadSkillBody(roadmapSkill) : null;
+    const roadmapKnowledge = scalarToString(orch?.frontmatter?.['roadmapKnowledge']) ?? undefined;
+    const roadmapKnowledgeBody = roadmapKnowledge ? loadRoadmapKnowledgeBody(roadmapKnowledge) : null;
     const roadmap = readRoadmap(nodeId) ?? '(no roadmap yet)';
     const rmPath = roadmapPath(nodeId);
     const parts = [
@@ -71,14 +70,14 @@ function orchestrationGuidance(nodeId, kind) {
         '',
         kernel,
     ];
-    if (skillBody) {
-        parts.push('', `--- How to shape a ${kind} roadmap (skill: ${roadmapSkill}) ---`, '', skillBody);
+    if (roadmapKnowledgeBody) {
+        parts.push('', `--- How to shape a ${kind} roadmap (knowledge: ${roadmapKnowledge}) ---`, '', roadmapKnowledgeBody);
     }
     parts.push('', `Your roadmap scaffold (\`${rmPath}\`) — author it now: state the goal, exit criteria, and the phase skeleton, using the approach above. Current contents:`, '', roadmap, '', 
     // The orchestrator framing for the context dir — the missing guidance a
     // promoted node never got at spawn (it spawned as a base worker). Same note
-    // a born-orchestrator gets in its <crtr-context> bearings block.
-    orchestratorContextNote(nodeId), '', 'Your three long-term memory scopes (user-global, project, node-local) already surface in your `<crtr-context>` block. What promotion changes is USE, not access: you now persist across refresh cycles, so node-local carries what THIS goal needs between your refreshes, and durable facts you commit to user-global or project outlive this node. Use `crtr memory write` to save a document; `crtr memory list` to browse; `crtr memory find` to search (see "Your long-term memory" above for the full substrate flow).', '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
+    // a born-orchestrator gets in its <crtr-bearings> block.
+    orchestratorContextNote(nodeId), '', 'Your three long-term memory scopes (user-global, project, node-local) already surface in your bearings at boot. What promotion changes is USE, not access: you now persist across refresh cycles, so node-local carries what THIS goal needs between your refreshes, and durable facts you commit to user-global or project outlive this node. Use `crtr memory write` to save a document; `crtr memory list` to browse; `crtr memory find` to search (see "Your long-term memory" above for the full substrate flow).', '', 'Then delegate each phase with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap.');
     return parts.join('\n');
 }
 // ---------------------------------------------------------------------------

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

@@ -1,6 +1,6 @@
 import { type FocusRow } from '../canvas/index.js';
 export type { FocusRow };
-export { splitWindow, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, installMenuBinding, setPaneOption, getPaneOption, piCommand, respawnPaneSync, closePane, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, installMenuBinding, setPaneOption, getPaneOption, piCommand, respawnPaneSync, closePane, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
 export type { RespawnPaneOpts } from './tmux.js';
 /** The viewer a node has on screen, or null. UNIQUE(node_id) ⇒ at most one. */
 export declare function focusOf(nodeId: string): FocusRow | null;
@@ -22,17 +22,26 @@ export declare function listFocuses(): FocusRow[];
  *  tmux probe, so the pane may be stale; the caller liveness-checks before
  *  targeting it. */
 export declare function graphSurfaceTarget(nodeId: string): FocusRow | null;
-/** Synchronously wait until a broker's view.sock accepts a connection. The spawn
- *  and focus flows are sync (the command layer calls them directly), so the async
- *  net poll runs in a worker THREAD while this thread blocks on `Atomics.wait` —
- *  in-process, no child Node cold-start. Success proves more than file existence:
- *  it is robust to a stale leftover socket the launching broker has not unlinked
- *  yet, because only an accepting listener yields a `connect`. */
-export declare function waitForBrokerViewSocket(nodeId: string): boolean;
+/** Wait until a broker's view.sock accepts a connection. The launching caller
+ *  stays async, so the broker's real exit signal can fail fast the wait instead
+ *  of being masked by a zombie pid. Success proves more than file existence: it
+ *  is robust to a stale leftover socket the broker has not unlinked yet,
+ *  because only an accepting listener yields a `connect`. */
+export declare function waitForBrokerViewSocket(nodeId: string, exited?: Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}>): Promise<boolean>;
 /** A reviver: ensure a node's broker ENGINE is alive (idempotent → reviveNode →
  *  headlessBrokerHost.launch). Injected so placement.ts need not import revive.ts
  *  (which imports placement.ts — a cycle). */
-export type Reviver = (nodeId: string) => void;
+export type Reviver = (nodeId: string) => {
+    launch?: {
+        exited: Promise<{
+            code: number | null;
+            signal: NodeJS.Signals | null;
+        }>;
+    };
+} | void;
 /** Result of a focus op. `inPlace` = navigated to an existing viewer (no new
  *  pane); false = a fresh viewer pane was opened/moved. `revived` = this call
  *  had to (re)launch the broker engine. */
@@ -72,32 +81,11 @@ export declare function openViewerWindow(nodeId: string, session: string, opts?:
     cwd?: string;
     besidePane?: string;
 }): FocusRow | null;
-/** Bring a node's ONE viewer pane forefront (§A.4). Every node is a detached
- *  broker, so there is no engine pane to swap into the caller's viewport — focus
- *  instead ensures the node's single `crtr attach` viewer is on screen beside (or
- *  navigated to) the caller:
- *    (a) ensure the broker ENGINE is alive (idempotent injected reviver) and its
- *        view.sock is ACCEPTING (closes the cold-start race against attach's
- *        single connect) — without this the freshly-opened viewer would exit
- *        "no broker".
- *    (b) `--new-pane` → always a fresh viewer beside the caller (e.g. two
- *        different nodes side by side); drop any prior viewer first (UNIQUE).
- *    (c) the node already has a live viewer:
- *          - in the caller's session ⇒ navigate to it (switchClient+selectWindow),
- *            no new pane (inPlace).
- *          - elsewhere (e.g. a --root's viewer in another session) ⇒ MOVE it: close the old
- *            viewer pane (the broker runs on; the fresh viewer replays full
- *            scrollback from the broker `welcome` snapshot), drop its row, reopen
- *            beside the caller.
- *    (d) no live viewer ⇒ open one beside the caller and register the row.
- *
- *  crtr is tmux-only: with no caller pane there is no viewport to open and no
- *  non-tmux fallback — report not-focused. */
 export declare function focus(nodeId: string, opts: {
     pane?: string;
     newPane?: boolean;
     revive: Reviver;
-}): FocusResult;
+}): Promise<FocusResult>;
 /** Tear a node off its viewer (close/reset/cancel teardown). The broker engine
  *  is killed by its own host teardown over view.sock — this only closes the
  *  on-screen viewer: kill its pane (the window collapses once its last pane goes)
@@ -112,3 +100,20 @@ export declare function tearDownNode(nodeId: string): void;
  *  acts on (the Alt+C menu's `#{pane_id}`); falls back to the node's registered
  *  viewer pane. No-op (false) when there is no live viewer pane to close. */
 export declare function detachToBackground(nodeId: string, pane?: string): boolean;
+/** Reap `nodeId` IFF it is an empty shell (see {@link isEmptyNode}): tear down its
+ *  broker engine, close any viewer, and hard-delete its row (edges cascade) + dir.
+ *  The user closing or detaching from a node that never said anything wants it
+ *  GONE, not parked as a canceled husk. Returns true when it reaped. No-op (false)
+ *  on a node that produced output, is mid-first-turn, or no longer exists. */
+export declare function reapIfEmpty(nodeId: string): boolean;
+/** Sweep the whole canvas for empty shells and reap them — the bulk cleanup
+ *  behind `crtr canvas prune --empty`, for the husks that accumulated before
+ *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), nodes
+ *  mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a running
+ *  engine is the daemon's domain and may have output not yet persisted, so bulk
+ *  GC never kills one (the per-action {@link reapIfEmpty} does, since the user
+ *  explicitly closed/detached that node). `dryRun` reports candidates without
+ *  deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
+export declare function reapEmptyNodes(opts?: {
+    dryRun?: boolean;
+}): string[];

package/dist/core/runtime/placement.js

@@ -23,25 +23,29 @@
 //     model-over-driver so the §5.1 import-lint ("only placement.ts /
 //     tmux-chrome.ts import tmux.ts") holds — every other module reaches the
 //     driver verbs through here.
-import { Worker } from 'node:worker_threads';
-import { join } from 'node:path';
-import { getNode, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, view, } from '../canvas/index.js';
-import { paneExists, paneLocation, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, getPaneOption, } from './tmux.js';
+import { createConnection } from 'node:net';
+import { getNode, deleteNode, listNodes, openFocusRow, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, view, } from '../canvas/index.js';
+import { nodeHasAssistantMessage, isNodeStreaming } from '../canvas/render.js';
+import { headlessBrokerHost } from './host.js';
+import { paneExists, paneLocation, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, } from './tmux.js';
 import { newNodeId, rootOfSpine } from './nodes.js';
-import { nodeDir } from '../canvas/paths.js';
+import { viewSocketPath } from '../canvas/paths.js';
 import { isPidAlive } from '../canvas/pid.js';
 // Placement is the sanctioned model-over-driver (§2.1): non-placement runtime /
 // command modules that legitimately need a raw driver verb get it from here, so
 // the §5.1 lint can hold "only placement.ts / tmux-chrome.ts import tmux.ts".
 // These are the chrome + viewer verbs that survive the cut (the engine-in-pane
 // verbs — respawnPane, respawnPaneDetached, swapPaneInPlace, breakPaneToSession,
-// joinPane, selectLayout, setWindowOption, setRemainOnExit — are deleted).
+// joinPane, setWindowOption, setRemainOnExit — are deleted). `breakPane` +
+// `selectLayout` are FRESH minimal viewer-chrome helpers (not the deleted
+// engine-in-pane `breakPaneToSession`): `canvas tmux-spread` breaks the caller's
+// viewer pane into its own window and tiles sibling viewers beside it.
 // `piCommand` + `paneCurrentPath` are KEPT: the sessionless `crtr view` system
 // (view-cycle.ts / view-run.ts) builds its pane commands with them, and the §5.1
 // import-lint forbids those commands importing tmux.ts directly — they must reach
 // the driver through placement. (They are NOT engine-in-pane; the design's
 // "nothing keeps" classification missed the view consumers.)
-export { splitWindow, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, installMenuBinding, setPaneOption, getPaneOption, piCommand, respawnPaneSync, closePane, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, installMenuBinding, setPaneOption, getPaneOption, piCommand, respawnPaneSync, closePane, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, } from './tmux.js';
 // ---------------------------------------------------------------------------
 // Viewer registry reads — COMPOSE over the canvas focuses table (§2.3/§4).
 //
@@ -115,61 +119,68 @@ export function graphSurfaceTarget(nodeId) {
 // ---------------------------------------------------------------------------
 const BROKER_FOCUS_SOCKET_WAIT_MS = 30_000;
 const BROKER_FOCUS_SOCKET_RETRY_MS = 100;
-// The probe runs inside a worker thread (see waitForBrokerViewSocket). Async net
-// events drive the same poll loop; the worker reports its verdict into a shared
-// Int32 (0 = pending, 1 = accepted, 2 = gave up) and Atomics.notify wakes the
-// blocked main thread. eval:true ⇒ CommonJS, so `require` and workerData apply.
-const VIEW_SOCKET_PROBE_WORKER = `
-const net = require('node:net');
-const { workerData, parentPort } = require('node:worker_threads');
-const { buffer, sockPath, waitMs, retryMs } = workerData;
-const result = new Int32Array(buffer);
-const deadline = Date.now() + waitMs;
-const report = (code) => { Atomics.store(result, 0, code); Atomics.notify(result, 0); };
-function attempt() {
-  let socket;
-  let settled = false;
-  const finish = (ok) => {
-    if (settled) return;
-    settled = true;
-    if (socket !== undefined) socket.destroy();
-    if (ok) { report(1); return; }
-    if (Date.now() >= deadline) { report(2); return; }
-    setTimeout(attempt, retryMs);
-  };
-  try {
-    socket = net.createConnection(sockPath);
-  } catch {
-    finish(false);
-    return;
-  }
-  socket.once('connect', () => finish(true));
-  socket.once('error', () => finish(false));
-  socket.setTimeout(retryMs, () => finish(false));
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
 }
-attempt();
-void parentPort;
-`;
-/** Synchronously wait until a broker's view.sock accepts a connection. The spawn
- *  and focus flows are sync (the command layer calls them directly), so the async
- *  net poll runs in a worker THREAD while this thread blocks on `Atomics.wait` —
- *  in-process, no child Node cold-start. Success proves more than file existence:
- *  it is robust to a stale leftover socket the launching broker has not unlinked
- *  yet, because only an accepting listener yields a `connect`. */
-export function waitForBrokerViewSocket(nodeId) {
-    const sockPath = join(nodeDir(nodeId), 'view.sock');
-    const buffer = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT);
-    const result = new Int32Array(buffer);
-    const worker = new Worker(VIEW_SOCKET_PROBE_WORKER, {
-        eval: true,
-        workerData: { buffer, sockPath, waitMs: BROKER_FOCUS_SOCKET_WAIT_MS, retryMs: BROKER_FOCUS_SOCKET_RETRY_MS },
+function probeBrokerViewSocket(sockPath, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let socket = null;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            if (socket !== null)
+                socket.destroy();
+            resolve(ok);
+        };
+        try {
+            socket = createConnection(sockPath);
+        }
+        catch {
+            finish(false);
+            return;
+        }
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+        socket.setTimeout(timeoutMs, () => finish(false));
     });
-    worker.unref();
-    // Block until the worker reports (or a hard timeout matching the old
-    // spawnSync). 'not-equal' covers the worker finishing before we wait.
-    Atomics.wait(result, 0, 0, BROKER_FOCUS_SOCKET_WAIT_MS + 1_000);
-    void worker.terminate();
-    return Atomics.load(result, 0) === 1;
+}
+/** Wait until a broker's view.sock accepts a connection. The launching caller
+ *  stays async, so the broker's real exit signal can fail fast the wait instead
+ *  of being masked by a zombie pid. Success proves more than file existence: it
+ *  is robust to a stale leftover socket the broker has not unlinked yet,
+ *  because only an accepting listener yields a `connect`. */
+export async function waitForBrokerViewSocket(nodeId, exited) {
+    const sockPath = viewSocketPath(nodeId);
+    const deadline = Date.now() + BROKER_FOCUS_SOCKET_WAIT_MS;
+    const exitSeen = exited?.then(() => 'exit');
+    while (Date.now() <= deadline) {
+        const remaining = Math.max(0, deadline - Date.now());
+        const probe = probeBrokerViewSocket(sockPath, Math.min(BROKER_FOCUS_SOCKET_RETRY_MS, remaining)).then((ok) => (ok ? 'ready' : 'retry'));
+        // Race the probe against the broker's real exit ONLY when we have one. With
+        // no exit promise, an `?? Promise.resolve('retry')` would settle instantly
+        // and always beat the probe, so readiness could never observe a `connect`.
+        const outcome = exitSeen === undefined ? await probe : await Promise.race([probe, exitSeen]);
+        if (outcome === 'ready')
+            return true;
+        if (outcome === 'exit')
+            return false;
+        if (exitSeen !== undefined) {
+            const sleptOrExit = await Promise.race([
+                sleep(BROKER_FOCUS_SOCKET_RETRY_MS).then(() => 'sleep'),
+                exitSeen,
+            ]);
+            if (sleptOrExit === 'exit')
+                return false;
+        }
+        else {
+            await sleep(BROKER_FOCUS_SOCKET_RETRY_MS);
+        }
+    }
+    return false;
 }
 function newFocusId() {
     return `f-${newNodeId()}`;
@@ -263,7 +274,17 @@ export function openViewerWindow(nodeId, session, opts = {}) {
  *
  *  crtr is tmux-only: with no caller pane there is no viewport to open and no
  *  non-tmux fallback — report not-focused. */
-export function focus(nodeId, opts) {
+/** After a viewer pane is opened/moved beside the caller, make it the ACTIVE
+ *  pane and rebalance its window's panes to an even side-by-side layout — so
+ *  picking a node (e.g. from the alt+g graph) lands the keyboard on the fresh
+ *  viewer and the panes are evenly sized again, not halved. Best-effort. */
+function surfaceNewPane(pane) {
+    const win = paneLocation(pane)?.window ?? null;
+    if (win !== null)
+        selectLayout(win, 'even-horizontal');
+    selectPane(pane);
+}
+export async function focus(nodeId, opts) {
     const meta = getNode(nodeId);
     if (meta === null)
         return { focused: false, session: null, inPlace: false, revived: false };
@@ -274,9 +295,9 @@ export function focus(nodeId, opts) {
     // (a) Ensure the broker engine is alive + its view.sock accepts. Capture prior
     //     liveness so the result reports whether THIS focus had to launch it.
     const wasAlive = isPidAlive(meta.pi_pid ?? null);
-    opts.revive(nodeId);
+    const revivedLaunch = opts.revive(nodeId);
     const revived = !wasAlive;
-    if (!waitForBrokerViewSocket(nodeId)) {
+    if (!(await waitForBrokerViewSocket(nodeId, revivedLaunch?.launch?.exited))) {
         return { focused: false, session: null, inPlace: false, revived };
     }
     // focus always opens BESIDE the caller pane, so `fallbackSession` is only the
@@ -296,6 +317,8 @@ export function focus(nodeId, opts) {
         const opened = openViewerWindow(nodeId, fallbackSession, { cwd: meta.cwd, besidePane: callerPane });
         if (opened === null)
             return { focused: false, session: null, inPlace: false, revived };
+        if (opened.pane !== null)
+            surfaceNewPane(opened.pane);
         return { focused: true, session: opened.session, inPlace: false, revived };
     }
     // (c) Reuse / move the node's one live viewer — but ONLY a pane that still
@@ -315,6 +338,8 @@ export function focus(nodeId, opts) {
                 // Viewer is in the caller's session — just navigate to it.
                 switchClient(loc.session);
                 selectWindow(loc.session, loc.window);
+                if (existing.pane !== null)
+                    selectPane(existing.pane);
                 return { focused: true, session: loc.session, inPlace: true, revived };
             }
             // Viewer lives elsewhere — MOVE it: close the old pane (broker runs on; the
@@ -334,6 +359,8 @@ export function focus(nodeId, opts) {
     const opened = openViewerWindow(nodeId, fallbackSession, { cwd: meta.cwd, besidePane: callerPane });
     if (opened === null)
         return { focused: false, session: null, inPlace: false, revived };
+    if (opened.pane !== null)
+        surfaceNewPane(opened.pane);
     return { focused: true, session: opened.session, inPlace: false, revived };
 }
 // ---------------------------------------------------------------------------
@@ -366,5 +393,63 @@ export function detachToBackground(nodeId, pane) {
     const f = focusByPane(viewer);
     if (f !== null)
         closeFocusRow(f.focus_id);
-    return closePane(viewer);
+    const closed = closePane(viewer);
+    // A node the user detached from that never produced any AI output is a useless
+    // shell taking up graph + disk space — reap it (engine + row + dir) outright
+    // rather than leaving an empty broker running headless off-screen.
+    reapIfEmpty(nodeId);
+    return closed;
+}
+// ---------------------------------------------------------------------------
+// Reaping empty nodes (no AI output) on close / detach
+// ---------------------------------------------------------------------------
+/** Is this node an EMPTY SHELL right now — a node whose engine never produced an
+ *  assistant message? Such nodes are pure dead weight on the graph. A node
+ *  actively generating its FIRST turn is NOT empty (its output just hasn't landed
+ *  on disk yet), so streaming nodes are spared. */
+function isEmptyNode(nodeId) {
+    const m = getNode(nodeId);
+    if (m === null)
+        return false;
+    if (isNodeStreaming(nodeId))
+        return false;
+    return !nodeHasAssistantMessage(m.pi_session_file);
+}
+/** Reap `nodeId` IFF it is an empty shell (see {@link isEmptyNode}): tear down its
+ *  broker engine, close any viewer, and hard-delete its row (edges cascade) + dir.
+ *  The user closing or detaching from a node that never said anything wants it
+ *  GONE, not parked as a canceled husk. Returns true when it reaped. No-op (false)
+ *  on a node that produced output, is mid-first-turn, or no longer exists. */
+export function reapIfEmpty(nodeId) {
+    if (!isEmptyNode(nodeId))
+        return false;
+    headlessBrokerHost.teardown(nodeId);
+    tearDownNode(nodeId);
+    deleteNode(nodeId);
+    return true;
+}
+/** Sweep the whole canvas for empty shells and reap them — the bulk cleanup
+ *  behind `crtr canvas prune --empty`, for the husks that accumulated before
+ *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), nodes
+ *  mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a running
+ *  engine is the daemon's domain and may have output not yet persisted, so bulk
+ *  GC never kills one (the per-action {@link reapIfEmpty} does, since the user
+ *  explicitly closed/detached that node). `dryRun` reports candidates without
+ *  deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
+export function reapEmptyNodes(opts = {}) {
+    const dryRun = opts.dryRun ?? false;
+    const selfId = process.env['CRTR_NODE_ID'] ?? '';
+    const reaped = [];
+    for (const row of listNodes()) {
+        const id = row.node_id;
+        if (id === selfId || isPidAlive(row.pi_pid) || !isEmptyNode(id))
+            continue;
+        if (!dryRun) {
+            headlessBrokerHost.teardown(id);
+            tearDownNode(id);
+            deleteNode(id);
+        }
+        reaped.push(id);
+    }
+    return reaped;
 }

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

@@ -34,4 +34,6 @@ export interface YieldResult {
 export declare function requestYield(nodeId: string, opts?: {
     kind?: string;
     model?: string;
+}, deps?: {
+    ensure?: () => void;
 }): YieldResult;