@north-light/crouter 0.3.154

package/dist/core/__tests__/inline-memory-refs.test.js

@@ -0,0 +1,320 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/inline-memory-refs.test.ts
+//
+// Load-bearing shared-contract regression for the inline memory-reference
+// token grammar (spec §4.1): `src/core/memory/inline-ref-grammar.ts` is the
+// SINGLE implementation the broker, terminal attach viewer, and web composer
+// all consume. This file (Wave C1) covers the grammar/caret/browser-barrel
+// cases. Wave C4 extends it (below, in its own `describe`) with the
+// corpus/inventory/guidance cases: `buildRefInventory`'s precedence dedup,
+// both-kinds/gated/slash:false referenceability, INDEX naming, and
+// metadata-only output, plus `buildGuidance`'s exact-match resolution,
+// duplicate collapse, and first-appearance ordering.
+import { test, describe, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findRefTokens, formatRefToken, findRefTokenAtCaret, } from '../memory/inline-ref-grammar.js';
+import { resetScopeCache } from '../scope.js';
+import { clearSessionCache } from '../substrate/session-cache.js';
+import { memoryDir as nodeMemoryDir } from '../runtime/memory.js';
+import { buildRefInventory } from '../memory/inline-ref-inventory.js';
+import { buildGuidance } from '../memory/inline-ref-guidance.js';
+// One compact case table drives `findRefTokens` over the spec §4.1 + §5
+// examples: candidate decoding, punctuation trimming, first-segment-only
+// stops, and ASCII whitespace-boundary rejection.
+const GRAMMAR_CASES = [
+    { text: '/dev', expect: [{ raw: '/dev', candidate: 'dev' }] },
+    { text: 'read /dev before starting', expect: [{ raw: '/dev', candidate: 'dev' }] },
+    { text: '/taste:foo', expect: [{ raw: '/taste:foo', candidate: 'taste/foo' }] },
+    { text: '/a:b:c', expect: [{ raw: '/a:b:c', candidate: 'a/b/c' }] },
+    // Trailing punctuation is excluded (never even captured, since it is
+    // outside the [A-Za-z0-9_:-] class).
+    { text: 'read /dev. before starting', expect: [{ raw: '/dev', candidate: 'dev' }] },
+    { text: 'see /taste:foo)', expect: [{ raw: '/taste:foo', candidate: 'taste/foo' }] },
+    { text: '/dev,', expect: [{ raw: '/dev', candidate: 'dev' }] },
+    // Trailing `:` `-` `_` inside the captured run ARE trimmed (step 3).
+    { text: '/dev:', expect: [{ raw: '/dev', candidate: 'dev' }] },
+    { text: '/dev-', expect: [{ raw: '/dev', candidate: 'dev' }] },
+    { text: '/dev_', expect: [{ raw: '/dev', candidate: 'dev' }] },
+    { text: '/dev__--::', expect: [{ raw: '/dev', candidate: 'dev' }] },
+    // Nothing survives the trim -> no token.
+    { text: '/___', expect: [] },
+    { text: '/:::', expect: [] },
+    // A first segment only: `/foo/bar` yields the token `/foo`; `/bar` is not
+    // at a whitespace boundary.
+    { text: '/foo/bar', expect: [{ raw: '/foo', candidate: 'foo' }] },
+    // ASCII boundary rejection: a `/` preceded by any non-whitespace character
+    // is not a token start.
+    { text: 'http://example.com', expect: [] },
+    { text: 'and/or', expect: [] },
+    { text: '/usr/local/bin', expect: [{ raw: '/usr', candidate: 'usr' }] },
+    // Case sensitivity: candidate preserves original case (no normalization).
+    { text: '/Dev', expect: [{ raw: '/Dev', candidate: 'Dev' }] },
+    { text: '/dev /Dev', expect: [{ raw: '/dev', candidate: 'dev' }, { raw: '/Dev', candidate: 'Dev' }] },
+    // No leading text at all: start-of-input is a valid boundary.
+    { text: '/dev fix the build', expect: [{ raw: '/dev', candidate: 'dev' }] },
+    // No token characters at all after the slash.
+    { text: 'a / b', expect: [] },
+];
+test('findRefTokens: §4.1 grammar table', () => {
+    for (const { text, expect } of GRAMMAR_CASES) {
+        const tokens = findRefTokens(text);
+        assert.deepEqual(tokens.map((t) => ({ raw: t.raw, candidate: t.candidate })), expect, `findRefTokens(${JSON.stringify(text)})`);
+        // start/end must always bound `raw` exactly.
+        for (const t of tokens) {
+            assert.equal(text.slice(t.start, t.end), t.raw, `span mismatch for ${JSON.stringify(text)}`);
+        }
+    }
+});
+test('findRefTokens: nested-decode offsets are exact', () => {
+    const text = 'see /taste:foo) now';
+    const [tok] = findRefTokens(text);
+    assert.equal(tok.start, 4);
+    assert.equal(tok.end, 14); // just past 'o' in 'foo', before ')'
+    assert.equal(text.slice(tok.start, tok.end), '/taste:foo');
+});
+test('formatRefToken: canonical name -> surface token', () => {
+    assert.equal(formatRefToken('dev'), '/dev');
+    assert.equal(formatRefToken('taste/foo'), '/taste:foo');
+    assert.equal(formatRefToken('a/b/c'), '/a:b:c');
+});
+test('formatRefToken round-trips through findRefTokens candidates', () => {
+    for (const name of ['dev', 'taste/foo', 'a/b/c', 'spec-driven-development/spec-writing']) {
+        const surface = formatRefToken(name);
+        const [tok] = findRefTokens(surface);
+        assert.equal(tok?.candidate, name, `round-trip for ${name}`);
+    }
+});
+test('findRefTokenAtCaret: incomplete prefix (no trailing name segment yet)', () => {
+    const text = '/taste:';
+    const caret = findRefTokenAtCaret(text, text.length);
+    assert.deepEqual(caret, { start: 0, end: 7, surfacePrefix: '/taste:' });
+});
+test('findRefTokenAtCaret: caret mid-token is suffix-inclusive', () => {
+    const text = 'before /dev after';
+    const idx = text.indexOf('/dev') + 2; // caret between 'd' and 'e'
+    const caret = findRefTokenAtCaret(text, idx);
+    assert.deepEqual(caret, { start: 7, end: 11, surfacePrefix: '/d' });
+    assert.equal(text.slice(caret.start, caret.end), '/dev');
+});
+test('findRefTokenAtCaret: caret just after a bare slash', () => {
+    const text = 'prose / ';
+    const caret = findRefTokenAtCaret(text, text.indexOf('/') + 1);
+    assert.deepEqual(caret, { start: 6, end: 7, surfacePrefix: '/' });
+});
+test('findRefTokenAtCaret: no token touching caret -> null', () => {
+    assert.equal(findRefTokenAtCaret('plain prose', 3), null);
+    assert.equal(findRefTokenAtCaret('and/or here', 6), null); // '/' not a token start
+    assert.equal(findRefTokenAtCaret('', 0), null);
+});
+test('findRefTokenAtCaret: caret at start of a leading token', () => {
+    const text = '/dev fix this';
+    const caret = findRefTokenAtCaret(text, 1); // right after the slash
+    assert.deepEqual(caret, { start: 0, end: 4, surfacePrefix: '/' });
+});
+test('browser barrel (src/web/index.ts) re-exports the identical grammar', async () => {
+    const barrel = await import('../../web/index.js');
+    assert.equal(barrel.findRefTokens, findRefTokens, 'must be the same function, not a mirrored copy');
+    assert.equal(barrel.formatRefToken, formatRefToken);
+    assert.equal(barrel.findRefTokenAtCaret, findRefTokenAtCaret);
+    // And it behaves identically when driven through the barrel.
+    const [tok] = barrel.findRefTokens('read /dev before starting');
+    assert.equal(tok.candidate, 'dev');
+    assert.equal(barrel.formatRefToken('taste/foo'), '/taste:foo');
+});
+// ---------------------------------------------------------------------------
+// Wave C4 — buildGuidance: pure over (text, names), no filesystem/corpus
+// involved. See the fixture-backed buildRefInventory suite below for the
+// corpus/precedence/metadata cases.
+// ---------------------------------------------------------------------------
+const GUIDANCE_HEADER = 'The human explicitly referenced these memory documents. Before acting on the portion of their message that references each document, run the corresponding command and treat its returned content as authoritative context:';
+test('buildGuidance: single resolved ref emits the exact directive header + one read line', () => {
+    const names = new Set(['dev']);
+    const result = buildGuidance('read /dev before starting', names);
+    assert.equal(result, [GUIDANCE_HEADER, '- crtr memory read dev'].join('\n'));
+});
+test('buildGuidance: nested-name candidates decode back to slash form in the read line', () => {
+    const names = new Set(['taste/foo']);
+    const result = buildGuidance('see /taste:foo) now', names);
+    assert.equal(result, [GUIDANCE_HEADER, '- crtr memory read taste/foo'].join('\n'));
+});
+test('buildGuidance: duplicate refs collapse to one instruction; distinct refs list in first-appearance order', () => {
+    const names = new Set(['dev', 'taste/foo']);
+    const result = buildGuidance('/dev do X, then /taste:foo, and /dev again', names);
+    assert.equal(result, [GUIDANCE_HEADER, '- crtr memory read dev', '- crtr memory read taste/foo'].join('\n'));
+});
+test('buildGuidance: an unresolved/unknown token produces no guidance', () => {
+    assert.equal(buildGuidance('/nope has nothing to do with it', new Set(['dev'])), null);
+});
+test('buildGuidance: text with no slash tokens at all returns null', () => {
+    assert.equal(buildGuidance('plain prose, nothing to see here', new Set(['dev'])), null);
+});
+test('buildGuidance: exact case-sensitive matching — a differently-cased token does not resolve', () => {
+    assert.equal(buildGuidance('/Dev fix this', new Set(['dev'])), null);
+});
+// ---------------------------------------------------------------------------
+// Wave C4 — buildRefInventory: the authoritative corpus builder. Fixture-
+// backed (node/project/user scope docs on disk), since precedence dedup,
+// referenceability-ignores-gate/slash, and INDEX folding are all corpus-shape
+// facts that a pure in-memory test can't exercise. Fixture names are prefixed
+// to avoid any collision with the real shipped builtin/user corpus that
+// listAllMemoryDocs() also picks up in this environment.
+// ---------------------------------------------------------------------------
+describe('buildRefInventory (fixture-backed corpus)', () => {
+    const NODE_ID = 'crtr-inline-ref-fixture-node';
+    let canvasHome;
+    let userHome;
+    let projectBase;
+    let projectRoot;
+    let prevCwd;
+    let prevCanvasHome;
+    let prevUserHome;
+    let prevNodeId;
+    function writeDoc(dir, file, frontmatter, body = 'Body.') {
+        mkdirSync(dir, { recursive: true });
+        const path = join(dir, file);
+        writeFileSync(path, `---\n${frontmatter}\n---\n${body}\n`, 'utf8');
+        return path;
+    }
+    function projectMemoryDir() {
+        return join(projectRoot, '.crouter', 'memory');
+    }
+    function userMemoryDir() {
+        return join(userHome, '.crouter', 'memory');
+    }
+    function nodeScopeMemoryDir() {
+        return nodeMemoryDir(NODE_ID);
+    }
+    before(() => {
+        prevCanvasHome = process.env['CRTR_HOME'];
+        prevUserHome = process.env['HOME'];
+        prevNodeId = process.env['CRTR_NODE_ID'];
+        prevCwd = process.cwd();
+    });
+    beforeEach(() => {
+        canvasHome = mkdtempSync(join(tmpdir(), 'crtr-inline-ref-canvas-'));
+        userHome = mkdtempSync(join(tmpdir(), 'crtr-inline-ref-user-'));
+        projectBase = mkdtempSync(join(tmpdir(), 'crtr-inline-ref-project-'));
+        projectRoot = join(projectBase, 'root');
+        mkdirSync(projectRoot, { recursive: true });
+        process.env['CRTR_HOME'] = canvasHome;
+        process.env['HOME'] = userHome;
+        process.env['CRTR_NODE_ID'] = NODE_ID;
+        process.chdir(projectRoot);
+        resetScopeCache();
+        clearSessionCache();
+    });
+    after(() => {
+        process.chdir(prevCwd);
+        resetScopeCache();
+        clearSessionCache();
+        rmSync(canvasHome, { recursive: true, force: true });
+        rmSync(userHome, { recursive: true, force: true });
+        rmSync(projectBase, { recursive: true, force: true });
+        if (prevCanvasHome === undefined)
+            delete process.env['CRTR_HOME'];
+        else
+            process.env['CRTR_HOME'] = prevCanvasHome;
+        if (prevUserHome === undefined)
+            delete process.env['HOME'];
+        else
+            process.env['HOME'] = prevUserHome;
+        if (prevNodeId === undefined)
+            delete process.env['CRTR_NODE_ID'];
+        else
+            process.env['CRTR_NODE_ID'] = prevNodeId;
+    });
+    test('nearest scope wins by canonical name: node > project > user', () => {
+        const name = 'crtr-inline-ref-fixture-shared';
+        writeDoc(userMemoryDir(), `${name}.md`, "kind: knowledge\nshort-form: 'user copy'");
+        writeDoc(projectMemoryDir(), `${name}.md`, "kind: knowledge\nshort-form: 'project copy'");
+        writeDoc(nodeScopeMemoryDir(), `${name}.md`, "kind: knowledge\nshort-form: 'node copy'");
+        let { refs, names } = buildRefInventory();
+        assert.ok(names.has(name));
+        let winner = refs.find((r) => r.name === name);
+        assert.equal(winner?.scope, 'node');
+        assert.equal(winner?.shortForm, 'node copy');
+        // Remove the node-scope copy: project now wins.
+        rmSync(join(nodeScopeMemoryDir(), `${name}.md`));
+        clearSessionCache();
+        ({ refs, names } = buildRefInventory());
+        winner = refs.find((r) => r.name === name);
+        assert.equal(winner?.scope, 'project');
+        assert.equal(winner?.shortForm, 'project copy');
+        // Remove the project-scope copy too: user is the last resort.
+        rmSync(join(projectMemoryDir(), `${name}.md`));
+        clearSessionCache();
+        ({ refs, names } = buildRefInventory());
+        winner = refs.find((r) => r.name === name);
+        assert.equal(winner?.scope, 'user');
+        assert.equal(winner?.shortForm, 'user copy');
+    });
+    test('both kinds, a gated doc, and a slash:true doc are all referenceable — no gate/rung/slash filtering', () => {
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-knowledge.md', 'kind: knowledge');
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-preference.md', 'kind: preference');
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-gated.md', 'kind: knowledge\ngate:\n  never-matches: true');
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-slash.md', 'kind: knowledge\nslash: true');
+        const { refs, names } = buildRefInventory();
+        for (const name of [
+            'crtr-inline-ref-fixture-knowledge',
+            'crtr-inline-ref-fixture-preference',
+            'crtr-inline-ref-fixture-gated',
+            'crtr-inline-ref-fixture-slash',
+        ]) {
+            assert.ok(names.has(name), `expected ${name} to be referenceable`);
+        }
+        assert.equal(refs.find((r) => r.name === 'crtr-inline-ref-fixture-knowledge')?.kind, 'knowledge');
+        assert.equal(refs.find((r) => r.name === 'crtr-inline-ref-fixture-preference')?.kind, 'preference');
+    });
+    test('an INDEX doc folds to its bare directory name, not "<dir>/INDEX"', () => {
+        writeDoc(join(projectMemoryDir(), 'crtr-inline-ref-fixture-taste'), 'INDEX.md', "kind: knowledge\nshort-form: 'taste index'");
+        const { refs, names } = buildRefInventory();
+        assert.ok(names.has('crtr-inline-ref-fixture-taste'));
+        assert.ok(!names.has('crtr-inline-ref-fixture-taste/INDEX'));
+        const winner = refs.find((r) => r.name === 'crtr-inline-ref-fixture-taste');
+        assert.equal(winner?.shortForm, 'taste index');
+    });
+    test('a root INDEX doc is omitted, never exposed as an empty ref name', () => {
+        writeDoc(projectMemoryDir(), 'INDEX.md', "kind: knowledge\nshort-form: 'project root index'");
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-sibling.md', 'kind: knowledge');
+        const { refs, names } = buildRefInventory();
+        assert.ok(!names.has(''));
+        assert.ok(!refs.some((r) => r.name === ''));
+        // A sibling doc in the same corpus is unaffected.
+        assert.ok(names.has('crtr-inline-ref-fixture-sibling'));
+    });
+    test('refs are metadata-only: exactly {name, kind, scope, shortForm}, no body/path', () => {
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-meta.md', "kind: knowledge\nshort-form: 'hook'");
+        const { refs } = buildRefInventory();
+        const ref = refs.find((r) => r.name === 'crtr-inline-ref-fixture-meta');
+        assert.ok(ref);
+        assert.deepEqual(Object.keys(ref).sort(), ['kind', 'name', 'scope', 'shortForm']);
+    });
+    test('a malformed doc (no valid kind) is omitted from the inventory', () => {
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-malformed.md', "short-form: 'no kind here'");
+        const { names } = buildRefInventory();
+        assert.ok(!names.has('crtr-inline-ref-fixture-malformed'));
+    });
+    test('duplicate distinct-scope docs still produce ONE inventory row (not one per scope)', () => {
+        const name = 'crtr-inline-ref-fixture-dedup';
+        writeDoc(userMemoryDir(), `${name}.md`, 'kind: knowledge');
+        writeDoc(projectMemoryDir(), `${name}.md`, 'kind: knowledge');
+        const { refs } = buildRefInventory();
+        assert.equal(refs.filter((r) => r.name === name).length, 1);
+    });
+    test('refs are stably sorted by winning scope precedence then name', () => {
+        writeDoc(nodeScopeMemoryDir(), 'crtr-inline-ref-fixture-b-node.md', 'kind: knowledge');
+        writeDoc(nodeScopeMemoryDir(), 'crtr-inline-ref-fixture-a-node.md', 'kind: knowledge');
+        writeDoc(projectMemoryDir(), 'crtr-inline-ref-fixture-c-project.md', 'kind: knowledge');
+        const { refs } = buildRefInventory();
+        const fixtureRefs = refs.filter((r) => r.name.startsWith('crtr-inline-ref-fixture-'));
+        const idxA = fixtureRefs.findIndex((r) => r.name === 'crtr-inline-ref-fixture-a-node');
+        const idxB = fixtureRefs.findIndex((r) => r.name === 'crtr-inline-ref-fixture-b-node');
+        const idxC = fixtureRefs.findIndex((r) => r.name === 'crtr-inline-ref-fixture-c-project');
+        // Node-scope docs (a, b) sort before the project-scope doc (c); within the
+        // same scope, alphabetically by name.
+        assert.ok(idxA < idxB, 'a-node before b-node (alphabetical within node scope)');
+        assert.ok(idxB < idxC, 'node scope before project scope');
+    });
+});

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

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

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

