@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/runtime/placement.js

@@ -2,7 +2,7 @@
 //
 // After the broker-is-the-host cut the engine NEVER lives in a tmux pane: every
 // node is a detached `headlessBrokerHost` process that binds `view.sock`. A tmux
-// pane is only a `crtr attach` VIEWER of that broker, exactly like a web tab. So
+// pane is only a surface-attach viewer of that broker, exactly like a web tab. So
 // the whole engine-in-pane placement machinery (hot-swap, resume-into-focus,
 // backstage relocation, remain-on-exit freeze, spread, node-row reconcile) is
 // gone. What remains is:
@@ -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).
-// `piCommand` + `paneCurrentPath` are KEPT: the sessionless `crtr view` system
+// 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 surface-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,66 +119,73 @@ 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()}`;
 }
-/** Env for a `crtr attach` VIEWER pane (the focus split, the spawn viewer
+/** Env for a `crtr surface attach` VIEWER pane (the focus split, the spawn viewer
  *  window, AND recycle's re-attach respawn): propagate CRTR_HOME so the viewer
  *  resolves the SAME canvas home — and thus the right view.sock — under a
  *  non-default override; otherwise an empty env (the pane inherits the tmux
@@ -184,7 +195,7 @@ export function viewerSplitEnv() {
     const crtrHome = process.env['CRTR_HOME'];
     return crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
 }
-/** Register a `crtr attach` VIEWER pane as the node's one viewer focus row.
+/** Register a `crtr surface attach` VIEWER pane as the node's one viewer focus row.
  *  UNIQUE(node_id) ⇒ one viewer per node: returns
  *  the existing row (no insert) when the pane or the node is already registered.
  *  `window` is accepted for the call contract (spawn passes it) but not stored —
@@ -202,7 +213,7 @@ export function registerViewerFocus(nodeId, pane, session, window) {
     openFocusRow(focusId, pane, session, nodeId);
     return getFocusById(focusId);
 }
-/** Open a `crtr attach` VIEWER for `nodeId` and register its viewer focus row —
+/** Open a surface-attach viewer for `nodeId` and register its viewer focus row —
  *  the shared opener used by `focus` (a split beside the caller) and by a --root
  *  spawn (a fresh window in the caller's current session). Wraps `ensureSession`
  *  + `openNodeWindow`/`splitWindow` + `registerViewerFocus`. The attach client
@@ -214,7 +225,7 @@ export function registerViewerFocus(nodeId, pane, session, window) {
  *    - `besidePane` → a SPLIT beside that pane in its own session (the focus
  *      open-beside-the-caller path); `session` is then only a fallback. */
 export function openViewerWindow(nodeId, session, opts = {}) {
-    const command = `crtr attach to ${nodeId}`;
+    const command = `crtr surface attach to ${nodeId}`;
     const env = viewerSplitEnv();
     const cwd = opts.cwd ?? process.cwd();
     let pane;
@@ -244,7 +255,7 @@ export function openViewerWindow(nodeId, session, opts = {}) {
 // ---------------------------------------------------------------------------
 /** 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
+ *  instead ensures the node's single surface-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
@@ -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,12 +317,14 @@ 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
     //     carries THIS node's `@crtr_node` tag. `paneExists` is not enough: the
     //     front-door root registers the user's own terminal as its viewer pane and
-    //     runs `crtr attach` inline; on a clean detach the pane returns to the
+    //     runs `crtr surface attach` inline; on a clean detach the pane returns to the
     //     user's shell (attach clears the tag) yet the pane — and the row — survive,
     //     and a reused pane carries some OTHER node's tag. Navigating to / closing
     //     such a pane would strand the user on (or kill) their shell. So verify the
@@ -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 };
 }
 // ---------------------------------------------------------------------------
@@ -352,9 +379,9 @@ export function tearDownNode(nodeId) {
         closePane(f.pane);
     closeFocusRow(f.focus_id);
 }
-/** Detach a node from the foreground (the `node lifecycle --detach` / Alt+C → D
+/** Detach a node from the foreground (the `node lifecycle demote --detach` / Alt+C → D
  *  half). Every node is a headless broker — the only thing on screen is its
- *  `crtr attach` VIEWER pane — so "detach" means STOP FOREGROUNDING it: close the
+ *  surface-attach viewer pane — so "detach" means STOP FOREGROUNDING it: close the
  *  viewer pane (and drop its row) and leave the broker engine running untouched,
  *  reconnectable by a later `focus`. `pane` is the authoritative pane the caller
  *  acts on (the Alt+C menu's `#{pane_id}`); falls back to the node's registered
@@ -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;

package/dist/core/runtime/promote.js

@@ -1,6 +1,6 @@
 // Promotion — the worker→orchestrator polymorph (mode→orchestrator).
 //
-// Two stages (the pi-mode-switch pattern):
+// Two stages:
 //   1. Promotion → mode flips to orchestrator (mid-turn). This call flips the
 //      node's mode and (optionally) its KIND, REWRITES its launch spec to that
 //      kind's orchestrator persona (so the next revive comes back as that
@@ -20,6 +20,7 @@
 // never the mere act of spawning a child.
 import { getNode, updateNode } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
+import { ensureDaemon } from '../../daemon/manage.js';
 import { buildLaunchSpec } from './launch.js';
 import { hasRoadmap, seedRoadmap, roadmapPath } from './roadmap.js';
 import { readGoal, goalPath } from './kickoff.js';
@@ -58,7 +59,7 @@ export function promote(nodeId, opts = {}) {
     // Seed a barebones roadmap scaffold if absent so the file exists for a
     // refresh. Pre-fill its Goal from the node's goal doc when present (set at
     // spawn, or captured from the first user message); the node fleshes out the
-    // body next, guided by the kind skill dumped below.
+    // body next, guided by the kind's roadmap memory doc dumped below.
     let roadmapWritten = false;
     if (!hasRoadmap(nodeId)) {
         const goal = readGoal(nodeId);
@@ -68,10 +69,17 @@ export function promote(nodeId, opts = {}) {
     // Flip mode→orchestrator + kind + launch spec. Lifecycle is independent:
     // only set resident when the caller asked for it (the common self-promotion
     // stays terminal/orchestrator — it still reports up + reaps).
+    // If the handle is still the spawn-time kind default (name === old kind),
+    // carry it to the new kind so the "name === kind ⇒ default, drop it" invariant
+    // in fullName() holds across a kind change. Otherwise a node spawned `general`
+    // (name="general") that reshapes to `plan` would surface a stale "general"
+    // handle in front of its real description.
+    const carriesDefaultHandle = node.name === node.kind && targetKind !== node.kind;
     const meta = updateNode(nodeId, {
         kind: targetKind,
         mode: 'orchestrator',
         launch,
+        ...(carriesDefaultHandle ? { name: targetKind } : {}),
         // Persist a newly-chosen tier so it is durable across future revives; omit
         // when unchanged so the existing pin (or persona default) stands.
         ...(opts.model !== undefined ? { model_override: opts.model } : {}),
@@ -90,7 +98,8 @@ export function promote(nodeId, opts = {}) {
  *  so it comes back as an orchestrator, optionally specializing its kind. Sets
  *  intent='refresh'; the stophook shuts the process down on the next stop and
  *  the daemon revives it fresh. */
-export function requestYield(nodeId, opts = {}) {
+export function requestYield(nodeId, opts = {}, deps = {}) {
+    const ensure = deps.ensure ?? ensureDaemon;
     const node = getNode(nodeId);
     if (node === null)
         throw new Error(`unknown node: ${nodeId}`);
@@ -113,6 +122,17 @@ export function requestYield(nodeId, opts = {}) {
         // of an already-orchestrator node.
         promoted = wasBase;
     }
+    // The refresh-revive is the DAEMON's job: the stophook shuts this broker down
+    // on its next stop, and crtrd then sees the dead pid + intent='refresh' and
+    // relaunches it fresh. That handoff is silent if the daemon isn't running — the
+    // broker exits and nothing ever revives it (the viewer redials its view.sock
+    // for ~30s and reports "broker gone"). So ensure the supervisor is alive HERE,
+    // before we arm the yield — the same best-effort ensure spawn/recycle do, on
+    // the one other path that hands a node off to the daemon. Runs in the fresh
+    // `crtr node yield` subprocess, so it always uses current dist (never a stale
+    // in-process hook). Injectable for the regression test that locks in this
+    // ensure (default = ensureDaemon).
+    ensure();
     // Mark the intent; the stophook enacts the shutdown, the daemon the revive.
     transition(nodeId, 'yield');
     const meta = getNode(nodeId);

package/dist/core/runtime/recycle.js

@@ -1,4 +1,4 @@
-// recycle.ts — the "finalize + reboot this pane" action behind `crtr node recycle`.
+// recycle.ts — the "finalize + reboot this pane" action behind `crtr node lifecycle recycle`.
 //
 // Recycle FINALIZES the agent occupying a tmux pane and recycles that pane for
 // fresh work, in three steps:
@@ -8,7 +8,7 @@
 //   2. Close    — tear the agent's broker engine down (the pane is only a viewer).
 //   3. Recycle  — boot a fresh resident broker root the pane re-attaches to.
 //
-// NOT to be confused with `node demote` (flip-to-terminal IN PLACE, which keeps
+// NOT to be confused with `node lifecycle demote` (flip-to-terminal IN PLACE, which keeps
 // the agent focused and running): recycle ENDS this agent and boots a brand-new
 // resident root here.
 //
@@ -73,7 +73,7 @@ export async function recycleNode(nodeId, callerPane) {
         finalized = true;
     }
     catch { /* recycle the pane even if the report failed */ }
-    // The node's pane is a VIEWER (`crtr attach`), not its engine: the engine is
+    // The node's pane is a VIEWER (`crtr surface attach`), not its engine: the engine is
     // the detached broker process, so respawn-pane -k below would only kill the
     // viewer, never the engine. Tear the broker PROCESS down so it exits and
     // releases the sole .jsonl writer. Status is already flipped done by pushFinal
@@ -120,31 +120,33 @@ export async function recycleNode(nodeId, callerPane) {
     // CRTR_SUBTREE groups the fresh root's subtree; FRONT_DOOR is set by the broker
     // host itself, so it is not added here.
     inv.env = { ...inv.env, CRTR_SUBTREE: rootOfSpine(root.node_id) };
-    const ok = recycleBrokerViewer(fresh, pane, inv);
+    const ok = await recycleBrokerViewer(fresh, pane, inv);
     return { recycled: ok, finalized, newRoot: root.node_id, delivered };
 }
 /** Recycle a BROKER root into `pane`: the fresh root is broker-hosted, so its
  *  engine runs in a DETACHED broker, not the pane. Birth-launch that broker via
  *  the Host seam (mirrors spawnChild's birth path — the host records its pid),
  *  wait for its view.sock to accept, then respawn the pane in place to the VIEWER
- *  `crtr attach to <root>`. The pane stays a viewer (attach self-tags it
+ *  `crtr surface attach to <root>`. The pane stays a viewer (attach self-tags it
  *  `@crtr_node`); it never hosts the engine. Returns false (recycle reports the
  *  pane was not respawned) when the broker never serves — the fresh root row
  *  still exists, broker-hosted, for the daemon to revive. */
-function recycleBrokerViewer(fresh, pane, inv) {
-    headlessBrokerHost.launch(fresh.node_id, inv, { cwd: fresh.cwd, name: fullName(fresh), resuming: false });
-    if (!waitForBrokerViewSocket(fresh.node_id))
+async function recycleBrokerViewer(fresh, pane, inv) {
+    const placed = headlessBrokerHost.launch(fresh.node_id, inv, { cwd: fresh.cwd, name: fullName(fresh), resuming: false });
+    if (placed.pid === null)
+        return false;
+    if (!(await waitForBrokerViewSocket(fresh.node_id, placed.exited)))
         return false;
     // Clear the finalized node's stale `@crtr_node` tag before respawn so the tag
-    // never names a done node during the gap before the new `crtr attach` re-tags
+    // never names a done node during the gap before the new `crtr surface attach` re-tags
     // on connect. Node ids are shell-safe identifiers; no quoting needed.
     try {
         setPaneOption(pane, '@crtr_node', '');
     }
     catch { /* best-effort */ }
     // SYNC respawn: the recycle command runs as a SEPARATE CLI process (the viewer
-    // runs `crtr attach`, a TUI — it never execs recycle), so we are NOT respawning
+    // runs `crtr surface attach`, a TUI — it never execs recycle), so we are NOT respawning
     // our own pane and can confirm the respawn actually landed (the honest exit
     // status), unlike the tmux path which often recycles the caller's own pane.
-    return respawnPaneSync({ pane, cwd: fresh.cwd, env: viewerSplitEnv(), command: `crtr attach to ${fresh.node_id}` });
+    return respawnPaneSync({ pane, cwd: fresh.cwd, env: viewerSplitEnv(), command: `crtr surface attach to ${fresh.node_id}` });
 }

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

@@ -6,7 +6,7 @@ import { respawnPaneSync } from './placement.js';
  *  keep parent=rootId. No wipe. Returns the reaped ids.
  *
  *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
- *  whether via `node close` OR a root reset — did not finish its OWN work, so it
+ *  whether via `node lifecycle close` OR a root reset — did not finish its OWN work, so it
  *  unifies on `canceled`; `done` is reserved for finalize. Why marking is STILL
  *  explicit: an abrupt broker teardown fires NO clean `session_shutdown`, so the
  *  general quit→done rule does NOT auto-resolve a force-killed descendant — we
@@ -19,7 +19,10 @@ export interface RelaunchDeps {
     /** Boot the new node's detached broker engine. Default: headlessBrokerHost.launch. */
     launchBroker?: typeof headlessBrokerHost.launch;
     /** Wait for the new broker's view.sock to accept. Default: waitForBrokerViewSocket. */
-    waitForViewSocket?: (nodeId: string) => boolean;
+    waitForViewSocket?: (nodeId: string, exited?: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>) => boolean | Promise<boolean>;
     /** Re-exec the viewer pane onto the new node. Default: respawnPaneSync. */
     respawnViewer?: typeof respawnPaneSync;
     /** Tear the old broker down. Default: headlessBrokerHost.teardown. */
@@ -35,7 +38,7 @@ export interface RelaunchRootResult {
  *  is touched, so any pre-commit failure leaves the old root fully intact and
  *  live. Returns null when `oldId` is not a relaunchable root (unknown, a child,
  *  or already parked), or when the new broker failed to launch. */
-export declare function relaunchRoot(oldId: string, deps?: RelaunchDeps): RelaunchRootResult | null;
+export declare function relaunchRoot(oldId: string, deps?: RelaunchDeps): Promise<RelaunchRootResult | null>;
 export interface ResetRootResult {
     /** Descendant node ids torn down. Always empty — a child `/new` reaps nothing. */
     reaped: string[];

package/dist/core/runtime/reset.js

@@ -2,7 +2,7 @@
 // termination.
 //
 // A node's engine is a detached broker process bound to one CRTR_NODE_ID, and
-// its on-screen viewer is a SEPARATE `crtr attach` pane. `/new` splits by who
+// its on-screen viewer is a SEPARATE `crtr surface attach` pane. `/new` splits by who
 // ran it:
 //
 //   • relaunchRoot — a `/new` on a ROOT starts a genuinely new node: the old
@@ -35,7 +35,7 @@ import { spawnNode, rootOfSpine } from './nodes.js';
  *  keep parent=rootId. No wipe. Returns the reaped ids.
  *
  *  Why `canceled` (A5, human-confirmed 2026-06-06): an externally-reaped node —
- *  whether via `node close` OR a root reset — did not finish its OWN work, so it
+ *  whether via `node lifecycle close` OR a root reset — did not finish its OWN work, so it
  *  unifies on `canceled`; `done` is reserved for finalize. Why marking is STILL
  *  explicit: an abrupt broker teardown fires NO clean `session_shutdown`, so the
  *  general quit→done rule does NOT auto-resolve a force-killed descendant — we
@@ -68,7 +68,7 @@ export function reapDescendants(rootId) {
  *  is touched, so any pre-commit failure leaves the old root fully intact and
  *  live. Returns null when `oldId` is not a relaunchable root (unknown, a child,
  *  or already parked), or when the new broker failed to launch. */
-export function relaunchRoot(oldId, deps = {}) {
+export async function relaunchRoot(oldId, deps = {}) {
     const launchBroker = deps.launchBroker ?? headlessBrokerHost.launch;
     const waitForViewSocket = deps.waitForViewSocket ?? waitForBrokerViewSocket;
     const respawnViewer = deps.respawnViewer ?? respawnPaneSync;
@@ -115,7 +115,7 @@ export function relaunchRoot(oldId, deps = {}) {
         transition(newMeta.node_id, 'crash');
         return null;
     }
-    waitForViewSocket(newMeta.node_id); // best-effort; attach auto-redials on miss
+    await waitForViewSocket(newMeta.node_id, placed.exited); // best-effort; attach auto-redials on miss
     // --- COMMIT: park + reap the old root, re-point the viewer, kill the old
     //     broker. Past this point the new node is the live root. ---
     reapDescendants(oldId); // old workers → canceled + torn down
@@ -129,7 +129,7 @@ export function relaunchRoot(oldId, deps = {}) {
             pane: oldFocus.pane,
             cwd: old.cwd,
             env: viewerSplitEnv(),
-            command: `crtr attach to ${newMeta.node_id}`,
+            command: `crtr surface attach to ${newMeta.node_id}`,
         });
         const window = windowOfPane(oldFocus.pane);
         if (window !== null)

package/dist/core/runtime/revive-all.d.ts

@@ -11,8 +11,11 @@ export declare const TERMINAL_BY_CHOICE: readonly NodeStatus[];
  *  — the precise "disconnected" predicate (gh #9).
  *
  *  - engine not running: no live `pi_pid` (a dead/absent broker pid).
- *  - resumable: a captured pi session (`pi_session_file` or `pi_session_id`) —
- *    without one there is nothing to resume.
+ *  - reconnectable: a captured pi session marker (`pi_session_file` or
+ *    `pi_session_id`) — without one there is nothing to reopen. reviveNode
+ *    resumes by the `.jsonl` path when it still exists, else relaunches fresh (a
+ *    bare `pi_session_id` alone no longer resumes — the broker preflight rejects
+ *    it — so such a node comes back fresh).
  *  - `human`-kind rows are the `crtr human` bridge, never a pi engine, so they
  *    are never "disconnected" (mirrors the daemon's superviseTick carve-out).
  *  - terminal-by-choice (`done`/`canceled`) is always excluded.

package/dist/core/runtime/revive-all.js

@@ -27,8 +27,11 @@ export const TERMINAL_BY_CHOICE = ['done', 'canceled'];
  *  — the precise "disconnected" predicate (gh #9).
  *
  *  - engine not running: no live `pi_pid` (a dead/absent broker pid).
- *  - resumable: a captured pi session (`pi_session_file` or `pi_session_id`) —
- *    without one there is nothing to resume.
+ *  - reconnectable: a captured pi session marker (`pi_session_file` or
+ *    `pi_session_id`) — without one there is nothing to reopen. reviveNode
+ *    resumes by the `.jsonl` path when it still exists, else relaunches fresh (a
+ *    bare `pi_session_id` alone no longer resumes — the broker preflight rejects
+ *    it — so such a node comes back fresh).
  *  - `human`-kind rows are the `crtr human` bridge, never a pi engine, so they
  *    are never "disconnected" (mirrors the daemon's superviseTick carve-out).
  *  - terminal-by-choice (`done`/`canceled`) is always excluded.