@crouton-kit/crouter 0.3.19 → 0.3.20

package/dist/builtin-personas/design/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Architect a solution — produce one design document an implementer can build from without re-deciding anything left open.
+model: opus
 ---
 
 You are a design agent. Given a bounded design task — a component, subsystem, or interaction surface — you produce one design document an implementer can build from without re-deciding anything you left open. That, not emitting a document, is the bar for done.

package/dist/builtin-personas/design/orchestrator.md

@@ -1,5 +1,6 @@
 ---
 roadmapSkill: design
+model: opus
 ---
 
 You are a **design orchestrator** — you own a design effort too large for one agent and deliver one coherent design by decomposing it, delegating each sub-design to a `design` child, and integrating what returns into a unified artifact.

package/dist/builtin-personas/developer/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Implement a change — make the feature or fix genuinely work against its acceptance criteria, not merely compile.
+model: opus
 ---
 
 You are an implementation agent. Your job is to **implement this feature or change** so the goal it serves is genuinely met — not to emit a diff that compiles and stop.

package/dist/builtin-personas/developer/orchestrator.md

@@ -1,5 +1,6 @@
 ---
 roadmapSkill: development
+model: opus
 ---
 
 You are a **developer orchestrator** — a senior engineer who owns a feature-sized goal and delivers it by driving specialist children, never by writing the code yourself. Your children are `explore` (to map), `spec` (to specify), `plan` (to decompose), `developer` (to implement), and `review` (to validate). Keep them pointed at the right work with the right context, integrate what they return, and advance the goal phase by phase until it is genuinely done.

package/dist/builtin-personas/explore/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Map or investigate an unfamiliar codebase — read-only research that answers a question with concrete file:line evidence.
+model: haiku
 ---
 
 You are a fast codebase exploration agent. Your work is **read-only research** — do not modify any files.

package/dist/builtin-personas/explore/orchestrator.md

@@ -1,3 +1,7 @@
+---
+model: haiku
+---
+
 You are an **exploration orchestrator** — you own a research question too large for one window, and you answer it by fanning out scouts and synthesising what they find. You do not read the whole codebase yourself; that is exactly the context exhaustion you exist to avoid.
 
 Decompose the surface — by subsystem, directory, layer, or sub-question — into areas small enough for one `explore` scout to map well, and delegate each a sharp, self-contained question. Then integrate what they return into one coherent answer: the architecture, the call paths, where things live, with the `file:line` evidence preserved. The question is answered only when every sub-question is — a gap a scout left open is a gap you fill with another scout, not a guess. Reconcile contradictions the same way: when two scouts disagree, spawn a follow-up to settle it rather than picking the answer you like. Your deliverable is the synthesis, not a pile of child transcripts.

package/dist/builtin-personas/general/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Anything else — the catch-all worker for a task that does not fit a specialist kind.
+model: opus
 ---
 
 You are a general-purpose worker — the catch-all for work that doesn't fit a specialist kind. Your job is to complete whatever task is handed to you, and "done" means the **goal actually met**, whatever it was, not an artifact emitted in its direction.

package/dist/builtin-personas/general/orchestrator.md

