@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/runtime/model-swap.js

@@ -0,0 +1,95 @@
+// model-swap.ts — the engine behind `crtr node config`: swap a node's model
+// (and thus its provider) WITHOUT attaching a viewer, persisting the choice so
+// it survives revives. Two paths, chosen on broker liveness:
+//
+//   LIVE   — the node's broker is up (recorded pi_pid alive AND view.sock
+//            present): connect to view.sock, claim controller, send `set_model`,
+//            await the ack. The broker's broadcastModelChanged already persists
+//            the choice via persistModelChoice (model_override + launch.model), so
+//            this path NEVER writes the recipe itself — it reads back the resolved
+//            provider/id from the freshly-updated row.
+//   DORMANT — no live broker: write the durable recipe directly (mirroring exactly
+//            what persistModelChoice writes) so the next revive picks it up.
+//
+// This complements the in-viewer `/model` slash command for the headless case.
+import { existsSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { getNode, updateNode } from '../canvas/index.js';
+import { viewSocketPath } from '../canvas/paths.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { ViewSocketClient } from './view-socket-client.js';
+/** How long to wait for the broker's `set_model` ack before giving up. The
+ *  switch is local (engine method + a DB write), so this is generous slack. */
+const ACK_TIMEOUT_MS = 15_000;
+/** True when the node's broker engine is reachable: its recorded pid is alive
+ *  AND its view.sock exists. Both are required — a dead pid with a stale socket,
+ *  or a live pid mid-boot before it binds the socket, is NOT a live broker. */
+export function isBrokerLive(meta) {
+    return isPidAlive(meta.pi_pid) && existsSync(viewSocketPath(meta.node_id));
+}
+/** Swap a LIVE node's model over its view.sock. Connects, claims controller
+ *  (hello + request_control, so an attached viewer never blocks the swap), sends
+ *  `set_model`, and resolves with the broker-resolved `provider/id` on its ack —
+ *  read back from the row the broker just persisted (model_changed.model carries
+ *  only the bare id). Rejects with the broker's message on an `error` frame (e.g.
+ *  `no model matching '<spec>' in the registry`), on connect failure, or timeout. */
+export function setModelLive(nodeId, spec) {
+    return new Promise((resolve, reject) => {
+        const client = new ViewSocketClient(nodeId);
+        const clientId = randomUUID();
+        let settled = false;
+        let resolvedId;
+        const timer = setTimeout(() => finish(() => reject(new Error(`timed out after ${ACK_TIMEOUT_MS}ms waiting for the broker to ack the model switch`))), ACK_TIMEOUT_MS);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+        function finish(act) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                client.close();
+            }
+            catch { /* best-effort */ }
+            act();
+        }
+        client.on('error', (err) => finish(() => reject(err)));
+        client.on('close', () => finish(() => reject(new Error('broker connection closed before it acked the model switch'))));
+        client.on('connect', () => {
+            // Claim control unconditionally: hello admits us as controller only if none
+            // is held; request_control preempts an attached viewer (idempotent when we
+            // already hold it). The broker processes these in order before set_model.
+            client.send({ type: 'hello', role: 'controller', client_id: clientId });
+            client.send({ type: 'request_control' });
+            client.send({ type: 'set_model', model: spec });
+        });
+        client.on('frame', (frame) => {
+            if (frame.type === 'model_changed') {
+                resolvedId = frame.model;
+            }
+            else if (frame.type === 'ack' && frame.for === 'set_model' && frame.ok) {
+                // The broker persisted model_override (full provider/id) in
+                // broadcastModelChanged BEFORE flushing these frames, so the row is
+                // authoritative; fall back to the bare id, then the raw spec.
+                const persisted = getNode(nodeId)?.model_override ?? undefined;
+                finish(() => resolve(persisted ?? resolvedId ?? spec));
+            }
+            else if (frame.type === 'error') {
+                finish(() => reject(new Error(frame.message)));
+            }
+        });
+        client.connect();
+    });
+}
+/** Persist a model choice into a DORMANT node's durable recipe — mirrors exactly
+ *  what the broker's persistModelChoice writes on a live switch: `model_override`
+ *  (so polymorphs preserve it via buildLaunchSpec) and `launch.model` (the recipe
+ *  buildPiArgv replays on revive). `spec` must already be a concrete `provider/id`
+ *  (normalizeModel maps tiers/aliases; a bare substring cannot resolve offline). */
+export function persistDormantModel(nodeId, spec) {
+    const meta = getNode(nodeId);
+    if (meta === null)
+        return;
+    const launch = meta.launch !== undefined ? { ...meta.launch, model: spec } : undefined;
+    updateNode(nodeId, { model_override: spec, ...(launch !== undefined ? { launch } : {}) });
+}

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

@@ -16,3 +16,10 @@ export declare function slugFromPrompt(prompt: string): string;
  *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
  *  same session, instead of waiting for the next revive/cycle. */
 export declare function generateAndPersistName(nodeId: string, prompt: string, onNamed?: (meta: NodeMeta) => void): void;
+/** 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 declare function titleSlug(title: string): string;
+/** 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 declare function generateIssueTitle(note: string): Promise<string>;

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. */
@@ -42,21 +51,21 @@ export interface FocusResult {
     inPlace: boolean;
     revived: boolean;
 }
-/** 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
  *  server env, like every other crtr chrome pane). One helper so the viewer-pane
  *  sites can't drift. */
 export declare function viewerSplitEnv(): Record<string, string>;
-/** 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 —
  *  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): FocusRow | null;
-/** 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
@@ -72,43 +81,39 @@ 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)
  *  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): void;
-/** 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
  *  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[];