@crouton-kit/crouter 0.3.18 → 0.3.20

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

@@ -1,31 +1,20 @@
-// Tests for the three-tier scoped memory (src/core/runtime/memory.ts):
-//   1. The three store paths land under crtrHome (user-global / project / node).
-//   2. projectKey resolves the git-repo-root (walk up for .git), and falls back
-//      to the cwd itself when not inside a repo.
-//   3. seed* are guarded/idempotent (never clobber an evolved index).
-//   4. promote() seeds ALL THREE stores, guarded across re-promotion.
-//   5. The kernel + promotion guidance name the type\u2192store mapping.
-//
-// CRTR_HOME isolation, like context-intro.test.ts.
+// Tests for the substrate memory surface in the orchestration kernel:
+//   1. The kernel names the three memory scopes and the document substrate flow
+//      (crtr memory write/list/find/read).
+//   2. Promotion guidance names the three stores without re-listing their dirs.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/memory.test.ts
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
-import { crtrHome } from '../canvas/paths.js';
-import { mangleCwd } from '../artifact.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { promote } from '../runtime/promote.js';
 import { personaDrift } from '../runtime/persona.js';
 import { loadKernel } from '../personas/index.js';
-import { memoryDir, memoryPath, userMemoryDir, userMemoryPath, hasUserMemory, readUserMemory, seedUserMemory, projectKey, projectMemoryDir, projectMemoryPath, hasProjectMemory, readProjectMemory, seedProjectMemory, hasMemory, USER_MEMORY_TEMPLATE, PROJECT_MEMORY_TEMPLATE, } from '../runtime/memory.js';
 let home;
-// Scratch repos created per-test for the git-root keying cases; tracked so they
-// can be removed in `after` regardless of which test created them.
-const scratch = [];
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-memory-'));
     process.env['CRTR_HOME'] = home;
