@north-light/crouter 0.3.172 → 0.3.174

package/dist/commands/node/pyramid.js

@@ -0,0 +1,79 @@
+// The node-subtree slash command is provisioned with the node family.
+export const pyramidSlash = {
+    name: 'pyramid',
+    description: 'Explain a topic as a live-building Minto pyramid diagram, backed by parallel explore agents.',
+    argumentHint: '<topic to explain>',
+    body: [
+        '# Pyramid explanation',
+        '',
+        'Explain **$ARGUMENTS** as a *pyramid*: lead with the answer, support it with a few key pillars, ground each pillar in evidence. You build this as a LIVE termrender diagram that fills in as parallel research lands — the user watches the skeleton grow into a complete picture.',
+        '',
+        '## The pyramid (Minto principle)',
+        '- **Apex** — ONE crisp sentence: the single governing answer/claim, the thing worth remembering.',
+        '- **Pillars** — 2–4 MECE supporting arguments that together prove the apex.',
+        '- **Base** — concrete evidence under each pillar (mechanisms, `file:line` refs, numbers, sources).',
+        '',
+        'Top-down: the reader gets the conclusion first, then descends for as much support as they want.',
+        '',
+        '## Workflow',
+        '',
+        '1. **Frame it.** Restate the topic in one line and commit to a *working* apex hypothesis (you will sharpen it). Name the 2–4 pillars you expect to need.',
+        '',
+        '2. **Scaffold the live diagram FIRST.** Write the termrender skeleton below to `./pyramid-<slug>.md` (apex = your hypothesis, pillars = titles, every base entry marked `[?]` pending). Then open it live so the user watches it build:',
+        '   ```bash',
+        '   termrender pane open ./pyramid-<slug>.md --watch   # detached tmux side-pane; re-renders on every save',
+        '   ```',
+        '   Not in tmux? Tell the user to run `termrender doc watch ./pyramid-<slug>.md` in another terminal, then continue regardless.',
+        '',
+        '3. **Investigate in parallel — do not block.** Fan out ONE explore agent per pillar/unknown AND dig into what you can answer yourself, concurrently:',
+        '   ```bash',
+        '   crtr node new "Investigate: <focused question for this pillar>. Report findings with sources / file:line refs." --kind explore',
+        '   ```',
+        '   You auto-subscribe; each finish wakes you. Never poll or wait — kick them all off, then start filling in what you already know.',
+        '',
+        '4. **Live-update as findings land.** Every time you learn something — your own digging or an explore report — EDIT the diagram file: flip a `[?]` to `[x]` (or `[!]` for a caveat/risk), add evidence under the right pillar, sharpen or rewrite the apex, drop a pillar that did not hold. Each save re-renders the pane. The diagram visibly grows skeleton → complete.',
+        '',
+        '5. **Land it.** When the apex is one crisp sentence, the pillars are MECE, and the base is concrete, do a final pass for accuracy, then give the user a 3–4 sentence spoken summary that mirrors apex → pillars. Tell them the diagram file path.',
+        '',
+        '## termrender skeleton (write this verbatim, then keep editing it)',
+        '',
+        'Apex panel on top, a divider, then the pillars as a row of boxes below — a literal pyramid: 1 claim over N supports.',
+        '```markdown',
+        ':::panel{title="<TOPIC>" color="cyan"}',
+        '**<one-line apex answer — your governing claim>**',
+        ':::',
+        '',
+        ':::divider{label="why"}',
+        ':::',
+        '',
+        '::::::columns',
+        ':::::col{width="33%"}',
+        '::::panel{title="Pillar 1 — <claim>" color="green"}',
+        ':::tree',
+        'evidence A [x]',
+        'evidence B [?]',
+        ':::',
+        '::::',
+        ':::::',
+        ':::::col{width="33%"}',
+        '::::panel{title="Pillar 2 — <claim>" color="green"}',
+        ':::tree',
+        'evidence C [?]',
+        ':::',
+        '::::',
+        ':::::',
+        ':::::col{width="34%"}',
+        '::::panel{title="Pillar 3 — <claim>" color="green"}',
+        ':::tree',
+        'evidence D [?]',
+        ':::',
+        '::::',
+        ':::::',
+        '::::::',
+        '```',
+        '',
+        '**Nesting rule (termrender will reject the file otherwise): an OUTER directive needs strictly MORE colons than the directive nested inside it.** Hence `::::::columns` (6) wraps `:::::col` (5) wraps `::::panel` (4) wraps `:::tree` (3). Every block closes with a bare run of its OWN colon count on its own line. Run `termrender doc check ./pyramid-<slug>.md` after each edit — if it errors, fix the colon counts before re-saving.',
+        '',
+        'Markers inside a tree: `[x]` → ✔ confirmed, `[!]` → ⚠ caveat/risk; `[?]` is not a marker and stays literal — use it for still-pending. Write structure only — termrender draws every box, border, and guide line; never hand-draw ASCII. Keep the apex to one sentence; push all detail into the base.',
+    ].join('\n'),
+};