@@ -0,0 +1,148 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/kickoff.test.ts
+//
+// The fresh-revive kickoff split (runtime/kickoff.ts). drainBearings reads the
+// durable yield note and consumes the feed/persona acknowledgements; after it,
+// buildReviveKickoff is a PURE string assembler. session_start separately commits
+// the note handoff through clearYieldMessage.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, subscribe } from '../canvas/canvas.js';
+import { reportsDir } from '../canvas/paths.js';
+import { closeDb } from '../canvas/db.js';
+import { buildReviveKickoff, clearYieldMessage, drainBearings, readYieldMessage, writeYieldMessage, yieldMessagePath, } from '../runtime/kickoff.js';
+import { appendInbox, readCursor } from '../feed/inbox.js';
+import { appendSituationalContext } from '../runtime/situational-context.js';
+import { buildContextIntro } from '../../pi-extensions/canvas-context-intro.js';
+let home;
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-kickoff-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('drainBearings preserves the yield note until explicit boot confirmation', () => {
+    const id = 'n1';
+    const meta = createNode(node(id));
+    writeYieldMessage(id, 'on wake, finish step 3');
+    appendInbox(id, { from: 'w1', tier: 'normal', kind: 'update', label: 'first', ref: '/tmp/a.md' });
+    const last = appendInbox(id, { from: 'w1', tier: 'normal', kind: 'update', label: 'second', ref: '/tmp/b.md' });
+    const b1 = drainBearings(meta);
+    assert.equal(b1.yieldMsg?.trim(), 'on wake, finish step 3');
+    assert.ok(b1.unreadDigest !== null && b1.unreadDigest.length > 0);
+    assert.equal(existsSync(yieldMessagePath(id)), true, 'yield note remains pending before confirmation');
+    assert.equal(readYieldMessage(id), 'on wake, finish step 3', 'reader sees the same persisted note');
+    assert.equal(readCursor(id), last.entry_id, 'cursor advanced to the last unread entry');
+    const b2 = drainBearings(meta);
+    assert.equal(b2.yieldMsg, 'on wake, finish step 3', 'a failed launch can read the same note again');
+    assert.equal(b2.unreadDigest, null, 'the independently committed feed cursor remains drained');
+    clearYieldMessage(id);
+    clearYieldMessage(id);
+    assert.equal(readYieldMessage(id), null, 'confirmation clear is idempotent');
+    assert.equal(existsSync(yieldMessagePath(id)), false, 'confirmed handoff removes the note');
+});
+test('the feed block frames awaiting workers as alive + auto-waking, so a fresh revive has no reason to poll', () => {
+    const parent = createNode(node('p1'));
+    const child = createNode(node('c1')); // status 'active' by default
+    subscribe(parent.node_id, child.node_id); // parent awaits child
+    const msg = buildReviveKickoff(parent, drainBearings(parent));
+    // The roster names the live child...
+    assert.ok(msg.includes(child.node_id), 'awaiting roster lists the live child');
+    // ...and asserts aliveness + the automatic wake at the source, so the node
+    // has nothing to check, poll, or verify separately.
+    assert.ok(/alive and running/.test(msg), 'states the worker is alive and running');
+    assert.ok(/wake you the moment/.test(msg), 'states the wake is automatic on push');
+    assert.ok(/still working, not stalled/.test(msg), 'frames the empty feed as expected, not a problem');
+});
+test('a fresh revive is pointed at its subscriptions\' on-disk report history (catch-up bug)', () => {
+    // Regression for the fresh-revive catch-up bug: on a refresh-yield
+    // (resume:false) the old conversation is gone AND the inbox cursor has already
+    // advanced past everything drained pre-yield, so the revived node needs a
+    // durable catch-up breadcrumb for reports its subscriptions pushed BEFORE the
+    // yield. The bodies persist forever at reports/<ts>-<kind>.md; the kickoff
+    // surfaces a collapsed index with the newest ref and expansion commands.
+    const parent = createNode(node('p1'));
+    const worker = createNode(node('w1'));
+    subscribe(parent.node_id, worker.node_id);
+    // The worker pushed two reports BEFORE the parent's refresh-yield.
+    const dir = reportsDir(worker.node_id);
+    mkdirSync(dir, { recursive: true });
+    const older = join(dir, '20260608T120000-update.md');
+    const newer = join(dir, '20260608T130000-final.md');
+    writeFileSync(older, '---\n---\nearly progress', 'utf8');
+    writeFileSync(newer, '---\n---\nthe result', 'utf8');
+    const msg = buildReviveKickoff(parent, drainBearings(parent));
+    // The feed block stays condensed: it reports that history exists and surfaces
+    // the newest report ref for immediate dereference, while older refs stay one
+    // command away instead of being preloaded into the revive prompt.
+    const olderRef = `${worker.node_id}:reports/20260608T120000-update.md`;
+    const newerRef = `${worker.node_id}:reports/20260608T130000-final.md`;
+    assert.ok(/Report history on disk \(collapsed\): 2 reports across 1 subscribed node/.test(msg));
+    assert.ok(msg.includes(`latest final: ${newerRef}`), 'newest report ref surfaced');
+    assert.ok(!msg.includes(olderRef), 'older report ref omitted from collapsed kickoff');
+    assert.ok(!msg.includes(older), 'absolute report paths not rendered');
+    assert.ok(!msg.includes(newer), 'absolute report paths not rendered');
+    assert.ok(/canvas history read <ref>/.test(msg), 'points at one-report expansion');
+    assert.ok(/node inspect artifacts <node-id> --type report/.test(msg), 'points at full per-node expansion');
+    assert.ok(/node inspect artifacts <node-id> --type inbox/.test(msg), 'points at the cursor-independent full-history replay');
+});
+test('a fresh revive kickoff never carries situational context — it rides the hidden bearings seam instead', () => {
+    // Hiddenness regression: situational context must stay OUT of the visible
+    // fresh/cycling revive kickoff prompt. It is still delivered on this path, but
+    // hidden — canvas-context-intro's session_start handler re-fires on every
+    // fresh/cycling revive (a new pi process boot rooting a fresh branch) and
+    // re-injects buildContextIntro(), which already carries the sidecar's
+    // <situational-context> block as a sibling of <crtr-bearings> (see
+    // context-intro.test.ts for that seam's own coverage). buildReviveKickoff must
+    // never duplicate it into the visible prompt.
+    const id = 'n3';
+    const meta = createNode(node(id));
+    appendSituationalContext(id, 'user is mid-checkout on the store applet');
+    const kickoff = buildReviveKickoff(meta, drainBearings(meta));
+    assert.doesNotMatch(kickoff, /<situational-context>/, 'visible kickoff never carries the ambient block');
+    assert.doesNotMatch(kickoff, /mid-checkout on the store applet/, 'visible kickoff never carries the ambient text');
+    const hidden = buildContextIntro(id);
+    assert.match(hidden, /<situational-context>/, 'delivered instead via the hidden bearings/context-intro seam');
+    assert.match(hidden, /mid-checkout on the store applet/, 'hidden delivery carries the ambient text');
+});
+test('buildReviveKickoff is pure — building twice eats nothing', () => {
+    const id = 'n2';
+    const meta = createNode(node(id));
+    writeYieldMessage(id, 'remember the invariant');
+    const last = appendInbox(id, { from: 'w', tier: 'normal', kind: 'update', label: 'r', ref: '/tmp/r.md' });
+    // Drain once (the consuming step), then build twice off the same bearings.
+    const bearings = drainBearings(meta);
+    const cursorAfterDrain = readCursor(id);
+    assert.equal(cursorAfterDrain, last.entry_id);
+    const s1 = buildReviveKickoff(meta, bearings);
+    const s2 = buildReviveKickoff(meta, bearings);
+    // Identical output, and the build mutated nothing: cursor and note unchanged.
+    assert.equal(s1, s2);
+    assert.match(s1, /<yield-message>\nremember the invariant\n<\/yield-message>/, 'yield note is delivered inline');
+    const contextInventory = s1.match(/<context-dir path="[^"]+">[\s\S]*?<\/context-dir>/)?.[0];
+    assert.ok(contextInventory, 'context inventory is present');
+    assert.doesNotMatch(contextInventory, /yield-message\.md/, 'ephemeral yield note is not addressable from inventory');
+    assert.equal(readCursor(id), cursorAfterDrain, 'build does not touch the cursor');
+    assert.equal(readYieldMessage(id), 'remember the invariant', 'build does not mutate the persisted note');
+});

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

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

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

