@north-light/api 0.3.580 → 0.3.588

package/dist/core/runtime/placement-tmux.js

@@ -0,0 +1,81 @@
+// placement-tmux.ts — the PURE tmux + broker-socket half of placement.
+//
+// After the broker-is-the-host cut, the on-screen surface for a node is a
+// `crtr surface attach` VIEWER pane. Opening/sizing that pane and waiting for the
+// broker's view.sock are pure tmux + net operations — no canvas-db read. They
+// live here so CLI/viewer consumers (workspace, surface-tmux-spread, sysprompt,
+// viewer.ts) can reach the tmux front door WITHOUT dragging placement.ts's
+// canvas state-store (the focuses table) into their bundle.
+//
+// placement.ts RE-EXPORTS viewerSplitEnv + waitForBrokerViewSocket from here so
+// its existing importers (daemon runtime, handlers) are unchanged, and its
+// openViewerWindow composes openViewerPane (here) + registerViewerFocus (the db
+// write, which stays in placement.ts).
+//
+// §5.1 import-lint: placement-tmux.ts is an allowed direct importer of
+// tmux-driver.ts — it is the sanctioned pure-tmux seam, re-exporting the driver
+// verbs other modules need so they never import the driver directly.
+import { envHomeOverride } from '../../shared/env.js';
+import { paneLocation, ensureSession, openNodeWindow, splitWindow, selectLayout, } from './tmux-driver.js';
+import { BROKER_VIEW_SOCKET_WAIT_MS } from './view-socket.js';
+// Re-export the pure tmux driver verbs the CLI/viewer consumers need without
+// exposing the canvas focuses table or sending command modules to the raw driver.
+export { paneExists, paneLocation, paneOfNode, paneCurrentPath, paneSize, paneRunning, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, renameWindow, displayPopup, displayPopupAsync, windowOfPane, respawnPaneSync, respawnPaneInBackground, respawnPaneInPlace, runShellInBackground, paneStartCommand, swapPanes, paneCurrentCommand, closeWindow, panePid, windowAlive, listLivePanes, VIEWER_STAMP_OPTION, stampViewerPaneAsync, liveViewerPanes, sendAttachControl, displayClientMessage, displayMessage, windowIndex, sessionExists, tmuxAvailable, tmuxInteractive, } from './tmux-driver.js';
+export { installTmuxBindings } from './tmux-bindings.js';
+// view.sock readiness — the one shared broker-cold-start primitive
+export { BROKER_VIEW_SOCKET_WAIT_MS, waitForBrokerViewSocket } from './view-socket.js';
+// Viewer pane opener (tmux half, NO focus-row write)
+/** 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
+ *  server env, like every other crtr chrome pane). One helper so the viewer-pane
+ *  sites can't drift. */
+export function viewerSplitEnv() {
+    const crtrHome = envHomeOverride();
+    return crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
+}
+/** Open a `crtr surface attach` VIEWER pane for `nodeId` — the PURE tmux half of
+ *  placement's openViewerWindow (no focus-row write). Wraps `ensureSession` +
+ *  `openNodeWindow`/`splitWindow`. The attach client connects to the node's
+ *  `view.sock` and renders/drives the live broker engine — it NEVER launches the
+ *  engine (the one-writer invariant; the caller ensures the broker is alive
+ *  first). Returns the opened pane's coordinates, or null if tmux refused.
+ *    - default → a fresh WINDOW in `session` (the --root spawn-viewer path).
+ *    - `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 openViewerPane(nodeId, session, opts = {}) {
+    const command = `crtr surface attach to ${nodeId}`;
+    // When the broker may not have bound view.sock yet (a viewer opened right after
+    // a fresh spawn), hand the attach pane CRTR_ATTACH_WAIT_MS so it POLLS the
+    // socket until it accepts instead of failing fast on a cold socket and closing
+    // the pane instantly — the same self-polling bootRoot/resume rely on. The
+    // deadline is the shared BROKER_VIEW_SOCKET_WAIT_MS (one source of truth), not
+    // a literal duplicated at the call site.
+    const env = {
+        ...viewerSplitEnv(),
+        ...(opts.waitForBroker === true ? { CRTR_ATTACH_WAIT_MS: String(BROKER_VIEW_SOCKET_WAIT_MS) } : {}),
+        ...(opts.initialWhip === true ? { CRTR_ATTACH_INITIAL_WHIP: '1' } : {}),
+    };
+    const cwd = opts.cwd ?? process.cwd();
+    if (opts.besidePane !== undefined) {
+        const pane = splitWindow(opts.besidePane, { cwd, env, command });
+        if (pane === null)
+            return null;
+        const loc = paneLocation(pane);
+        const sess = loc?.session ?? session;
+        const window = loc?.window ?? null;
+        // Rebalance the window to even side-by-side widths. Without this each split
+        // halves the pane it split from, so repeated spawns beside the same pane keep
+        // shrinking (¼, ⅛, …); an even-horizontal relayout gives every viewer in the
+        // window equal width instead. Best-effort — sizing never fails the open.
+        if (window !== null)
+            selectLayout(window, 'even-horizontal');
+        return { pane, session: sess, window };
+    }
+    ensureSession(session, cwd);
+    const opened = openNodeWindow({ session, name: opts.name ?? nodeId, cwd, env, command });
+    if (opened === null)
+        return null;
+    return { pane: opened.pane, session, window: opened.window };
+}

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

@@ -0,0 +1,116 @@
+import { type FocusRow } from '../canvas/index.js';
+export type { FocusRow };
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, listLivePanesAsync, paneStateAsync, } from './tmux-driver.js';
+export type { RespawnPaneOpts } from './tmux-driver.js';
+export { installTmuxBindings } from './tmux-bindings.js';
+export type { TmuxInstalledPair, TmuxInstallDiagnostic, TmuxInstallResult } from './tmux-bindings.js';
+/** The viewer a node has on screen, or null. UNIQUE(node_id) ⇒ at most one. */
+export declare function focusOf(nodeId: string): Promise<FocusRow | null>;
+/** A node's viewer, probed ahead of a canvas write: `live` is the row whose pane tmux answered for (or did not answer for in time),
+ *  `stale` the row whose pane tmux reported gone; both null means the node had no row. The probe is a snapshot taken outside the
+ *  write, so the write passes it through {@link confirmViewer} before deciding from it. */
+export interface ViewerProbe {
+    nodeId: string;
+    live: FocusRow | null;
+    stale: FocusRow | null;
+}
+/** Read a node's viewer row and probe its pane with a bounded, non-blocking tmux call. Call it BEFORE `withCanvasWrite`: the
+ *  probe holds no connection, and a hung tmux costs one timeout instead of an open transaction. A timed-out probe counts as live. */
+export declare function probeViewer(nodeId: string): Promise<ViewerProbe>;
+/** Inside the write: re-read the node's viewer row under its lock and compare it with the probe. A row that matches the probe
+ *  (same focus and pane) keeps the probe's verdict, and a stale one is deleted here, only while it is still on the probed pane.
+ *  A row that differs from the probe — re-pointed to another pane, or created after an empty probe — was never probed, so it
+ *  counts as a live viewer and nothing is deleted; the next settle probes it. No tmux runs here. */
+export declare function confirmViewer(probe: ViewerProbe): Promise<ViewerProbe>;
+/** Does this node have a live viewer on screen? */
+export declare function isFocused(nodeId: string): Promise<boolean>;
+/** The viewer realized by a given pane (`%id`), or null. */
+export declare function focusByPane(pane: string): Promise<FocusRow | null>;
+/** The set of node ids that currently have a live viewer. */
+export declare function focusedNodes(): Promise<Set<string>>;
+/** Every live viewer row (GC'ing any whose pane has gone). */
+export declare function listFocuses(): Promise<FocusRow[]>;
+/** 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) => {
+    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. */
+export interface FocusResult {
+    focused: boolean;
+    session: string | null;
+    inPlace: boolean;
+    revived: boolean;
+}
+/** 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 —
+ *  the focuses table keys on pane + session only. The attach client self-tags the
+ *  pane `@crtr_node` on connect, so `nodeInPane` resolves it either way. */
+export declare function registerViewerFocus(nodeId: string, pane: string, session: string | null, window: string | null): Promise<FocusRow | null>;
+/** 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
+ *  connects to the node's `view.sock` and renders/drives the live broker engine
+ *  — it NEVER launches the engine (the one-writer invariant; the caller ensures
+ *  the broker is alive first). Returns the registered viewer row, or null if tmux
+ *  refused.
+ *    - default → a fresh WINDOW in `session` (the --root spawn-viewer path).
+ *    - `besidePane` → a SPLIT beside that pane in its own session (the focus
+ *      open-beside-the-caller path); `session` is then only a fallback. */
+export declare function openViewerWindow(nodeId: string, session: string, opts?: {
+    name?: string;
+    cwd?: string;
+    besidePane?: string;
+    waitForBroker?: boolean;
+    initialWhip?: boolean;
+}): Promise<FocusRow | null>;
+export declare function focus(nodeId: string, opts: {
+    pane?: string;
+    newPane?: boolean;
+    inPlace?: boolean;
+    revive: Reviver;
+}): 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)
+ *  and drop its registry row. Best-effort tmux; the DB write always lands. No-op
+ *  when the node has no viewer. */
+export declare function tearDownNode(nodeId: string, keepPane?: string): Promise<void>;
+/** 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
+ *  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
+ *  viewer pane. No-op (false) when there is no live viewer pane to close. */
+export declare function detachToBackground(nodeId: string, pane?: string): Promise<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 — except an OPEN managed worktree keeps
+ *  its node identity so the worktree remains owned and can later be closed.
+ *  Returns true when it reaped. No-op (false) on a node that produced output,
+ *  is mid-first-turn, owns an open managed worktree, or no longer exists. */
+export declare function reapIfEmpty(nodeId: string, keepPane?: string, teardown?: boolean): Promise<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), dead rows,
+ *  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;
+}): Promise<string[]>;