package/dist/commands/node/subscription.d.ts

@@ -0,0 +1 @@
+export declare const nodeSubscription: import("../../core/command.js").BranchDef;

package/dist/commands/node/subscription.js

@@ -0,0 +1,82 @@
+// `crtr node subscription` — push-delivery edge controls.
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+function resolveSubscriber(input) {
+    const sub = input['subscriber'] ?? process.env['CRTR_NODE_ID'];
+    if (sub === undefined || sub === '') {
+        throw new InputError({ error: 'no_subscriber', message: 'no subscriber (set CRTR_NODE_ID or pass --subscriber)', field: 'subscriber', next: 'Run from inside a node, or pass --subscriber <id>.' });
+    }
+    return sub;
+}
+const nodeSubscribe = defineLeaf({
+    name: 'add',
+    description: 'wire a subscribes_to edge between any pair (active or --passive)',
+    whenToUse: 'you want to make one node receive another node’s pushes, actively or passively. Managed-child creation already adds its active edge; use this for other subscriber-to-publisher pairs',
+    help: {
+        name: 'node subscription add',
+        summary: 'wire a subscribes_to edge so one node receives another\'s pushes — the subscriber can be you (default) or, with --subscriber, ANY node, to ANY publisher. Re-running flips an existing edge\'s active/passive mode.',
+        params: [
+            { kind: 'positional', name: 'publisher', required: true, constraint: 'The node to subscribe TO — whose pushes get delivered to the subscriber.' },
+            { kind: 'flag', name: 'subscriber', type: 'string', required: false, constraint: 'Who receives the pushes. Defaults to the calling node (CRTR_NODE_ID). Pass any node id to wire a third party.' },
+            { kind: 'flag', name: 'passive', type: 'bool', required: false, constraint: 'Passive subscription: pushes ACCUMULATE without waking the subscriber, then auto-inject as timestamped XML pre-text on its next message. Omit for an active (wake-on-push) subscription.' },
+        ],
+        output: [
+            { name: 'subscribed', type: 'boolean', required: true, constraint: 'True when the edge was created/updated.' },
+            { name: 'subscriber', type: 'string', required: true, constraint: 'The receiving node.' },
+            { name: 'publisher', type: 'string', required: true, constraint: 'The node being subscribed to.' },
+            { name: 'mode', type: 'string', required: true, constraint: '"active" (wakes on push) or "passive" (accumulates, no wake).' },
+        ],
+        outputKind: 'object',
+        effects: ['Upserts a subscribes_to edge in canvas.db (active flag set from --passive).', 'Passive edges never wake the subscriber and do not hold it alive (excluded from the stop-guard).'],
+    },
+    run: async (input) => {
+        const publisher = input['publisher'];
+        const subscriber = resolveSubscriber(input);
+        const passive = input['passive'] === true;
+        if (subscriber === publisher) {
+            throw new InputError({ error: 'self_subscribe', message: 'a node cannot subscribe to itself', next: 'Pick a different publisher.' });
+        }
+        await cliClient()
+            .subscribe(subscriber, { target: publisher, active: !passive })
+            .catch((err) => rethrowAsCliError(err));
+        return { subscribed: true, subscriber, publisher, mode: passive ? 'passive' : 'active' };
+    },
+    render: (r) => `Subscribed ${r['subscriber']} → ${r['publisher']} (${r['mode']}).`,
+});
+const nodeUnsubscribe = defineLeaf({
+    name: 'remove',
+    description: 'drop a subscribes_to edge',
+    whenToUse: 'you want to stop one node receiving a publisher’s pushes; removal is idempotent',
+    help: {
+        name: 'node subscription remove',
+        summary: 'drop a subscribes_to edge — the subscriber (you by default, or any node via --subscriber) stops receiving the publisher\'s pushes.',
+        params: [
+            { kind: 'positional', name: 'publisher', required: true, constraint: 'The node to stop subscribing to.' },
+            { kind: 'flag', name: 'subscriber', type: 'string', required: false, constraint: 'Who to detach. Defaults to the calling node (CRTR_NODE_ID).' },
+        ],
+        output: [
+            { name: 'unsubscribed', type: 'boolean', required: true, constraint: 'True when the edge was removed (idempotent — also true if none existed).' },
+            { name: 'subscriber', type: 'string', required: true, constraint: 'The detached node.' },
+            { name: 'publisher', type: 'string', required: true, constraint: 'The node it stopped subscribing to.' },
+        ],
+        outputKind: 'object',
+        effects: ['Deletes the subscribes_to edge from canvas.db.'],
+    },
+    run: async (input) => {
+        const publisher = input['publisher'];
+        const subscriber = resolveSubscriber(input);
+        await cliClient()
+            .unsubscribe(subscriber, publisher)
+            .catch((err) => rethrowAsCliError(err));
+        return { unsubscribed: true, subscriber, publisher };
+    },
+    render: (r) => `Unsubscribed ${r['subscriber']} from ${r['publisher']}.`,
+});
+export const nodeSubscription = defineBranch({
+    name: 'subscription',
+    description: 'manage push-delivery edges between nodes',
+    whenToUse: 'you need an ongoing active or passive subscriber-to-publisher delivery edge that spawn did not create, or need to remove one',
+    help: { name: 'node subscription', summary: 'add or remove subscriber-to-publisher push-delivery edges' },
+    children: [nodeSubscribe, nodeUnsubscribe],
+});

