@north-light/crouter 0.3.154 → 0.3.157

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

@@ -7,10 +7,11 @@
 // 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 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.
+// 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.
 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,8 +3,9 @@ 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 as a controller,
- *  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, claims controller
+ *  (hello + request_control, so an attached viewer never blocks the swap), sends
+ *  `set_model`, and resolves with the broker-resolved `provider/id` on its ack —
  *  read back from the row the broker just persisted (model_changed.model carries
  *  only the bare id). Rejects with the broker's message on an `error` frame (e.g.
  *  `no model matching '<spec>' in the registry`), on connect failure, or timeout.

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 as a controller, send `set_model`,
+//            present): connect to view.sock, claim controller, send `set_model`,
 //            await the ack. The broker's broadcastModelChanged already persists
 //            the choice via persistModelChoice (model_override + launch.model), so
 //            this path NEVER writes the recipe itself — it reads back the resolved
@@ -23,8 +23,9 @@ 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 as a controller,
- *  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, claims controller
+ *  (hello + request_control, so an attached viewer never blocks the swap), sends
+ *  `set_model`, and resolves with the broker-resolved `provider/id` on its ack —
  *  read back from the row the broker just persisted (model_changed.model carries
  *  only the bare id). Rejects with the broker's message on an `error` frame (e.g.
  *  `no model matching '<spec>' in the registry`), on connect failure, or timeout.

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

@@ -1,24 +1,4 @@
 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 { jobDir, nodeDir, sessionPtrPath } from '../canvas/paths.js';
+import { 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,39 +98,6 @@ 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
- *  open this terminal to view it. On success it execs the viewer inline and
+ *  take over 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 writable viewer —
+// is reviving the last root here and making THIS pane its controller-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
- *  open this terminal to view it. On success it execs the viewer inline and
+ *  take over 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 foreground viewer, then exec
- *  `crtr surface attach` inline so this terminal becomes a writable viewer. The attach's
+/** 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
  *  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 foreground viewer. A dormant root's prior focus row
+    // Make THIS pane the node's one 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,
+    // discipline of registerViewerFocus (UNIQUE(node_id): one viewer per node),
     // 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 foreground viewer
-        // in the CALLER'S CURRENT session (below), so it appears where the spawner is
+        // 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
         // 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
-        // a foreground viewer below.
+        // one 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 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. */
+    /** This viewer's broker-assigned role. */
     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,10 +29,8 @@ 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 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
+    /** 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
      *  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
@@ -48,4 +46,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): SessionState;
+export declare function reduce(state: SessionState, frame: BrokerToClient, clientId: string): SessionState;

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

@@ -11,10 +11,9 @@
 //   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 (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
+// 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
 // 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.
@@ -27,6 +26,7 @@ const EMPTY_DISPLAY = { statuses: {}, widgets: {}, title: undefined };
 export function initialSessionState(role = 'observer') {
     return {
         role,
+        controllerId: null,
         agentDir: undefined,
         engine: undefined,
         contextTokens: undefined,
@@ -48,6 +48,7 @@ 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,
@@ -62,16 +63,25 @@ 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) {
+export function reduce(state, frame, clientId) {
     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).
+            // showing one — a control handoff re-routes it).
             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 { readNodeSession, readNodeSnapshot, transcriptMarkdown } from '../../../core/runtime/node-read.js';
+import { 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,22 +233,6 @@ 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);
@@ -523,7 +507,6 @@ 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 focus from the front door's own inline attach in the
-    // user's pane.
+    // 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.
     // 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, 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 { 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 { SessionStats } from '@earendil-works/pi-coding-agent';
 export { general } from './core/errors.js';
 export type { CrtrError } from './core/errors.js';