@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/runtime/broker-protocol.js

@@ -1,7 +1,7 @@
 // broker-protocol.ts — the client↔broker wire protocol for the headless node
 // Surface (design §5.2). Pure types + a newline-delimited JSON codec; no I/O, no
 // SDK construction. Consumed by the broker (src/core/runtime/broker.ts) and, in
-// Phase 4, by the `crtr attach` terminal client and the `crtr web` bridge.
+// Phase 4, by the `crtr surface attach` terminal client and the surface web bridge.
 //
 // The transport is one unix socket per node (`nodeDir(id)/view.sock`) speaking
 // newline-delimited JSON frames. Live engine events are relayed VERBATIM — the
@@ -88,7 +88,7 @@ export const BROKER_READ_CAPS = {
  *  arriving in ~64 KiB socket chunks costs O(frame) total instead of O(frame ×
  *  chunks). The old `buf += chunk; buf.indexOf('\n')` shape flattened + re-walked
  *  the whole carry per chunk: a 16 MiB welcome snapshot cost ~250 ms of
- *  event-loop stall in `crtr attach` (typing lag) and the same again in the
+ *  event-loop stall in `crtr surface attach` (typing lag) and the same again in the
  *  broker; this shape decodes it in ~13 ms.
  *
  *  A `StringDecoder` decodes incoming Buffer chunks: an incomplete trailing

package/dist/core/runtime/broker.js

@@ -22,13 +22,42 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { getAgentDir, initTheme, } from '@earendil-works/pi-coding-agent';
-import { jobDir, nodeDir } from '../canvas/paths.js';
+import { jobDir, nodeDir, viewSocketPath } from '../canvas/paths.js';
 import { getNode, updateNode } from '../canvas/index.js';
 import { FRONT_DOOR_ENV } from './front-door.js';
-import { piInvocationToSdkConfig } from './launch.js';
+import { equivalentOtherProviderModel, normalizeModel, piInvocationToSdkConfig, } from './launch.js';
 import { assertEngineVersion, loadBrokerEngine } from './broker-sdk.js';
+import { classify } from '../fault-classifier.js';
+import { isModelNotFoundError, readFault, recordFault } from './fault.js';
+import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY } from './fault-recovery-nudge.js';
+import { markFatalOnExhaust, nextFaultRetry, policyFor } from './fault-recovery.js';
+import { probeOnline as probeOnlineReal } from './connectivity.js';
 import { BUILTIN_SLASH_COMMANDS } from './pi-vendored.js';
 import { encodeFrame, FrameDecoder, FrameOverflowError, BROKER_READ_CAPS, } from './broker-protocol.js';
+const THINKING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh']);
+function parseModelSpec(spec) {
+    const i = spec.lastIndexOf(':');
+    if (i <= 0)
+        return { modelSpec: spec };
+    const suffix = spec.slice(i + 1);
+    if (!THINKING_LEVELS.has(suffix))
+        return { modelSpec: spec };
+    return { modelSpec: spec.slice(0, i), thinkingLevel: suffix };
+}
+function formatModelSpec(model, thinkingLevel) {
+    if (model === null || model === undefined)
+        return null;
+    const suffix = thinkingLevel !== undefined && thinkingLevel !== '' && thinkingLevel !== 'off' ? `:${thinkingLevel}` : '';
+    return `${model.provider}/${model.id}${suffix}`;
+}
+function faultRetryProbe() {
+    const mode = process.env['CRTR_FAULT_RETRY_PROBE'];
+    if (mode === 'always')
+        return async () => true;
+    if (mode === 'never')
+        return async () => false;
+    return probeOnlineReal;
+}
 // ---------------------------------------------------------------------------
 // Tunables (T3 backpressure / T4 dialog anti-deadlock)
 // ---------------------------------------------------------------------------