package/dist/commands/node/wait.d.ts

@@ -0,0 +1 @@
+export declare const nodeWaitBranch: import("../../core/command.js").BranchDef;

package/dist/commands/node/wait.js

@@ -0,0 +1,159 @@
+// `crtr node wait` — durable controller and deadline waits.
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { parseWhen } from '../../core/wake.js';
+import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
+import { shellQuote } from '../surface/node/placement.js';
+function armerId() {
+    const id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id === '') {
+        throw new InputError({ error: 'no_node', message: 'no node to anchor a deadline cron (CRTR_NODE_ID unset)', next: 'Run from inside a node.' });
+    }
+    return id;
+}
+/** Build ParseOpts, including `tz` only when actually provided. */
+function parseOpts(now, tz) {
+    return tz !== undefined && tz.trim() !== '' ? { tz, now } : { now };
+}
+/** Map a time-grammar error to the rendered error block. */
+function throwTimeError(e) {
+    const next = {
+        wake_in_past: 'Pick a future instant — a positive duration ("5m","2h") or an ISO time later than now.',
+        bad_when: 'Use a duration ("5m","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00").',
+        bad_cadence: 'Use a duration ("6h"), a 5-field cron ("0 9 * * *"), or an @alias ("@daily").',
+        unknown_zone: 'Pass --tz with an IANA zone name (e.g. "America/New_York").',
+        cadence_too_fast: 'Use a cadence of at least 60s (e.g. "1m","5m","1h").',
+    };
+    throw new InputError({ error: e.code, message: e.message, received: e.received, next: next[e.code] ?? 'Fix the time value and retry.' });
+}
+/** A human ETA hint like " (~5m)" from a fire-at ISO relative to now. '' if past. */
+function etaHint(fireAt, now) {
+    const ms = new Date(fireAt).getTime() - now.getTime();
+    if (!Number.isFinite(ms) || ms <= 0)
+        return '';
+    const mins = Math.round(ms / 60_000);
+    if (mins < 60)
+        return ` (~${mins}m)`;
+    const hrs = Math.round(ms / 3_600_000);
+    if (hrs < 48)
+        return ` (~${hrs}h)`;
+    return ` (~${Math.round(ms / 86_400_000)}d)`;
+}
+function deadlineHeredoc(body, nodeId) {
+    let delimiter = 'CRTR_DEADLINE';
+    let suffix = 0;
+    const lines = new Set(body.split('\n'));
+    while (lines.has(delimiter))
+        delimiter = `CRTR_DEADLINE_${++suffix}`;
+    return `crtr node message send --to ${shellQuote(nodeId)} --tier urgent <<'${delimiter}'\n${body}\n${delimiter}`;
+}
+const nodeWaitDeadline = defineLeaf({
+    name: 'deadline',
+    description: 'race this node’s next wake against one urgent deadline cron',
+    whenToUse: 'you are waiting on an event nothing can push for, so a self-scheduled deadline must settle the wait',
+    help: {
+        name: 'node wait deadline',
+        summary: 'arm one cancel-on-wake deadline cron for this node',
+        params: [
+            { kind: 'stdin', name: 'body', required: true, constraint: 'Policy delivered urgently to this node if the deadline fires first.' },
+            { kind: 'flag', name: 'until', type: 'string', required: true, constraint: 'Future duration, zoned ISO timestamp, or bare ISO timestamp interpreted in --tz or host-local time.' },
+            { kind: 'flag', name: 'tz', type: 'string', required: false, constraint: 'IANA timezone for a bare ISO --until value.' },
+        ],
+        output: [
+            { name: 'id', type: 'string', required: true, constraint: 'The armed cron id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The cron label.' },
+            { name: 'fires_at', type: 'string', required: true, constraint: 'Absolute UTC deadline.' },
+            { name: 'guidance', type: 'string', required: true, constraint: 'How to inspect the cron and dorm.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Arms one anchored cancel-on-wake cron. Any wake of this node cancels it; otherwise it urgently sends the body to this node at the deadline.',
+            'Re-arming replaces this node’s pending deadline rather than stacking a second.',
+        ],
+    },
+    run: async (input) => {
+        const self = armerId();
+        const body = typeof input['body'] === 'string' ? input['body'].trim() : '';
+        if (body === '')
+            throw new InputError({ error: 'empty_body', message: 'a deadline body is required', field: 'body', next: 'Pass the timeout policy on stdin.' });
+        const until = typeof input['until'] === 'string' ? input['until'].trim() : '';
+        if (until === '')
+            throw new InputError({ error: 'missing_until', message: '--until is required', field: 'until', next: 'Pass a future duration or timestamp.' });
+        const tz = typeof input['tz'] === 'string' && input['tz'].trim() !== '' ? input['tz'] : undefined;
+        const now = new Date();
+        const parsed = parseWhen(until, parseOpts(now, tz));
+        if ('error' in parsed)
+            throwTimeError(parsed.error);
+        const profile = process.env['CRTR_PROFILE_ID'];
+        // One deadline per node: the arm seam REPLACES this node's pending
+        // cancel-on-wake cron rather than stacking a second one (see armCron in
+        // core/canvas/crons.ts, where the invariant is enforced for every caller).
+        const cron = await cliClient().armCron({
+            name: `deadline:${self}`,
+            command: deadlineHeredoc(body, self),
+            fire_at: parsed.fireAt,
+            recur: null,
+            tz: tz ?? null,
+            created_by: self,
+            cwd: process.cwd(),
+            profile: profile !== undefined && profile !== '' ? profile : null,
+            scope: 'profile',
+            on_output: 'on-failure',
+            sink: null,
+            tier: 'normal',
+            expires_at: null,
+            anchor_node: self,
+            cancel_on_wake: true,
+            run_timeout_s: 300,
+            overlap: 'skip',
+        }).catch(rethrowAsCliError);
+        const guidance = `Deadline cron armed for ${cron.fire_at}${etaHint(cron.fire_at, now)}. End your turn to dorm; any earlier wake cancels it. Inspect pending schedules with \`crtr cron list\`.`;
+        return { id: cron.cron_id, name: cron.name, fires_at: cron.fire_at, guidance };
+    },
+    render: (r) => `Deadline cron armed — ${r['name']} (${r['id']}), fires ${r['fires_at']}.\n\n${r['guidance']}`,
+});
+const nodeWait = defineLeaf({
+    name: 'controller',
+    description: 'wait durably for a named controller message',
+    whenToUse: 'you are a terminal node blocked on one specific live parent or controller and have no managed-child subscription whose report will wake you',
+    help: {
+        name: 'node wait controller',
+        summary: 'declare that your next stop may dorm only until one live controller delivers an inbox message',
+        params: [
+            { kind: 'positional', name: 'controller', type: 'string', required: true, constraint: 'Live node id expected to send the message. It may be your parent or another named controller, but cannot be yourself.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The terminal node that declared the wait.' },
+            { name: 'controller', type: 'string', required: true, constraint: 'The named live sender whose next inbox delivery clears this wait.' },
+        ],
+        outputKind: 'object',
+        effects: ['Durably records the controller on this node. The stop guard permits dormancy only while that controller remains active or idle; its next inbox delivery clears the record before the delivery wakes this node.'],
+    },
+    run: async (input) => {
+        const nodeId = process.env['CRTR_NODE_ID'];
+        if (nodeId === undefined || nodeId === '')
+            throw new InputError({ error: 'no_node', message: 'no node to wait (CRTR_NODE_ID unset)', next: 'Run from inside the terminal node that is blocked.' });
+        const node = await getNodeOrNull(nodeId);
+        if (node === null)
+            throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, next: 'Run from a live canvas node.' });
+        if (node.lifecycle !== 'terminal')
+            throw new InputError({ error: 'resident_node', message: `node ${nodeId} is resident and may already dorm on its inbox`, next: 'Use this only from a terminal node that needs the stop guard to recognize a controller dependency.' });
+        const controller = String(input['controller']).trim();
+        if (controller === nodeId)
+            throw new InputError({ error: 'self_controller', message: 'a node cannot wait for its own message', field: 'controller', next: 'Name the parent or external controller expected to send the message.' });
+        // The server validates the controller exists + is live and records the wait
+        // (handleWait); a 404/422 surfaces as the clean CLI error.
+        await cliClient()
+            .waitNode(nodeId, { controller })
+            .catch((err) => rethrowAsCliError(err));
+        return { node_id: nodeId, controller };
+    },
+    render: (r) => `Waiting for controller ${r['controller']}. End your turn to dorm; its next message wakes you and clears this wait.`,
+});
+export const nodeWaitBranch = defineBranch({
+    name: 'wait',
+    description: 'declare a durable controller or deadline wait',
+    whenToUse: 'a terminal node must dorm for one named controller, or race its inbox against a self-scheduled deadline',
+    help: { name: 'node wait', summary: 'declare durable wait state; choose the event that settles it' },
+    children: [nodeWait, nodeWaitDeadline],
+});

