@north-light/crouter 0.3.154

package/dist/core/__tests__/canvas-inbox-watcher.test.js

@@ -0,0 +1,255 @@
+// Tests for the canvas-node inbox watcher pi extension.
+//
+// Run with: node --import tsx/esm --test src/core/__tests__/canvas-inbox-watcher.test.ts
+//
+// Focus: a finished node (push final → InboxEntry kind 'final') must STEER a
+// mid-stream subscriber, not queue behind its current turn as a follow-up.
+// Part 2 — the refresh-yield HOLD path and idle delivery — lives in
+// canvas-inbox-watcher-hold.test.ts (split for node:test file-level parallelism).
+import { test, describe, before, after, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasInboxWatcher from '../../pi-extensions/canvas-inbox-watcher.js';
+import { createNode } from '../canvas/canvas.js';
+import { reportsDir } from '../canvas/paths.js';
+import { closeDb } from '../canvas/db.js';
+import { appendInbox, coalesce, finalizeInboxEntry } from '../feed/inbox.js';
+import { appendSituationalContext, SITUATIONAL_CONTEXT_CUSTOM_TYPE } from '../runtime/situational-context.js';
+// Drive the watcher's injectable cadence seam (CRTR_WATCHER_TICK_MS /
+// CRTR_WATCHER_DEBOUNCE_MS) at a fast tempo so the watcher delivers in tens of
+// milliseconds, not seconds — exactly the resolve+seed tick, read tick, and
+// debounce window it runs against the real 800/1000 cadence. Tests then poll for
+// the delivery with waitFor() rather than sleeping a fixed settle window, so a
+// starved interval tick on a loaded CI runner can't race the assertion.
+const TICK_MS = 20;
+const DEBOUNCE_MS = 25;
+let origHome;
+let origNode;
+const homes = [];
+const disposers = [];
+/** Point CRTR_HOME at a fresh temp canvas root and bind CRTR_NODE_ID. */
+function freshNode(nodeId) {
+    const home = join(tmpdir(), `crtr-canvas-watcher-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(home, { recursive: true });
+    homes.push(home);
+    process.env['CRTR_HOME'] = home;
+    process.env['CRTR_NODE_ID'] = nodeId;
+}
+function makeFakePi() {
+    const handlers = {};
+    return {
+        injected: [],
+        sentMessages: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
+        sendMessage(message) { this.sentMessages.push(message); },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+// Register the watcher, then fire session_start — the real lifecycle gate
+// that arms its poll interval and initial tick (see canvas-inbox-watcher.ts).
+// registerCanvasInboxWatcher() alone only wires up handlers; without this the
+// watcher never polls or sends anything.
+function registerWatcher(pi) {
+    const dispose = registerCanvasInboxWatcher(pi);
+    pi.fire('session_start', { type: 'session_start' }, undefined);
+    return dispose;
+}
+// Poll `predicate` until it holds or `timeoutMs` elapses, then return either
+// way. The watcher delivers on its own setInterval cadence, which competes for
+// the event loop with this test's timers; a fixed sleep before asserting is
+// unreliable on an oversubscribed CI runner (--test-concurrency=4), where an
+// interval tick is starved past the debounce window and the assertion runs
+// before the flush — the observed `0 !== 1` flake. Polling returns the instant
+// delivery lands (fast in the common case) and tolerates scheduling jitter with
+// a generous ceiling; returning on timeout lets the following asserts produce a
+// precise message instead of a generic wait error.
+async function waitFor(predicate, timeoutMs = 3000, stepMs = 10) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (predicate())
+            return;
+        await wait(stepMs);
+    }
+}
+test('coalesce inlines short reports with their absolute path and only hints for remaining canonical refs', () => {
+    freshNode('child');
+    const child = createNode({
+        node_id: 'child',
+        name: 'child',
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    });
+    const reportPath = join(reportsDir(child.node_id), 'short-update.md');
+    mkdirSync(reportsDir(child.node_id), { recursive: true });
+    writeFileSync(reportPath, '---\nnode: child\nkind: update\n---\nshort report body', 'utf8');
+    const digest = coalesce([
+        finalizeInboxEntry({ from: 'child', tier: 'normal', kind: 'update', label: 'short report', ref: 'child:reports/short-update.md' }),
+    ]);
+    assert.match(digest, new RegExp(`\\[update\\] short report at ${reportPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:`));
+    assert.match(digest, /short report body/);
+    assert.doesNotMatch(digest, /Dereference a ref with/);
+    const guidance = 'Dereference a ref with `crtr canvas history read <ref>`.';
+    const canonical = coalesce([
+        finalizeInboxEntry({ from: 'child', tier: 'normal', kind: 'final', label: 'done', ref: 'child:reports/final.md' }),
+    ]);
+    assert.equal(canonical.endsWith(`\n\n${guidance}`), true);
+    const spilled = coalesce([
+        finalizeInboxEntry({ from: 'child', tier: 'normal', kind: 'message', label: 'long', ref: '/tmp/message.md', data: { body: 'long body' } }),
+    ]);
+    assert.doesNotMatch(spilled, /Dereference a ref with/);
+    closeDb();
+});
+let origTick;
+let origDebounce;
+before(() => {
+    origHome = process.env['CRTR_HOME'];
+    origNode = process.env['CRTR_NODE_ID'];
+    origTick = process.env['CRTR_WATCHER_TICK_MS'];
+    origDebounce = process.env['CRTR_WATCHER_DEBOUNCE_MS'];
+    process.env['CRTR_WATCHER_TICK_MS'] = String(TICK_MS);
+    process.env['CRTR_WATCHER_DEBOUNCE_MS'] = String(DEBOUNCE_MS);
+});
+afterEach(() => {
+    while (disposers.length > 0)
+        disposers.pop()();
+});
+after(() => {
+    if (origHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = origHome;
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+    if (origTick === undefined)
+        delete process.env['CRTR_WATCHER_TICK_MS'];
+    else
+        process.env['CRTR_WATCHER_TICK_MS'] = origTick;
+    if (origDebounce === undefined)
+        delete process.env['CRTR_WATCHER_DEBOUNCE_MS'];
+    else
+        process.env['CRTR_WATCHER_DEBOUNCE_MS'] = origDebounce;
+    for (const h of homes) {
+        try {
+            rmSync(h, { recursive: true, force: true });
+        }
+        catch { /* noop */ }
+    }
+});
+describe('canvas inbox watcher — finished-node delivery', () => {
+    test('mid-stream: a finished node (kind final) steers the subscriber', async () => {
+        freshNode('node-final');
+        const pi = makeFakePi();
+        disposers.push(registerWatcher(pi));
+        // Subscriber is actively streaming when the worker finishes.
+        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await wait(TICK_MS + 100);
+        appendInbox('node-final', { from: 'child-1', tier: 'normal', kind: 'final', label: 'all done' });
+        await waitFor(() => pi.injected.length >= 1);
+        assert.equal(pi.injected.length, 1, 'one coalesced injection');
+        assert.equal(pi.injected[0].deliverAs, 'steer', 'a finished node steers, not follows up');
+    });
+    test('mid-stream: a routine update still follows up', async () => {
+        freshNode('node-update');
+        const pi = makeFakePi();
+        disposers.push(registerWatcher(pi));
+        pi.fire('agent_start', { type: 'agent_start' }, { isIdle: () => false });
+        await wait(TICK_MS + 100);
+        appendInbox('node-update', { from: 'child-2', tier: 'normal', kind: 'update', label: 'still working' });
+        await waitFor(() => pi.injected.length >= 1);
+        assert.equal(pi.injected.length, 1);
+        assert.equal(pi.injected[0].deliverAs, 'followUp', 'a normal update is not urgent → followUp');
+    });
+});
+describe('canvas inbox watcher — hidden situational-context delivery', () => {
+    test('a situational-only entry (no visible body) never reaches the visible digest, only the hidden sendMessage', async () => {
+        freshNode('node-situational-only');
+        appendSituationalContext('node-situational-only', 'the user is mid-checkout on the store applet');
+        const pi = makeFakePi();
+        disposers.push(registerWatcher(pi));
+        appendInbox('node-situational-only', {
+            from: null,
+            tier: 'normal',
+            kind: 'message',
+            label: '(ambient context updated)',
+            data: { situational: true, situationalOnly: true },
+        });
+        // A situational-only flush sets sentMessages (never injected) in a single
+        // synchronous flush(), so waiting on the hidden send is sufficient to also
+        // settle the injected.length === 0 assertion below.
+        await waitFor(() => pi.sentMessages.length >= 1);
+        assert.equal(pi.injected.length, 0, 'a situational-only entry never triggers a visible digest');
+        assert.equal(pi.sentMessages.length, 1, 'exactly one hidden custom message sent');
+        assert.match(pi.sentMessages[0].content, /<situational-context>/);
+        assert.match(pi.sentMessages[0].content, /the user is mid-checkout on the store applet/);
+        // Pins the seam the attach viewer keys its collapsed-rendering dispatch off
+        // (src/clients/attach/render/chat-view.ts): a regression here (e.g. someone routing
+        // the situational update through a different/generic customType) would make
+        // the viewer fall through to the prominent, uncollapsed CustomMessageComponent.
+        assert.equal(pi.sentMessages[0].customType, SITUATIONAL_CONTEXT_CUSTOM_TYPE);
+    });
+    test('a combined entry (visible body + situational flag) puts the body in the digest and the ambient text ONLY in the hidden sendMessage', async () => {
+        freshNode('node-situational-combined');
+        appendSituationalContext('node-situational-combined', 'the hidden ambient checkout state');
+        const pi = makeFakePi();
+        disposers.push(registerWatcher(pi));
+        appendInbox('node-situational-combined', {
+            from: 'child-3',
+            tier: 'normal',
+            kind: 'message',
+            label: 'visible update',
+            data: { body: 'the visible message body', situational: true },
+        });
+        // The hidden send and the visible digest both fire in one synchronous
+        // flush(); the injection is the later of the two, so wait on it.
+        await waitFor(() => pi.injected.length >= 1 && pi.sentMessages.length >= 1);
+        assert.equal(pi.injected.length, 1, 'the visible body still reaches the digest');
+        assert.match(pi.injected[0].content, /the visible message body/);
+        assert.doesNotMatch(pi.injected[0].content, /hidden ambient checkout state/, 'ambient text never rides the visible digest');
+        assert.equal(pi.sentMessages.length, 1, 'exactly one hidden custom message sent');
+        assert.match(pi.sentMessages[0].content, /<situational-context>/);
+        assert.match(pi.sentMessages[0].content, /the hidden ambient checkout state/);
+    });
+    test('a situational-only entry survives a transient sendMessage failure — retried, not dropped', async () => {
+        // Durability regression: the cursor advances past a situational-only entry
+        // BEFORE flush() runs, so a swallowed sendMessage failure with no re-queue
+        // would drop the hidden wake permanently (never re-read from the inbox,
+        // never retried) — unlike the visible digest path, which already re-queues
+        // on failure. This pins the same durability contract for the hidden path.
+        freshNode('node-situational-retry');
+        appendSituationalContext('node-situational-retry', 'retry me please');
+        const pi = makeFakePi();
+        let calls = 0;
+        const realSendMessage = pi.sendMessage.bind(pi);
+        pi.sendMessage = (message, options) => {
+            calls += 1;
+            if (calls === 1)
+                throw new Error('transient failure');
+            realSendMessage(message, options);
+        };
+        disposers.push(registerWatcher(pi));
+        appendInbox('node-situational-retry', {
+            from: null,
+            tier: 'normal',
+            kind: 'message',
+            label: '(ambient context updated)',
+            data: { situational: true, situationalOnly: true },
+        });
+        // First send throws (re-queued), so a later flush retries: wait for the
+        // successful second delivery rather than a fixed multi-settle sleep.
+        await waitFor(() => calls >= 2 && pi.sentMessages.length >= 1);
+        assert.ok(calls >= 2, 'sendMessage retried after the first failure instead of being swallowed once');
+        assert.equal(pi.injected.length, 0, 'still never reaches the visible digest');
+        assert.equal(pi.sentMessages.length, 1, 'eventually delivered exactly once after the retry succeeds');
+        assert.match(pi.sentMessages[0].content, /retry me please/);
+    });
+});

package/dist/core/__tests__/canvas.test.d.ts

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

package/dist/core/__tests__/canvas.test.js

@@ -0,0 +1,201 @@
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, getRow, updateNode, setStatus, listNodes, subscribe, unsubscribe, setSubscriptionActive, recordSpawn, subscribersOf, subscriptionsOf, view, hasActiveLiveSubscription, rebuildIndex, } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { contextDir, reportsDir, jobDir, nodeMetaPath, } from '../canvas/paths.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-canvas-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    // Fresh db + dirs per test for isolation.
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('createNode scaffolds dirs, writes meta, indexes the row', () => {
+    createNode(node('a'));
+    assert.ok(existsSync(contextDir('a')));
+    assert.ok(existsSync(reportsDir('a')));
+    assert.ok(existsSync(jobDir('a')));
+    assert.ok(existsSync(nodeMetaPath('a')));
+    const meta = getNode('a');
+    assert.equal(meta?.node_id, 'a');
+    assert.equal(meta?.kind, 'general');
+    const row = getRow('a');
+    assert.equal(row?.node_id, 'a');
+    assert.equal(row?.status, 'active');
+});
+test('meta.json is the source of truth on disk', () => {
+    createNode(node('a', { kind: 'developer' }));
+    const raw = JSON.parse(readFileSync(nodeMetaPath('a'), 'utf8'));
+    assert.equal(raw.kind, 'developer');
+});
+test('updateNode merges meta and re-indexes the row', () => {
+    createNode(node('a'));
+    updateNode('a', { mode: 'orchestrator', lifecycle: 'resident' });
+    assert.equal(getNode('a')?.mode, 'orchestrator');
+    assert.equal(getRow('a')?.lifecycle, 'resident');
+    // unspecified fields preserved
+    assert.equal(getNode('a')?.kind, 'general');
+});
+// Regression: cycle_pending is an IDENTITY field (meta.json-only, no db
+// column — like pi_session_file) written by reviveNode/canvas-stophook and
+// read back by reviveNode's locked launch arbitration. writeMeta only persists
+// keys listed in IDENTITY_KEYS; if cycle_pending is missing from that whitelist,
+// updateNode silently drops it and a competing caller can request strict resume.
+test('cycle_pending survives the updateNode/getNode meta.json round-trip', () => {
+    createNode(node('a'));
+    assert.equal(getNode('a')?.cycle_pending, undefined); // never set
+    updateNode('a', { cycle_pending: true });
+    assert.equal(getNode('a')?.cycle_pending, true);
+    updateNode('a', { cycle_pending: false });
+    assert.equal(getNode('a')?.cycle_pending, false);
+});
+test('setStatus updates both meta and row', () => {
+    createNode(node('a'));
+    setStatus('a', 'done');
+    assert.equal(getNode('a')?.status, 'done');
+    assert.equal(getRow('a')?.status, 'done');
+});
+test('listNodes filters by status', () => {
+    createNode(node('a', { status: 'active' }));
+    createNode(node('b', { status: 'idle' }));
+    createNode(node('c', { status: 'done' }));
+    assert.equal(listNodes().length, 3);
+    assert.deepEqual(listNodes({ status: ['active', 'idle'] }).map((n) => n.node_id).sort(), ['a', 'b']);
+});
+test('subscription spine: subscribersOf / subscriptionsOf', () => {
+    createNode(node('mgr'));
+    createNode(node('w1'));
+    createNode(node('w2'));
+    // mgr subscribes to both workers (parent watches children)
+    subscribe('mgr', 'w1');
+    subscribe('mgr', 'w2', false);
+    // w1's subscribers = who a w1 push fans out to = mgr
+    assert.deepEqual(subscribersOf('w1').map((s) => s.node_id), ['mgr']);
+    // mgr's subscriptions = its reports = both workers
+    const subs = subscriptionsOf('mgr');
+    assert.deepEqual(subs.map((s) => s.node_id).sort(), ['w1', 'w2']);
+    assert.equal(subs.find((s) => s.node_id === 'w1')?.active, true);
+    assert.equal(subs.find((s) => s.node_id === 'w2')?.active, false);
+});
+test('subscribe is idempotent and flips active', () => {
+    createNode(node('a'));
+    createNode(node('b'));
+    subscribe('a', 'b', true);
+    subscribe('a', 'b', false); // re-subscribe updates the flag, no dup
+    const subs = subscriptionsOf('a');
+    assert.equal(subs.length, 1);
+    assert.equal(subs[0].active, false);
+    setSubscriptionActive('a', 'b', true);
+    assert.equal(subscriptionsOf('a')[0].active, true);
+    unsubscribe('a', 'b');
+    assert.equal(subscriptionsOf('a').length, 0);
+});
+test('view = transitive closure down the subscription spine', () => {
+    // root → mid → leaf, plus root → sib
+    for (const id of ['root', 'mid', 'leaf', 'sib'])
+        createNode(node(id));
+    subscribe('root', 'mid');
+    subscribe('root', 'sib');
+    subscribe('mid', 'leaf');
+    assert.deepEqual(view('root').sort(), ['leaf', 'mid', 'sib']);
+    assert.deepEqual(view('mid'), ['leaf']);
+});
+test('view is cycle-safe', () => {
+    createNode(node('a'));
+    createNode(node('b'));
+    subscribe('a', 'b');
+    subscribe('b', 'a');
+    assert.deepEqual(view('a'), ['b']);
+});
+test('hasActiveLiveSubscription: the stop-guard primitive', () => {
+    createNode(node('mgr'));
+    createNode(node('child', { status: 'active' }));
+    // no subscription yet
+    assert.equal(hasActiveLiveSubscription('mgr'), false);
+    subscribe('mgr', 'child', true);
+    assert.equal(hasActiveLiveSubscription('mgr'), true); // active sub to a live node
+    setStatus('child', 'done');
+    assert.equal(hasActiveLiveSubscription('mgr'), false); // child no longer live
+    setStatus('child', 'active');
+    setSubscriptionActive('mgr', 'child', false);
+    assert.equal(hasActiveLiveSubscription('mgr'), false); // passive sub doesn't count
+});
+test('recordSpawn writes the audit-only spawned_by edge', () => {
+    createNode(node('parent'));
+    createNode(node('child', { parent: 'parent' }));
+    recordSpawn('child', 'parent');
+    // spawned_by does not appear in the subscription spine
+    assert.equal(subscriptionsOf('child').length, 0);
+    assert.equal(subscribersOf('parent').length, 0);
+});
+// --- Durability contract: meta.json is durable and never truncated -------
+// writeMeta uses atomic rename with fsync on both the temp file and parent
+// directory to ensure atomicity and durability. readMeta/rebuildIndex tolerate
+// an empty/corrupt meta.json as MISSING (returning null) rather than throwing,
+// gracefully handling rare disk/NFS anomalies without breaking recovery.
+test('writeMeta produces a durable, non-empty, atomically-named meta.json', () => {
+    createNode(node('a'));
+    const p = nodeMetaPath('a');
+    assert.ok(statSync(p).size > 0, 'meta.json must be non-empty');
+    assert.ok(!existsSync(`${p}.tmp`), 'temp file must be renamed away, not left behind');
+    assert.equal(getNode('a')?.node_id, 'a');
+});
+test('getNode returns null (not throw) on a 0-byte meta.json', () => {
+    createNode(node('a'));
+    writeFileSync(nodeMetaPath('a'), ''); // the observed NFS 0-byte corruption
+    assert.equal(getNode('a'), null);
+});
+test('getNode returns null (not throw) on an unparseable meta.json', () => {
+    createNode(node('a'));
+    writeFileSync(nodeMetaPath('a'), '{ broken json');
+    assert.equal(getNode('a'), null);
+});
+test('rebuildIndex skips a corrupt-meta node instead of throwing', () => {
+    createNode(node('good'));
+    createNode(node('bad'));
+    writeFileSync(nodeMetaPath('bad'), ''); // 0-byte corruption on one node
+    closeDb();
+    rmSync(join(home, 'canvas.db'), { force: true });
+    rmSync(join(home, 'canvas.db-wal'), { force: true });
+    rmSync(join(home, 'canvas.db-shm'), { force: true });
+    assert.doesNotThrow(() => rebuildIndex());
+    assert.equal(getRow('good')?.node_id, 'good'); // healthy node reindexed
+    assert.equal(getRow('bad'), null); // corrupt node skipped, no crash
+});
+test('rebuildIndex reconstructs node rows from on-disk metas', () => {
+    createNode(node('a', { parent: null }));
+    createNode(node('b', { parent: 'a' }));
+    // wipe just the db, keep the node dirs
+    closeDb();
+    rmSync(join(home, 'canvas.db'), { force: true });
+    rmSync(join(home, 'canvas.db-wal'), { force: true });
+    rmSync(join(home, 'canvas.db-shm'), { force: true });
+    assert.equal(getRow('a'), null); // gone from index
+    rebuildIndex();
+    assert.equal(getRow('a')?.node_id, 'a');
+    assert.equal(getRow('b')?.parent, 'a');
+});

package/dist/core/__tests__/chat-view-reconnect.test.d.ts

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

package/dist/core/__tests__/chat-view-reconnect.test.js

@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+// @ts-ignore -- chat core is a plain built view module with no generated .d.ts.
+import core from '../../builtin-views/chat/core.mjs';
+import { openLocalStream } from '../view/stream-local.js';
+// Settle a real async open failure: the channel is returned synchronously, then
+// the terminal error/close arrive on later ticks. The no-node existence check now
+// goes through crtrd's API (an async socket round-trip), not a synchronous db
+// read, so we poll to a real settle instead of a single microtask flush.
+const settle = async (pred, timeoutMs = 5000) => {
+    const deadline = Date.now() + timeoutMs;
+    while (!pred() && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 10));
+    }
+};
+test('local invalid/no-node stream failures close asynchronously after the channel returns', async () => {
+    // 'not/valid' fails the synchronous target validation; the second is a valid but
+    // nonexistent id whose existence check resolves through the API. Both must report
+    // a clear terminal error and then close, and neither may fire before the channel
+    // is returned. The exact error KIND for the nonexistent id depends on whether
+    // crtrd answers (no-node on a 404) or is unreachable (broker-unavailable once the
+    // broker socket refuses) — the product contract is only "clear error + prompt
+    // close", so we assert generically on the error/close shape.
+    for (const target of ['not/valid', 'definitely-not-a-real-node-review-5362b32']) {
+        const events = [];
+        const channel = openLocalStream({ kind: 'stream', target, role: 'controller' }, {
+            onFrame() {
+                events.push('frame');
+            },
+            onClose(reason) {
+                events.push(`close:${reason}`);
+            },
+            onError(err) {
+                events.push(`error:${err.kind}`);
+            },
+        });
+        assert.equal(events.length, 0, `${target}: callbacks stay deferred until after openLocalStream returns`);
+        assert.equal(typeof channel.close, 'function', `${target}: channel is returned before failure callbacks fire`);
+        await settle(() => events.length >= 2);
+        assert.ok(events[0]?.startsWith('error:'), `${target}: reports the terminal open failure as an error`);
+        assert.equal(events[1]?.startsWith('close:'), true, `${target}: follows with streamClose`);
+    }
+});
+test('reconnect keeps the requested role while welcome and read_only remain authoritative', () => {
+    let current = core.init({ target: 'n1', role: 'controller' });
+    const sent = [];
+    const requestedRoles = [];
+    const closed = [];
+    const channels = [
+        { id: 'first-channel', send(frame) { sent.push(frame); }, close() { closed.push('first-channel'); } },
+        { id: 'replacement-channel', send(frame) { sent.push(frame); }, close() { closed.push('replacement-channel'); } },
+    ];
+    let nextChannel = 0;
+    const ctx = {
+        get state() {
+            return current;
+        },
+        set(next) {
+            current = typeof next === 'function' ? next(current) : next;
+        },
+        connect(_stream, opts) {
+            requestedRoles.push(opts.role);
+            return channels[nextChannel++];
+        },
+        dispatch(intent) {
+            return core.intents[intent](ctx);
+        },
+        signal: {
+            clearBanner() { },
+            setBanner() { },
+            setStatus() { },
+            setSubtitle() { },
+            setMode() { },
+            quit() { },
+        },
+    };
+    core.intents.refresh(ctx);
+    const firstChannel = current.channel;
+    assert.equal(current.desiredRole, 'controller');
+    assert.equal(current.conn, 'connecting');
+    assert.deepEqual(requestedRoles, ['controller']);
+    core.intents.streamOpen(ctx, firstChannel);
+    core.intents.streamFrame(ctx, { type: 'welcome', role: 'controller', snapshot: { state: {}, messages: [] } });
+    assert.equal(current.role, 'controller');
+    assert.equal(current.conn, 'open');
+    core.intents.reconnect(ctx);
+    assert.deepEqual(closed, ['first-channel']);
+    assert.equal(current.desiredRole, 'controller');
+    assert.equal(current.channel?.id, 'replacement-channel');
+    assert.deepEqual(requestedRoles, ['controller', 'controller']);
+    const replacementChannel = current.channel;
+    core.intents.streamOpen(ctx, replacementChannel);
+    core.intents.streamFrame(ctx, { type: 'welcome', role: 'observer', snapshot: { state: {}, messages: [] } });
+    assert.equal(current.role, 'observer', 'welcome.role is authoritative for the active connection');
+    assert.equal(current.desiredRole, 'controller', 'the requested controller role survives reconnect');
+    assert.equal(current.conn, 'open');
+    core.intents.streamClose(ctx, { channelId: 'first-channel', reason: 'closed' });
+    assert.equal(current.channel, replacementChannel, 'a stale close cannot clear the replacement channel');
+    assert.equal(current.conn, 'open');
+    core.intents.streamFrame(ctx, { type: 'error', code: 'read_only' });
+    core.intents.setDraft(ctx, 'hello');
+    core.intents.submitDraft(ctx);
+    assert.deepEqual(sent, [], 'read-only welcome state prevents writes');
+    assert.match(current.notices.at(-1).text, /read-only — sending is disabled/);
+});

package/dist/core/__tests__/child-death-wake.test.d.ts

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