@@ -0,0 +1,165 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/lifecycle.test.ts
+//
+// The status×intent state machine (runtime/lifecycle.ts). Every LEGAL event
+// from every valid from-status lands the documented (status, intent), and every
+// ILLEGAL move throws — illegal states are unrepresentable. This IS the old
+// markCleanExitDone guard + the dozen scattered setStatus/setIntent pairs, now
+// table-driven. All assertions read back through getNode() (the hydrated view).
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getNode, setStatus, setIntent } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { transition } from '../runtime/lifecycle.js';
+let home;
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+/** Create a node forced into a precise (status, intent) start state. */
+function mk(id, status, intent = null) {
+    createNode(node(id));
+    setStatus(id, status);
+    setIntent(id, intent);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-lifecycle-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+const ALL = ['active', 'idle', 'done', 'dead', 'canceled'];
+const LIVE = ['active', 'idle'];
+const TERMINAL = ['done', 'dead', 'canceled'];
+// ---------------------------------------------------------------------------
+// finalize → done + intent='done', legal only from active|idle
+// ---------------------------------------------------------------------------
+test('finalize: active|idle → done + intent=done', () => {
+    for (const from of LIVE) {
+        mk(`n_${from}`, from, 'refresh');
+        const m = transition(`n_${from}`, 'finish');
+        assert.equal(m.status, 'done', `finalize from ${from}`);
+        assert.equal(m.intent, 'done', `finalize from ${from} sets intent=done`);
+    }
+});
+test('finalize: illegal from done|dead|canceled → throws, status untouched', () => {
+    for (const from of TERMINAL) {
+        mk(`n_${from}`, from);
+        assert.throws(() => transition(`n_${from}`, 'finish'), /illegal lifecycle transition/);
+        assert.equal(getNode(`n_${from}`)?.status, from, `${from} unchanged on illegal finalize`);
+    }
+});
+// ---------------------------------------------------------------------------
+// cancel → canceled + intent cleared, legal from ANY status (forced teardown).
+// A5 (human-confirmed 2026-06-06): the `reap` event was COLLAPSED into `cancel`
+// — they were identical (status differed only; both intent=null, from=ANY, no
+// side effects in transition()). Every external reap (close cascade AND
+// reset/relaunch) now routes through `cancel`; `done` is reserved for finalize.
+// ---------------------------------------------------------------------------
+test('cancel: any status → canceled + intent cleared', () => {
+    for (const from of ALL) {
+        mk(`n_${from}`, from, 'idle-release');
+        const m = transition(`n_${from}`, 'cancel');
+        assert.equal(m.status, 'canceled', `cancel from ${from}`);
+        assert.equal(m.intent, null, `cancel from ${from} clears intent`);
+    }
+});
+// ---------------------------------------------------------------------------
+// crash → dead, intent UNCHANGED, legal only from active|idle
+// ---------------------------------------------------------------------------
+test('crash: active|idle → dead, intent preserved', () => {
+    for (const from of LIVE) {
+        mk(`n_${from}`, from, 'refresh');
+        const m = transition(`n_${from}`, 'crash');
+        assert.equal(m.status, 'dead', `crash from ${from}`);
+        assert.equal(m.intent, 'refresh', `crash from ${from} leaves intent untouched`);
+    }
+});
+test('crash: illegal from done|dead|canceled → throws', () => {
+    for (const from of TERMINAL) {
+        mk(`n_${from}`, from);
+        assert.throws(() => transition(`n_${from}`, 'crash'), /illegal lifecycle transition/);
+    }
+});
+// ---------------------------------------------------------------------------
+// yield → intent='refresh', status UNCHANGED, legal only from active|idle
+// ---------------------------------------------------------------------------
+test('yield: active|idle → intent=refresh, status preserved', () => {
+    for (const from of LIVE) {
+        mk(`n_${from}`, from);
+        const m = transition(`n_${from}`, 'yield');
+        assert.equal(m.status, from, `yield from ${from} keeps status`);
+        assert.equal(m.intent, 'refresh', `yield from ${from} sets intent=refresh`);
+    }
+});
+test('yield: illegal from done|dead|canceled → throws', () => {
+    for (const from of TERMINAL) {
+        mk(`n_${from}`, from);
+        assert.throws(() => transition(`n_${from}`, 'yield'), /illegal lifecycle transition/);
+    }
+});
+// ---------------------------------------------------------------------------
+// release → idle + intent='idle-release', legal only from active|idle
+// ---------------------------------------------------------------------------
+test('release: active|idle → idle + intent=idle-release', () => {
+    for (const from of LIVE) {
+        mk(`n_${from}`, from);
+        const m = transition(`n_${from}`, 'release');
+        assert.equal(m.status, 'idle', `release from ${from}`);
+        assert.equal(m.intent, 'idle-release', `release from ${from} sets intent=idle-release`);
+    }
+});
+test('release: illegal from done|dead|canceled → throws', () => {
+    for (const from of TERMINAL) {
+        mk(`n_${from}`, from);
+        assert.throws(() => transition(`n_${from}`, 'release'), /illegal lifecycle transition/);
+    }
+});
+// ---------------------------------------------------------------------------
+// refresh-launch → active + intent=refresh, legal from ANY status. This is the
+// provisional launch transition; session_start commits through revive below.
+// ---------------------------------------------------------------------------
+test('refresh-launch: any status → active + intent=refresh', () => {
+    for (const from of ALL) {
+        mk(`n_${from}`, from, 'idle-release');
+        const m = transition(`n_${from}`, 'refresh-launch');
+        assert.equal(m.status, 'active', `refresh-launch from ${from}`);
+        assert.equal(m.intent, 'refresh', `refresh-launch from ${from} preserves refresh authority`);
+    }
+});
+// ---------------------------------------------------------------------------
+// revive → active + intent cleared, legal from ANY status (the universal "back")
+// ---------------------------------------------------------------------------
+test('revive: any status → active + intent cleared', () => {
+    for (const from of ALL) {
+        mk(`n_${from}`, from, 'idle-release');
+        const m = transition(`n_${from}`, 'revive');
+        assert.equal(m.status, 'active', `revive from ${from}`);
+        assert.equal(m.intent, null, `revive from ${from} clears intent`);
+    }
+});
+// ---------------------------------------------------------------------------
+// unknown node → throws for every event
+// ---------------------------------------------------------------------------
+test('transition on an unknown node throws', () => {
+    for (const ev of ['finish', 'cancel', 'crash', 'yield', 'release', 'refresh-launch', 'revive']) {
+        assert.throws(() => transition('ghost', ev), /unknown node/);
+    }
+});

package/dist/core/__tests__/live-lifecycle-prompt.test.d.ts

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