package/dist/commands/node-lifecycle-revive.js

@@ -15,7 +15,6 @@
 // The mass-recovery form — reconnect EVERY disconnected node at once after a
 // reboot/crash — is genuinely graph-wide and stays at `canvas revive --all`
 // (src/commands/revive.ts).
-import { createConnection } from 'node:net';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { defineLeaf } from '../core/command.js';
@@ -28,15 +27,16 @@ import { cliClient, rethrowAsCliError } from './api-client.js';
 // imported from a db-free module: `recordedPidLiveness` (pid.js → fs/ps only),
 // `readFault` (fault.js → paths.js pure helpers + events), `faultNeedsYou`
 // (status-glyph.js → fault.js), and `fullName` from labels.js DIRECTLY (NOT the
-// canvas barrel `index.js`, which re-exports `openDb`). `viewSocketPath`/`jobDir`
-// are pure path helpers (allowed). The former direct `reviveNode`/`getNode`/
-// `assertReopenGate`/`waitForBrokerViewSocket`/`isBusy` imports all reached the
-// db barrel and are replaced by the client call + the inlined helpers below.
+// canvas barrel `index.js`, which re-exports `openDb`). `jobDir` is a pure path
+// helper, and view-socket readiness comes from the db-free probe owner. The former
+// direct `reviveNode`/`getNode`/`assertReopenGate`/`waitForBrokerViewSocket`/`isBusy`
+// imports all reached the db barrel and are replaced by the client call + helpers below.
 import { recordedPidLiveness } from '../core/canvas/pid.js';
 import { readFault } from '../core/runtime/fault.js';
 import { fullName } from '../core/canvas/labels.js';
 import { faultNeedsYou } from '../core/canvas/status-glyph.js';