@@ -1,3 +1,7 @@
+---
+model: opus
+---
+
 You are a **general orchestrator** — the manager for goals that don't belong to a single specialty. You have no lens of your own; your entire edge is decomposition and routing — reading a goal, breaking it into units, and sending each to the most specific kind that fits.
 
 That routing is the discipline. When a whole goal is squarely a build, a research sweep, a spec, or a review, you are not its best owner — hand it to that specialist (created as an orchestrator if it's large) and let their completion expertise carry it. You keep the goals that are genuinely mixed or hard to classify, and you guarantee them done by making sure each routed unit lands with a kind that owns its outcome — never by quietly grinding a specialist's work yourself because routing it felt like overhead.

package/dist/builtin-personas/plan/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Break work into steps — turn a spec or design into a concrete, phased, parallelizable plan with every decision resolved.
+model: opus
 ---
 
 You are a planning agent. Given a spec, design, or requirement, you produce a concrete, navigable plan an implementer builds from without guessing — every decision resolved, not a document that defers the hard calls to the build. A plan that is 80% right costs more than no plan, because agents build the wrong thing confidently.

package/dist/builtin-personas/plan/orchestrator.md

@@ -1,5 +1,6 @@
 ---
 roadmapSkill: planning
+model: opus
 ---
 
 You are a **plan orchestrator** — you own a planning effort end-to-end and deliver one coherent, implementation-ready plan. Planning is the sharpest test of owning a goal: a plan's flaws are invisible until implementation makes them expensive, so a flaw you resolve here is orders of magnitude cheaper than the same flaw caught in the diff. You both write plans directly and decompose large ones; read `crtr memory read planning` for the decomposition thresholds, plan shapes, task templates, and exit-criteria patterns before you shape the roadmap.

package/dist/builtin-personas/plan/reviewers/architecture-fit/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: proposed files/modules/abstractions fit the system's existing decomposition; flags new units that duplicate existing ones or cross layer boundaries
+model: opus
 ---
 
 You are an **architecture-fit reviewer**. Given a plan, verify that the files, modules, and abstractions it proposes fit the system's existing decomposition rather than cutting across it.

package/dist/builtin-personas/plan/reviewers/code-smells/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: nullability mismatches, type conflicts across parts, hidden N+1s, over-fetching, missing error boundaries, leaky abstractions; owns file-level conflicts between parts
+model: opus
 ---
 
 You are a **code-smells / design reviewer**. Given a plan, find the design flaws that would ship if it were implemented as written — before any code makes them expensive.

package/dist/builtin-personas/plan/reviewers/pattern-consistency/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: the plan honors the codebase's real conventions; reads actual source and cites the pattern each finding deviates from; owns contract-level conflicts between parts
+model: opus
 ---
 
 You are a **pattern-consistency reviewer**. Given a plan, verify that what it proposes honors the conventions the codebase actually follows — naming, error handling, API shape, module layout, data access, test structure.

package/dist/builtin-personas/plan/reviewers/requirements-coverage/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: every requirement and design constraint maps to a concrete plan task, classified Covered/Partial/Missing; flags only blocking gaps
+model: opus
 ---
 
 You are a **requirements-coverage reviewer**. Given a plan plus the requirements and design it must satisfy, verify that every requirement and every design constraint maps to a concrete task in the plan.

package/dist/builtin-personas/plan/reviewers/security/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: input validation, injection surfaces, auth/authz gaps, data exposure, races; flags only risks with a concrete exploit path
+model: opus
 ---
 
 You are a **security reviewer**. Given a plan, assess the security risks that would ship if it were implemented as written.

package/dist/builtin-personas/review/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Validate or critique code, a plan, or a spec — deliver a complete, severity-rated verdict without adjudicating.
+model: opus
 ---
 
 You are a review agent. Your job is to deliver a **verdict** on the code, plan, or spec you were given — a complete, accurate account of what is and isn't sound. Be critical and precise.

package/dist/builtin-personas/review/orchestrator.md

@@ -1,3 +1,7 @@
+---
+model: opus
+---
+
 You are a **review orchestrator** — you own a review surface too large for one agent to assess well, and you deliver one coherent verdict by fanning reviews across it in parallel.
 
 Decompose the surface two ways: by **unit** (files, modules, subsystems) and by **lens** (correctness, security, architecture-fit, tests, style). Delegate each child a sharp scope — exactly what to review and which lens to apply — and give it scope, not your suspicions, so it finds problems independently instead of anchoring on a hint. Then synthesise the child reports into one verdict: deduplicated, severity-normalised so a Major from one child outranks a Minor from another, most important first. You detect across the whole surface; you do not adjudicate — report what is there and let the owner decide what gates. The synthesis is your deliverable: integrate the findings into one voice, never forward raw child output, and where two children's findings conflict, reconcile them rather than pasting both.

package/dist/builtin-personas/spec/PERSONA.md

@@ -1,5 +1,6 @@
 ---
 whenToUse: Write a specification — pin down behavior, non-goals, interfaces, edge cases, and testable acceptance criteria from a goal.
+model: opus
 ---
 
 You are a spec writer. Given a goal or feature request, you produce a specification a planner turns into tasks without guessing your intent — that, not emitting a document, is the bar for done.

package/dist/builtin-personas/spec/orchestrator.md

@@ -1,5 +1,6 @@
 ---
 roadmapSkill: spec
+model: opus
 ---
 
 You are a **spec orchestrator** — you own a specification effort and deliver a spec a planner turns into tasks with zero guessing. You reach that through three gated stages: **SHAPE** (clarify intent with the human until the goal is unambiguous), **DESIGN** (produce the blueprint), and **REQUIREMENTS** (derive precise, testable requirements from the finished design). This is one of the few kinds where human engagement is load-bearing — Shape is interactive, and the human gates each stage before the next begins. You drive and decide; the human answers questions and signs off the artifact each stage produces.

package/dist/commands/human/queue.js

@@ -8,6 +8,7 @@ import { transition } from '../../core/runtime/lifecycle.js';
 import { appendInbox } from '../../core/feed/inbox.js';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { inbox, scanInbox, parseDeck, deckPath, responsePath, isResolved, atomicWriteJson, ask, launchReview, readJson, display, } from '@crouton-kit/humanloop';
 import { killPane } from './shared.js';
 // ---------------------------------------------------------------------------
@@ -243,6 +244,16 @@ export const humanRun = defineLeaf({
                 catch {
                     /* render pane is best-effort; the review itself must not die */
                 }
+                // Dock the render pane BESIDE this worker pane. tmux resolves an
+                // untargeted split-window against the attached client's current window
+                // (which wins over $TMUX_PANE), so the pane can land in whatever window
+                // the user happens to be looking at — away from the editor. move-pane
+                // with explicit src/dst is deterministic: raw source and rendered doc
+                // always sit side by side.
+                const selfPane = process.env['TMUX_PANE'];
+                if (renderPane !== undefined && selfPane !== undefined && selfPane !== '') {
+                    spawnSync('tmux', ['move-pane', '-h', '-s', renderPane, '-t', selfPane], { stdio: 'ignore' });
+                }
                 if (renderPane !== undefined) {
                     const rcPath = join(dir, 'run.json');
                     const cur = readJson(rcPath);

package/dist/commands/node.js

@@ -119,6 +119,7 @@ const nodeNew = defineLeaf({
             { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an INDEPENDENT root instead of a managed child: no parent (top-level on the canvas), NO subscription back to you (you are NOT woken by it), resident lifecycle. It records spawned_by=you for provenance and is brought forefront so it can be driven directly. Use for a node you hand off and do not manage (e.g. a sub-orchestrator a human will discuss with).' },
             { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'FORK the new node from an existing pi conversation instead of starting it fresh: pass a node id (forks from that node\'s session), an absolute session `.jsonl` path, or a partial pi session uuid. pi copies that whole history into a NEW session for the child (the source is untouched), then the prompt is delivered as the next message — i.e. the child wakes up as a continuation of that conversation. Use to branch exploratory work off a node that already built up the context you need, instead of re-deriving it. One-shot at birth: the fork resumes its own session thereafter.' },
             { kind: 'flag', name: 'headless', type: 'bool', required: false, constraint: 'Spawn the node on the HEADLESS broker host (no tmux pane) instead of a tmux window. Overrides the `headless` config default for this spawn; omit to use that default (which itself defaults to a tmux pane).' },
+            { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong', 'medium', 'light'], required: false, constraint: 'Override the model the node runs on, by capability TIER: ultra (frontier), strong (opus), medium (sonnet), light (haiku). Omit to use the kind\'s persona default (explore=light, every other kind=strong). The override is durable — it survives revives and polymorphs (promote/demote).' },
         ],
         output: [
             { name: 'node_id', type: 'string', required: true, constraint: 'The new node id.' },
@@ -148,9 +149,10 @@ const nodeNew = defineLeaf({
         const parent = input['parent'];
         const root = input['root'] === true;
         const forkFrom = input['forkFrom'];
+        const model = input['model'];
         // Host precedence: explicit --headless flag > config `headless` default > tmux.
         const hostKind = input['headless'] === true ? 'broker' : readConfig('user').headless === true ? 'broker' : 'tmux';
-        const res = spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, hostKind });
+        const res = spawnChild({ kind, mode, cwd, name, prompt, parent, root, forkFrom, hostKind, model });
         return {
             node_id: res.node.node_id,
             name: res.node.name,
@@ -682,6 +684,7 @@ function setLifecycle(id, value, opts) {
     const { launch } = buildLaunchSpec(target.kind, target.mode, {
         lifecycle: value,
         hasManager: target.parent !== null,
+        model: target.model_override ?? undefined,
     });
     const meta = updateNode(id, { lifecycle: value, launch });
     // --detach: shove the still-running agent into the background crtr session,

package/dist/core/__tests__/broker-attach-limits.test.d.ts

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

package/dist/core/__tests__/broker-attach-limits.test.js

@@ -0,0 +1,157 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-attach-limits.test.ts
+//
+// T8 — the `crtr attach` acceptance gate, gates G4/G7/G8/G9 (controller
+// arbitration, decoder overflow caps, backpressure shedding, and the load-bearing
+// ONE-WRITER proof). Split out of broker-lifecycle.test.ts (see its header for
+// the full file map); the tests are the original acceptance gate, unchanged, on
+// their own isolated harness. Each test drives the REAL detached broker process +
+// REAL view.sock with the enriched fake engine, using the PRODUCTION
+// ViewSocketClient (helpers/broker-clients.ts) as the controller/observer — raw
+// node:net only where the client lifecycle is awkward (G7 oversized line, G8
+// stalled viewer). The engine is hosted IN-PROCESS by the broker, so engine pid
+// == broker pid == node.pi_pid == boot.pid.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { join } from 'node:path';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { createAttachKit, delay, tok, frameHas, brokerLogText, lsofHolders, } from './helpers/broker-clients.js';
+let h;
+let root;
+const kit = createAttachKit(() => h);
+const { attach, attachUntil, connectRaw } = kit;
+before(async () => {
+    if (!hasTmux())
+        return;
+    h = await createHarness({ sessionPrefix: 'crtr-brklim' });
+    root = h.spawnRoot('broker-attach-limits suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const brokerPid = (id) => h.node(id).pi_pid;
+// ---------------------------------------------------------------------------
+// G4 — arbitration + observer read. Guards: 2nd client is admitted observer, an
+// observer prompt is rejected not_controller, BOTH clients receive the relay.
+// Failure mode: two controllers, or an observer driving the engine, or fan-out
+// that misses a viewer.
+// ---------------------------------------------------------------------------
+test('G4 — second client is observer; observer prompt → error{not_controller}; both receive the stream', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G4');
+    const c1 = await attach(id, 'controller', 'g4-ctrl');
+    assert.equal(c1.welcome.role, 'controller', 'first client holds control');
+    const c2 = await attach(id, 'controller', 'g4-second'); // requests control; held → observer
+    assert.equal(c2.welcome.role, 'observer', 'second client is admitted read-only observer (first-attach-wins)');
+    c2.send({ type: 'prompt', text: 'observer must not drive' });
+    const err = await c2.waitFrame((f) => f.type === 'error', 'G4 observer prompt rejected');
+    assert.equal(err.code, 'not_controller', 'G4: observer prompt → error{not_controller}');
+    const token = tok('G4-BROADCAST');
+    c1.send({ type: 'prompt', text: token });
+    await c1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G4 controller received the stream');
+    await c2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G4 observer ALSO received the stream');
+});
+// ---------------------------------------------------------------------------
+// G7 — decoder overflow (guards C5 OOM). A client line over BROKER_READ_CAPS is
+// cap-and-dropped; the broker survives and other clients are unaffected. Failure
+// mode: an unbounded decoder buffer growing the broker to OOM.
+// ---------------------------------------------------------------------------
+test('G7 — an oversized client line is dropped (frame_overflow), the broker survives, other clients unaffected', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G7');
+    const pid = brokerPid(id);
+    const boots = h.bootCount(id);
+    const survivor = await attach(id, 'observer', 'g7-survivor');
+    // 26 MiB with NO newline > BROKER_READ_CAPS.maxLineBytes (24 MiB) → the bounded
+    // FrameDecoder throws FrameOverflowError; the broker drops the peer.
+    const bad = await connectRaw(id, { read: true });
+    bad.writeRaw(Buffer.alloc(26 * 1024 * 1024, 0x78));
+    await bad.waitClosed('G7 oversized peer dropped by the broker');
+    await h.waitFor(() => /frame overflow/.test(brokerLogText(h, id)) || null, { label: 'G7 broker logged the frame-overflow drop' });
+    // The broker survives and the other client is unaffected: a fresh turn relays.
+    const token = tok('G7-AFTER');
+    h.fakeCmd(id, { cmd: 'stream', text: token });
+    await survivor.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G7 survivor still receives live frames');
+    assert.equal(isPidAlive(pid), true, 'G7: the broker survived the overflow');
+    assert.equal(brokerPid(id), pid, 'G7: broker pid unchanged');
+    assert.equal(h.bootCount(id), boots, 'G7: no reboot');
+});
+// ---------------------------------------------------------------------------
+// G8 — backpressure leak (guards M1). A stalled (non-reading) viewer is shed at
+// the HWM (32 MiB byte cap) while the broker + other viewers are unaffected.
+// Failure mode: an indefinitely-growing per-viewer queue (broker OOM) or a slow
+// viewer back-pressuring the shared engine.
+// ---------------------------------------------------------------------------
+test('G8 — a stalled viewer is dropped at the backpressure HWM; the broker + fast viewers are unaffected', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G8');
+    const pid = brokerPid(id);
+    const fast = await attach(id, 'observer', 'g8-fast'); // reads normally
+    // A helloed viewer that NEVER reads (paused socket). It must be in the broadcast
+    // set before the flood; hello, then a short beat for the broker to process it.
+    const stalled = await connectRaw(id, { read: false });
+    stalled.send({ type: 'hello', role: 'observer', client_id: 'g8-stalled' });
+    await delay(400);
+    // A fast event stream: ~60 MiB across 240 message_update frames. The stalled
+    // viewer's per-viewer backlog crosses the 32 MiB byte cap → dropped; the fast
+    // viewer drains between frames (per-update yield) and survives.
+    //
+    // The DROP SIGNAL is the broker's own log line, NOT the stalled socket's 'close':
+    // a PAUSED node socket does not surface the peer FIN/close until it is resumed,
+    // so the broker-side `backpressure high-water mark exceeded` line is the
+    // deterministic, race-free proof that the slow viewer was shed at the HWM.
+    const token = tok('G8-FLOOD');
+    h.fakeCmd(id, { cmd: 'stream', text: token, updates: 240, padBytes: 256 * 1024, tool: false });
+    await h.waitFor(() => /backpressure high-water mark exceeded/.test(brokerLogText(h, id)) || null, { label: 'G8 broker shed the stalled viewer at the HWM', timeoutMs: 30_000 });
+    // The fast viewer drained the WHOLE stream (agent_end is the terminal frame) —
+    // proving only the stalled viewer was shed, while the fast one was unaffected.
+    await fast.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G8 fast viewer received the whole stream', 30_000);
+    assert.equal(isPidAlive(pid), true, 'G8: the broker survived the slow-viewer flood');
+    assert.equal(brokerPid(id), pid, 'G8: broker pid unchanged (the engine was not back-pressured into a restart)');
+});
+// ---------------------------------------------------------------------------
+// G9 — the load-bearing ONE-WRITER assertion. Across attach→detach→reattach the
+// broker pid AND engine pid (the same, in-process) are UNCHANGED and no second
+// engine is ever spawned; the viewer holds ONLY the socket (never the .jsonl).
+// Failure mode: a viewer that spawns/forks a second engine or opens the session
+// .jsonl — the corruption the headless design exists to prevent.
+// ---------------------------------------------------------------------------
+test('G9 — one-writer: broker/engine pid stable across attach→detach→reattach; no second engine; viewer holds only the socket', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G9');
+    const pid0 = brokerPid(id);
+    const boots0 = h.bootCount(id);
+    const c1 = await attach(id, 'controller', 'g9-a');
+    const a = tok('G9-A');
+    c1.send({ type: 'prompt', text: a });
+    await c1.waitFrame((f) => f.type === 'agent_end' && frameHas(f, a), 'G9 first turn relayed');
+    c1.send({ type: 'bye' });
+    c1.close();
+    await delay(300);
+    assert.equal(brokerPid(id), pid0, 'G9: broker/engine pid unchanged after detach');
+    assert.equal(isPidAlive(pid0), true, 'G9: the one engine is still alive after detach');
+    assert.equal(h.bootCount(id), boots0, 'G9: no second engine spawned across detach');
+    // attachUntil (not a fixed sleep) synchronizes on the controller handoff: the
+    // detach's controllerId=null lands a beat after close, so retry until the
+    // reattach is admitted controller before driving the second prompt.
+    const c2 = await attachUntil(id, 'controller', 'g9-b', (x) => x.welcome.role === 'controller', 'G9 reattach re-takes control');
+    assert.equal(c2.welcome.role, 'controller', 'G9: the reattached client drives the SAME engine as controller');
+    const b = tok('G9-B');
+    c2.send({ type: 'prompt', text: b });
+    await c2.waitFrame((f) => f.type === 'agent_end' && frameHas(f, b), 'G9 reattached controller drives the SAME engine');
+    assert.equal(brokerPid(id), pid0, 'G9: STILL the same broker/engine pid after reattach (one writer, never two)');
+    assert.equal(isPidAlive(pid0), true, 'G9: the single engine is alive across the full cycle');
+    assert.equal(h.bootCount(id), boots0, 'G9: exactly one engine boot across attach→detach→reattach');
+    // fd-check (best-effort): the viewer host (this test process) must NOT hold the
+    // session .jsonl — only the broker may. With the fake engine the .jsonl is not
+    // held open continuously, so the meaningful assertion is that the VIEWER never
+    // appears among its holders (and any holder that exists is the broker).
+    const jsonl = join(h.home, 'nodes', id, 'fake-session.jsonl');
+    const holders = lsofHolders(jsonl);
+    if (holders !== null) {
+        assert.ok(!holders.includes(process.pid), 'G9: the attach client (this process) does NOT hold the session .jsonl');
+        for (const holder of holders) {
+            assert.equal(holder, pid0, 'G9: the ONLY holder of the session .jsonl is the broker/engine');
+        }
+    }
+});

package/dist/core/__tests__/broker-attach-stream.test.d.ts

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

package/dist/core/__tests__/broker-attach-stream.test.js

@@ -0,0 +1,125 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/broker-attach-stream.test.ts
+//
+// T8 — the `crtr attach` acceptance gate, gates G1/G1b/G2/G3 (controller drive,
+// relay/coalescing, detach survival, catch-up snapshot). Split out of
+// broker-lifecycle.test.ts (see its header for the full file map); the tests are
+// the original acceptance gate, unchanged, on their own isolated harness. Each
+// test drives the REAL detached broker process + REAL view.sock with the enriched
+// fake engine, using the PRODUCTION ViewSocketClient (helpers/broker-clients.ts)
+// as the controller/observer. The engine is hosted IN-PROCESS by the broker, so
+// engine pid == broker pid == node.pi_pid == boot.pid; "engine pid unchanged" ==
+// broker pid unchanged + no new boot. Each test's lead comment names its gate #
+// and the failure mode it guards.
+import { test, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { isPidAlive } from '../canvas/pid.js';
+import { createAttachKit, delay, tok, frameHas } from './helpers/broker-clients.js';
+let h;
+let root;
+const kit = createAttachKit(() => h);
+const { attach, attachUntil } = kit;
+before(async () => {
+    if (!hasTmux())
+        return;
+    h = await createHarness({ sessionPrefix: 'crtr-brkstrm' });
+    root = h.spawnRoot('broker-attach-stream suite root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+afterEach(() => {
+    kit.closeAll();
+});
+const brokerPid = (id) => h.node(id).pi_pid;
+// ---------------------------------------------------------------------------
+// G1 — controller drive + live relay. Guards: a controller's `prompt` runs the
+// engine AND the streaming AgentSessionEvents are fanned out to the client
+// VERBATIM. Failure mode: a broken relay/fan-out (viewer sees nothing).
+// ---------------------------------------------------------------------------
+test('G1 — controller prompt runs the engine and the streamed AgentSessionEvents relay to the client', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G1');
+    const c = await attach(id, 'controller', 'g1-ctrl');
+    assert.equal(c.welcome.role, 'controller', 'first controller is admitted as controller');
+    const token = tok('G1-PROMPT');
+    c.send({ type: 'prompt', text: token });
+    // The full streaming turn relays: agent_end carrying the token proves the turn
+    // ran AND its terminal frame reached the client; the intermediate types prove
+    // the stream (not just a final blob) was fanned out.
+    await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G1 agent_end carrying the prompt token');
+    for (const t of ['message_start', 'message_update', 'tool_execution_start', 'tool_execution_end', 'message_end', 'turn_end', 'agent_start', 'turn_start']) {
+        assert.ok(c.frames.some((f) => f.type === t), `G1: client received a relayed ${t} frame`);
+    }
+    assert.ok(c.frames.some((f) => f.type === 'message_start' && frameHas(f, token)), 'G1: a relayed message carries the prompt token');
+});
+// ---------------------------------------------------------------------------
+// G1b — message_update coalescing preserves ordering (regression for the F2
+// attach typing-lag fix, 2026-06-09). The broker holds the latest message_update
+// on a ~75ms timer; any OTHER event must flush it FIRST, so a viewer can never
+// observe message_update AFTER its message_end (which would resurrect stale
+// streaming text over the final message), and the LAST coalesced update must not
+// be silently dropped at end-of-turn. Failure modes: a flush ordered after the
+// non-update event, or a pending update discarded when message_end wins the race.
+// ---------------------------------------------------------------------------
+test('G1b — coalesced message_update never arrives after message_end; updates still relayed', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G1b');
+    const c = await attach(id, 'controller', 'g1b-ctrl');
+    const token = tok('G1B');
+    // 12 updates at the fake engine's setImmediate pace — far faster than the 75ms
+    // coalesce window, so coalescing genuinely engages (fewer relayed than emitted).
+    h.fakeCmd(id, { cmd: 'stream', text: token, updates: 12 });
+    await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, token), 'G1b turn relayed');
+    const types = c.frames.map((f) => f.type);
+    const lastUpdate = types.lastIndexOf('message_update');
+    const msgEnd = types.indexOf('message_end');
+    assert.ok(lastUpdate >= 0, 'G1b: at least one message_update relayed (coalescing must not starve updates)');
+    assert.ok(msgEnd >= 0, 'G1b: message_end relayed');
+    assert.ok(lastUpdate < msgEnd, `G1b: a message_update arrived AFTER message_end (update@${lastUpdate} vs end@${msgEnd}) — the coalescer flushed out of order`);
+    // tool/turn/agent frames must also never precede a stale held update.
+    for (const t of ['tool_execution_start', 'turn_end', 'agent_end']) {
+        const i = types.indexOf(t);
+        assert.ok(i < 0 || lastUpdate < i, `G1b: message_update relayed after ${t}`);
+    }
+});
+// ---------------------------------------------------------------------------
+// G2 — detach leaves the engine running. Guards: `bye`/close drops ONE listener,
+// never the engine. Failure mode: a detach that disposes the broker/engine.
+// ---------------------------------------------------------------------------
+test('G2 — detach (bye+close) leaves the broker alive + the engine still emitting; engine pid unchanged', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G2');
+    const pid = brokerPid(id);
+    const boots = h.bootCount(id);
+    const c = await attach(id, 'controller', 'g2-ctrl');
+    const p = tok('G2-PROMPT');
+    c.send({ type: 'prompt', text: p });
+    await c.waitFrame((f) => f.type === 'agent_end' && frameHas(f, p), 'G2 turn relayed before detach');
+    c.send({ type: 'bye' });
+    c.close();
+    await delay(300); // let the broker process the 'close'
+    assert.equal(isPidAlive(pid), true, 'G2: broker still alive after detach');
+    assert.equal(brokerPid(id), pid, 'G2: engine (== broker) pid UNCHANGED across detach');
+    assert.equal(h.bootCount(id), boots, 'G2: no reboot — no second engine spawned');
+    // Still emitting: drive a turn with no client, then a fresh observer's snapshot
+    // carries it (the engine kept running and processing after the detach).
+    const after = tok('G2-AFTER-DETACH');
+    h.fakeCmd(id, { cmd: 'stream', text: after });
+    const o = await attachUntil(id, 'observer', 'g2-obs', (a) => JSON.stringify(a.welcome.snapshot.messages).includes(after), 'G2 post-detach message in snapshot');
+    assert.ok(o.welcome.snapshot.messages.length > 0, 'G2: the engine produced a message after the detach');
+    assert.equal(isPidAlive(pid), true, 'G2: broker still alive after the post-detach turn');
+});
+// ---------------------------------------------------------------------------
+// G3 — catch-up snapshot. Guards: messages produced with NO viewer attached are
+// in welcome.snapshot on reattach, and live events resume. Failure mode: a viewer
+// that reattaches blind to history / gets no further events.
+// ---------------------------------------------------------------------------
+test('G3 — messages produced while detached appear in welcome.snapshot on reattach; live events resume', { skip: !hasTmux() }, async () => {
+    const id = await h.spawnHeadlessChild(root, 'headless worker — G3');
+    const past = tok('G3-DETACHED');
+    h.fakeCmd(id, { cmd: 'stream', text: past }); // produced with zero viewers attached
+    const o = await attachUntil(id, 'observer', 'g3-obs', (a) => JSON.stringify(a.welcome.snapshot.messages).includes(past), 'G3 detached message in snapshot');
+    assert.ok(JSON.stringify(o.welcome.snapshot.messages).includes(past), 'G3: welcome.snapshot.messages contains the message produced while detached');
+    const live = tok('G3-LIVE');
+    h.fakeCmd(id, { cmd: 'stream', text: live });
+    await o.waitFrame((f) => f.type === 'agent_end' && frameHas(f, live), 'G3 live events resume after reattach');
+});

package/dist/core/__tests__/broker-crash-teardown.test.d.ts

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