package/dist/core/runtime/placement.js

@@ -0,0 +1,418 @@
+// placement.ts — the VIEWER REGISTRY + the model-over-driver tmux front door.
+//
+// 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 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:
+//
+//   • The VIEWER REGISTRY — the `focuses` table, schema unchanged, now read as
+//     "node_id -> the node's one viewer %pane in `session`" (UNIQUE(node_id) =
+//     one viewer per node). focusOf/isFocused/focusByPane/focusedNodes/
+//     listFocuses read it (lazily GC'ing rows whose pane is gone or no longer
+//     carries this node's `@crtr_node` tag); registerViewerFocus writes it.
+//   • focus(nodeId) — ensure the broker engine is alive (injected reviver) +
+//     wait view.sock, then ensure the node's ONE viewer pane is forefront: reuse
+//     it wherever it already lives (switching sessions when needed), else open
+//     one beside the caller.
+//   • openViewerWindow / registerViewerFocus — the shared viewer-pane opener +
+//     row registrar used by BOTH spawn (a background viewer window) and focus.
+//   • tearDownNode / detachToBackground — close a node's viewer pane + row.
+//   • The chrome/viewer tmux re-exports (§2.1): placement stays the sanctioned
+//     model-over-driver. Raw driver access is confined to placement, its pure
+//     tmux half, the bindings owner, and tmux chrome.
+import { envNodeId } from '../../shared/env.js';
+import { getNode, fullName, deleteNode, listNodes, openFocusRow, closeFocusRow, closeFocusRowOnPane, getFocusByNodeForUpdate, getFocusByNode, getFocusByPane, getFocusById, listFocuses as listFocusRows, } from '../canvas/index.js';
+import { nodeHasAssistantMessage } from '../canvas/render-source.js';
+import { headlessBrokerHost } from './host.js';
+import { publishNotice } from './close.js';
+import { paneExists, paneStateAsync, listLivePanesAsync, paneLocation, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, respawnPaneSync, windowOfPane, renameWindow, } from './tmux-driver.js';
+// The PURE tmux + broker-socket half now lives in placement-tmux.ts. placement
+// composes the viewer OPENER over openViewerPane (tmux) + registerViewerFocus
+// (the db write). viewerSplitEnv + waitForBrokerViewSocket are re-exported here
+// (below) so placement's existing importers (daemon runtime, handlers) are
+// unchanged.
+import { openViewerPane, viewerSplitEnv, waitForBrokerViewSocket } from './placement-tmux.js';
+import { newJobId } from './nodes.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.
+// These are the chrome + viewer verbs that survive the cut (the engine-in-pane
+// verbs — respawnPane, respawnPaneDetached, swapPaneInPlace, breakPaneToSession,
+// joinPane, setWindowOption, setRemainOnExit — are deleted). `breakPane` +
+// `selectLayout` are FRESH minimal viewer-chrome helpers (not the deleted
+// engine-in-pane `breakPaneToSession`): `surface tmux-spread` breaks the caller's
+// viewer pane into its own window and tiles sibling viewers beside it.
+// `piCommand`, `paneCurrentPath`, and `shellQuote` remain available to command
+// modules that need to build or inspect tmux pane commands without importing
+// tmux-driver.ts directly.
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, listLivePanesAsync, paneStateAsync, } from './tmux-driver.js';
+export { installTmuxBindings } from './tmux-bindings.js';
+// Viewer registry reads — COMPOSE over the canvas focuses table (§2.3/§4).
+//
+// placement is the front door for "which nodes have a viewer on screen"; the SQL
+// lives in the canvas layer (canvas/focuses.ts) and placement just reads it. A
+// node has at most one viewer (UNIQUE node_id), so focusOf returns a single row.
+//
+// GC is lazy on read: a row whose viewer pane no longer exists (the user closed
+// the window, the attach client died) is pruned the next time it is read, so the
+// registry self-heals without a sweeper.
+/** Prune a viewer row whose pane is gone; return it iff its pane is still live. `livePanes` is one `list-panes` answer for a batch of rows. */
+async function liveOrPrune(f, livePanes = null) {
+    if (f === null)
+        return null;
+    // A probe that timed out is not "gone": only a pane tmux answered for as missing loses its row.
+    if (f.pane !== null && !(livePanes !== null ? livePanes.has(f.pane) : await paneStateAsync(f.pane) !== 'gone')) {
+        await closeFocusRow(f.focus_id);
+        return null;
+    }
+    return f;
+}
+/** The viewer a node has on screen, or null. UNIQUE(node_id) ⇒ at most one. */
+export async function focusOf(nodeId) {
+    return await liveOrPrune(await getFocusByNode(nodeId));
+}
+/** Read a node's viewer row and probe its pane with a bounded, non-blocking tmux call. Call it BEFORE `withCanvasWrite`: the
+ *  probe holds no connection, and a hung tmux costs one timeout instead of an open transaction. A timed-out probe counts as live. */
+export async function probeViewer(nodeId) {
+    const row = await getFocusByNode(nodeId);
+    if (row === null)
+        return { nodeId, live: null, stale: null };
+    if (row.pane === null || await paneStateAsync(row.pane) !== 'gone')
+        return { nodeId, live: row, stale: null };
+    return { nodeId, live: null, stale: row };
+}
+/** Inside the write: re-read the node's viewer row under its lock and compare it with the probe. A row that matches the probe
+ *  (same focus and pane) keeps the probe's verdict, and a stale one is deleted here, only while it is still on the probed pane.
+ *  A row that differs from the probe — re-pointed to another pane, or created after an empty probe — was never probed, so it
+ *  counts as a live viewer and nothing is deleted; the next settle probes it. No tmux runs here. */
+export async function confirmViewer(probe) {
+    const current = await getFocusByNodeForUpdate(probe.nodeId);
+    const probed = probe.live ?? probe.stale;
+    if (current === null)
+        return { nodeId: probe.nodeId, live: null, stale: null };
+    if (probed === null || probed.focus_id !== current.focus_id || probed.pane !== current.pane) {
+        return { nodeId: probe.nodeId, live: current, stale: null };
+    }
+    if (probe.stale !== null) {
+        await closeFocusRowOnPane(current.focus_id, current.pane);
+        return { nodeId: probe.nodeId, live: null, stale: null };
+    }
+    return { nodeId: probe.nodeId, live: current, stale: null };
+}
+/** Does this node have a live viewer on screen? */
+export async function isFocused(nodeId) {
+    return await focusOf(nodeId) !== null;
+}
+/** The viewer realized by a given pane (`%id`), or null. */
+export async function focusByPane(pane) {
+    return await liveOrPrune(await getFocusByPane(pane));
+}
+/** The set of node ids that currently have a live viewer. */
+export async function focusedNodes() {
+    return new Set((await listFocuses()).map((f) => f.node_id));
+}
+/** Every live viewer row (GC'ing any whose pane has gone). */
+export async function listFocuses() {
+    const live = [];
+    const rows = await listFocusRows();
+    // One non-blocking probe for every row: a canvas snapshot lists focuses, and a blocking tmux exec per row stalls the daemon's event loop.
+    // An unreachable tmux (null) falls back to the per-pane probe.
+    const livePanes = rows.some((f) => f.pane !== null) ? await listLivePanesAsync() : null;
+    for (const f of rows) {
+        if (await liveOrPrune(f, livePanes) !== null)
+            live.push(f);
+    }
+    return live;
+}
+function newFocusId() {
+    return `f-${newJobId()}`;
+}
+/** 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 —
+ *  the focuses table keys on pane + session only. The attach client self-tags the
+ *  pane `@crtr_node` on connect, so `nodeInPane` resolves it either way. */
+export async function registerViewerFocus(nodeId, pane, session, window) {
+    void window;
+    const byPane = await getFocusByPane(pane);
+    if (byPane !== null)
+        return byPane;
+    const byNode = await getFocusByNode(nodeId);
+    if (byNode !== null)
+        return byNode;
+    const focusId = newFocusId();
+    await openFocusRow(focusId, pane, session, nodeId);
+    return await getFocusById(focusId);
+}
+/** 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
+ *  connects to the node's `view.sock` and renders/drives the live broker engine
+ *  — it NEVER launches the engine (the one-writer invariant; the caller ensures
+ *  the broker is alive first). Returns the registered viewer row, or null if tmux
+ *  refused.
+ *    - default → a fresh WINDOW in `session` (the --root spawn-viewer path).
+ *    - `besidePane` → a SPLIT beside that pane in its own session (the focus
+ *      open-beside-the-caller path); `session` is then only a fallback. */
+export async function openViewerWindow(nodeId, session, opts = {}) {
+    const opened = openViewerPane(nodeId, session, opts);
+    if (opened === null)
+        return null;
+    return await registerViewerFocus(nodeId, opened.pane, opened.session, opened.window);
+}
+// focus — the front door for `surface node focus` / `surface node cycle` / nav (§A.4)
+/** 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 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
+ *        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 ⇒ navigate to it in place
+ *        (switchClient+selectWindow+selectPane), including when it lives in a
+ *        different session. The viewer's established spatial home wins over
+ *        opening or moving a duplicate 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. */
+/** 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 = await getNode(nodeId);
+    if (meta === null)
+        return { focused: false, session: null, inPlace: false, revived: false };
+    const callerPane = opts.pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    if (callerPane === undefined || callerPane === '') {
+        return { focused: false, session: null, inPlace: false, revived: false };
+    }
+    // (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);
+    const revivedLaunch = opts.revive(nodeId);
+    const revived = !wasAlive;
+    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
+    // session name openViewerWindow falls back to if it cannot read the freshly
+    // split pane's location — the caller's own session.
+    const callerSession = paneLocation(callerPane)?.session ?? null;
+    const fallbackSession = callerSession ?? '';
+    // (b0) --in-place → the CALLER pane BECOMES this node's viewer, replacing
+    //      whatever it showed (the attach subagent scroll+swap: ↓ into the reports
+    //      roster, Enter dives into that child right here, no new split). This
+    //      re-execs the caller pane via `respawn-pane -k`, so it MUST be driven
+    //      from OUTSIDE that pane's process tree (the viewer shells this through
+    //      `tmux run-shell`, never a direct child) — else the respawn kills its own
+    //      driver mid-call. Move the child's viewer here if it had one elsewhere
+    //      (UNIQUE one-viewer-per-node) and drop the caller pane's prior viewer row
+    //      (that node's broker keeps running headless, reconnectable by a later
+    //      focus). The respawned `crtr surface attach` replays scrollback from the
+    //      welcome snapshot and self-tags the pane `@crtr_node`.
+    if (opts.inPlace === true) {
+        const prior = await focusOf(nodeId);
+        if (prior !== null) {
+            if (prior.pane !== null && prior.pane !== callerPane && paneExists(prior.pane))
+                closePane(prior.pane);
+            await closeFocusRow(prior.focus_id);
+        }
+        const here = await getFocusByPane(callerPane);
+        if (here !== null && here.node_id !== nodeId)
+            await closeFocusRow(here.focus_id);
+        // Clear the stale tag before respawn so it never names the wrong node during
+        // the gap before the fresh attach re-tags on connect.
+        try {
+            setPaneOption(callerPane, '@crtr_node', '');
+        }
+        catch { /* best-effort */ }
+        const window = windowOfPane(callerPane);
+        // Continuity: the fresh viewer highlights the previously open node, which
+        // becomes visible in its self-excluding roster after the swap.
+        const priorNodeId = here?.node_id;
+        const env = priorNodeId === undefined
+            ? viewerSplitEnv()
+            : { ...viewerSplitEnv(), CRTR_ATTACH_ROSTER: priorNodeId };
+        const ok = respawnPaneSync({ pane: callerPane, cwd: meta.cwd, env, command: `crtr surface attach to ${nodeId}` });
+        if (ok) {
+            if (window !== null)
+                renameWindow(window, fullName(meta));
+            await registerViewerFocus(nodeId, callerPane, callerSession, window);
+        }
+        return { focused: ok, session: callerSession, inPlace: true, revived };
+    }
+    // (b) --new-pane → always a fresh viewer beside the caller. Drop any prior
+    //     viewer this node holds elsewhere (UNIQUE(node_id): one viewer per node).
+    if (opts.newPane === true) {
+        const prior = await focusOf(nodeId);
+        if (prior !== null) {
+            if (prior.pane !== null && paneExists(prior.pane))
+                closePane(prior.pane);
+            await closeFocusRow(prior.focus_id);
+        }
+        const opened = await 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 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
+    //     tag names this node; on mismatch the row is stale → prune it and fall
+    //     through to open a fresh viewer beside the caller.
+    const existing = await focusOf(nodeId);
+    if (existing !== null && existing.pane !== null) {
+        if (getPaneOption(existing.pane, '@crtr_node') === nodeId) {
+            const loc = paneLocation(existing.pane);
+            if (loc !== null) {
+                // Navigate to the viewer wherever it already lives. For a cross-session
+                // target, switch-client carries this tmux client to that session; for a
+                // same-session target it is an idempotent no-op. Never destroy and reopen
+                // a viewer merely because its established pane lives in another session.
+                switchClient(loc.session);
+                selectWindow(loc.session, loc.window);
+                selectPane(existing.pane);
+                return { focused: true, session: loc.session, inPlace: true, revived };
+            }
+            // The row names a pane that vanished between focusOf() and paneLocation().
+            // Prune it and fall through to opening the node's one viewer beside caller.
+            await closeFocusRow(existing.focus_id);
+        }
+        else {
+            // Pane survived but no longer hosts this node's viewer (clean detach left
+            // the user's shell, or the pane was reused) — drop the stale row only; do
+            // NOT closePane (it is the user's shell / another node's viewer).
+            await closeFocusRow(existing.focus_id);
+        }
+    }
+    // (d) No live viewer → open one beside the caller and register the row.
+    const opened = await 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 };
+}
+// Teardown / detach — close a node's viewer pane + row
+/** 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)
+ *  and drop its registry row. Best-effort tmux; the DB write always lands. No-op
+ *  when the node has no viewer. */
+export async function tearDownNode(nodeId, keepPane) {
+    const f = await focusOf(nodeId);
+    if (f === null)
+        return; // no viewer (focusOf already GC'd a gone one)
+    // `keepPane` is a BORROWED pane crtr did not create — the front-door root's
+    // viewer runs inside the user's own pre-existing shell pane (bootRoot registers
+    // that shell pane as the viewer focus). Killing it here would take the user's
+    // shell down with the node, closing the whole tmux pane on a plain ctrl+c
+    // detach. crtr must never kill a pane it merely borrowed: drop the row, let the
+    // pane fall back to its shell when the viewer process exits.
+    if (f.pane !== null && f.pane !== keepPane && paneExists(f.pane))
+        closePane(f.pane);
+    await closeFocusRow(f.focus_id);
+}
+/** 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
+ *  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
+ *  viewer pane. No-op (false) when there is no live viewer pane to close. */
+export async function detachToBackground(nodeId, pane) {
+    const viewer = pane ?? (await focusOf(nodeId))?.pane ?? null;
+    if (viewer === null || !paneExists(viewer))
+        return false;
+    const f = await focusByPane(viewer);
+    if (f !== null)
+        await closeFocusRow(f.focus_id);
+    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.
+    await 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. */
+async function isEmptyNode(nodeId) {
+    const m = await getNode(nodeId);
+    if (m === null)
+        return false;
+    if (m.streaming === true && isPidAlive(m.pi_pid))
+        return false;
+    return !await 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 — except an OPEN managed worktree keeps
+ *  its node identity so the worktree remains owned and can later be closed.
+ *  Returns true when it reaped. No-op (false) on a node that produced output,
+ *  is mid-first-turn, owns an open managed worktree, or no longer exists. */
+export async function reapIfEmpty(nodeId, keepPane, teardown = true) {
+    const meta = await getNode(nodeId);
+    if (meta?.managed_worktree?.state === 'open' || !await isEmptyNode(nodeId))
+        return false;
+    if (teardown)
+        void headlessBrokerHost.teardown(nodeId);
+    await tearDownNode(nodeId, keepPane);
+    return (await deleteNode(nodeId)).deleted;
+}
+/** 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), dead rows,
+ *  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 async function reapEmptyNodes(opts = {}) {
+    const dryRun = opts.dryRun ?? false;
+    const selfId = envNodeId() ?? '';
+    const reaped = [];
+    for (const row of await listNodes()) {
+        const id = row.node_id;
+        const meta = await getNode(id);
+        if (id === selfId
+            || row.status === 'dead'
+            || isPidAlive(row.pi_pid)
+            || meta?.managed_worktree?.state === 'open'
+            || !await isEmptyNode(id))
+            continue;
+        if (!dryRun) {
+            await publishNotice(id, 'notice.close', `Child closed — ${meta?.name ?? id} (${id}) was closed from the canvas and is no longer running.`, { reason: 'child-closed', child: id });
+            void headlessBrokerHost.teardown(id);
+            await tearDownNode(id);
+            if (!(await deleteNode(id)).deleted)
+                continue;
+        }
+        reaped.push(id);
+    }
+    return reaped;
+}

package/dist/core/runtime/progress-bar.d.ts

@@ -0,0 +1,13 @@
+/** A running progress bar line. `setFraction` fills it from a real count;
+ *  leaving it unset keeps the indeterminate slider. `stop` erases the line and
+ *  resolves once the painter has released the terminal, so the caller can
+ *  write its own outcome line without interleaving. */
+export interface ProgressBar {
+    setFraction(fraction: number): void;
+    stop(): Promise<void>;
+}
+/** Start an animated bar on `stream`, drawn by a child process so it keeps
+ *  moving while this process blocks inside the step it describes. */
+export declare function startProgressBar(label: string, stream?: NodeJS.WriteStream & {
+    fd: number;
+}): ProgressBar;