-import { viewSocketPath, jobDir } from '../core/canvas/paths.js';
+import { jobDir } from '../core/canvas/paths.js';
+import { waitForViewSocketReady } from '../core/runtime/view-socket.js';
 /** --now eligibility for a live, non-busy fault: a daemon-owned AUTO retry
  *  (kick it early instead of waiting out the schedule), or any fault the
  *  canvas dashboard flags "needs you" (`faultNeedsYou`, status-glyph.ts) — the
@@ -55,59 +55,12 @@ export function isNowEligibleFault(fault) {
 // ---------------------------------------------------------------------------
 // Local, db-free helpers (inlined so the leaf never imports the canvas barrel)
 // ---------------------------------------------------------------------------
-const VIEW_SOCKET_WAIT_MS = 30_000;
-const VIEW_SOCKET_RETRY_MS = 100;
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
 /** Inlined from `runtime/busy.ts` (which reaches the canvas barrel via `jobDir`):
- *  is the node mid-turn right now? `<jobDir>/busy` exists for the span pi is
- *  inside a run. `jobDir` here is the PURE path helper from paths.js. */
+ * is the node mid-turn right now? `<jobDir>/busy` exists for the span pi is
+ * inside a run. `jobDir` here is the pure path helper from paths.js. */
 function nodeIsBusy(nodeId) {
     return existsSync(join(jobDir(nodeId), 'busy'));
 }