@@ -37,116 +26,35 @@ beforeEach(() => {
 after(() => {
     closeDb();
     rmSync(home, { recursive: true, force: true });
-    for (const d of scratch)
-        rmSync(d, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
 // ---------------------------------------------------------------------------
-// Store paths
-// ---------------------------------------------------------------------------
-test('the three stores all live under crtrHome, at their scoped paths', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    // user-global: <crtrHome>/memory/
-    assert.equal(userMemoryDir(), join(crtrHome(), 'memory'));
-    assert.equal(userMemoryPath(), join(crtrHome(), 'memory', 'MEMORY.md'));
-    // project: <crtrHome>/projects/<key>/memory/
-    assert.equal(projectMemoryDir('/tmp/work'), join(crtrHome(), 'projects', projectKey('/tmp/work'), 'memory'));
-    assert.equal(projectMemoryPath('/tmp/work'), join(projectMemoryDir('/tmp/work'), 'MEMORY.md'));
-    // node-local: <crtrHome>/nodes/<id>/context/memory/ (unchanged)
-    assert.ok(memoryDir(meta.node_id).startsWith(join(crtrHome(), 'nodes', meta.node_id)));
-    assert.ok(memoryPath(meta.node_id).endsWith('/context/memory/MEMORY.md'));
-});
-// ---------------------------------------------------------------------------
-// projectKey: git-root vs not-in-a-repo fallback
-// ---------------------------------------------------------------------------
-test('projectKey resolves the git-repo-root by walking up for a .git entry', () => {
-    const repo = mkdtempSync(join(tmpdir(), 'crtr-repo-'));
-    scratch.push(repo);
-    mkdirSync(join(repo, '.git')); // a .git directory marks the repo root
-    const nested = join(repo, 'pkg', 'src');
-    mkdirSync(nested, { recursive: true });
-    // A cwd deep inside the repo keys to the repo ROOT, not the cwd.
-    assert.equal(projectKey(nested), mangleCwd(repo));
-    assert.equal(projectKey(repo), mangleCwd(repo));
-    // A .git FILE (worktree/submodule) is recognized the same way.
-    const wt = mkdtempSync(join(tmpdir(), 'crtr-wt-'));
-    scratch.push(wt);
-    writeFileSync(join(wt, '.git'), 'gitdir: /elsewhere\n');
-    assert.equal(projectKey(join(wt, 'a')), mangleCwd(wt));
-});
-test('projectKey falls back to the mangled cwd when not inside a repo', () => {
-    const bare = mkdtempSync(join(tmpdir(), 'crtr-bare-'));
-    scratch.push(bare);
-    const sub = join(bare, 'x', 'y');
-    mkdirSync(sub, { recursive: true });
-    // No .git anywhere up the tree \u2192 the cwd itself is the key.
-    assert.equal(projectKey(sub), mangleCwd(sub));
-});
-// ---------------------------------------------------------------------------
-// seed*: guarded / idempotent
-// ---------------------------------------------------------------------------
-test('seedUserMemory / seedProjectMemory write the template once, then never clobber', () => {
-    assert.equal(hasUserMemory(), false);
-    assert.equal(seedUserMemory(), true, 'first seed writes');
-    assert.equal(readUserMemory(), USER_MEMORY_TEMPLATE);
-    assert.equal(hasUserMemory(), true);
-    const evolved = '# Memory\n\n- [Likes terse replies](terse.md) \u2014 keep it short\n';
-    writeFileSync(userMemoryPath(), evolved);
-    assert.equal(seedUserMemory(), false, 'second seed is a no-op');
-    assert.equal(readUserMemory(), evolved, 'evolved index left untouched');
-    assert.equal(seedProjectMemory('/tmp/work'), true, 'project first seed writes');
-    assert.equal(readProjectMemory('/tmp/work'), PROJECT_MEMORY_TEMPLATE);
-    assert.equal(seedProjectMemory('/tmp/work'), false, 'project second seed is a no-op');
-});
-// ---------------------------------------------------------------------------
-// promote(): seeds all three, guarded across re-promotion
-// ---------------------------------------------------------------------------
-test('promote() seeds all three stores and surfaces all three paths', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    assert.equal(hasMemory(meta.node_id), false);
-    assert.equal(hasUserMemory(), false);
-    assert.equal(hasProjectMemory('/tmp/work'), false);
-    const res = promote(meta.node_id);
-    assert.ok(hasMemory(meta.node_id), 'node-local seeded');
-    assert.ok(hasUserMemory(), 'user-global seeded');
-    assert.ok(hasProjectMemory('/tmp/work'), 'project seeded');
-    assert.ok(existsSync(userMemoryDir()), 'user dir created for direct writes');
-    assert.ok(existsSync(projectMemoryDir('/tmp/work')), 'project dir created for direct writes');
-    assert.equal(res.memoryPath, memoryPath(meta.node_id));
-    assert.equal(res.userMemoryPath, userMemoryPath());
-    assert.equal(res.projectMemoryPath, projectMemoryPath('/tmp/work'));
-});
-test('promote() is idempotent across re-promotion \u2014 never clobbers evolved stores', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    promote(meta.node_id);
-    const evolvedUser = '# Memory\n\n- [CTO, terse](cto.md) \u2014 senior, wants density\n';
-    const evolvedProject = '# Memory\n\n- [ESM only](esm.md) \u2014 .js extensions required\n';
-    writeFileSync(userMemoryPath(), evolvedUser);
-    writeFileSync(projectMemoryPath('/tmp/work'), evolvedProject);
-    promote(meta.node_id); // re-promote
-    assert.equal(readUserMemory(), evolvedUser, 'user store survived re-promotion');
-    assert.equal(readProjectMemory('/tmp/work'), evolvedProject, 'project store survived re-promotion');
-});
-// ---------------------------------------------------------------------------
-// The kernel + guidance name the type\u2192store mapping
+// Kernel + guidance: substrate flow, not MEMORY.md
 // ---------------------------------------------------------------------------
-test('the orchestration kernel names the three stores and the type\u2192store mapping', () => {
+test('the orchestration kernel names the three stores and the substrate commands', () => {
     const kernel = loadKernel();
     for (const store of ['user-global', 'project', 'node-local']) {
         assert.ok(kernel.includes(store), `kernel names the ${store} store`);
     }
-    // The type taxonomy still drives placement.
-    assert.match(kernel, /`type`/, 'kernel still frames the type taxonomy');
-    assert.match(kernel, /user.*\u2192.*user-global|`user` \u2192 user-global/, 'maps user \u2192 user-global');
-});
-test('promotion guidance names all three stores so a base-spawned node learns where to write', () => {
+    // The substrate commands must be present.
+    assert.ok(kernel.includes('crtr memory write'), 'kernel mentions crtr memory write');
+    assert.ok(kernel.includes('crtr memory list'), 'kernel mentions crtr memory list');
+    assert.ok(kernel.includes('crtr memory find'), 'kernel mentions crtr memory find');
+    assert.ok(kernel.includes('crtr memory read'), 'kernel mentions crtr memory read');
+    // The old MEMORY.md pointer-line flow must NOT be present.
+    assert.ok(!kernel.includes('MEMORY.md'), 'kernel does not mention MEMORY.md');
+    assert.ok(!kernel.includes('pointer line'), 'kernel does not teach the pointer-line flow');
+});
+test('promotion guidance references the three stores; no <memory> block', () => {
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     promote(meta.node_id);
-    // Guidance is now built by the persona injector, not returned by promote().
-    const guidance = personaDrift(meta.node_id)?.guidance ?? '';
+    const drift = personaDrift(meta.node_id);
+    assert.ok(drift !== null, 'promotion drifts the persona');
+    const guidance = drift.guidance;
+    // It NAMES the three stores so a promoting node knows its memory scopes.
     for (const store of ['user-global', 'project', 'node-local']) {
         assert.ok(guidance.includes(store), `guidance names the ${store} store`);
     }
-    assert.ok(guidance.includes(userMemoryDir()), 'guidance names the user-global dir');
-    assert.ok(guidance.includes(projectMemoryDir('/tmp/work')), 'guidance names the project dir');
+    // The old <memory> block reference must NOT be present in guidance.
+    assert.ok(!guidance.includes('<memory>'), 'guidance does not point at the removed <memory> block');
 });

package/dist/core/__tests__/placement-focus.test.js

@@ -267,6 +267,11 @@ test('detachToBackground: a FOCUSED node sent to the backstage CLOSES its focus
             createNode(node('N', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: process.pid, home_session: back }));
             openFocusRow('f1', focusPane, user, 'N'); // N is the focus occupant
             assert.equal(getFocusByNode('N')?.focus_id, 'f1', 'precondition: N is focused');
+            // N must read as GENERATING for the relocate-to-backstage path: detach now
+            // gates the break-pane (Bug 1 / Invariant P) on isGenerating = busy &&
+            // pidAlive. pi_pid is this (alive) process; set the busy marker so N is
+            // genuinely mid-turn (otherwise the gate would RELEASE + reap it instead).
+            markBusy('N');
             const ok = detachToBackground('N', focusPane);
             assert.equal(ok, true, 'the break to the backstage succeeded');
             // The fix: N is now generating-but-UNFOCUSED, so its focus row is CLOSED.

package/dist/core/__tests__/placement-teardown.test.js

@@ -5,9 +5,11 @@
 // never realized, so closePane no-ops and only the DB effects are asserted):
 //
 //   • handFocusToManager(focusId, managerId) — the §1.6 manager-takeover, a PURE
-//     DB occupant swap. Returns true (TAKEOVER) only when there is a distinct,
-//     not-already-focused manager; false (caller closes the focus) in each of the
-//     three guard cases. Each guard is asserted distinctly.
+//     DB occupant swap. Returns true (TAKEOVER) only when a successor will
+//     GENUINELY claim the frozen pane — a live manager (swapped in) or a dormant
+//     manager the daemon will revive (status='idle' && intent='idle-release').
+//     Returns false (caller disarms the freeze + closes the focus) for every
+//     other case; each guard is asserted distinctly.
 //   • tearDownNode(nodeId) — close/reset teardown: close the focus row it
 //     occupies and null its LOCATION.
 import { test, before, after, beforeEach } from 'node:test';
@@ -62,10 +64,13 @@ after(() => {
 // ---------------------------------------------------------------------------
 // handFocusToManager (pure DB) — §1.6 manager-takeover + its three false-guards.
 // ---------------------------------------------------------------------------
-test('handFocusToManager: distinct, free manager → TAKEOVER (repoints the row, returns true)', () => {
+test('handFocusToManager: dormant idle-release manager → TAKEOVER (repoints the row, returns true)', () => {
     openFocusRow('f', '%m', 'Sa', 'M');
-    createNode(node('mgr'));
-    assert.equal(handFocusToManager('f', 'mgr'), true, 'a valid manager takes the focus');
+    // The daemon's superviseTick second pass revives a node ONLY when it is idle +
+    // idle-release (crtrd.ts ~309) — that is the ONLY dormant manager that will be
+    // brought into the frozen %m, so it is the ONLY dormant takeover that returns true.
+    createNode(node('mgr', { status: 'idle', intent: 'idle-release' }));
+    assert.equal(handFocusToManager('f', 'mgr'), true, 'a manager the daemon WILL revive takes the focus');
     assert.equal(getFocusByNode('mgr')?.focus_id, 'f', 'the row now shows the manager');
     assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies it');
     // Non-vacuous: a no-op impl returns false / leaves M as occupant → both the
@@ -140,12 +145,14 @@ test('handFocusToManager: LIVE backstage manager → swaps its pane INTO the foc
         spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
     }
 });
-test('handFocusToManager: DORMANT manager (dead pane) → occupant repointed, NO swap, focus pane UNCHANGED', () => {
+test('handFocusToManager: DORMANT idle-release manager (dead pane) → occupant repointed, NO swap, focus pane UNCHANGED', () => {
     openFocusRow('f', '%focus', 'Suser', 'M');
-    // The manager has a pane recorded but it is NOT a live tmux pane (its dead-pi
-    // window collapsed). isNodePaneAlive(mgr) is therefore false, so the live-swap
-    // is skipped — the external daemon later respawns it into the frozen %focus.
-    createNode(node('mgr', { pane: '%mgr-dead', tmux_session: 'back', window: '@wb', pi_pid: process.pid }));
+    // The manager is dormant + idle-release (the ONLY dormant manager the daemon
+    // revives): its pane is recorded but NOT a live tmux pane (its dead-pi window
+    // collapsed) and its pi is dead. isNodePaneAlive(mgr) is therefore false, so the
+    // live-swap is skipped — the external daemon later respawns it into the frozen
+    // %focus, exactly because status='idle' && intent='idle-release'.
+    createNode(node('mgr', { pane: '%mgr-dead', tmux_session: 'back', window: '@wb', pi_pid: null, status: 'idle', intent: 'idle-release' }));
     assert.equal(handFocusToManager('f', 'mgr'), true, 'still a takeover (occupant repointed)');
     assert.equal(getFocusByNode('mgr')?.focus_id, 'f', 'the manager occupies the focus row (DB repoint)');
     assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies it');
@@ -162,6 +169,42 @@ test('handFocusToManager: DORMANT manager (dead pane) → occupant repointed, NO
     // manager having a pane.
 });
 // ---------------------------------------------------------------------------
+// BUG REGRESSION (dead-focus-pane): handFocusToManager must return FALSE — so
+// the stophook caller runs closeFocusToShell to DISARM remain-on-exit and the
+// pane REAPS on exit — whenever NO successor will actually claim the frozen pane.
+// Pre-fix it repointed the occupant and returned true for ANY non-null,
+// not-already-focused manager (even done/dead/canceled, idle-but-not-idle-
+// release, or a live-but-paneless inline root). The daemon revives NONE of those
+// into the frozen pane, so closeFocusToShell was skipped, remain-on-exit stayed
+// ON, and the focus pane FROZE forever as a dead pane with no reaper.
+// Diagnosis: nodes/mq32wjve-68de0c31/context/dead-focus-pane-fix.md
+// ---------------------------------------------------------------------------
+test('handFocusToManager (BUG REGRESSION): a manager the daemon will NEVER revive → false, occupant UNCHANGED (caller disarms + reaps)', () => {
+    openFocusRow('f', '%focus', 'Suser', 'M'); // M occupies the frozen focus pane
+    // (a) DONE manager — the daemon ignores done nodes entirely (the most common
+    //     trigger: demoting a child to terminal whose manager already finished).
+    createNode(node('mgrDone', { status: 'done', pane: '%d', tmux_session: 'back', window: '@wd' }));
+    assert.equal(handFocusToManager('f', 'mgrDone'), false, 'a DONE manager will never be revived → caller must disarm + reap');
+    assert.equal(getFocusByNode('mgrDone'), null, 'a DONE manager is NOT repointed into the focus row');
+    // (b) DORMANT but NOT idle-release — idle with a different intent; crtrd's
+    //     second pass (idle && idle-release) skips it, so it never enters the pane.
+    createNode(node('mgrIdleDone', { status: 'idle', intent: 'done', pane: '%i', tmux_session: 'back', window: '@wi' }));
+    assert.equal(handFocusToManager('f', 'mgrIdleDone'), false, 'idle but NOT idle-release → daemon never revives it → false');
+    assert.equal(getFocusByNode('mgrIdleDone'), null, 'a non-idle-release manager is NOT repointed');
+    // (c) LIVE-but-PANELESS manager (an inline root, pane == null) — the live-swap
+    //     branch is skipped (no pane to swap) and, being active not idle-release,
+    //     the daemon never revives it either.
+    createNode(node('mgrPaneless', { status: 'active', pi_pid: process.pid, pane: null }));
+    assert.equal(handFocusToManager('f', 'mgrPaneless'), false, 'a live-but-paneless inline root cannot claim the pane → false');
+    assert.equal(getFocusByNode('mgrPaneless'), null, 'a paneless manager is NOT repointed');
+    // The occupant is untouched across all three → the caller (canvas-stophook
+    // agent_end done-branch) runs closeFocusToShell, disarming the freeze.
+    assert.equal(getFocusById('f')?.node_id, 'M', 'M still occupies its focus → caller disarms remain-on-exit + closes the row');
+    // Non-vacuous: the pre-fix impl repointed the occupant + returned true for each
+    // of (a)/(b)/(c), so every false return AND every "NOT repointed" assert fails
+    // against it — and that stray true would have stranded the pane frozen forever.
+});
+// ---------------------------------------------------------------------------
 // tearDownNode (pure DB; no tmux — pane is null so closePane never runs).
 // ---------------------------------------------------------------------------
 test('tearDownNode: closes the focus row M occupied and nulls its LOCATION', () => {

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

@@ -109,8 +109,9 @@ test('relaunchRoot parks the old root (canceled, edges intact, no wipe) and mint
     assert.equal(existsSync(roadmapPath('root')), true, 'roadmap preserved');
     assert.equal(existsSync(inboxPath('root')), true, 'inbox preserved');
     assert.equal(existsSync(join(reportsDir('root'), '20260101T000000-update.md')), true, 'report preserved');
-    // New root: fresh base resident, active, intent=refresh, empty context dir,
-    // spawned_by=old, focused.
+    // New root: fresh base resident, active, intent=refresh, a clean-slate context
+    // dir (only the born-with memory store, nothing inherited), spawned_by=old,
+    // focused.
     const fresh = getNode(newId);
     assert.equal(fresh?.parent, null, 'new node is a root');
     assert.equal(fresh?.mode, 'base');
@@ -122,7 +123,7 @@ test('relaunchRoot parks the old root (canceled, edges intact, no wipe) and mint
     assert.equal(fresh?.tmux_session, 'crtr', 'adopted the old root window location');
     assert.equal(fresh?.window, '@7');
     assert.ok(fresh?.launch, 'a fresh base launch spec was written');
-    assert.equal(readdirSync(contextDir(newId)).length, 0, 'fresh empty context dir');
+    assert.deepEqual(readdirSync(contextDir(newId)).sort(), ['memory'], 'fresh context dir holds only the born-with node-local memory store — nothing inherited from the old root');
     // Focus follows content: the focus row the old root held now shows the new root.
     assert.equal(getFocusByNode(newId)?.focus_id, 'fRoot', 'focus row repointed to the new root');
     assert.equal(getFocusByNode('root'), null, 'old root no longer occupies the focus');

package/dist/core/__tests__/review-render-pane-regression.test.d.ts

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

package/dist/core/__tests__/review-render-pane-regression.test.js

@@ -0,0 +1,133 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/review-render-pane-regression.test.ts
+//
+// BUG REGRESSION: `crtr human review` showed the human RAW markdown — literal
+// `:::callout{...}` / `#` / `**bold**` source — instead of the termrender-
+// rendered document the leaf help promises ("directive-flavored markdown
+// rendered by termrender (panels, columns, trees, callouts, mermaid)").
+//
+// Root cause: the review surface was ONLY the read-only nvim buffer. nvim must
+// show the raw source (anchored comments hang off source line/col numbers), and
+// `-u NONE` treesitter/render-markdown styling never interprets ::: directives —
+// so nothing anywhere rendered the doc. There was no termrender invocation in
+// the entire review path (crouter `_run` review branch + humanloop
+// launchReview): the managed venv binary was healthy and never asked.
+//
+// THE FIX (src/commands/human/queue.ts, `_run` review branch): open a live
+// termrender watch pane via humanloop `display()` BESIDE the editor, record its
+// pane id as `render_pane_id` on run.json (so `human cancel` can clear it), and
+// kill it in a `finally` when the editor exits. The editor keeps the raw
+// source; the human reads the rendered pane.
+//
+// This test drives the REAL `crtr human _run` worker (review mode) in a REAL
+// but isolated tmux session — no mocks — and asserts:
+//   (a) a second pane appears beside the editor running termrender on the file,
+//   (b) that pane's content is RENDERED ANSI (box-drawing panels), not raw `:::`,
+//   (c) run.json carries render_pane_id for the cancel path,
+//   (d) the render pane is torn down when the editor exits.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { hasTmux } from './helpers/harness.js';
+const CROUTER = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const CLI_SRC = join(CROUTER, 'src', 'cli.ts');
+const TSX_ESM = createRequire(import.meta.url).resolve('tsx/esm');
+function tmux(args) {
+    const r = spawnSync('tmux', args, { encoding: 'utf8' });
+    return { code: r.status ?? -1, out: (r.stdout ?? '').trim(), err: (r.stderr ?? '').trim() };
+}
+function sessionPanes(session) {
+    const r = tmux(['list-panes', '-s', '-t', session, '-F', '#{pane_id}\t#{pane_current_command}']);
+    if (r.code !== 0)
+        return [];
+    return r.out
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => {
+        const [id, cmd] = l.split('\t');
+        return { id: id ?? '', cmd: cmd ?? '' };
+    });
+}
+function paneContent(paneId) {
+    return tmux(['capture-pane', '-p', '-t', paneId]).out;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function waitFor(fn, timeoutMs, label) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const v = fn();
+        if (v !== undefined)
+            return v;
+        if (Date.now() > deadline)
+            throw new Error(`timeout waiting for ${label}`);
+        await sleep(300);
+    }
+}
+const SKIP = !hasTmux();
+test('review-render-pane regression: `human _run` (review) opens a live termrender pane showing RENDERED panels, not raw ::: source', { skip: SKIP ? 'tmux unavailable' : false, timeout: 90_000 }, async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-review-render-'));
+    const session = `crtr-revrender-${process.pid}-${Date.now().toString(36)}`;
+    const mdPath = join(dir, 'doc.md');
+    // A directive doc: rendered output has box-drawing panels; raw output has `:::`.
+    writeFileSync(mdPath, '# Render check\n\n:::callout{type="info"}\nRENDER-MARKER body\n:::\n');
+    writeFileSync(join(dir, 'run.json'), JSON.stringify({ mode: 'review', job_id: '', file: mdPath, output: join(dir, 'feedback.json') }));
+    try {
+        // The worker runs the real `crtr human _run` from src via tsx, exactly the
+        // command shape detachHumanTui bakes into the spawned pane. job_id is ''
+        // so pushFinal is skipped (no canvas home needed) — the surface under
+        // test is the panes, not the report fan-out.
+        const workerCmd = `CRTR_HUMAN_DIR='${dir}' '${process.execPath}' --import '${TSX_ESM}' '${CLI_SRC}' human _run; sleep 120`;
+        const created = tmux(['new-session', '-d', '-s', session, '-x', '200', '-y', '50', workerCmd]);
+        assert.equal(created.code, 0, `create isolated session failed: ${created.err}`);
+        // (a) a SECOND pane appears: the termrender watch pane beside the editor.
+        const renderPane = await waitFor(() => {
+            const panes = sessionPanes(session);
+            if (panes.length < 2)
+                return undefined;
+            // The render pane is the one NOT hosting the editor/worker shell.
+            const candidates = panes.filter((p) => !/zsh|bash|sh|node|nvim|vim/i.test(p.cmd));
+            return candidates[0]?.id;
+        }, 30_000, 'termrender render pane to open');
+        // (b) its content is RENDERED: panel box-drawing present, raw ::: absent.
+        const rendered = await waitFor(() => {
+            const c = paneContent(renderPane);
+            return c.includes('RENDER-MARKER') ? c : undefined;
+        }, 30_000, 'rendered body to paint');
+        assert.ok(/[┌│└]/.test(rendered), `render pane draws panels (box chars): ${rendered.slice(0, 200)}`);
+        assert.ok(!rendered.includes(':::'), 'render pane does NOT show raw ::: directive source');
+        // (c) run.json carries render_pane_id so `human cancel` can clear the pane.
+        const rc = JSON.parse(readFileSync(join(dir, 'run.json'), 'utf8'));
+        assert.equal(rc.render_pane_id, renderPane, 'run.json records the render pane id');
+        // (d) editor exit (any quit submits) tears the render pane down. The
+        // editor pane is the OTHER pane (nvim runs as a child of the worker, so
+        // #{pane_current_command} may report node/zsh — match on its content:
+        // the read-only buffer shows the RAW ::: source).
+        const editorPane = await waitFor(() => {
+            const other = sessionPanes(session).find((p) => p.id !== renderPane);
+            if (other === undefined)
+                return undefined;
+            return paneContent(other.id).includes(':::') ? other.id : undefined;
+        }, 30_000, 'editor pane showing the raw source buffer');
+        tmux(['send-keys', '-t', editorPane, 'Space', 's']);
+        await waitFor(() => (existsSync(join(dir, 'feedback.json')) ? true : undefined), 30_000, 'feedback.json after submit');
+        await waitFor(() => (sessionPanes(session).some((p) => p.id === renderPane) ? undefined : true), 15_000, 'render pane to be killed after editor exit');
+    }
+    finally {
+        tmux(['kill-session', '-t', session]);
+        // The worker may still be flushing job files as it exits; retry the rm
+        // briefly so a write racing the first attempt can't fail the test.
+        for (let i = 0; i < 10; i++) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+                break;
+            }
+            catch {
+                await sleep(300);
+            }
+        }
+    }
+});

package/dist/core/__tests__/spawn-root.test.js

@@ -10,6 +10,7 @@ import { createNode, getNode, getRow, subscribersOf } from '../canvas/canvas.js'
 import { closeDb } from '../canvas/db.js';
 import { nodeDir } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
+import { resolveSpawner } from '../runtime/spawn.js';
 let home;
 function spawner(id) {
     return {
@@ -62,6 +63,15 @@ test('independent root: provenance only, no parent, no subscription', () => {
     assert.equal(meta.lifecycle, 'resident', 'a root is resident');
     assert.equal(subscribersOf(root.node_id).length, 0, 'nobody is subscribed to an independent root — the spawner is not woken by it');
 });
+test('resolveSpawner: a --root spawn needs no caller; a managed child does (regression)', () => {
+    // Bug-regression: `crtr node new --root` from a human shell (no CRTR_NODE_ID,
+    // no --parent) threw "spawnChild requires a calling node" even though a root
+    // has no spine parent and the spawner id is provenance only.
+    assert.equal(resolveSpawner(undefined, null, true), null, 'human root spawn: no caller is fine');
+    assert.equal(resolveSpawner(undefined, 'A', true), 'A', 'node root spawn: provenance recorded');
+    assert.equal(resolveSpawner('A', null, false), 'A', 'explicit parent satisfies a child spawn');
+    assert.throws(() => resolveSpawner(undefined, null, false), /requires a calling node/, 'a managed child with no caller still throws');
+});
 test('unknown parent: spawnNode throws and mints NO node dir / row (validate before create)', () => {
     // Pre-allocate the would-be id so we can prove nothing was scaffolded for it.
     const orphanId = 'orphan-under-ghost';

package/dist/core/__tests__/spike-harness.test.js

@@ -46,6 +46,7 @@ const CANVAS_ENV_KEYS = [
     'CRTR_NODE_ID',
     'CRTR_HOME',
     'CRTR_ROOT_SESSION',
+    'CRTR_SUBTREE',
     'CRTR_NODE_SESSION',
     'CRTR_PARENT_NODE_ID',
     'CRTR_FRONT_DOOR',

package/dist/core/__tests__/wake-bearings.test.d.ts

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

package/dist/core/__tests__/wake-bearings.test.js

@@ -0,0 +1,156 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/wake-bearings.test.ts
+//
+// Wake-origin self-knowledge (the <crtr-wake> provenance block). Regression
+// guard for the observed gap: a node woken or BORN by a scheduled TIMER could
+// not tell it came from a timer — a scheduled wake arrived indistinguishable
+// from an ordinary refresh/message (the Invariant B/D anti-goal). These lock:
+//   • buildWakeBearings renders the right decision-first block per wake kind /
+//     cadence, and never crashes when the armer was reaped (no resolved name);
+//   • the bare-wake revive kickoff carries that block (so a scheduled alarm is
+//     distinguishable from a generic context-refresh), placed AFTER the kickoff
+//     sentinel (goal-capture keys on it) and BEFORE the roadmap/disk bearings;
+//   • an ordinary fresh revive (no wakeReason) carries NO block.
+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 } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { buildWakeBearings } from '../runtime/bearings.js';
+import { buildReviveKickoff, drainBearings, REVIVE_KICKOFF_SENTINEL, } from '../runtime/kickoff.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',
+    };
+}
+const ARMED = '2026-06-08T13:30:00.000Z';
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-wake-bearings-'));
+    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'];
+});
+// --- buildWakeBearings: one per kind / cadence variant ----------------------
+test('spawn one-shot: names a deferred birth + the armer, and says it does not recur', () => {
+    const o = {
+        kind: 'spawn',
+        ownerId: 'arm-1',
+        ownerName: 'release-orch',
+        armedAt: ARMED,
+        recur: null,
+    };
+    const b = buildWakeBearings(o);
+    assert.ok(b.startsWith('<crtr-wake>') && b.endsWith('</crtr-wake>'));
+    assert.match(b, /BORN by a scheduled wake/);
+    assert.match(b, /deferred birth/);
+    // Armer named ROLE-explicitly so the newborn never reads the id as its own.
+    assert.match(b, /armed by node arm-1 \("release-orch"\)/);
+    assert.match(b, /only run, not a recurring job/);
+    assert.match(b, /Your task follows\./);
+});
+test('spawn cron: surfaces the cadence + frames it as one run of a standing job', () => {
+    const o = {
+        kind: 'spawn',
+        ownerId: 'arm-1',
+        ownerName: 'nightly',
+        armedAt: ARMED,
+        recur: JSON.stringify({ cron: '0 9 * * *', tz: 'America/New_York' }),
+    };
+    const b = buildWakeBearings(o);
+    assert.match(b, /recurring spawn-cron armed by node arm-1 \("nightly"\)/);
+    // The cadence renders via the shared cadenceDisplay (matches `wake list`).
+    assert.match(b, /firing cron `0 9 \* \* \*` \(America\/New_York\)/);
+    assert.match(b, /one run of a standing job, not a one-off/);
+    assert.match(b, /inherit nothing from prior runs but this task/);
+});
+test('spawn interval cron: renders the every-N cadence', () => {
+    const o = {
+        kind: 'spawn',
+        ownerId: 'arm-1',
+        ownerName: 'poller',
+        armedAt: ARMED,
+        recur: JSON.stringify({ every: '6h' }),
+    };
+    assert.match(buildWakeBearings(o), /firing every 6h/);
+});
+test('spawn with a reaped armer: renders the bare id, no name, never crashes', () => {
+    const o = {
+        kind: 'spawn',
+        ownerId: 'gone-9',
+        ownerName: undefined, // armer no longer exists → no resolved name
+        armedAt: ARMED,
+        recur: JSON.stringify({ every: '12h' }),
+    };
+    const b = buildWakeBearings(o);
+    assert.match(b, /armed by node gone-9 \(now gone\)/); // bare id, flagged reaped
+    assert.doesNotMatch(b, /\("/); // never an empty/dangling name
+});
+test('bare one-shot: frames a timed re-check, NOT a new request', () => {
+    const o = { kind: 'bare', ownerId: 'n1', ownerName: 'n1', armedAt: ARMED, recur: null };
+    const b = buildWakeBearings(o);
+    assert.match(b, /a scheduled alarm fired/);
+    assert.match(b, /a timer, NOT a new message or request/);
+    assert.match(b, /timed re-check, not a new task/);
+    assert.match(b, /re-read your roadmap/);
+    // No armer attribution on bare (could be `--node`-armed by another), no ISO.
+    assert.doesNotMatch(b, /you set/);
+    assert.doesNotMatch(b, new RegExp(ARMED));
+});
+test('bare recurring: frames one tick of a standing re-check + the cadence', () => {
+    const o = {
+        kind: 'bare',
+        ownerId: 'n1',
+        ownerName: 'n1',
+        armedAt: ARMED,
+        recur: JSON.stringify({ every: '6h' }),
+    };
+    const b = buildWakeBearings(o);
+    assert.match(b, /recurring scheduled alarm fired \(every 6h\)/);
+    assert.match(b, /one tick of a standing re-check/);
+});
+// --- the bare-wake revive seam (Seam 2) -------------------------------------
+test('a bare scheduled wake makes the fresh-revive kickoff distinguishable from a refresh', () => {
+    const id = 'b1';
+    const meta = createNode(node(id));
+    const wakeReason = {
+        kind: 'bare',
+        ownerId: id,
+        ownerName: id,
+        armedAt: ARMED,
+        recur: null,
+    };
+    const msg = buildReviveKickoff(meta, drainBearings(meta), wakeReason);
+    // The block is present, and the kickoff STILL starts with the sentinel that
+    // goal-capture keys on (so the prompt is never mistaken for a user mandate).
+    assert.ok(msg.startsWith(REVIVE_KICKOFF_SENTINEL), 'kickoff still leads with the sentinel');
+    assert.match(msg, /<crtr-wake>/);
+    assert.match(msg, /a scheduled alarm fired/);
+    // Placement: sentinel < <crtr-wake> < <roadmap> — "why you woke" precedes
+    // "what to rebuild from".
+    const iSentinel = msg.indexOf(REVIVE_KICKOFF_SENTINEL);
+    const iWake = msg.indexOf('<crtr-wake>');
+    const iRoadmap = msg.indexOf('<roadmap');
+    assert.ok(iSentinel === 0 && iSentinel < iWake && iWake < iRoadmap, 'block sits after sentinel, before roadmap');
+});
+test('an ordinary fresh revive (no wakeReason) carries NO wake block', () => {
+    const id = 'b2';
+    const meta = createNode(node(id));
+    const msg = buildReviveKickoff(meta, drainBearings(meta));
+    assert.doesNotMatch(msg, /<crtr-wake>/);
+});