@@ -126,6 +155,7 @@ export async function runBroker(nodeId) {
     // eslint-disable-next-line prefer-const
     let { session, services, resuming, runtime } = await buildBrokerSession(engine, cfg);
     activeSession = session;
+    const retryProbe = faultRetryProbe();
     // Initialize pi's process-global theme. The pi binary does this at boot
     // (main.js: initTheme(settingsManager.getTheme(), appMode === 'interactive')),
     // but the SDK convenience path the broker uses does NOT. Without it, ANY
@@ -147,7 +177,7 @@ export async function runBroker(nodeId) {
     // -------------------------------------------------------------------------
     // Socket fan-out + controller arbitration state
     // -------------------------------------------------------------------------
-    const sockPath = join(dir, 'view.sock');
+    const sockPath = viewSocketPath(nodeId);
     const attachPath = join(jobDir(nodeId), 'attach.json');
     const clients = new Set();
     const pendingDialogs = new Map();
@@ -289,6 +319,7 @@ export async function runBroker(nodeId) {
     // ---------------------------------------------------------------------------
     let pendingUpdate = null;
     let pendingUpdateTimer = null;
+    let faultRetryTimer = null;
     const flushPendingUpdate = () => {
         if (pendingUpdateTimer !== null) {
             clearTimeout(pendingUpdateTimer);
@@ -300,8 +331,221 @@ export async function runBroker(nodeId) {
             broadcast(frame);
         }
     };
+    const clearFaultRetryTimer = () => {
+        if (faultRetryTimer === null)
+            return;
+        clearTimeout(faultRetryTimer);
+        faultRetryTimer = null;
+    };
+    const failedRetryProviders = new Set();
+    let providerFallbackInFlight = null;
+    // Models that have already produced a 404 not_found this session. Guards the
+    // not-found fallback below against an infinite swap→re-drive→404 loop when the
+    // fallback TARGET is itself unavailable (or equals the model that just failed).
+    const notFoundModels = new Set();
+    let notFoundFallbackInFlight = null;
+    const maybeSwitchProviderForRetry = (event) => {
+        if (event.type !== 'auto_retry_start')
+            return;
+        const retry = event;
+        const kind = classify('pi→provider', retry.errorMessage ?? '').kind;
+        if (kind !== 'rate-limit' && kind !== 'connection')
+            return;
+        if (providerFallbackInFlight !== null)
+            return;
+        const currentSpec = formatModelSpec(session.model, session.thinkingLevel);
+        if (currentSpec === null)
+            return;
+        const next = equivalentOtherProviderModel(currentSpec, failedRetryProviders);
+        if (next === null)
+            return;
+        providerFallbackInFlight = (async () => {
+            const model = findModelSpec(next.model);
+            if (model === undefined) {
+                logBroker(`provider fallback skipped: ${next.model} is not registered`);
+                return;
+            }
+            const requested = parseModelSpec(next.model);
+            await session.setModel(model);
+            if (requested.thinkingLevel !== undefined)
+                session.setThinkingLevel(requested.thinkingLevel);
+            failedRetryProviders.add(next.fromProvider);
+            broadcastModelChanged();
+            logBroker(`provider fallback after ${kind}: ${currentSpec} → ${formatModelSpec(session.model, session.thinkingLevel) ?? next.model}`);
+        })()
+            .catch((err) => {
+            logBroker(`provider fallback failed: ${err instanceof Error ? err.message : String(err)}`);
+        })
+            .finally(() => {
+            providerFallbackInFlight = null;
+        });
+    };
+    // A 404 not_found is NOT one of pi's auto-retried kinds (it retries 429/5xx
+    // only) and never resolves on its own — the configured model id is wrong or
+    // decommissioned (e.g. the default `anthropic/ultra` pointing at a model the
+    // account can't reach). Left alone the node errors out, the stophook parks it
+    // as a stall, and the daemon force-recycles it onto the SAME bad model in a
+    // loop. Instead: fail the node over to the strong-anthropic ladder model and
+    // re-drive the turn so the work continues. broadcastModelChanged persists the
+    // swap into the durable launch recipe, so a later revive uses the good model
+    // too. Fires on the terminal-error message (stopReason 'error'), the signal a
+    // non-retried request surfaces.
+    const maybeFallbackOnModelNotFound = (event) => {
+        if (event.type !== 'message_end')
+            return;
+        const msg = event.message;
+        if (msg === undefined || msg.role !== 'assistant' || msg.stopReason !== 'error')
+            return;
+        if (!isModelNotFoundError(msg.errorMessage ?? ''))
+            return;
+        if (notFoundFallbackInFlight !== null)
+            return;
+        const currentSpec = formatModelSpec(session.model, session.thinkingLevel);
+        if (currentSpec === null)
+            return;
+        notFoundModels.add(currentSpec);
+        // The strong-anthropic ladder cell — "whatever the current strong anthropic
+        // provider model is" (config modelLadders.anthropic.strong), not hardcoded.
+        const target = normalizeModel('anthropic/strong');
+        // Don't loop: the failed model already IS the target, or the target itself
+        // 404'd earlier this session. Leave it to the normal stall/recycle path.
+        if (target === currentSpec || notFoundModels.has(target)) {
+            logBroker(`not_found fallback skipped: ${currentSpec} has no healthy strong-anthropic target (${target})`);
+            return;
+        }
+        notFoundFallbackInFlight = (async () => {
+            const model = findModelSpec(target);
+            if (model === undefined) {
+                logBroker(`not_found fallback skipped: ${target} is not registered`);
+                return;
+            }
+            const requested = parseModelSpec(target);
+            await session.setModel(model);
+            if (requested.thinkingLevel !== undefined)
+                session.setThinkingLevel(requested.thinkingLevel);
+            broadcastModelChanged();
+            const resolved = formatModelSpec(session.model, session.thinkingLevel) ?? target;
+            logBroker(`not_found fallback: ${currentSpec} unavailable → ${resolved}; re-driving turn`);
+            // Re-drive: a 404 left the turn errored, so the model swap alone changes
+            // nothing until the next prompt — re-issue so the now-healthy model picks
+            // the task back up. We fire on message_end, BEFORE the errored turn has
+            // fully settled, so wait for the engine to go idle first: prompt() THROWS
+            // if called while streaming without a streamingBehavior, which would swap
+            // the model but silently skip the continuation.
+            await session.agent.waitForIdle();
+            await session.prompt(`The previous model (${currentSpec}) was unavailable (provider 404 not_found), so you were automatically switched to ${resolved}. Continue the task from where the failed turn left off.`);
+        })()
+            .catch((err) => {
+            logBroker(`not_found fallback failed: ${err instanceof Error ? err.message : String(err)}`);
+        })
+            .finally(() => {
+            notFoundFallbackInFlight = null;
+        });
+    };
+    const isActiveAutoFault = (fault) => {
+        if (fault === null)
+            return false;
+        if (fault.retry.disposition !== 'auto')
+            return false;
+        if (fault.retry.by !== 'daemon')
+            return false;
+        return fault.kind === 'connection' || fault.kind === 'rate-limit' || fault.kind === 'overloaded';
+    };
+    const faultRetryDelayMs = (fault, now) => {
+        if (fault.retry.nextAt !== undefined) {
+            const ms = Date.parse(fault.retry.nextAt) - now;
+            return Number.isFinite(ms) ? Math.max(0, ms) : null;
+        }
+        const plan = nextFaultRetry(fault, now);
+        return plan?.delayMs ?? null;
+    };
+    const clearAndArmFaultRetry = (delayMs) => {
+        clearFaultRetryTimer();
+        faultRetryTimer = setTimeout(() => {
+            faultRetryTimer = null;
+            void runFaultRetry().catch((err) => {
+                logBroker(`fault retry fire failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }, delayMs);
+        if (typeof faultRetryTimer.unref === 'function')
+            faultRetryTimer.unref();
+    };
+    const scheduleFaultRetry = () => {
+        if (session.isStreaming)
+            return;
+        if (faultRetryTimer !== null)
+            return;
+        const fault = readFault(nodeId);
+        if (!isActiveAutoFault(fault)) {
+            clearFaultRetryTimer();
+            return;
+        }
+        const delayMs = faultRetryDelayMs(fault, Date.now());
+        if (delayMs === null)
+            return;
+        clearAndArmFaultRetry(delayMs);
+    };
+    const runFaultRetry = async () => {
+        if (session.isStreaming)
+            return;
+        const initial = readFault(nodeId);
+        if (!isActiveAutoFault(initial))
+            return;
+        let fault = initial;
+        if (initial.kind === 'connection') {
+            const online = await retryProbe();
+            // The probe can take seconds. A turn may have started, or the marker may
+            // have been cleared/replaced/recovered, in that window. Re-validate
+            // against fresh state before re-arming or consuming an attempt —
+            // otherwise a stale retry resurrects a recovered episode or double-drives
+            // a now-streaming session.
+            if (session.isStreaming)
+                return;
+            const fresh = readFault(nodeId);
+            if (!isActiveAutoFault(fresh) || fresh.since !== initial.since)
+                return;
+            if (!online) {
+                clearAndArmFaultRetry(policyFor(fresh.kind).baseDelayMs);
+                return;
+            }
+            fault = fresh;
+        }
+        const now = Date.now();
+        const attempt = fault.retry.attempt ?? 0;
+        const policy = policyFor(fault.kind);
+        if (attempt >= policy.max) {
+            recordFault(nodeId, markFatalOnExhaust(fault));
+            return;
+        }
+        const plan = nextFaultRetry(fault, now);
+        if (plan === null) {
+            recordFault(nodeId, markFatalOnExhaust(fault));
+            return;
+        }
+        const anchorEntryId = fault.anchorEntryId;
+        if (anchorEntryId !== undefined) {
+            try {
+                const leafId = session.sessionManager.getLeafId?.() ?? null;
+                if (leafId !== anchorEntryId) {
+                    await session.navigateTree(anchorEntryId);
+                }
+            }
+            catch (err) {
+                logBroker(`fault retry rewind skipped: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        recordFault(nodeId, plan.fault);
+        await session.prompt(fault.kind === 'connection' ? CONNECTION_FAULT_RECOVERY_BODY : PROVIDER_FAULT_RECOVERY_BODY);
+    };
     const relayEvent = (event) => {
-        if (event.type === 'message_update') {
+        maybeSwitchProviderForRetry(event);
+        maybeFallbackOnModelNotFound(event);
+        const type = event.type;
+        if (type === 'agent_start' || type === 'turn_start')
+            clearFaultRetryTimer();
+        if (type === 'agent_end' && !session.isStreaming)
+            scheduleFaultRetry();
+        if (type === 'message_update') {
             pendingUpdate = event; // latest full-message update supersedes the held one
             if (pendingUpdateTimer === null) {
                 pendingUpdateTimer = setTimeout(flushPendingUpdate, MESSAGE_UPDATE_COALESCE_MS);
@@ -330,10 +574,9 @@ export async function runBroker(nodeId) {
     // broker's own env (merged by piInvocationToSdkConfig at boot).
     const persistModelChoice = () => {
         const nodeId = process.env['CRTR_NODE_ID'];
-        const m = session.model;
-        if (nodeId === undefined || nodeId === '' || m === null || m === undefined)
+        const spec = formatModelSpec(session.model, session.thinkingLevel);
+        if (nodeId === undefined || nodeId === '' || spec === null)
             return;
-        const spec = `${m.provider}/${m.id}`;
         try {
             const meta = getNode(nodeId);
             if (meta === null)
@@ -478,6 +721,16 @@ export async function runBroker(nodeId) {
     // a subscriber otherwise propagates as a run failure that would crash the broker.
     // -------------------------------------------------------------------------
     let unsubscribe;
+    const captureSystemPrompt = () => {
+        try {
+            const dir = jobDir(nodeId);
+            mkdirSync(dir, { recursive: true });
+            writeFileSync(join(dir, 'system-prompt.md'), session.systemPrompt, 'utf8');
+        }
+        catch {
+            /* non-fatal: diagnostic only */
+        }
+    };
     const rebindSession = async () => {
         if (runtime !== undefined) {
             session = runtime.session; // the runtime replaced it; follow the new one
@@ -505,6 +758,7 @@ export async function runBroker(nodeId) {
             clearTimeout(pendingUpdateTimer);
             pendingUpdateTimer = null;
         }
+        clearFaultRetryTimer();
         pendingUpdate = null;
         unsubscribe = session.subscribe((event) => {
             try {
@@ -514,6 +768,7 @@ export async function runBroker(nodeId) {
                 logBroker(`event relay threw: ${String(err)}`);
             }
         });
+        captureSystemPrompt();
     };
     // Register the rebind BEFORE the first bind so a replacement triggered during
     // startup is honored; then do the initial bind + subscribe.
@@ -521,6 +776,7 @@ export async function runBroker(nodeId) {
         await rebindSession();
     });
     await rebindSession();
+    captureSystemPrompt();
     // -------------------------------------------------------------------------
     // Drive the engine on behalf of the single controller.
     // -------------------------------------------------------------------------
@@ -555,8 +811,51 @@ export async function runBroker(nodeId) {
                 void session.followUp(frame.text, frame.images).catch(relayError);
                 break;
             case 'abort':
-                void session.abort().catch(relayError);
+                // esc/abort cancels whatever is live: a running `!` command (abortBash)
+                // takes precedence over the agent turn, mirroring pi interactive mode.
+                if (session.isBashRunning)
+                    session.abortBash();
+                else
+                    void session.abort().catch(relayError);
+                break;
+            case 'bash': {
+                // `!`/`!!` bash: run via session.executeBash (records a bashExecution
+                // context message, starts NO agent turn) and relay its lifecycle to ALL
+                // viewers as bash_start/bash_output/bash_end so each renders the live
+                // component. Serialized like pi's interactive mode — reject a second `!`
+                // while one is already running rather than racing _bashAbortController.
+                const command = frame.command;
+                if (command.trim() === '')
+                    break;
+                if (session.isBashRunning) {
+                    sendFrame(client, {
+                        type: 'error',
+                        code: 'bash_busy',
+                        message: 'A bash command is already running',
+                    });
+                    break;
+                }
+                const exclude = frame.excludeFromContext === true;
+                // Order before any held assistant message_update, so a `!` run mid-stream
+                // never renders ahead of the update it follows.
+                flushPendingUpdate();
+                broadcast({ type: 'bash_start', command, excludeFromContext: exclude });
+                void session
+                    .executeBash(command, (chunk) => broadcast({ type: 'bash_output', chunk }), {
+                    excludeFromContext: exclude,
+                })
+                    .then((result) => {
+                    broadcast({
+                        type: 'bash_end',
+                        exitCode: result.exitCode,
+                        cancelled: result.cancelled,
+                        truncated: result.truncated,
+                        fullOutputPath: result.fullOutputPath,
+                    });
+                })
+                    .catch(relayError);
                 break;
+            }
         }
     };
     // -------------------------------------------------------------------------
@@ -593,10 +892,11 @@ export async function runBroker(nodeId) {
      *  carries any extension-registered providers). Pure: returns undefined on a
      *  malformed spec or an unknown model. */
     const findModelSpec = (spec) => {
-        const slash = spec.indexOf('/');
+        const { modelSpec } = parseModelSpec(spec);
+        const slash = modelSpec.indexOf('/');
         if (slash <= 0)
             return undefined;
-        return services.modelRegistry.find(spec.slice(0, slash), spec.slice(slash + 1));
+        return services.modelRegistry.find(modelSpec.slice(0, slash), modelSpec.slice(slash + 1));
     };
     /** Resolve a model from a free-text query — `/model opus`, `/model fable`. Tries
      *  the exact `provider/id` spec first; failing that, searches the registry the
@@ -767,6 +1067,10 @@ export async function runBroker(nodeId) {
             thinkingLevel: session.thinkingLevel,
             availableThinkingLevels: session.getAvailableThinkingLevels(),
             currentTheme: sm.getTheme() ?? '',
+            // Light/dark appearance is a property of the terminal the VIEWER is attached
+            // to; the headless broker has none, so emit a placeholder. The viewer owns
+            // the theme submenu and resolves real terminal appearance locally.
+            terminalTheme: 'dark',
             availableThemes,
             hideThinkingBlock: sm.getHideThinkingBlock(),
             collapseChangelog: sm.getCollapseChangelog(),
@@ -856,7 +1160,8 @@ export async function runBroker(nodeId) {
             case 'prompt':
             case 'steer':
             case 'follow_up':
-            case 'abort': {
+            case 'abort':
+            case 'bash': {
                 if (notController(client, 'drive the engine'))
                     break;
                 driveEngine(client, frame);
@@ -904,11 +1209,12 @@ export async function runBroker(nodeId) {
             case 'set_model': {
                 if (notController(client, 'set the model'))
                     break;
+                const requested = parseModelSpec(frame.model);
                 let model;
                 try {
                     // Accept both an exact `provider/id` (from the picker) and a free-text
                     // query (`/model opus`) — resolveModelQuery falls back to a search match.
-                    model = resolveModelQuery(frame.model);
+                    model = resolveModelQuery(requested.modelSpec);
                 }
                 catch (err) {
                     // N2: registry.find should never throw on the real SDK, but a degenerate
@@ -927,6 +1233,8 @@ export async function runBroker(nodeId) {
                 void session
                     .setModel(model)
                     .then(() => {
+                    if (requested.thinkingLevel !== undefined)
+                        session.setThinkingLevel(requested.thinkingLevel);
                     ackTo(client, 'set_model');
                     broadcastModelChanged();
                 })
@@ -1206,8 +1514,13 @@ export async function runBroker(nodeId) {
                 break;
             }
             case 'reload_auth': {
-                if (notController(client, 'reload auth'))
-                    break;
+                // Open to any client: reload_auth is an idempotent local re-read of the
+                // shared auth.json + a model-registry refresh. It does NOT steer the
+                // conversation, so there is nothing to gate behind controller. Gating it
+                // forced callers (notably the daemon's canvas-wide fan, which propagates
+                // a single /login to every live broker) to first request_control, which
+                // ALWAYS preempts — silently demoting any attached human to observer on
+                // every login. Letting an observer trigger this is the safer default.
                 try {
                     services.authStorage.reload();
                     services.modelRegistry.refresh();
@@ -1293,6 +1606,7 @@ export async function runBroker(nodeId) {
     });
     server.on('error', (err) => {
         process.stderr.write(`[broker] socket server error: ${String(err)}\n`);
+        process.exit(1);
     });
     server.listen(sockPath);
     // Initialize presence to the truthful zero state at boot — this also
@@ -1373,16 +1687,24 @@ export async function buildBrokerSession(engine, cfg) {
             resourceLoaderOptions: {
                 additionalExtensionPaths: cfg.extensionPaths,
                 appendSystemPrompt: cfg.appendSystemPromptPath !== undefined ? [cfg.appendSystemPromptPath] : undefined,
+                // Suppress pi's <project_context> in the SYSTEM PROMPT — crouter
+                // re-renders the same AGENTS.md/CLAUDE.md files into the first-message
+                // <crtr-context> bearings instead (buildProjectContextBlock), so all
+                // project instructions ride the user message, not the system prompt.
+                noContextFiles: true,
             },
         });
         // 3. Resolve the model spec (`anthropic/sonnet` → a Model) against the
         //    SERVICES registry — which has any extension-provided providers (C3).
         //    Undefined ⇒ the SDK picks the settings default.
         let model;
+        let thinkingLevel;
         if (cfg.model !== undefined && cfg.model !== '') {
-            const slash = cfg.model.indexOf('/');
+            const parsedModel = parseModelSpec(cfg.model);
+            thinkingLevel = parsedModel.thinkingLevel;
+            const slash = parsedModel.modelSpec.indexOf('/');
             if (slash > 0) {
-                model = services.modelRegistry.find(cfg.model.slice(0, slash), cfg.model.slice(slash + 1));
+                model = services.modelRegistry.find(parsedModel.modelSpec.slice(0, slash), parsedModel.modelSpec.slice(slash + 1));
                 if (model === undefined) {
                     process.stderr.write(`[broker] WARNING: model '${cfg.model}' not found in registry — ` +
                         `falling back to the SDK default model.\n`);
@@ -1397,6 +1719,7 @@ export async function buildBrokerSession(engine, cfg) {
             services,
             sessionManager: o.sessionManager,
             model,
+            thinkingLevel,
             tools: cfg.tools,
             sessionStartEvent: o.sessionStartEvent,
         });
@@ -1565,8 +1888,10 @@ export function makeBrokerUiContext(deps) {
             });
         },
         setTitle: (title) => deps.broadcast({ type: 'display_title', title }),
-        // Inert print-mode surface (never reached by a Model hook in Phase 3).
-        notify: noop,
+        notify: (message, type) => {
+            const notifyType = type === 'warn' ? 'warning' : type;
+            deps.broadcast({ type: 'extension_ui_request', id: randomUUID(), method: 'notify', message, notifyType });
+        },
         onTerminalInput: () => noop,
         setWorkingMessage: noop,
         setWorkingVisible: noop,

package/dist/core/runtime/close.js

@@ -1,4 +1,4 @@
-// close.ts — the "close this node + its subtree" action behind `crtr node close`.
+// close.ts — the "close this node + its subtree" action behind `crtr node lifecycle close`.
 //
 // Closing a node tears down the focused node and every descendant it
 // EXCLUSIVELY owns, walking DOWN the subscribes_to spine (subscriptionsOf = a
@@ -33,7 +33,7 @@
 import { getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { headlessBrokerHost } from './host.js';
-import { tearDownNode } from './placement.js';
+import { tearDownNode, reapIfEmpty } from './placement.js';
 import { appendInbox } from '../feed/inbox.js';
 import { appendPassive } from '../feed/passive.js';
 /** The set of nodes to close: the root plus every descendant reachable down the
@@ -139,35 +139,45 @@ export function closeNode(rootId, opts = {}) {
             const deadChildren = subscriptionsOf(id)
                 .map((s) => s.node_id)
                 .filter((c) => closing.has(c));
-            // 1) Terminal status set BEFORE the window dies (daemon race). The root may
-            //    finalize to `done` (a deliberate "mark complete" close-out); every
-            //    descendant, and the root by default, `cancel`s. finalize is legal only
-            //    from a live status — an already-terminal root keeps its status.
-            if (id === rootId && rootEvent === 'finalize') {
-                if (m.status === 'active' || m.status === 'idle')
-                    transition(id, 'finalize');
-            }
-            else {
-                transition(id, 'cancel');
+            // Surviving managers captured BEFORE any teardown — a reap (below) deletes
+            //    this node's edges, so the step-4 fan-out must read them up front.
+            const survivors = subscribersOf(id).filter((s) => !closing.has(s.node_id));
+            // 0) An EMPTY node (engine never produced an assistant message) is a useless
+            //    shell — don't park it as a canceled husk, reap it outright (engine +
+            //    viewer + row + dir). reapIfEmpty handles the teardown; when it fires we
+            //    skip the cancel transition + resume notice (the node is gone) but still
+            //    fan the "child gone" wake out to surviving managers below.
+            if (!reapIfEmpty(id)) {
+                // 1) Terminal status set BEFORE the window dies (daemon race). The root may
+                //    finalize to `done` (a deliberate "mark complete" close-out); every
+                //    descendant, and the root by default, `cancel`s. finalize is legal only
+                //    from a live status — an already-terminal root keeps its status.
+                if (id === rootId && rootEvent === 'finalize') {
+                    if (m.status === 'active' || m.status === 'idle')
+                        transition(id, 'finalize');
+                }
+                else {
+                    transition(id, 'cancel');
+                }
+                // 2) Tear the node's ENGINE down: send the `shutdown` frame so the broker
+                //    PROCESS exits and releases the sole .jsonl writer. Then proactively
+                //    close the viewer pane + registry row — attach auto-reconnects, so on a
+                //    deliberate close the viewer must be torn down here or it lingers ~30s
+                //    showing a misleading "reconnecting…" instead of going away at once.
+                headlessBrokerHost.teardown(id);
+                tearDownNode(id);
+                // 3) Leave the resume notice AFTER the watcher is gone, so it survives.
+                appendInbox(id, {
+                    from: null,
+                    tier: 'normal',
+                    kind: 'message',
+                    label: cancellationLabel(id === rootId, deadChildren),
+                    data: { reason: 'user-close', cascade_root: rootId, canceled_children: deadChildren },
+                });
             }
-            // 2) Tear the node's ENGINE down: send the `shutdown` frame so the broker
-            //    PROCESS exits and releases the sole .jsonl writer. Then proactively
-            //    close the viewer pane + registry row — attach auto-reconnects, so on a
-            //    deliberate close the viewer must be torn down here or it lingers ~30s
-            //    showing a misleading "reconnecting…" instead of going away at once.
-            headlessBrokerHost.teardown(id);
-            tearDownNode(id);
-            // 3) Leave the resume notice AFTER the watcher is gone, so it survives.
-            appendInbox(id, {
-                from: null,
-                tier: 'normal',
-                kind: 'message',
-                label: cancellationLabel(id === rootId, deadChildren),
-                data: { reason: 'user-close', cascade_root: rootId, canceled_children: deadChildren },
-            });
             // 4) Wake any SURVIVING manager subscribed to this node — the doctrine wake.
             //    A node going dormant trusts the runtime to wake it on a child's
-            //    terminal outcome; D-1 found that `node close` notified ONLY the closed
+            //    terminal outcome; D-1 found that `node lifecycle close` notified ONLY the closed
             //    node itself, never its subscribers, so a parent that delegated then
             //    just stopped hangs forever when its child is closed out from under it.
             //    Only the close ROOT can have a surviving subscriber (closingSet adds a
@@ -176,9 +186,7 @@ export function closeNode(rootId, opts = {}) {
             //    never fires inside a self-contained cascade. Active → inbox (wakes a
             //    dormant manager via its live watcher / the daemon's dormant-revive
             //    second pass); passive → passive accumulator (delivered, not woken).
-            for (const sub of subscribersOf(id)) {
-                if (closing.has(sub.node_id))
-                    continue; // also being torn down — pointless
+            for (const sub of survivors) {
                 const notice = {
                     from: id,
                     tier: 'normal',

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

@@ -0,0 +1,12 @@
+/** Default per-target connect timeout. Short — a healthy network connects in
+ *  tens of ms; a down network should be declared down quickly so the daemon tick
+ *  isn't held up. */
+export declare const PROBE_TIMEOUT_MS = 3000;
+/** Resolve true iff a TCP connection to host:port completes within timeoutMs.
+ *  Any error/timeout resolves false (never rejects). The socket is always torn
+ *  down. Exported for unit testing against a local listener. */
+export declare function tcpReachable(host: string, port: number, timeoutMs: number): Promise<boolean>;
+/** True when the box can reach the internet (any PROBE_TARGET accepts a TCP
+ *  connection within the timeout). The broker uses this for connection-fault
+ *  retries. Never throws. */
+export declare function probeOnline(timeoutMs?: number): Promise<boolean>;