@north-light/crouter 0.3.258 → 0.3.259

package/dist/api/dto/attach.d.ts

@@ -5,6 +5,9 @@ export interface AttachEnsureRequest {
     resume?: boolean;
     /** Revive if dormant (default true); false returns a possibly-dead socket. */
     revive?: boolean;
+    /** Wake an exact unfinalized parked resident (default true). Focus/navigation
+     * sets false so it can open the saved conversation without launching. */
+    wakeParked?: boolean;
 }
 /** Result of a local attach-ensure. */
 export interface AttachEnsureResultDTO {
@@ -13,4 +16,7 @@ export interface AttachEnsureResultDTO {
     socket_path: string;
     revived: boolean;
     resumed: boolean;
+    /** True when a non-waking focus ensure found an exact parked resident with no
+     * live broker. `socket_path` is then the target the viewer will later redial. */
+    parked: boolean;
 }

package/dist/api/dto/nodes.d.ts

@@ -239,8 +239,23 @@ export interface NodeSnapshotDTO {
     node_id: NodeIdDTO;
     snapshot: {
         messages: unknown[];
+        messageIds?: string[];
         stats: unknown;
         state: Record<string, unknown>;
+        display: {
+            statuses: Record<string, string>;
+            widgets: Record<string, {
+                lines: string[];
+                placement: 'aboveEditor' | 'belowEditor';
+            }>;
+            title?: string;
+        };
+        queued?: {
+            steering: string[];
+            followUp: string[];
+        };
+        toolGroupSummaries?: Record<string, unknown>;
+        workingActivity?: string;
     };
     commands: {
         name: string;

package/dist/clients/attach/command.js

@@ -60,6 +60,8 @@ function attachToLeaf(namespace) {
             const nodeId = input['node'];
             const observer = input['observer'] ?? false;
             const canvasName = input['canvas'];
+            const wakeParked = process.env['CRTR_ATTACH_WAKE_PARKED'] !== '0';
+            delete process.env['CRTR_ATTACH_WAKE_PARKED'];
             // attach IS the in-pane interactive program — it only needs a TTY (crtr is
             // tmux-only, but the pane itself is the surface). Non-TTY (piped) → static
             // notice + exit, never a non-tmux interactive fallback. Guarded BEFORE the
@@ -73,7 +75,7 @@ function attachToLeaf(namespace) {
             mark('viewer.bundle_import_start');
             const { runAttach } = await import('./viewer.js');
             mark('viewer.bundle_loaded');
-            await runAttach(nodeId, observer, canvasName);
+            await runAttach(nodeId, observer, canvasName, wakeParked);
             // The session has sent its final broker frame and restored the terminal.
             // Force this one-shot viewer process out now: pi's bundled UI dependencies
             // can retain libuv handles after their visible work is finished. The exit

package/dist/clients/attach/input/capabilities.d.ts

@@ -16,6 +16,9 @@ export interface ViewerCapabilityInput {
     remote: boolean;
     nodeId: string;
     profileId: string | undefined;
+    /** Dynamic transport state. Authorization stays role-based; broker-only
+     * operations refuse locally while a parked viewer has no live engine. */
+    isBrokerOffline?: () => boolean;
 }
 /** Build the one authority for a viewer session. Remote viewers are observers
  * even when a caller supplied a controller role; keep that invariant local to

package/dist/clients/attach/input/capabilities.js

@@ -25,14 +25,18 @@ export function createViewerCapabilities(input) {
         permittedOperations,
         permits: (operation) => permittedOperations.has(operation),
         refusal: (operation, command) => {
+            const prefix = command === undefined ? '' : `/${command} `;
+            if (input.isBrokerOffline?.() === true
+                && (operation === 'engine-drive' || operation === 'dequeue' || operation === 'auth')) {
+                return `${prefix}needs a live broker; this node is parked — submit a message to wake it`;
+            }
             if (permittedOperations.has(operation))
                 return undefined;
-            const prefix = command === undefined ? '' : `/${command} `;
             if (remote && (operation === 'canvas-resume' || operation === 'local-canvas-inspect' || operation === 'canvas-inbox')) {
-                return `${prefix}is not available for a remote attach (--canvas) — it acts on this machine's local canvas`;
+                return `${prefix}Read-only remote attach — not available with --canvas because it acts on this machine's local canvas`;
             }
             if (remote)
-                return `${prefix}is not available for a remote attach (--canvas) — view-only`;
+                return `${prefix}Read-only remote attach — not available with --canvas (view-only)`;
             return `${prefix}is not available to a read-only observer attach (--observer) — it would drive this node`;
         },
     };

package/dist/clients/attach/input/controller.d.ts

@@ -61,7 +61,7 @@ export declare class InputController {
     openAuthPicker(prepare: Parameters<InputOverlayOwner['openAuthPicker']>[0]): Promise<void>;
     private readonly send;
     private emitCommand;
-    private readOnlyLabel;
+    private openBrokerPicker;
     private wire;
     private slashContext;
     /** Record a leading slash command as used. Called only once the command has

package/dist/clients/attach/input/controller.js

@@ -69,15 +69,21 @@ export class InputController {
     };
     emitCommand(frame) {
         const operation = viewerOperationForFrame(frame);
-        if (operation === undefined || this.capabilities.permits(operation)) {
+        const refusal = operation === undefined ? undefined : this.capabilities.refusal(operation);
+        if (refusal === undefined) {
             this.hooks.onCommand(frame);
             return true;
         }
-        this.notify(`${this.readOnlyLabel()} — cannot drive the engine`);
+        this.notify(refusal);
         return false;
     }
-    readOnlyLabel() {
-        return this.capabilities.remote ? 'Read-only remote attach' : 'Read-only observer attach';
+    openBrokerPicker(open) {
+        const refusal = this.capabilities.refusal('engine-drive');
+        if (refusal !== undefined) {
+            this.notify(refusal);
+            return;
+        }
+        open();
     }
     wire() {
         this.editor.onSubmit = (text) => this.handleSubmit(text);
@@ -91,7 +97,7 @@ export class InputController {
             const now = Date.now();
             if (now - this.lastEscapeAt < DOUBLE_ESCAPE_MS) {
                 this.lastEscapeAt = 0;
-                void this.overlays.openTreePicker();
+                this.openBrokerPicker(() => void this.overlays.openTreePicker());
             }
             else {
                 this.lastEscapeAt = now;
@@ -109,10 +115,10 @@ export class InputController {
         this.editor.onAction('app.tools.expand', () => this.hooks.onToggleToolsExpand?.());
         this.editor.onAction('app.thinking.toggle', () => this.hooks.onToggleThinking?.());
         this.editor.onAction('app.editor.external', () => void this.openExternalEditor());
-        this.editor.onAction('app.model.select', () => void this.overlays.openModelPicker());
-        this.editor.onAction('app.session.tree', () => void this.overlays.openTreePicker());
-        this.editor.onAction('app.session.fork', () => void this.overlays.openForkPicker());
-        this.editor.onAction('app.session.resume', () => void this.overlays.openSessionPicker());
+        this.editor.onAction('app.model.select', () => this.openBrokerPicker(() => void this.overlays.openModelPicker()));
+        this.editor.onAction('app.session.tree', () => this.openBrokerPicker(() => void this.overlays.openTreePicker()));
+        this.editor.onAction('app.session.fork', () => this.openBrokerPicker(() => void this.overlays.openForkPicker()));
+        this.editor.onAction('app.session.resume', () => this.openBrokerPicker(() => void this.overlays.openSessionPicker()));
     }
     slashContext() {
         return {
@@ -131,12 +137,12 @@ export class InputController {
             onColor: this.hooks.onColor,
             onNodeMetadata: this.hooks.onNodeMetadata,
             onFoldTools: this.hooks.onFoldTools,
-            openModelPicker: () => void this.overlays.openModelPicker(),
-            openSessionPicker: () => void this.overlays.openSessionPicker(),
-            openForkPicker: () => void this.overlays.openForkPicker(),
-            openTreePicker: () => void this.overlays.openTreePicker(),
-            openSettingsPicker: () => void this.overlays.openSettingsPicker(),
-            openScopedModelsPicker: () => void this.overlays.openScopedModelsPicker(),
+            openModelPicker: () => this.openBrokerPicker(() => void this.overlays.openModelPicker()),
+            openSessionPicker: () => this.openBrokerPicker(() => void this.overlays.openSessionPicker()),
+            openForkPicker: () => this.openBrokerPicker(() => void this.overlays.openForkPicker()),
+            openTreePicker: () => this.openBrokerPicker(() => void this.overlays.openTreePicker()),
+            openSettingsPicker: () => this.openBrokerPicker(() => void this.overlays.openSettingsPicker()),
+            openScopedModelsPicker: () => this.openBrokerPicker(() => void this.overlays.openScopedModelsPicker()),
             openMcpPicker: (serverName) => this.overlays.openMcpPicker(serverName),
             openLoginPicker: this.hooks.openLoginPicker,
             openLogoutPicker: this.hooks.openLogoutPicker,
@@ -188,6 +194,13 @@ export class InputController {
             return;
         }
         const isDormant = this.hooks.isDormant?.() === true;
+        // Unknown slash commands and `!` bash are broker operations, not human
+        // conversation input. Keep their text and refuse visibly while offline;
+        // only an ordinary submitted message crosses the durable wake boundary.
+        if (isDormant && (trimmed.startsWith('/') || trimmed.startsWith('!'))) {
+            this.notify('This node is parked — submit a message to wake it; broker commands need a live engine');
+            return;
+        }
         const classification = classifySubmit(text, {
             isDormant,
             canWakeDormant: isDormant && this.capabilities.permits('wake-dormant') && this.hooks.onDormantSubmit !== undefined,
@@ -240,8 +253,9 @@ export class InputController {
         this.clearPastedImages();
     }
     async handleDequeue() {
-        if (!this.capabilities.permits('dequeue')) {
-            this.notify(`${this.readOnlyLabel()} — cannot restore queued messages`);
+        const refusal = this.capabilities.refusal('dequeue');
+        if (refusal !== undefined) {
+            this.notify(refusal);
             return;
         }
         const request = this.hooks.onRequest;

package/dist/clients/attach/session/connection.d.ts

@@ -1,4 +1,4 @@
-import type { ClientRole } from '../../../core/runtime/broker-protocol.js';
+import type { BrokerSnapshot, ClientRole } from '../../../core/runtime/broker-protocol.js';
 import type { CanvasSource } from '../../../core/canvas/source.js';
 import type { NodeMeta } from '../../../core/canvas/types.js';
 import { BrokerClient } from '../../../core/broker-client/index.js';
@@ -31,8 +31,17 @@ export interface AttachConnection {
     /** The attached node's persona/lifecycle, when this canvas can tell us —
      *  `undefined` for a remote attach until the viewer refetches it. */
     readonly nodeIdentity: Pick<NodeMeta, 'kind' | 'mode' | 'lifecycle' | 'icon'> | undefined;
-    /** The one socket to the node's headless broker, already connected. */
+    /** The one socket target for the node's headless broker. It is intentionally
+     * disconnected only when focus opened an exact parked resident offline. */
     readonly socket: BrokerClient;
+    /** Saved snapshot used to seed an offline parked viewer. Absent for direct
+     * attach and for focus paths whose broker was live or legitimately woke. */
+    readonly initialSnapshot?: BrokerSnapshot;
+    readonly initialCommands?: ReadonlyArray<{
+        name: string;
+        description: string;
+        source: string;
+    }>;
     /** Re-throw a connect-adjacent failure that landed AFTER `connect` resolved.
      *  Call once, synchronously, just before permanent socket wiring takes over;
      *  a no-op if nothing failed. See the never-removed error listener below. */
@@ -41,4 +50,4 @@ export interface AttachConnection {
 /** Resolve the target, revive the node if it is dormant (server-side), and dial
  *  the broker. Rejects with a plain `InputError` — no terminal has been taken
  *  over at this point, so a failure here is an ordinary non-zero CLI exit. */
-export declare function connectToNode(nodeId: string, canvasName?: string): Promise<AttachConnection>;
+export declare function connectToNode(nodeId: string, canvasName?: string, wakeParked?: boolean): Promise<AttachConnection>;

package/dist/clients/attach/session/connection.js

@@ -53,7 +53,7 @@ export async function preWaitForViewSocket(nodeId) {
 /** Resolve the target, revive the node if it is dormant (server-side), and dial
  *  the broker. Rejects with a plain `InputError` — no terminal has been taken
  *  over at this point, so a failure here is an ordinary non-zero CLI exit. */
-export async function connectToNode(nodeId, canvasName) {
+export async function connectToNode(nodeId, canvasName, wakeParked = true) {
     const remote = canvasName !== undefined;
     // Attach must NOT silently honor a durable `crtr canvas use` selection: the
     // local branch has a hard local-unix-socket assumption baked into its
@@ -74,6 +74,8 @@ export async function connectToNode(nodeId, canvasName) {
     let meta;
     let nodeIdentity;
     let transport;
+    let initialSnapshot;
+    let initialCommands;
     if (remote) {
         meta = { cwd: process.cwd() };
         transport = new RelayTransport(nodeId, resolveRemoteCanvasTarget(canvasName));
@@ -97,14 +99,23 @@ export async function connectToNode(nodeId, canvasName) {
         // revive here and let BrokerClient(nodeId) connect over the local socket as
         // before — this LOCAL process never launches pi or writes the session.
         try {
-            await cliClient().ensureAttach(nodeId, { resume: true, revive: true });
+            const attach = await cliClient().ensureAttach(nodeId, { resume: true, revive: true, wakeParked });
+            if (attach.parked) {
+                const saved = await cliClient().getSnapshot(nodeId);
+                // The API DTO stays dependency-light and structural; this viewer is the
+                // consumer that knows the complete broker snapshot contract.
+                initialSnapshot = saved.snapshot;
+                initialCommands = saved.commands;
+            }
         }
         catch (err) {
             rethrowAsCliError(err, 'The node may be finalized or otherwise not attachable.');
         }
         // Local only: remote attach reaches crtrd over WebSocket rather than a
-        // local socket file, so `--canvas` has nothing to pre-wait on.
-        await preWaitForViewSocket(nodeId);
+        // local socket file, so `--canvas` has nothing to pre-wait on. An offline
+        // parked focus has deliberately no socket to wait for.
+        if (initialSnapshot === undefined)
+            await preWaitForViewSocket(nodeId);
     }
     const socket = new BrokerClient(nodeId, { transport });
     /** One error shape for a connect-time failure, whether the connect race below
@@ -137,34 +148,38 @@ export async function connectToNode(nodeId, canvasName) {
             terminalStartupError = err;
     });
     // Connect FIRST (race connect/error) so a missing broker exits non-zero
-    // cleanly, BEFORE the TUI takes over the terminal.
-    await new Promise((resolve, reject) => {
-        const onConnect = () => {
-            cleanup();
-            resolve();
-        };
-        const onErr = (err) => {
-            cleanup();
-            reject(err);
-        };
-        const cleanup = () => {
-            socket.off('connect', onConnect);
-            socket.off('error', onErr);
-        };
-        socket.on('connect', onConnect);
-        socket.on('error', onErr);
-        socket.connect();
-    }).catch((err) => {
-        throw toAttachError(err);
-    });
+    // cleanly, BEFORE the TUI takes over the terminal. Offline parked focus is
+    // the one intentional exception: reconnect owns its first dial after paint.
+    if (initialSnapshot === undefined) {
+        await new Promise((resolve, reject) => {
+            const onConnect = () => {
+                cleanup();
+                resolve();
+            };
+            const onErr = (err) => {
+                cleanup();
+                reject(err);
+            };
+            const cleanup = () => {
+                socket.off('connect', onConnect);
+                socket.off('error', onErr);
+            };
+            socket.on('connect', onConnect);
+            socket.on('error', onErr);
+            socket.connect();
+        }).catch((err) => {
+            throw toAttachError(err);
+        });
+    }
     return {
         remote,
         canvasSource,
         meta,
         nodeIdentity,
         socket,
+        ...(initialSnapshot === undefined ? {} : { initialSnapshot, initialCommands }),
         assertConnected: () => {
-            if (terminalStartupError !== undefined)
+            if (initialSnapshot === undefined && terminalStartupError !== undefined)
                 throw toAttachError(terminalStartupError);
         },
     };

package/dist/clients/attach/session/input-wiring.d.ts

@@ -45,6 +45,6 @@ export interface InputWiringHooks {
     frecency: FrecencyStore;
 }
 /** Construct the viewer's one capability authority. */
-export declare function createViewerCapabilitiesForInput(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta'>): ViewerCapabilities;
+export declare function createViewerCapabilitiesForInput(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta'>, isBrokerOffline: () => boolean): ViewerCapabilities;
 /** Build the viewer's InputController with every hook answered. */
 export declare function createInputController(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta' | 'socket' | 'tui' | 'editor' | 'containers'>, km: KeybindingsManager, capabilities: ViewerCapabilities, hooks: InputWiringHooks): InputController;

package/dist/clients/attach/session/input-wiring.js

@@ -17,12 +17,13 @@ import { cliClient } from '../../../commands/api-client.js';
 import { buildLoginPicker, buildLogoutPicker } from '../overlays/auth.js';
 import { defaultAgentDir } from '../config.js';
 /** Construct the viewer's one capability authority. */
-export function createViewerCapabilitiesForInput(ctx) {
+export function createViewerCapabilitiesForInput(ctx, isBrokerOffline) {
     return createViewerCapabilities({
         nodeId: ctx.nodeId,
         profileId: ctx.meta.profile_id ?? undefined,
         remote: ctx.remote,
         role: ctx.role,
+        isBrokerOffline,
     });
 }
 /** Build the viewer's InputController with every hook answered. */
@@ -93,7 +94,10 @@ export function createInputController(ctx, km, capabilities, hooks) {
         // /fork, /tree, /settings, /scoped-models) fetch their payloads over.
         // Without it every picker degrades to the "isn't available in this viewer"
         // notice (see slash/dispatch.ts + InputController.openPicker).
-        onRequest: (frame) => socket.request(frame),
+        onRequest: (frame) => {
+            const refusal = capabilities.refusal('engine-drive');
+            return refusal === undefined ? socket.request(frame) : Promise.reject(new Error(refusal));
+        },
         // Mount pickers inline in the chrome stack, directly under the editor
         // (queued-panel pattern) rather than as a floating centered modal, so a
         // picker reads as part of the editor — like pi's own selectors.

package/dist/clients/attach/session/reconnect.d.ts

@@ -16,15 +16,19 @@ export interface ReconnectHooks {
     /** End the session. `node-done` is a clean finalize (the node pushed its
      *  final report) and closes the pane; `broker-gone` freezes the corpse. */
     teardown: (reason: 'node-done' | 'broker-gone') => void;
-    /** Called once each time the node is first seen as dormant. An idle-released
-     *  broker has settled its turn and will relay no final session event, so the
-     *  viewer must clear its live-only display itself. */
+    /** The viewer was bootstrapped from a saved parked snapshot before any socket
+     * connection. */
+    initialDormant?: boolean;
+    /** Called once each time the node is first seen as dormant. A stopped broker
+     * will relay no final session event, so the viewer clears live-only display. */
     onEnterDormancy: () => void;
 }
 export interface ReconnectSupervisor {
     /** Send the hello handshake. Called once after `tui.start()`, then again on
      *  every successful redial. */
     sendHello: () => void;
+    /** Begin redialing an offline parked viewer after its saved snapshot paints. */
+    startDormant: () => void;
     /** True while the node has no live broker — the input layer routes a
      *  submitted prompt through a wake message rather than a dead socket. */
     isDormant: () => boolean;

package/dist/clients/attach/session/reconnect.js

@@ -16,7 +16,7 @@ export function createReconnect(ctx, hooks) {
     const { nodeId, socket, canvasSource } = ctx;
     let lastSocketError;
     let reconnecting = false;
-    let viewerDormant = false;
+    let viewerDormant = hooks.initialDormant === true;
     // Captured at give-up: a terminal `done` is a CLEAN finalize — the viewer
     // closes its pane instead of freezing a scary "broker gone" corpse.
     // `dead`/`canceled` keep the corpse.
@@ -97,7 +97,12 @@ export function createReconnect(ctx, hooks) {
                 // submit shows "waking node…" the moment you send — so a persistent
                 // "node dormant" banner is pure noise. Clear the footer when dormant;
                 // keep the reconnecting notice only for a transient broker relaunch.
-                const dormant = row?.status === 'idle' || row?.intent === 'idle-release';
+                const dormant = row?.status === 'idle'
+                    || row?.intent === 'idle-release'
+                    || (row?.lifecycle === 'resident'
+                        && row.status === 'done'
+                        && row.intent === 'parked'
+                        && row.final_report == null);
                 const enteredDormancy = dormant && !viewerDormant;
                 viewerDormant = dormant;
                 if (enteredDormancy)
@@ -150,6 +155,12 @@ export function createReconnect(ctx, hooks) {
     };
     return {
         sendHello,
+        startDormant: () => {
+            if (reconnecting || stopped || hooks.isTornDown())
+                return;
+            hooks.onEnterDormancy();
+            void attemptReconnect();
+        },
         isDormant: () => viewerDormant,
         lastSocketError: () => lastSocketError,
         install,

package/dist/clients/attach/slash/dispatch.js

@@ -38,7 +38,7 @@ export const CANVAS_SLASH_COMMANDS = [
     { name: 'graph', description: 'Toggle the canvas GRAPH view (your local subscription tree)' },
     { name: 'inbox', description: 'Toggle the human inbox — pending asks and reviews for you' },
     { name: 'promote', description: 'Promote this node to an orchestrator — /promote, or /promote <kind> to specialize' },
-    { name: 'resume-node', description: 'Open the canvas navigator (search/scope/sort/tree) and resume the chosen node' },
+    { name: 'resume-node', description: 'Open the canvas navigator and focus the chosen node; parked residents wake only on submitted input' },
     { name: 'context', description: 'Browse this node + its subscriptions’ context dirs in a read-only nvim popup' },
     { name: 'plugins', description: 'Open the interactive plugin browser for this machine' },
     { name: 'node-metadata', description: 'Inspect this node — identity, lifecycle, runtime, graph, artifacts, paths, and agent surfaces' },

package/dist/clients/attach/viewer.d.ts

@@ -5,4 +5,4 @@ import './session/pi-oauth-flows.js';
  *  always restoring the terminal first. `canvasName`, when set, attaches over
  *  a relayed WebSocket to that `remoteCanvas.targets.<name>` instead of the
  *  local unix socket — see the `--canvas` flag on `attachToLeaf`. */
-export declare function runAttach(nodeId: string, observer: boolean, canvasName?: string): Promise<void>;
+export declare function runAttach(nodeId: string, observer: boolean, canvasName?: string, wakeParked?: boolean): Promise<void>;