@north-light/crouter 0.3.308 → 0.3.310

package/dist/commands/__tests__/node-message.test.js

@@ -58,6 +58,19 @@ test('node message send explains a positional node id without a target flag', as
         assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self.');
         return true;
     }));
+    await withFakeStdin(pipedStdin(''), () => assert.rejects(() => parseArgv(params, [nodeId, 'message body']), (error) => {
+        assert.equal(error.code, 'bad_invocation');
+        assert.equal(error.message, 'no target given — the positional argument is the message body, not a node id');
+        assert.equal(error.details?.field, 'to');
+        assert.equal(error.details?.next, 'Pass the node id with --to <node-id> and pipe the message body on stdin, or use --self.');
+        return true;
+    }));
+    await withFakeStdin(pipedStdin(''), () => assert.rejects(() => parseArgv(params, [nodeId, 'message body', '--to', 'target-node']), (error) => {
+        assert.equal(error.code, 'bad_invocation');
+        assert.equal(error.message, 'unexpected extra positional argument (value withheld: this leaf reads "body" from stdin, never argv)');
+        assert.equal(error.details?.next, 'Pipe it on stdin instead of passing it as a positional argument.');
+        return true;
+    }));
 });
 test('node message request gives the same no-target guidance', async () => {
     const request = messageLeaf('request');

package/dist/commands/canvas-history/grep.js

@@ -52,7 +52,7 @@ export const grepLeaf = defineLeaf({
                 hits: res.hits,
                 next_cursor: res.next_cursor,
                 total: res.total,
-                follow_up: 'Read a hit with `canvas history read <ref>`; narrow with `canvas history grep -h`.',
+                follow_up: 'Read a hit with `crtr canvas history read <ref>`; narrow with `crtr canvas history grep -h`.',
             };
         }
         catch (err) {

package/dist/commands/canvas-history/read.js

@@ -32,7 +32,7 @@ export const readLeaf = defineLeaf({
         if (!ref.includes(':')) {
             throw usage(`ref must be <node-id>:<relpath>; received: ${ref}`, {
                 received: ref,
-                next: 'Get a valid ref from `canvas history search` or `node inspect artifacts <node-id>`.',
+                next: 'Get a valid ref from `crtr canvas history search` or `crtr node inspect artifacts <node-id>`.',
             });
         }
         try {

package/dist/commands/canvas-history/search.js

@@ -58,7 +58,7 @@ export const searchLeaf = defineLeaf({
                 hits: res.hits,
                 next_cursor: res.next_cursor,
                 total: res.total,
-                follow_up: 'Read a hit with `canvas history read <ref>`; narrow with `canvas history search -h`.',
+                follow_up: 'Read a hit with `crtr canvas history read <ref>`; narrow with `crtr canvas history search -h`.',
             };
         }
         catch (err) {

package/dist/commands/memory/__tests__/command-selector-and-mutation-guards.test.js

@@ -189,6 +189,26 @@ test('editing the repository-root guide preserves its namespace declaration', as
     });
     assert.match(readFileSync(join(storeDir(root), 'INDEX.md'), 'utf8'), /^namespace: acme$/m);
 });
+test('memory edit preserves the supplied body bytes and accepts leading-newline removal', async () => {
+    const target = join(storeDir(root), 'foo.md');
+    const withLeadingNewline = '\nBODY WITH CALLER BLANK';
+    await editLeaf.run({
+        name: 'acme/foo',
+        dir: root,
+        rationale: 'regression: a leading blank line must remain exactly as supplied',
+        body: withLeadingNewline,
+    });
+    assert.ok(readFileSync(target, 'utf8').endsWith(`\n---\n${withLeadingNewline}`));
+    const withoutLeadingNewline = 'BODY WITH CALLER BLANK';
+    const result = (await editLeaf.run({
+        name: 'acme/foo',
+        dir: root,
+        rationale: 'regression: removing a supplied leading blank line must be an edit',
+        body: withoutLeadingNewline,
+    }));
+    assert.deepEqual(result.changed, ['body']);
+    assert.ok(readFileSync(target, 'utf8').endsWith(`\n---\n${withoutLeadingNewline}`));
+});
 test('move and delete recover same-store collisions by stable physical path, while edit and origin refuse', async () => {
     const collisionLeaf = join(storeDir(root), 'collision.md');
     const collisionIndex = join(storeDir(root), 'collision', 'INDEX.md');

package/dist/commands/memory/edit.js

@@ -184,16 +184,13 @@ export const editLeaf = defineLeaf({
             surfacesVal.some((e) => e !== null && typeof e === 'object' && e['on'] === 'workspace-open')) {
             throw usage('a workspace-open surfaces entry is a project-store mount route; user, profile, and node memory cannot carry one — drop the entry');
         }
-        // LITERAL SAVE: the piped bytes reach disk untransformed, one structural
-        // blank line after the fence. Omitting stdin re-emits the existing body
-        // sliced from the raw file — never the parser's body, which drops leading
-        // blank lines and indentation.
+        // LITERAL SAVE: a supplied body reaches disk unchanged; omitting stdin
+        // preserves the raw body after the fence, including leading whitespace.
         const existingBody = literalBodySegment(before);
-        const bodySegment = stdinBody === '' ? existingBody : `\n${stdinBody}`;
-        // The no-op check compares against the document as it would serialize
-        // WITHOUT a fresh timestamp — `last-updated` changes on every edit, so
-        // stamping first would make every no-op look like a change.
-        const candidate = serializeMemoryDocLiteral(frontmatter, bodySegment);
+        const body = stdinBody === '' ? existingBody : stdinBody;
+        // The no-op check compares the exact bytes that would be written, without
+        // a fresh timestamp — `last-updated` changes on every edit.
+        const candidate = serializeMemoryDocLiteral(frontmatter, body);
         if (candidate === before) {
             throw usage(`edit changed nothing \u2014 ${doc.name} already says exactly this, so there is nothing to record`, {
                 memory: doc.name,
@@ -201,7 +198,7 @@ export const editLeaf = defineLeaf({
             });
         }
         frontmatter['last-updated'] = new Date().toISOString();
-        const after = serializeMemoryDocLiteral(frontmatter, bodySegment);
+        const after = serializeMemoryDocLiteral(frontmatter, body);
         writeText(doc.path, after);
         const logPath = historyLogPathFor(doc.root, doc.path);
         appendHistoryRecord(logPath, buildHistoryRecord({ op: 'edit', rationale, ...(verbatim ? { verbatim: true } : {}), before, after }));
@@ -209,7 +206,7 @@ export const editLeaf = defineLeaf({
             .filter((key) => key !== 'last-updated')
             .filter((key) => JSON.stringify(previous[key]) !== JSON.stringify(frontmatter[key]))
             .sort((a, b) => a.localeCompare(b));
-        const changed = [...(bodySegment !== existingBody ? ['body'] : []), ...changedFields];
+        const changed = [...(body !== existingBody ? ['body'] : []), ...changedFields];
         return {
             name: doc.name,
             kind: String(frontmatter['kind'] ?? ''),

package/dist/commands/node-inspect-artifacts.js

@@ -69,7 +69,7 @@ export const nodeArtifactsLeaf = defineLeaf({
             arts = list.artifacts;
         }
         catch (err) {
-            rethrowAsCliError(err, 'List nodes with `crtr node inspect list`, or find one with `canvas history search`.');
+            rethrowAsCliError(err, 'List nodes with `crtr node inspect list`, or find one with `crtr canvas history search`.');
         }
         const ms = (ts) => Date.parse(ts) || 0;
         arts.sort((a, b) => (sort === 'oldest' ? ms(a.ts) - ms(b.ts) : ms(b.ts) - ms(a.ts)) || a.ref.localeCompare(b.ref));
@@ -85,7 +85,7 @@ export const nodeArtifactsLeaf = defineLeaf({
         return {
             node: `${name} (${nodeId})`,
             artifacts,
-            follow_up: 'Read one with `canvas history read <ref>`; reopen the node with `node lifecycle revive ' + nodeId + '`.',
+            follow_up: 'Read one with `crtr canvas history read <ref>`; reopen the node with `crtr node lifecycle revive ' + nodeId + '`.',
         };
     },
     render: (r) => {

package/dist/commands/push.js

@@ -258,7 +258,7 @@ export function registerPush() {
         help: {
             name: 'push',
             summary: 'push a report to your subscribers',
-            model: "A push writes a markdown report to the node's reports/ history and fans a lightweight pointer to every subscriber's inbox. Delivery inlines reports under 1,000 characters with their absolute path; larger reports remain pointers to dereference. Nothing is pushed automatically — the feed contains only what a node pushes explicitly, so push whenever you want a manager to see something. Pipe markdown via a single-quoted heredoc so it reaches the report literally. `push final` is how ANY node finishes: write the canonical result, mark done, close the window.",
+            model: "A push writes a markdown report to the node's reports/ history and fans a lightweight pointer to every subscriber's inbox. Delivery inlines reports under 1,000 characters; each report ref is read with `crtr canvas history read <ref>`. Nothing is pushed automatically — the feed contains only what a node pushes explicitly, so push whenever you want a manager to see something. Pipe markdown via a single-quoted heredoc so it reaches the report literally. `push final` is how ANY node finishes: write the canonical result, mark done, close the window.",
         },
         children: [makePushLeaf('update'), makePushLeaf('final'), makeResultLeaf()],
     });

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

@@ -114,7 +114,7 @@ test('coalesce renders one inbox card whose entries inline short report bodies a
     assert.equal(card.senders[0].id, 'child');
     // The label is NOT reprinted above the body it duplicates.
     assert.deepEqual(card.senders[0].entries, [
-        { kind: 'update', disposition: 'report', body: 'short report body', ref: 'child:reports/short-update.md' },
+        { kind: 'update', disposition: 'report', body: 'short report body\n\nRead this report with `crtr canvas history read child:reports/short-update.md`.', ref: 'child:reports/short-update.md' },
     ]);
     assert.equal(reportPath.endsWith('short-update.md'), true);
     // A report too large to inline (here: absent) keeps its label and its ref.
@@ -125,7 +125,7 @@ test('coalesce renders one inbox card whose entries inline short report bodies a
         ])),
     });
     assert.deepEqual(canonical.senders[0].entries, [
-        { kind: 'final', disposition: 'report', body: 'done', ref: 'child:reports/final.md' },
+        { kind: 'final', disposition: 'report', body: 'done\n\nRead this report with `crtr canvas history read child:reports/final.md`.', ref: 'child:reports/final.md' },
     ]);
     assert.equal(canonical.senders[0].finished, true);
     const spilled = parseCard({
@@ -135,7 +135,7 @@ test('coalesce renders one inbox card whose entries inline short report bodies a
         ])),
     });
     assert.deepEqual(spilled.senders[0].entries, [
-        { kind: 'message', disposition: 'report', body: 'long body', ref: '/tmp/message.md' },
+        { kind: 'message', disposition: 'report', body: 'long body\n\nPreview only. Read the full body from file `/tmp/message.md`.', ref: '/tmp/message.md' },
     ]);
     closeDb();
 });

package/dist/core/__tests__/human-deliver.test.js

@@ -164,7 +164,7 @@ describe('terminal ticket delivery', () => {
         const card = parseCard({ role: 'user', content: deliveries[0].text });
         assert.ok(card);
         const answer = card.senders.flatMap((sender) => sender.entries).find((entry) => entry.disposition === 'human-answer');
-        assert.deepEqual(answer, { kind: 'final', disposition: 'human-answer', body: 'yes, ship', ref: final.ref });
+        assert.deepEqual(answer, { kind: 'final', disposition: 'human-answer', body: `yes, ship\n\nRead this report with \`crtr canvas history read ${final.ref}\`.`, ref: final.ref });
     });
     test('a replay against a terminal bridge is a no-op', async () => {
         const { parent, bridge } = bridgeUnder();

package/dist/core/__tests__/integration/broker-wedge-supervision.test.d.ts

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

package/dist/core/__tests__/integration/broker-wedge-supervision.test.js

@@ -0,0 +1,102 @@
+// Run with: npm run test:integration
+//
+// Regression coverage for #938/#1081. The busy marker survives an interrupted
+// turn for recovery, but supervision must only treat a marker written after the
+// current broker launch as that broker's progress clock. The daemon also must
+// revalidate that clock after asynchronous ps sampling and report a failed
+// SIGTERM honestly.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, utimesSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHeadlessHarness } from '../helpers/harness.js';
+import { getRow, recordLaunch, recordPid, subscribe } from '../../canvas/canvas.js';
+import { jobDir } from '../../canvas/paths.js';
+import { markBusy } from '../../runtime/busy.js';
+import { BrokerSupervisionReconciler, WEDGE_QUIET_MS } from '../../../daemon/reconcilers/broker-supervision.js';
+const T0 = 20_000_000;
+function setBusyAt(id, at) {
+    markBusy(id);
+    utimesSync(join(jobDir(id), 'busy'), at / 1_000, at / 1_000);
+}
+function context(h, id) {
+    return {
+        rows: [getRow(id)],
+        fleet: h.fleet,
+        lifecycle: { acceptsDetachedWork: () => false, registerDetached: () => { } },
+    };
+}
+test('wedge supervision discards a busy marker refreshed while ps sampling', async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-wedge-sample' });
+    try {
+        const id = h.fabricateBrokerNode({ status: 'active', pi_session_id: 'wedge-sample' });
+        recordLaunch(id, new Date(T0 - WEDGE_QUIET_MS - 1).toISOString());
+        recordPid(id, process.pid);
+        h.fleet.register(id, { pid: process.pid, exited: new Promise(() => { }) });
+        setBusyAt(id, T0 - WEDGE_QUIET_MS);
+        let finishSample;
+        const sampled = new Promise((resolve) => { finishSample = resolve; });
+        const signals = [];
+        const supervisor = new BrokerSupervisionReconciler({
+            readTreeSample: async () => sampled,
+            signal: (_pid, signal) => { signals.push(signal); },
+        });
+        const running = supervisor.run(T0, context(h, id));
+        setBusyAt(id, T0 - 1);
+        finishSample({ cpuPercent: 0, hasDescendants: false });
+        await running;
+        assert.deepEqual(signals, [], 'a marker updated while ps ran cannot produce a wedge SIGTERM');
+    }
+    finally {
+        await h.dispose();
+    }
+});
+test('wedge supervision does not attribute a predecessor busy marker to a new broker', async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-wedge-predecessor' });
+    try {
+        const id = h.fabricateBrokerNode({ status: 'active', pi_session_id: 'wedge-predecessor' });
+        setBusyAt(id, T0 - WEDGE_QUIET_MS - 1);
+        recordLaunch(id, new Date(T0).toISOString());
+        recordPid(id, process.pid);
+        h.fleet.register(id, { pid: process.pid, exited: new Promise(() => { }) });
+        let samples = 0;
+        const supervisor = new BrokerSupervisionReconciler({
+            readTreeSample: async () => {
+                samples += 1;
+                return { cpuPercent: 0, hasDescendants: false };
+            },
+            signal: () => { throw new Error('a predecessor marker must not reach the signal path'); },
+        });
+        await supervisor.run(T0, context(h, id));
+        assert.equal(samples, 0, 'the old marker is not a progress observation for the new broker');
+    }
+    finally {
+        await h.dispose();
+    }
+});
+test('wedge supervision reports a throwing SIGTERM as an attempted, failed kick', async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-wedge-signal' });
+    try {
+        const parent = h.fabricateBrokerNode({ status: 'active' });
+        const id = h.fabricateBrokerNode({ status: 'active', pi_session_id: 'wedge-signal' });
+        subscribe(parent, id);
+        recordLaunch(id, new Date(T0 - WEDGE_QUIET_MS - 1).toISOString());
+        recordPid(id, process.pid);
+        h.fleet.register(id, { pid: process.pid, exited: new Promise(() => { }) });
+        setBusyAt(id, T0 - WEDGE_QUIET_MS);
+        const supervisor = new BrokerSupervisionReconciler({
+            readTreeSample: async () => ({ cpuPercent: 0, hasDescendants: false }),
+            signal: () => { throw new Error('EPERM'); },
+        });
+        await supervisor.run(T0, context(h, id));
+        const notice = h.inbox(parent).at(-1);
+        assert.match(notice.label, /attempted SIGTERM to the broker, but the signal call failed/);
+        assert.equal(notice.data?.['kick_attempted'], true);
+        assert.equal(notice.data?.['kicked'], false);
+        const events = readFileSync(join(h.home, 'crtrd.log'), 'utf8');
+        assert.match(events, /broker\.wedge\.signal_failed/);
+    }
+    finally {
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/integration/refresh-stall-recycle.test.js

@@ -21,10 +21,14 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawn } from 'node:child_process';
+import { utimesSync } from 'node:fs';
+import { join } from 'node:path';
 import { createHeadlessHarness } from '../helpers/harness.js';
-import { recordPid } from '../../canvas/canvas.js';
+import { getRow, recordLaunch, recordPid } from '../../canvas/canvas.js';
+import { jobDir } from '../../canvas/paths.js';
 import { isPidAlive } from '../../canvas/pid.js';
-import { yieldStallVerdict, YIELD_STALL_GRACE_MS } from '../../../daemon/reconcilers/broker-supervision.js';
+import { markBusy } from '../../runtime/busy.js';
+import { BrokerSupervisionReconciler, yieldStallVerdict, YIELD_STALL_GRACE_MS } from '../../../daemon/reconcilers/broker-supervision.js';
 // D4a — the pure refresh-stall truth table.
 test('D4a yieldStallVerdict: kill ONLY a live, not-busy, refresh engine past the grace', () => {
     const G = YIELD_STALL_GRACE_MS;
@@ -36,6 +40,7 @@ test('D4a yieldStallVerdict: kill ONLY a live, not-busy, refresh engine past the
 // D4b — daemon integration: a stuck refresh on a LIVE engine is force-recycled.
 const T0 = 7_000_000;
 const T_KILL = T0 + YIELD_STALL_GRACE_MS + 1; // one ms past the grace from t0
+const KILL_ESCALATE_MS = 20_000;
 test('D4b daemon force-recycles a stuck refresh: a live, not-busy refresh engine past the grace is SIGTERM\'d', { timeout: 30_000 }, async () => {
     const h = await createHeadlessHarness({ sessionPrefix: 'crtr-d4b' });
     // A real live subprocess standing in for the hung/stale-hook engine. `sleep`
@@ -86,3 +91,64 @@ test('D4b daemon force-recycles a stuck refresh: a live, not-busy refresh engine
         await h.dispose();
     }
 });
+test('D4c yield escalation is scoped to the broker that received SIGTERM', { timeout: 30_000 }, async () => {
+    const h = await createHeadlessHarness({ sessionPrefix: 'crtr-d4c' });
+    const original = spawn('sleep', ['300'], { stdio: 'ignore' });
+    let replacement;
+    try {
+        const id = h.fabricateBrokerNode({
+            kind: 'developer',
+            status: 'active',
+            intent: 'refresh',
+            pi_pid: original.pid,
+            pi_session_id: 'sess-d4c',
+        });
+        recordLaunch(id, new Date(T0).toISOString());
+        recordPid(id, original.pid);
+        h.fleet.register(id, { pid: original.pid, exited: new Promise(() => { }) });
+        const supervisor = new BrokerSupervisionReconciler();
+        const context = () => ({
+            rows: [getRow(id)],
+            fleet: h.fleet,
+            lifecycle: { acceptsDetachedWork: () => false, registerDetached: () => { } },
+        });
+        await supervisor.run(T0, context());
+        await supervisor.run(T_KILL, context());
+        await h.waitFor(() => (isPidAlive(original.pid) ? null : true), {
+            label: 'original refresh broker received SIGTERM',
+            timeoutMs: 10_000,
+        });
+        h.fleet.forget(id);
+        markBusy(id); // interrupted predecessor witness must not block the replacement's refresh timer
+        utimesSync(join(jobDir(id), 'busy'), T_KILL / 1_000, T_KILL / 1_000);
+        replacement = spawn(process.execPath, ['-e', 'process.on("SIGTERM", () => {}); console.log("ready"); setInterval(() => {}, 1000)'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        await new Promise((resolve, reject) => {
+            replacement.stdout.once('data', () => resolve());
+            replacement.once('error', reject);
+        });
+        recordLaunch(id, new Date(T_KILL + 1).toISOString());
+        recordPid(id, replacement.pid);
+        h.fleet.register(id, { pid: replacement.pid, exited: new Promise(() => { }) });
+        const replacementStarted = T_KILL + KILL_ESCALATE_MS + 1;
+        await supervisor.run(replacementStarted, context());
+        assert.equal(isPidAlive(replacement.pid), true, 'the old SIGKILL deadline does not target the replacement');
+        await supervisor.run(replacementStarted + YIELD_STALL_GRACE_MS + 1, context());
+        assert.equal(isPidAlive(replacement.pid), true, 'the replacement survives its own SIGTERM when still stalled');
+        await supervisor.run(replacementStarted + YIELD_STALL_GRACE_MS + KILL_ESCALATE_MS + 1, context());
+        await h.waitFor(() => (isPidAlive(replacement.pid) ? null : true), {
+            label: 'replacement refresh broker received its own SIGKILL',
+            timeoutMs: 10_000,
+        });
+    }
+    finally {
+        for (const child of [original, replacement]) {
+            if (child?.pid === undefined)
+                continue;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* already gone */ }
+        }
+        await h.dispose();
+    }
+});

package/dist/core/__tests__/integration/worktree-reap.test.js

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import { gitSync } from '../../git.js';
 import { withExclusiveDirectoryLockAsync } from '../../exclusive-lock.js';
 import { createManagedWorktree, closeManagedWorktree, worktreeLockPathForCommonDir } from '../../worktree.js';
+import { abandonManagedWorktreeAsync } from '../../worktree-mutation-async.js';
 import { reconcileManagedWorktree } from '../../worktree-sweep.js';
 import { createApiServer } from '../../../daemon/api/server.js';
 import { ManagedWorktreeSweepReconciler } from '../../../daemon/reconcilers/managed-worktree-sweep.js';
@@ -476,6 +477,36 @@ test('async close yields while an async repository holder runs, keeping API requ
         await server.close();
     }
 });
+test('async abandon retains clean committed work after its base branch is deleted without a remote (#929)', async () => {
+    const repo = mkdtempSync(join(tmpdir(), 'crtr-worktree-929-'));
+    try {
+        run(['init', '-b', 'main'], repo);
+        run(['config', 'user.email', 'test@example.com'], repo);
+        run(['config', 'user.name', 'Test'], repo);
+        writeFileSync(join(repo, 'README.md'), 'hello\n');
+        run(['add', '.'], repo);
+        run(['commit', '-m', 'init'], repo);
+        const nodeId = 'wt-abandon-missing-base';
+        const wt = createManagedWorktree(repo, nodeId);
+        createNode(node(nodeId, { cwd: wt.path, status: 'done', managed_worktree: wt }));
+        writeFileSync(join(wt.path, 'committed.txt'), 'committed work\n');
+        run(['add', 'committed.txt'], wt.path);
+        run(['commit', '-m', 'real work'], wt.path);
+        const tipSha = gitSync(['rev-parse', 'HEAD'], wt.path).stdout.trim();
+        assert.equal(gitSync(['remote'], repo).stdout.trim(), '', 'the repository has no remote that could prove delivery');
+        run(['checkout', '--detach'], repo);
+        run(['branch', '-D', 'main'], repo);
+        const result = await abandonManagedWorktreeAsync(nodeId, 'test-invoker');
+        assert.equal(result.branch_deleted, false, 'without containment proof the committed branch must be retained');
+        assert.equal(result.tip_sha, tipSha, 'abandon must retain the exact committed tip');
+        assert.equal(existsSync(wt.path), false, 'abandon removes only the checkout');
+        assert.equal(gitSync(['rev-parse', wt.branch], repo).stdout.trim(), tipSha, 'the retained branch still reaches the committed work');
+        assert.equal(getNode(nodeId)?.managed_worktree?.state, 'abandoned', 'the node records the abandoned disposition');
+    }
+    finally {
+        rmSync(repo, { recursive: true, force: true });
+    }
+});
 test('abandon preserves committed and dirty work, records its retained tip, and releases finalization', async () => {
     const nodeId = 'wt-abandon';
     const wt = createManagedWorktree(sourceDir, nodeId);

package/dist/core/__tests__/seam/inbox-reference-guidance.test.d.ts

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

package/dist/core/__tests__/seam/inbox-reference-guidance.test.js

@@ -0,0 +1,70 @@
+// Run with: npm run build && node --test --test-timeout=180000 dist/core/__tests__/seam/inbox-reference-guidance.test.js
+//
+// Pins the delivered inbox text from the compiled runtime: report handles name
+// the history reader, spilled messages name their exact recipient-side file,
+// and bearings reserve context for agent-authored shared documents.
+import { after, before, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { subscribe } from '../../canvas/index.js';
+import { resolveRef } from '../../canvas/history.js';
+import { appendInbox, coalesce, readInboxSince } from '../../feed/inbox.js';
+import { pushUpdate } from '../../feed/feed.js';
+import { contextDirNote } from '../../runtime/bearings-render.js';
+import { coalesceBrokerInbox } from '../../runtime/broker/inbox.js';
+import { createHeadlessHarness } from '../helpers/harness.js';
+let h;
+let root;
+let recipient;
+before(async () => {
+    h = await createHeadlessHarness({ sessionPrefix: 'crtr-inbox-reference-guidance' });
+    root = h.spawnRoot('inbox reference guidance seam root');
+    recipient = h.fabricateBrokerNode({ id: 'inbox-reference-recipient', parent: root, status: 'idle' });
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+function onlyCard(entries) {
+    const deliveries = coalesce(entries);
+    assert.equal(deliveries.length, 1, 'one non-human inbox entry produces one card');
+    assert.equal(deliveries[0].kind, 'card');
+    return deliveries[0].text;
+}
+test('delivered report and message refs name the exact way to read their bodies', async () => {
+    const publisher = h.fabricateBrokerNode({ id: 'inbox-reference-publisher', parent: root, status: 'idle' });
+    subscribe(recipient, publisher, true);
+    const reportBody = 'published report body';
+    await pushUpdate(publisher, reportBody);
+    const reportEntry = readInboxSince(recipient).at(-1);
+    assert.equal(reportEntry.ref?.startsWith(`${publisher}:reports/`), true, 'delivery carries the canonical report handle');
+    const reportRef = reportEntry.ref;
+    const reportCard = onlyCard([reportEntry]);
+    const brokerReportCard = coalesceBrokerInbox([reportEntry], new Map())[0].text;
+    for (const card of [reportCard, brokerReportCard]) {
+        assert.ok(card.includes(`crtr canvas history read ${reportRef}`), 'delivery names the exact command for its handle');
+    }
+    assert.equal(resolveRef(reportRef)?.body, reportBody, 'the exact delivered handle resolves to the freshly published report');
+    for (const body of [
+        'a'.repeat(1001),
+        Array.from({ length: 13 }, (_, i) => `line ${i + 1}`).join('\n'),
+    ]) {
+        const message = appendInbox(recipient, {
+            from: publisher,
+            tier: 'normal',
+            kind: 'message',
+            label: 'long message',
+            data: { body },
+        });
+        assert.ok(message.ref?.startsWith('/'), 'a clipped message stores its full body at an absolute recipient path');
+        const messageCard = onlyCard([message]);
+        const brokerMessageCard = coalesceBrokerInbox([message], new Map())[0].text;
+        for (const card of [messageCard, brokerMessageCard]) {
+            assert.ok(card.includes(`Preview only. Read the full body from file \`${message.ref}\`.`), 'the preview names the exact full-body path');
+        }
+        assert.equal(readFileSync(message.ref, 'utf8'), body, 'the exact delivered path holds the complete message');
+    }
+    const bearings = contextDirNote(recipient);
+    assert.match(bearings, /where you write documents to share with other nodes on the canvas/);
+    assert.doesNotMatch(bearings, /one place the other nodes on the canvas can read from/);
+});

package/dist/core/canvas/__tests__/session-window.test.d.ts

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

package/dist/core/canvas/__tests__/session-window.test.js

@@ -0,0 +1,70 @@
+// session-window.test.ts — the preview readers see the ends of a huge session
+// without slurping the middle.
+//
+// A pi session file grows without bound (67 MB on a real canvas), and reading one
+// whole to show a few turns is what stalled the browse preview panel. The readers
+// now take a head and a tail window, which introduces the one thing worth pinning:
+// each cut lands in the MIDDLE of a jsonl record, so the fragment on the inside
+// edge must be dropped rather than parsed. Get that wrong and the newest turn
+// silently disappears — a rendering bug that looks like a node with no history.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readSessionParts, readTranscript } from '../render-source.js';
+/** One pi-shaped jsonl message record. */
+function rec(role, text) {
+    return JSON.stringify({ type: 'message', message: { role, content: [{ type: 'text', text }] } });
+}
+/** A session whose bulk sits between the first and last turns, big enough that the
+ *  4 MiB transcript tail and 1 MiB parts head cannot both reach the same records. */
+function hugeSession(dir) {
+    const filler = rec('assistant', 'x'.repeat(64 * 1024));
+    const lines = [rec('user', 'FIRST-PROMPT')];
+    for (let i = 0; i < 120; i++)
+        lines.push(filler);
+    lines.push(rec('user', 'LAST-PROMPT'), rec('assistant', 'LAST-REPLY'));
+    const file = join(dir, 'huge.jsonl');
+    writeFileSync(file, `${lines.join('\n')}\n`);
+    return file;
+}
+test('a small session reads exactly as it did before windowing', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'session-window-'));
+    try {
+        const file = join(dir, 'small.jsonl');
+        writeFileSync(file, `${[rec('user', 'hello'), rec('assistant', 'hi there')].join('\n')}\n`);
+        const parts = readSessionParts(file);
+        assert.equal(parts.prompts, 'hello');
+        assert.equal(parts.lastAssistant, 'hi there');
+        assert.deepEqual(readTranscript(file).map((t) => t.text), ['hello', 'hi there']);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a huge session still yields its newest turns', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'session-window-'));
+    try {
+        const file = hugeSession(dir);
+        // The tail window lands mid-record; the newest turns must survive it intact.
+        const turns = readTranscript(file);
+        assert.equal(turns.at(-1)?.text, 'LAST-REPLY');
+        assert.equal(turns.at(-2)?.text, 'LAST-PROMPT');
+        // Nothing partial got through: every turn is a whole record's text.
+        for (const t of turns)
+            assert.ok(t.text.length > 0);
+        const parts = readSessionParts(file);
+        assert.ok(parts.prompts?.includes('FIRST-PROMPT'), 'head window keeps the opening prompt');
+        assert.equal(parts.lastAssistant, 'LAST-REPLY');
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a missing session file is empty, not a throw', () => {
+    assert.deepEqual(readSessionParts(join(tmpdir(), 'nope-does-not-exist.jsonl')), {});
+    assert.deepEqual(readTranscript(join(tmpdir(), 'nope-does-not-exist.jsonl')), []);
+    assert.deepEqual(readSessionParts(null), {});
+    assert.deepEqual(readTranscript(undefined), []);
+});