@north-light/crouter 0.3.157 → 0.3.158

package/dist/core/runtime/interactive-deliver.js

@@ -7,11 +7,10 @@
 // two-channel inbox path had (send rode the watcher's ~1.8s inject; stop rode a
 // direct abort frame; no shared ordering).
 //
-// Both ride the shared one-shot controller round-trip (broker-request.ts):
-// connect → `hello` + `request_control` (preempting any attached viewer for one
-// frame) → send the correlated frame → await its ack. A connection failure
-// BEFORE establishment surfaces as `BrokerUnreachableError` so the caller can
-// fall back to the durable path.
+// Both ride the shared one-shot writable round-trip (broker-request.ts):
+// connect → `hello` as controller → send the correlated frame → await its ack.
+// A connection failure BEFORE establishment surfaces as `BrokerUnreachableError`
+// so the caller can fall back to the durable path.
 import { oneShotControllerRequest } from './broker-request.js';
 /** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
  *  broker routes it itself (idle → prompt, streaming → steer) and acks once

package/dist/core/runtime/model-swap.d.ts

@@ -3,9 +3,8 @@ import { type NodeMeta } from '../canvas/index.js';
  *  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 declare function isBrokerLive(meta: NodeMeta): boolean;
-/** 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 —
+/** Swap a LIVE node's model over its view.sock. Connects as a controller,
+ *  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.

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

@@ -3,7 +3,7 @@
 // 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`,
+//            present): connect to view.sock as a 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
@@ -23,9 +23,8 @@ import { oneShotControllerRequest } from './broker-request.js';
 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 —
+/** Swap a LIVE node's model over its view.sock. Connects as a controller,
+ *  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.

package/dist/core/runtime/node-read.d.ts

@@ -1,4 +1,24 @@
 import type { BrokerSnapshot } from './broker-protocol.js';
+/** The node's conversation exactly as it ran: the raw session `.jsonl` bytes
+ *  plus the assembled system prompt. Nothing here is interpreted — this is the
+ *  faithful record (every session-tree entry, every cycle, every branch, every
+ *  custom role), as opposed to `readNodeSnapshot`'s cycle-flattened
+ *  `AgentMessage[]` reconstruction. */
+export interface NodeSessionRead {
+    nodeId: string;
+    /** Absolute path of the session file the bytes came from. */
+    sessionFile: string;
+    /** Verbatim contents of the session `.jsonl`. */
+    sessionJsonl: string;
+    /** The assembled system prompt as last captured, or `null` if never written. */
+    systemPrompt: string | null;
+}
+/** Read a node's raw conversation record off disk — no broker, no attach, no
+ *  mapping. The system prompt is NOT part of the session file (pi assembles it
+ *  per boot), so it is read from the sidecar the broker captures on every
+ *  rebind (`<jobDir>/system-prompt.md`), falling back to the one `launch.ts`
+ *  writes at spawn (`<nodeDir>/system-prompt.md`). */
+export declare function readNodeSession(nodeId: string): NodeSessionRead;
 export interface NodeSnapshotRead {
     nodeId: string;
     snapshot: BrokerSnapshot;

package/dist/core/runtime/node-read.js

@@ -12,7 +12,7 @@ import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
 import { InputError } from '../io.js';
 import { fullName, getNode } from '../canvas/index.js';
-import { sessionPtrPath } from '../canvas/paths.js';
+import { jobDir, nodeDir, sessionPtrPath } from '../canvas/paths.js';
 import { SessionManager } from './broker-sdk.js';
 import { piAgentDir } from './package-health.js';
 import { BUILTIN_SLASH_COMMANDS } from './pi-vendored.js';
@@ -98,6 +98,39 @@ function statsFromMessages(messages, sessionId, sessionFile) {
     stats.tokens.total = stats.tokens.input + stats.tokens.output + stats.tokens.cacheRead + stats.tokens.cacheWrite;
     return stats;
 }
+/** Read a node's raw conversation record off disk — no broker, no attach, no
+ *  mapping. The system prompt is NOT part of the session file (pi assembles it
+ *  per boot), so it is read from the sidecar the broker captures on every
+ *  rebind (`<jobDir>/system-prompt.md`), falling back to the one `launch.ts`
+ *  writes at spawn (`<nodeDir>/system-prompt.md`). */
+export function readNodeSession(nodeId) {
+    const node = getNode(nodeId);
+    if (node === null) {
+        throw new InputError({ error: 'not_found', message: `no node: ${nodeId}`, field: 'id', next: 'List nodes with `crtr node inspect list`.' });
+    }
+    const sessionFile = resolveSessionFile(nodeId, node.pi_session_file);
+    if (sessionFile === null) {
+        throw new InputError({ error: 'no_session', message: `node has no readable session file: ${nodeId}`, field: 'id', next: 'Choose a node with captured conversation history.' });
+    }
+    return {
+        nodeId,
+        sessionFile,
+        // A live broker appends to this file; a torn read would truncate the last
+        // line, so the caller gets whatever was complete at read time (the same
+        // at-rest guarantee `readNodeSnapshot`'s copy has).
+        sessionJsonl: readFileSync(sessionFile, 'utf8'),
+        systemPrompt: readIfPresent(join(jobDir(nodeId), 'system-prompt.md'))
+            ?? readIfPresent(join(nodeDir(nodeId), 'system-prompt.md')),
+    };
+}
+function readIfPresent(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
 /** Reconstruct a persisted session without launching its broker. Backs the
  * machine-readable snapshot endpoint and the human transcript render. */
 export async function readNodeSnapshot(nodeId) {

package/dist/core/runtime/resume-root.d.ts

@@ -1,5 +1,5 @@
 /** Resolve a front-door resume: pick a target root (MRU or via picker), then
- *  take over this terminal to view it. On success it execs the viewer inline and
+ *  open this terminal to view it. On success it execs the viewer inline and
  *  never returns. Otherwise reports why it did not: `'empty'` (no resumable root
  *  here → caller boots a fresh one) or `'aborted'` (the picker was dismissed →
  *  caller exits without surprise-booting). */

package/dist/core/runtime/resume-root.js

@@ -8,7 +8,7 @@
 //
 // A "session" in the Claude-Code sense is a crtr ROOT node: a durable pi
 // conversation pinned to a cwd that never dies, only goes dormant. So resuming
-// is reviving the last root here and making THIS pane its controller-viewer —
+// is reviving the last root here and making THIS pane its writable viewer —
 // mirroring the front-door boot tail (register the pane as the viewer focus,
 // then exec `crtr surface attach` inline). cwd is the key so it never teleports
 // across projects.
@@ -50,7 +50,7 @@ async function listResumableRoots(cwd) {
         .sort((a, b) => (a.created < b.created ? 1 : a.created > b.created ? -1 : 0)); // created DESC = MRU
 }
 /** Resolve a front-door resume: pick a target root (MRU or via picker), then
- *  take over this terminal to view it. On success it execs the viewer inline and
+ *  open this terminal to view it. On success it execs the viewer inline and
  *  never returns. Otherwise reports why it did not: `'empty'` (no resumable root
  *  here → caller boots a fresh one) or `'aborted'` (the picker was dismissed →
  *  caller exits without surprise-booting). */
@@ -70,8 +70,8 @@ export async function resumeRoot(cwd, pick) {
     await attachInline(target.node_id);
     return 'aborted'; // unreachable — attachInline execs and exits
 }
-/** Register THIS pane as the target root's one viewer, then exec `crtr surface
- *  attach` inline so this terminal becomes the controller-viewer. The attach's
+/** Register THIS pane as the target root's foreground viewer, then exec
+ *  `crtr surface attach` inline so this terminal becomes a writable viewer. The attach's
  *  own ensureAttach revives the dormant broker + waits for its view socket
  *  server-side, so this does NOT revive in-process. Mirrors the front-door boot
  *  tail. Does not return. */
@@ -83,10 +83,10 @@ async function attachInline(nodeId) {
         installTmuxBindings();
     }
     catch { /* best-effort */ }
-    // Make THIS pane the node's one viewer. A dormant root's prior focus row
+    // Make THIS pane the node's foreground viewer. A dormant root's prior focus row
     // points at a stale/detached pane (the front door keeps the row across a
     // clean detach), so drop it and claim the current pane — the exact --new-pane
-    // discipline of registerViewerFocus (UNIQUE(node_id): one viewer per node),
+    // discipline of registerViewerFocus,
     // routed through crtrd since it is a canvas write.
     const here = currentTmux();
     if (here !== null) {

package/dist/core/runtime/spawn.js

@@ -302,8 +302,8 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         }
         // (The three scoped long-term memory stores are seeded for EVERY node at birth
         // in spawnNode — no orchestrator-gated seeding needed here.)
-        // An ATTENDED --root spawned from inside tmux opens its one viewer in the
-        // CALLER'S CURRENT session (below), so it appears where the spawner is
+        // An ATTENDED --root spawned from inside tmux opens its foreground viewer
+        // in the CALLER'S CURRENT session (below), so it appears where the spawner is
         // working; a managed child is a headless broker with NO viewer at all, and
         // so is an unattended terminal root (nobody asked to watch it).
         const here = attendedRoot ? currentTmux() : null;
@@ -318,7 +318,7 @@ export async function spawnChildPrepared(opts, beforeBrokerLaunch) {
         // Broker is the only host: launch the detached broker ENGINE. A managed child
         // gets NO viewer — spawning it returns once the engine is launched and a human
         // opens a viewer on demand via `crtr surface node focus` / surface attach. A --root gets
-        // one foreground viewer below.
+        // a foreground viewer below.
         const placed = launchBrokerOrCrash(meta.node_id, inv, {
             cwd: meta.cwd,
             name: fullName(meta),

package/dist/core/session-model/session-state.d.ts

@@ -12,10 +12,10 @@ export interface DisplayState {
     title: string | undefined;
 }
 export interface SessionState {
-    /** This viewer's broker-assigned role. */
+    /** This viewer's fixed role, stated by the broker in `welcome`. `controller`
+     *  means writable and `observer` means read-only; the broker never reassigns
+     *  it, so nothing after `welcome` can change this field. */
     role: ClientRole;
-    /** The client_id currently holding control, or null when nobody does. */
-    controllerId: string | null;
     /** The broker process's pi agent dir, from `welcome` — lets a viewer point an
      *  AuthStorage/ModelRegistry at the SAME auth.json. */
     agentDir: string | undefined;
@@ -29,8 +29,10 @@ export interface SessionState {
      *  this rather than leaving a dead broker's rows on screen. */
     queued: string[];
     display: DisplayState;
-    /** The blocking dialog awaiting an answer, or null. Only a controller is ever
-     *  sent one; `welcome.pending_dialog` carries one in flight at attach time, and
+    /** The blocking dialog awaiting an answer, or null. Only a writable client is
+     *  ever sent one, and every writable client is sent the SAME one — the first
+     *  answer wins and the broker dismisses the rest by id.
+     *  `welcome.pending_dialog` carries one in flight at attach time, and
      *  a welcome is a COMPLETE catch-up, so a welcome naming none clears it.
      *  (The terminal viewer does not read this field: its overlay is owned by
      *  `InputController`, which holds a live TUI handle rather than data. The field
@@ -46,4 +48,4 @@ export declare function initialSessionState(role?: ClientRole): SessionState;
 export declare function applySnapshot(frame: WelcomeFrame): SessionState;
 /** Fold one broker frame into the session state. Pure and total: a frame that
  *  carries no session state returns `state` UNCHANGED (same reference). */
-export declare function reduce(state: SessionState, frame: BrokerToClient, clientId: string): SessionState;
+export declare function reduce(state: SessionState, frame: BrokerToClient): SessionState;

package/dist/core/session-model/session-state.js

@@ -11,9 +11,10 @@
 //   SESSION state = anything derived SOLELY from what the broker sent.
 //   VIEWER  state = anything derived from local input or this terminal/tab.
 //
-// So `role` belongs here even though it differs per viewer (it is BROKER-assigned
-// — "identical across viewers" would get it wrong), while a transient notice, a
-// connection phase, a correlation id this viewer minted, and the transcript
+// So `role` belongs here even though it differs per viewer (the broker fixes it
+// from this viewer's `hello` and never changes it — "identical across viewers"
+// would get it wrong), while a transient notice, a connection phase, a
+// correlation id this viewer minted, and the transcript
 // RENDERING all stay with the viewer. The transcript itself is deliberately out
 // of scope: the terminal accumulates into a scrollback and the web replaces
 // wholesale, and that difference is legitimate.
@@ -26,7 +27,6 @@ const EMPTY_DISPLAY = { statuses: {}, widgets: {}, title: undefined };
 export function initialSessionState(role = 'observer') {
     return {
         role,
-        controllerId: null,
         agentDir: undefined,
         engine: undefined,
         contextTokens: undefined,
@@ -48,7 +48,6 @@ export function applySnapshot(frame) {
     const contextUsage = snapshot.stats.contextUsage;
     return {
         role: frame.role,
-        controllerId: frame.controller_id,
         agentDir: frame.agentDir,
         engine: snapshot.state,
         contextTokens: contextUsage?.tokens ?? undefined,
@@ -63,25 +62,16 @@ export function applySnapshot(frame) {
 }
 /** Fold one broker frame into the session state. Pure and total: a frame that
  *  carries no session state returns `state` UNCHANGED (same reference). */
-export function reduce(state, frame, clientId) {
+export function reduce(state, frame) {
     switch (frame.type) {
         case 'welcome':
             return applySnapshot(frame);
-        case 'control_changed': {
-            if (state.controllerId === frame.controller_id)
-                return state;
-            return {
-                ...state,
-                controllerId: frame.controller_id,
-                role: frame.controller_id === clientId ? 'controller' : 'observer',
-            };
-        }
         case 'model_changed':
             return patchEngine(state, { model: frame.model });
         case 'extension_ui_request': {
             // pi's uniform envelope: the three display METHODS are levels this model
             // retains; every other method is a dialog (a new one supersedes any
-            // showing one — a control handoff re-routes it).
+            // showing one).
             switch (frame.method) {
                 case 'setStatus': {
                     const current = state.display.statuses[frame.statusKey];

package/dist/daemon/api/handlers/nodes.js

@@ -13,7 +13,7 @@ import { childrenOf, subscribersOf, subscriptionsOf, setMessageWait, updateNode
 import { subtreeIds } from '../../../core/canvas/nav-model.js';
 import { contextDir, reportsDir } from '../../../core/canvas/paths.js';
 import { nodeArtifacts } from '../../../core/canvas/history.js';
-import { readNodeSnapshot, transcriptMarkdown } from '../../../core/runtime/node-read.js';
+import { readNodeSession, readNodeSnapshot, transcriptMarkdown } from '../../../core/runtime/node-read.js';
 import { reviveAll } from '../../../core/runtime/revive-all.js';
 import { promote, requestYield } from '../../../core/runtime/promote.js';
 import { recycleNode } from '../../../core/runtime/recycle.js';
@@ -233,6 +233,22 @@ async function handleSnapshot(ctx) {
     };
     return { status: 200, body };
 }
+/** The faithful export read: raw `.jsonl` bytes + assembled system prompt.
+ *  `/snapshot` reconstructs a cycle-flattened `AgentMessage[]` for renderers and
+ *  drops what a renderer cannot show; this drops nothing. */
+function handleSession(ctx) {
+    const id = ctx.params['id'];
+    requireMeta(id);
+    const read = readNodeSession(id);
+    const body = {
+        node_id: id,
+        session_file: read.sessionFile,
+        session_jsonl: read.sessionJsonl,
+        system_prompt: read.systemPrompt,
+        captured_at: nowIso(),
+    };
+    return { status: 200, body };
+}
 async function handleTranscript(ctx) {
     const id = ctx.params['id'];
     requireMeta(id);
@@ -507,6 +523,7 @@ export const nodeRoutes = [
     { method: 'POST', pattern: '/v1/nodes/revive-all', handler: () => handleReviveAll() },
     { method: 'GET', pattern: '/v1/nodes/:id', handler: handleDetail },
     { method: 'GET', pattern: '/v1/nodes/:id/snapshot', handler: handleSnapshot },
+    { method: 'GET', pattern: '/v1/nodes/:id/session', handler: handleSession },
     { method: 'GET', pattern: '/v1/nodes/:id/transcript', handler: handleTranscript },
     { method: 'GET', pattern: '/v1/nodes/:id/context', handler: handleContext },
     { method: 'GET', pattern: '/v1/nodes/:id/artifacts', handler: handleArtifacts },

package/dist/daemon/manage.js

@@ -50,8 +50,8 @@ export const DAEMON_ENV_STRIP_KEYS = [
     // reads `currentTmux()` for a --root's foreground viewer placement; a stale
     // inherited $TMUX makes that resolve to an arbitrary "current" pane, so a
     // front-door root (created through crtrd) opens a SECOND viewer window and
-    // focuses it — stealing the controller role from the front door's own inline
-    // attach, which is then demoted to a read-only observer in the user's pane.
+    // focuses it — stealing focus from the front door's own inline attach in the
+    // user's pane.
     // Strip them so the daemon is truly paneless and leaves root-viewer placement
     // to the front door. Explicit `-t <target>` tmux ops (focus/window mgmt) are
     // unaffected — the tmux CLI reaches the server via its default socket.

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { readTelemetry, readContextTokens } from './core/canvas/telemetry.js';
 export type { Telemetry } from './core/canvas/telemetry.js';
 export { BrokerClient, BrokerUnavailableError } from './core/broker-client/index.js';
 export { encodeFrame, FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, BROKER_READ_CAPS, } from './core/runtime/broker-protocol.js';
-export type { FrameDecoderCaps, BrokerSnapshot, ClientRole, WelcomeFrame, ControlChangedFrame, AckFrame, ErrorFrame, ExtensionUIRequestFrame, BrokerToClient, HelloFrame, PromptFrame, SteerFrame, FollowUpFrame, AbortFrame, RequestControlFrame, ReleaseControlFrame, ByeFrame, ShutdownFrame, SetModelFrame, CycleModelFrame, SetThinkingLevelFrame, SetAutoRetryFrame, SetAutoCompactionFrame, CompactFrame, NewSessionFrame, SwitchSessionFrame, ForkFrame, SetSessionNameFrame, GetCommandsFrame, NavigateTreeFrame, ReloadFrame, ExportFrame, ClientToBroker, RpcExtensionUIRequest, RpcExtensionUIResponse, ExtensionUIResponseFrame, } from './core/runtime/broker-protocol.js';
+export type { FrameDecoderCaps, BrokerSnapshot, ClientRole, WelcomeFrame, AckFrame, ErrorFrame, ExtensionUIRequestFrame, BrokerToClient, HelloFrame, PromptFrame, SteerFrame, FollowUpFrame, AbortFrame, ByeFrame, ShutdownFrame, SetModelFrame, CycleModelFrame, SetThinkingLevelFrame, SetAutoRetryFrame, SetAutoCompactionFrame, CompactFrame, NewSessionFrame, SwitchSessionFrame, ForkFrame, SetSessionNameFrame, GetCommandsFrame, NavigateTreeFrame, ReloadFrame, ExportFrame, ClientToBroker, RpcExtensionUIRequest, RpcExtensionUIResponse, ExtensionUIResponseFrame, } from './core/runtime/broker-protocol.js';
 export type { SessionStats } from '@earendil-works/pi-coding-agent';
 export { general } from './core/errors.js';
 export type { CrtrError } from './core/errors.js';

package/dist/pi-extensions/canvas-bash-valve.js

@@ -1,5 +1,6 @@
 // canvas-bash-valve.ts — the bash safety valve: auto-background hanging
-// commands, alert via inbox.
+// commands, alert via inbox at tier `urgent` so completion lands as a steering
+// message mid-turn rather than queuing behind the current turn.
 //
 // Loaded into every canvas node's pi process via the node's launch.extensions
 // list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job
@@ -58,7 +59,7 @@ const SUPERVISOR_SCRIPT = [
     'ec=$?',
     'echo "$ec" > "$3"',
     'if [ -f "$4" ]; then',
-    '  crtr node message send "Background bash job $5 finished (exit $ec). Log: $2  Command: $1" --to "$6" --tier normal || true',
+    '  crtr node message send "Background bash job $5 finished (exit $ec). Log: $2  Command: $1" --to "$6" --tier urgent || true',
     'fi',
 ].join('\n');
 function makeJobPaths(contextDir) {
@@ -215,7 +216,7 @@ export function createValveOperations(nodeId, contextDir) {
                 function background(auto = false) {
                     const elapsed = formatBashElapsed(Date.now() - startedAt);
                     const notice = `\n[backgrounded as job ${paths.jobId} after ${elapsed} in the foreground${auto ? ' (auto)' : ''}. ` +
-                        `You'll get an inbox message when it exits. ` +
+                        `It will interrupt you with a message when it exits. ` +
                         `Watch: tail -f ${paths.jobLog} ; stop: kill -- -${pgid}]`;
                     onData(Buffer.from(notice));
                     finish(() => resolve({ exitCode: 0 }));