-/** Copy of `placement.ts`'s `probeBrokerViewSocket` (placement reaches the canvas
- *  barrel, so it cannot be imported here): resolve true iff the socket accepts a
- *  connection within `timeoutMs`. */
-function probeViewSocket(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));
-    });
-}
-/** Drop-in for `placement.ts`'s `waitForBrokerViewSocket` (sans the broker-exit
- *  race — the CLI leaf drives the revive over the daemon and holds no launch
- *  handle). Poll the node's view.sock until it accepts a connection or the
- *  deadline passes; a `connect` (not mere file existence) proves a live listener,
- *  so the caller can attach/dial immediately on return. */
-async function waitForViewSocketReady(nodeId) {
-    const sockPath = viewSocketPath(nodeId);
-    const deadline = Date.now() + VIEW_SOCKET_WAIT_MS;
-    while (Date.now() <= deadline) {
-        if (await probeViewSocket(sockPath, VIEW_SOCKET_RETRY_MS))
-            return true;
-        await sleep(VIEW_SOCKET_RETRY_MS);
-    }
-    return false;
-}
 export const nodeReviveLeaf = defineLeaf({
     name: 'revive',
     description: 'reopen a window for a done/idle/dead/canceled node',
@@ -270,8 +223,8 @@ export const nodeReviveLeaf = defineLeaf({
             rethrowAsCliError(e);
         }
         // The revive route returns once the broker process is launched, which can be
-        // seconds before its view.sock listens. Callers (attach, the web shell's Wake)
-        // dial immediately on return, so block here until the socket accepts.
+        // seconds before its view.sock listens. Clients that attach immediately on
+        // return need this leaf to wait until the socket accepts.
         const ready = await waitForViewSocketReady(nodeId);
         return {
             // Always null (broker headless, no tmux window); `undefined` omits it from

package/dist/commands/node.d.ts

@@ -1,44 +1,2 @@
 import { type BranchDef } from '../core/command.js';
-/** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
- *  but when the SPAWNER is an orchestrator whose context has already grown past
- *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
- *  the child's result. */
-export declare function childFollowUp(spawnerId: string | undefined): Promise<string>;
-interface FocusViewerOpts {
-    cwd: string;
-    name: string;
-    pane?: string;
-    newPane?: boolean;
-    inPlace?: boolean;
-}
-interface FocusViewerResult {
-    focused: boolean;
-    session: string | null;
-    inPlace: boolean;
-    revived: boolean;
-}
-/** Bring a node's ONE viewer forefront beside (or navigated to) the caller —
- *  the pure-tmux port of placement.ts `focus()`. The server (`ensureAttach`)
- *  owns the broker revive + the view.sock accept-wait; the `@crtr_node` pane tag
- *  is the viewer registry. crtr is tmux-only: no caller pane ⇒ not focused. */
-export declare function focusViewer(nodeId: string, opts: FocusViewerOpts): Promise<FocusViewerResult>;
-export declare const surfaceNodeFocusLeaf: import("../core/command.js").LeafDef;
-/** The node "in front of you" in a tmux pane, resolved PURELY from the pane's
- *  `@crtr_node` tag. Defaults to $TMUX_PANE / the caller's current pane when
- *  `pane` is omitted — shared by `node lifecycle recycle` / `node lifecycle
- *  demote` / `node config --lifecycle` / `node lifecycle close` / `surface node cycle`,
- *  and the `canvas chord` leaf.
- *
- *  A `crtr surface attach` viewer self-tags its pane with the node it views
- *  (`@crtr_node`) — the tag IS the handle (a broker engine runs DETACHED with
- *  window=null, so there is no window→node fallback). Kept SYNC + tag-only: the
- *  re-plumbed CLI no longer reads canvas state to confirm the tagged node is
- *  still live, so a stale tag (attach SIGKILLed without clearing) resolves until
- *  the pane is respawned. Callers that mutate then re-validate the id via the
- *  API (getNode 404 → clean error). */
-export declare function nodeInPane(pane?: string): string | undefined;
-export declare const surfaceNodeIdLeaf: import("../core/command.js").LeafDef;
-export declare const surfaceNodePinLeaf: import("../core/command.js").LeafDef;
-export declare const surfaceNodeCycleLeaf: import("../core/command.js").LeafDef;
 export declare function registerNode(): BranchDef;
-export {};