@crouton-kit/crouter 0.3.28 → 0.3.29

package/dist/commands/workspace.js

@@ -0,0 +1,161 @@
+// workspace.ts — `crtr workspace enter`: the agent-centric editor layout.
+//
+// Turns the current tmux window into an editor view for attached headless nodes:
+// a narrow LEFT rail (the `workspace-sidebar` view — this graph + other live
+// agents in this cwd, with ⚑ inbox flags) beside a CHAT pane (`crtr attach`).
+// Selecting a node in the rail swaps it into the chat pane.
+//
+// Layout build (the only two driver acts, both through placement's seam):
+//   1. splitWindow(here, before+size) → the rail pane, left of here, runs
+//      `crtr view run workspace-sidebar`.
+//   2. `crtr node focus <node> --pane <here>` → swaps the chat node's attach
+//      viewer into here's slot (here's old content relocates to the backstage).
+// The rail finds the chat pane by DISCOVERY (the `@crtr_node` tag attach sets),
+// so it is robust to that swap — no launch-time pane id is threaded into it.
+//
+// Command shape: the path-walker forbids a flat top-level leaf (same constraint
+// as attach), so this is a BRANCH wrapping one leaf: `crtr workspace enter`.
+import { execFile } from 'node:child_process';
+import { defineBranch, defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { getNode, listNodes } from '../core/canvas/index.js';
+import { inTmux, currentTmux, splitWindow, piCommand } from '../core/runtime/placement.js';
+const RAIL_WIDTH = 32;
+/** Newest LIVE (active|idle) forest root started in `cwd` — the default node the
+ *  chat pane attaches to when `--node` is omitted. A root has no parent inside
+ *  the cwd-scoped set. Returns null when this cwd has no live root. */
+function defaultChatNode(cwd) {
+    const rows = listNodes({ status: ['active', 'idle'] }).filter((r) => r.cwd === cwd);
+    if (rows.length === 0)
+        return null;
+    const ids = new Set(rows.map((r) => r.node_id));
+    const roots = rows.filter((r) => r.parent === null || !ids.has(r.parent));
+    const pool = roots.length > 0 ? roots : rows;
+    pool.sort((a, b) => (a.created < b.created ? 1 : -1)); // newest first
+    return pool[0].node_id;
+}
+const workspaceEnterLeaf = defineLeaf({
+    name: 'enter',
+    description: 'enter the editor view — a node rail beside a chat pane, in this window',
+    whenToUse: 'you want to work in the agent-centric editor layout: a left rail listing this graph + the other live agents in this working directory (with ⚑ inbox flags) beside a chat pane attached to a node. Selecting a node in the rail swaps it into the chat pane. Opens in the CURRENT tmux window. tmux-only.',
+    help: {
+        name: 'workspace enter',
+        summary: 'split the current window into a left node-rail (the workspace-sidebar view) + a chat pane (crtr attach); ↵ in the rail swaps a node into the chat. tmux-only.',
+        params: [
+            {
+                kind: 'flag',
+                name: 'node',
+                type: 'string',
+                required: false,
+                constraint: 'Node to attach in the chat pane. Default: the newest live root in this cwd (rail-only, empty chat, if none).',
+            },
+            {
+                kind: 'flag',
+                name: 'width',
+                type: 'int',
+                required: false,
+                default: RAIL_WIDTH,
+                constraint: `Rail width in columns (default ${RAIL_WIDTH}).`,
+            },
+        ],
+        output: [
+            { name: 'rail', type: 'string', required: false, constraint: 'tmux pane id of the rail.' },
+            { name: 'chat', type: 'string', required: false, constraint: 'node id attached in the chat pane (absent if none).' },
+            { name: 'note', type: 'string', required: false, constraint: 'Set only on the non-TTY/piped path.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Splits a narrow LEFT pane in the current window running the workspace-sidebar view.',
+            'Swaps the chosen (or default) node into the current pane as a chat (crtr node focus), relocating the current pane to the backstage.',
+            'Outside a TTY/tmux: prints a notice and exits 0 (no layout change).',
+        ],
+    },
+    run: async (input) => {
+        const node = input['node'];
+        const width = input['width'] ?? RAIL_WIDTH;
+        if (!process.stdout.isTTY) {
+            return { note: 'crtr workspace enter builds a tmux layout — run it in a tmux pane (a TTY), not a pipe.' };
+        }
+        if (!inTmux()) {
+            throw new InputError({
+                error: 'not_in_tmux',
+                message: 'crtr workspace is tmux-only — run it inside the crtr tmux session',
+                next: 'Open it from inside tmux.',
+            });
+        }
+        const here = currentTmux();
+        if (here === null) {
+            throw new InputError({
+                error: 'no_tmux_location',
+                message: 'could not resolve the current tmux pane',
+                next: 'Run this inside a tmux pane.',
+            });
+        }
+        // Resolve the chat node (explicit --node, else newest live root here).
+        let chatNode = null;
+        if (node !== undefined && node !== '') {
+            if (getNode(node) === null) {
+                throw new InputError({
+                    error: 'not_found',
+                    message: `no node: ${node}`,
+                    received: node,
+                    next: 'List nodes with `crtr node inspect list`.',
+                });
+            }
+            chatNode = node;
+        }
+        else {
+            chatNode = defaultChatNode(process.cwd());
+        }
+        // 1. The rail — a narrow split to the LEFT of here. It discovers the chat
+        //    pane itself (the @crtr_node tag), so no pane id is threaded in.
+        const railCmd = piCommand(['view', 'run', 'workspace-sidebar', '--target', here.pane], 'crtr');
+        const rail = splitWindow(here.pane, {
+            cwd: process.cwd(),
+            env: {},
+            command: railCmd,
+            before: true,
+            size: Math.max(16, width),
+        });
+        if (rail === null) {
+            throw new InputError({
+                error: 'split_failed',
+                message: 'tmux could not split the rail pane',
+                next: 'Check the tmux server is reachable, then retry.',
+            });
+        }
+        // 2. The chat — swap the node's attach viewer into here's slot. Best-effort:
+        //    the rail is already up, so a focus failure degrades to a rail-only view
+        //    the user can drive (↵ a node) rather than aborting the whole layout.
+        if (chatNode !== null) {
+            await new Promise((resolve) => {
+                execFile('crtr', ['node', 'focus', chatNode, '--pane', here.pane], () => resolve());
+            });
+        }
+        return chatNode !== null ? { rail, chat: chatNode } : { rail };
+    },
+    render: (result) => {
+        if (result['note'] !== undefined)
+            return String(result['note']);
+        const chat = result['chat'];
+        return chat !== undefined
+            ? `Workspace ready — rail ${result['rail']}, chat attached to ${chat}.`
+            : `Workspace ready — rail ${result['rail']}. No live agent here yet; press ↵ on a node in the rail to open one.`;
+    },
+});
+export function registerWorkspace() {
+    return defineBranch({
+        name: 'workspace',
+        rootEntry: {
+            concept: 'the agent-centric editor view — a node rail beside a chat pane, in one tmux window',
+            desc: 'enter the editor layout for attached headless nodes',
+            useWhen: 'you want an editor-style workspace in tmux: a left rail of this graph + other live agents in this cwd (with ⚑ inbox flags) next to a chat pane attached to a node, where selecting a node in the rail swaps it into the chat. tmux-only.',
+        },
+        help: {
+            name: 'workspace',
+            summary: 'enter the agent-centric editor view (node rail + chat pane) in the current tmux window',
+            model: '`enter` splits the current window into a narrow left rail (the workspace-sidebar view — this graph + other live agents in this cwd, ⚑ inbox flags) and a chat pane (`crtr attach`) attached to a node (--node, or the newest live root here). ↵ in the rail swaps the selected node into the chat pane. tmux-only; piped it prints a notice and exits 0.',
+        },
+        children: [workspaceEnterLeaf],
+    });
+}

package/dist/core/__tests__/broker-double-spawn.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/broker-double-spawn.test.js

@@ -0,0 +1,143 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-double-spawn.test.ts
+//
+// BUG-REGRESSION (broker-universal-host cut, design §C "double-spawn verdict";
+// taste/broker-is-the-host). Two coupled invariants the cut introduced:
+//
+//   1. A pre-cut row carries host_kind='tmux' (or null). While its RAW pi pid is
+//      still ALIVE the daemon must NEVER relaunch it — a relaunch would put a
+//      SECOND vehicle on the same .jsonl (the double-spawn). Liveness is the
+//      recorded engine pid alone; an alive pid is always 'leave'.
+//   2. When that pid dies and the node revives, it comes back as a BROKER and the
+//      row's host_kind is lazily COERCED tmux→'broker' (reviveNode, revive.ts
+//      ~91-97) so inspect/history read honest values and the daemon never
+//      branches it back to a tmux host.
+//
+// Three legs, strongest→cheapest: the pure verdict (D1a), the direct reviveNode
+// coerce (D1b), and the full daemon integration over a real live→dead pid (D1c).
+// Regression check: if the cut's coerce is removed, D1b/D1c go RED (host_kind
+// stays 'tmux'); if an alive pid is ever revived, D1c's "no relaunch" asserts go
+// RED (cycles bumps / host_kind flips while the pid is still alive).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHeadlessHarness } from './helpers/harness.js';
+import { createNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { reviveNode } from '../runtime/revive.js';
+import { livenessVerdict, isPidAlive } from '../../daemon/crtrd.js';
+// A pid reaped (dead) by the time spawnSync returns — the "dead but supervised"
+// pid the grace path judges.
+function deadPid() {
+    const r = spawnSync('true', [], { stdio: 'ignore' });
+    return r.pid ?? 0x7ffffffe;
+}
+/** Fabricate a PRE-CUT host_kind='tmux' row directly (the harness's
+ *  fabricateBrokerNode hardcodes host_kind:'broker', so we mirror its body here
+ *  with host_kind:'tmux' — no harness edit). The result is a row the daemon
+ *  supervises by pid exactly as a legacy tmux node would be. */
+function fabricateTmuxNode(o) {
+    const meta = {
+        node_id: o.id,
+        name: o.id,
+        created: new Date().toISOString(),
+        cwd: process.cwd(),
+        host_kind: 'tmux',
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        parent: null,
+        pi_session_id: o.pi_session_id,
+        status: 'active',
+        intent: null,
+        pi_pid: o.pi_pid,
+    };
+    createNode(meta);
+    closeDb();
+    return o.id;
+}
+// REVIVE_GRACE_MS is 20_000 (crtrd.ts); pick offsets well inside / well past it.
+const T_ALIVE = 6_000_000;
+const T_DEAD = 6_100_000; // first dead observation
+const T_PAST = T_DEAD + 25_000; // > 20s after first-observed-dead → revive
+// ---------------------------------------------------------------------------
+// D1a — pure verdict: an alive pid is NEVER relaunched (no double-spawn).
+// ---------------------------------------------------------------------------
+test('D1a livenessVerdict: an ALIVE pid is left alone (never a double-spawn); a DEAD pid pends then revives', () => {
+    assert.equal(livenessVerdict(true, null), 'leave', 'alive pid, first obs → leave');
+    assert.equal(livenessVerdict(true, 10_000_000), 'leave', 'alive pid is NEVER relaunched');
+    assert.equal(livenessVerdict(false, null), 'pending', 'dead, first obs → pending (double-spawn guard)');
+    assert.equal(livenessVerdict(false, 1_000), 'pending', 'dead, within grace → pending');
+    assert.equal(livenessVerdict(false, 10_000_000), 'revive', 'dead past grace → revive');
+});
+// ---------------------------------------------------------------------------
+// D1b — direct reviveNode coerce: a tmux row flips to 'broker' on revive.
+// ---------------------------------------------------------------------------
+test('D1b reviveNode coerces a pre-cut host_kind=tmux row to broker', async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-d1b' });
+    try {
+        const id = fabricateTmuxNode({ id: 'd1b-node', pi_pid: deadPid(), pi_session_id: 'sess-d1b' });
+        assert.equal(h.node(id).host_kind, 'tmux', 'precondition: row is a legacy tmux host');
+        // reviveNode's lazy coerce runs at the top, before any launch (revive.ts ~91-97).
+        reviveNode(id, { resume: true });
+        assert.equal(h.node(id).host_kind, 'broker', 'tmux→broker coerced on revive (the daemon never branches it back)');
+    }
+    finally {
+        await h.dispose();
+    }
+});
+// ---------------------------------------------------------------------------
+// D1c — full integration: an ALIVE tmux pid is NOT relaunched; once it dies the
+// node revives as a broker (host_kind coerced, cycles bumped).
+// ---------------------------------------------------------------------------
+test('D1c daemon: a live tmux pi is never double-spawned; on death it revives as a broker', { timeout: 30_000 }, async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-d1c' });
+    // A real live subprocess whose pid stands in for the raw pi vehicle.
+    const child = spawn('sleep', ['300'], { stdio: 'ignore' });
+    const livePid = child.pid;
+    try {
+        assert.equal(isPidAlive(livePid), true, 'precondition: the raw pi pid is alive');
+        // pi_session_id SET so the dead-pid path routes the crash/grace revive, NOT
+        // the never-booted boot-failure branch.
+        const id = fabricateTmuxNode({ id: 'd1c-node', pi_pid: livePid, pi_session_id: 'sess-d1c' });
+        assert.equal(h.node(id).host_kind, 'tmux', 'precondition: pre-cut tmux host');
+        assert.equal(h.node(id).cycles ?? 0, 0, 'no revive yet');
+        // --- TICK while the pi is ALIVE: must be a no-op. The daemon never
+        //     relaunches a live pid, so reviveNode is never called → NO coerce, NO
+        //     cycle bump, pid unchanged. This is the double-spawn guard. ---
+        await h.tick(T_ALIVE);
+        {
+            const n = h.node(id);
+            assert.equal(n.host_kind, 'tmux', 'live pid: host_kind NOT coerced (reviveNode never ran → no double-spawn)');
+            assert.equal(n.cycles ?? 0, 0, 'live pid: NO revive (cycles still 0)');
+            assert.equal(n.pi_pid, livePid, 'live pid: pi_pid unchanged — no second vehicle launched');
+        }
+        // Kill the raw pi and wait until the daemon would observe it dead.
+        child.kill('SIGKILL');
+        await h.waitFor(() => (isPidAlive(livePid) ? null : true), { label: 'raw pi dead', timeoutMs: 10_000 });
+        // --- TICK: first dead observation → pending (within grace). No revive. ---
+        await h.tick(T_DEAD);
+        {
+            const n = h.node(id);
+            assert.equal(n.cycles ?? 0, 0, 'first-observed-dead: pends, no revive yet');
+            assert.equal(n.host_kind, 'tmux', 'still tmux until the revive actually fires');
+        }
+        // --- TICK past the grace: the crash/grace revive fires → reviveNode coerces
+        //     host_kind tmux→broker and bumps cycles (observable instantly, the
+        //     model effect lands before the detached broker spawn — grace-clock). ---
+        await h.tick(T_PAST);
+        {
+            const n = h.node(id);
+            assert.equal(n.cycles ?? 0, 1, 'past grace: revived → cycles bumped to 1');
+            assert.equal(n.host_kind, 'broker', 'past grace: host_kind coerced tmux→broker on revive');
+        }
+    }
+    finally {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/broker-fork-seam.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/broker-fork-seam.test.js

@@ -0,0 +1,102 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-fork-seam.test.ts
+//
+// BUG-REGRESSION (broker-universal-host cut, design §B.broker; U1 report
+// mq8ftenr-5d55313d). Before the cut, the headless broker had NO fork path — its
+// session selection THREW `--fork is not supported by the headless broker`. After
+// the cut EVERY node is a broker, so `node new --fork-from <id>` would always hit
+// that throw. The fix routes the broker's fork through pi's REAL fork seam,
+// SessionManager.forkFrom (broker.ts buildBrokerSession, the `forking` branch) —
+// the same method pi's own `--fork` CLI flag uses.
+//
+// This test drives the BROKER's OWN fork branch (broker.ts buildBrokerSession,
+// the `forking` branch ~1106) end to end: it calls `buildBrokerSession` with
+// `cfg.forkFrom` set to a real source session .jsonl — the EXACT path a
+// `node new --fork-from <id>` boot takes through the broker — and asserts the
+// resulting live session is a genuine fork: a NEW session id (not a colliding
+// copy) and a `parentSession` header pointing at the source, with the source's
+// history copied in. Because it invokes `buildBrokerSession` (not
+// `SessionManager.forkFrom` directly), it goes RED if broker.ts's fork branch
+// reverts to `throw "--fork is not supported by the headless broker"` — it
+// guards its own stated regression.
+//
+// Like the C3/C4 real-SDK wiring tests, it drives the REAL engine (broker-sdk's
+// static SDK re-exports) — NOT the CRTR_BROKER_ENGINE fake the lifecycle suite
+// uses, whose fixture omits forkFrom and so could never exercise this branch. It
+// runs offline (fork + session/services assembly are all local: no network/auth).
+//
+// (fork.test.ts covers the pure argv/resolve layers — buildPiArgv emitting
+// `--fork`, resolveForkSource turning a ref into a path. THIS file covers the
+// broker runtime branch those layers feed.)
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../runtime/broker-sdk.js';
+import { buildBrokerSession } from '../runtime/broker.js';
+// The REAL engine — bypasses the CRTR_BROKER_ENGINE fake entirely (the whole
+// point: the fake omits forkFrom, so only the real SDK can prove the branch).
+const realEngine = {
+    createAgentSessionServices,
+    createAgentSessionFromServices,
+    SessionManager,
+    VERSION,
+};
+let dir;
+before(() => {
+    dir = mkdtempSync(join(tmpdir(), 'crtr-fork-seam-'));
+});
+after(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+/** A minimal but VALID pi session .jsonl (the exact on-disk shape v3 emits): a
+ *  `session` header line + two `message` entries. This is what a node that has
+ *  run a turn or two carries on disk — the source the broker forks from. */
+function writeSourceSession(path, srcId) {
+    const lines = [
+        JSON.stringify({ type: 'session', version: 3, id: srcId, timestamp: '2026-06-10T20:27:32.891Z', cwd: dir }),
+        JSON.stringify({ type: 'message', id: 'a42170e1', parentId: null, timestamp: '2026-06-10T20:27:32.893Z', message: { role: 'user', content: 'source turn one' } }),
+        JSON.stringify({ type: 'message', id: 'f309b932', parentId: 'a42170e1', timestamp: '2026-06-10T20:27:32.893Z', message: { role: 'assistant', content: 'source reply one' } }),
+    ];
+    writeFileSync(path, lines.join('\n') + '\n');
+    return 2; // entry count (the two message lines)
+}
+test('D2 broker fork branch: buildBrokerSession(cfg.forkFrom) yields a NEW id + parentSession header, copying history (never throws "fork not supported")', async () => {
+    // 1. A real source session on disk.
+    const srcFile = join(dir, 'src.jsonl');
+    const srcId = '019eb338-029b-7536-b3eb-d33bd6f641a8';
+    const srcEntryCount = writeSourceSession(srcFile, srcId);
+    // 2. Drive the BROKER's fork branch: buildBrokerSession with cfg.forkFrom set —
+    //    the same recipe a `node new --fork-from <id>` boot produces. The OLD broker
+    //    THREW in this branch ("--fork is not supported by the headless broker"), so
+    //    if broker.ts:~1106 reverts to that throw, this rejects and the test goes RED.
+    const cfg = { cwd: dir, extensionPaths: [], forkFrom: srcFile };
+    let session;
+    let resuming;
+    await assert.doesNotReject(async () => {
+        const built = await buildBrokerSession(realEngine, cfg);
+        session = built.session;
+        resuming = built.resuming;
+    }, 'the broker fork branch must NOT throw "fork is not supported by the headless broker"');
+    assert.ok(session !== undefined, 'buildBrokerSession returned a live session for the fork');
+    try {
+        // 3. A fork boots as a FRESH spawn (resuming=false) so the kickoff firstPrompt
+        //    fires — the new node gets the source history AND a new task to start on.
+        assert.equal(resuming, false, 'a fork is a fresh spawn (resuming=false) so the kickoff fires');
+        // 4. Real fork metadata on the broker's selected SessionManager, not a
+        //    colliding .jsonl copy.
+        const sm = session.sessionManager;
+        assert.notEqual(sm.getSessionId(), srcId, 'the fork is a NEW session id (not a copy that would collide on resume)');
+        const header = sm.getHeader();
+        assert.equal(header?.parentSession, srcFile, 'the fork header records parentSession pointing at the source .jsonl');
+        // 5. The source history is carried into the fork (fork copies, not empty
+        //    start). The broker boot may append its own session-start entry, so the
+        //    fork holds AT LEAST the source's messages — a naïve empty session would
+        //    have zero.
+        assert.ok(sm.getEntries().length >= srcEntryCount, `the fork carries the source conversation history forward ` +
+            `(>= ${srcEntryCount} source entries; got ${sm.getEntries().length})`);
+    }
+    finally {
+        session.dispose();
+    }
+});

package/dist/core/__tests__/broker-sdk-wiring.test.js

@@ -107,6 +107,7 @@ test('C2 — zero-viewer UI context resolves dialogs to deny/cancel immediately
             throw new Error('C2: must NOT forward a dialog when no controller is attached');
         },
         pending: new Map(),
+        broadcast: () => { },
     });
     // confirm() WITH a large timeout: the fix must resolve at once (deny), NOT after
     // the timeout — the old timeout-reliant path would have waited 60s (or, with no
@@ -144,6 +145,7 @@ test('M2 — a forwarded dialog stays pending on controller detach, resolving on
         },
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         pending: pending,
+        broadcast: () => { },
     });
     // Controller attached → confirm() forwards + registers a pending dialog (with the
     // request retained for welcome.pending_dialog / re-route, T4) and does NOT