@crouton-kit/crouter 0.3.18 → 0.3.19

package/dist/core/__tests__/context-intro.test.js

@@ -1,28 +1,25 @@
-// Tests for the <crtr-context> bearings preamble + scoped memory:
-//   1. A plain spawned node gets NO MEMORY.md; promotion seeds it (the template).
-//   2. seedMemory is idempotent (never clobbers an evolved memory).
-//   3. Worker bearings = shared-doc framing only (no <memory> block);
-//      orchestrator bearings add the across-cycles framing + a <memory> block
-//      that MERGES the applicable stores, each a `label · dir` header over its
-//      live index POINTER LINES only (the how-to boilerplate is dropped — it
-//      lives once in the kernel); promotion delivers that same orchestrator
+// Tests for the <crtr-context> bearings preamble:
+//   1. Worker and orchestrator bearings carry the `## References` block
+//      (substrate reference docs + node-local docs as `###` sub-sections) in
+//      place of the removed `<memory>` block — no `label · dir` stanzas, no
+//      `(empty)` markers, no MEMORY.md index inlining. Orchestrators add the
+//      across-cycles framing; promotion delivers that same orchestrator
 //      context-dir framing to a node that spawned base.
-//   4. canvas-context-intro injects the block as its own session message at
+//   2. canvas-context-intro injects the block as its own session message at
 //      session_start (before the first prompt), idempotent across resumes.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/context-intro.test.ts
 import { test, before, beforeEach, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { existsSync } from 'node:fs';
 import { closeDb } from '../canvas/db.js';
 import { contextDir } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { promote } from '../runtime/promote.js';
 import { personaDrift } from '../runtime/persona.js';
-import { memoryPath, memoryDir, readMemory, seedMemory, hasMemory, MEMORY_TEMPLATE, userMemoryDir, userMemoryPath, projectMemoryDir, projectMemoryPath, } from '../runtime/memory.js';
+import { memoryDir } from '../runtime/memory.js';
 import registerCanvasContextIntro, { buildContextIntro, renderContextMessage, CONTEXT_INTRO_CUSTOM_TYPE, } from '../../pi-extensions/canvas-context-intro.js';
 let home;
 before(() => {
@@ -39,69 +36,80 @@ after(() => {
     delete process.env['CRTR_HOME'];
     delete process.env['CRTR_NODE_ID'];
 });
-test('a plain spawned node gets NO memory; promotion seeds the index + dir', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    assert.equal(hasMemory(meta.node_id), false, 'no memory before promotion');
-    promote(meta.node_id);
-    assert.ok(hasMemory(meta.node_id), 'MEMORY.md index exists after promotion');
-    assert.ok(existsSync(memoryDir(meta.node_id)), 'memory dir created for direct writes');
-    assert.ok(memoryPath(meta.node_id).endsWith('/memory/MEMORY.md'), 'index lives inside the memory dir');
-    assert.equal(readMemory(meta.node_id), MEMORY_TEMPLATE);
-});
-test('seedMemory is idempotent — never clobbers an evolved memory', () => {
-    const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    seedMemory(meta.node_id);
-    const evolved = '# Memory\n\n## Lessons\n- never trust the cache\n';
-    writeFileSync(memoryPath(meta.node_id), evolved);
-    assert.equal(seedMemory(meta.node_id), false, 'returns false when one exists');
-    assert.equal(readMemory(meta.node_id), evolved, 'left untouched');
-});
-test('worker bearings: shared-doc framing only, no orchestrator/memory framing', () => {
+test('worker bearings: base framing + ## References block (no <memory>, no label·dir stanzas), NO across-cycles framing', () => {
+    // Bug-regression: review finding M1 — buildContextBearings was changed from
+    // buildMemoryBlock (<memory> + label·dir per-store stanzas) to
+    // renderReferencesBlock (## References + ### <name> sub-sections). This test
+    // locks in the new contract.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
+    // Seed a node-local substrate doc so the ## References block is non-empty.
+    const dir = memoryDir(meta.node_id);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'test-ref.md'), '---\nkind: reference\nwhen: when testing\nwhy: regression fixture\nsystem-prompt-visibility: preview\n---\nTest body.\n');
     const block = buildContextIntro(meta.node_id);
     assert.match(block, new RegExp(`<crtr-context dir="${contextDir(meta.node_id)}">`));
     assert.match(block, /shared document store, not a task tracker/, 'base = shared docs, not tasks');
-    assert.doesNotMatch(block, /MEMORY\.md/, 'no memory pointer for a memory-less worker');
-    assert.doesNotMatch(block, /<memory>/, 'no memory block for a memory-less worker');
+    // New contract: NO <memory> block — replaced by ## References.
+    assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
+    // New contract: NO label·dir stanza headers (the removed per-store format).
+    assert.doesNotMatch(block, /user-global · /, 'no user-global label·dir stanza');
+    assert.doesNotMatch(block, /node-local · /, 'no node-local label·dir stanza');
+    // New contract: NO (empty) placeholder (the removed empty-store marker).
+    assert.doesNotMatch(block, /\(empty\)/, 'no (empty) placeholder');
+    // Reference content renders as ## References + ### sub-sections — no other shape.
+    assert.match(block, /## References\n\n###/, '## References followed by ### sub-sections');
+    // A terminal worker must NOT carry the orchestrator across-cycles framing.
     assert.doesNotMatch(block, /refresh cycles/, 'no across-cycles framing for a terminal worker');
     assert.match(block, /<\/crtr-context>/);
 });
-test('orchestrator bearings: across-cycles framing + a <memory> block whose body is the live pointer lines under `label · dir`', () => {
+test('orchestrator bearings: across-cycles framing + node-local substrate docs ride into ## References; the MEMORY.md index never renders', () => {
+    // Bug-regression: review finding M1 — buildContextBearings replaced the old
+    // <memory> pointer-line block with ## References. Node-local substrate docs
+    // render as ### sub-sections at their rung; the old index file never surfaces.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    seedMemory(meta.node_id);
-    // The seeded index carries the how-to comment + the empty marker; an evolved
-    // index adds a pointer line. The block must render ONLY the pointer line.
-    writeFileSync(memoryPath(meta.node_id), '# memory index — one pointer line per memory; how-to in "Your long-term memory".\n\n- [Flaky build](flaky-build.md) — first run fails\n');
+    promote(meta.node_id); // flip to orchestrator mode — the across-cycles gate
+    const dir = memoryDir(meta.node_id);
+    mkdirSync(dir, { recursive: true });
+    // Write a MEMORY.md file to verify it is never surfaced in the block.
+    const legacyIndexPath = join(dir, 'MEMORY.md');
+    writeFileSync(legacyIndexPath, '# memory index — one pointer line per memory; how-to in "Your long-term memory".\n\n- [Flaky build](flaky-build.md) — first run fails\n');
+    // A node-local substrate doc DOES ride into ## References at its rung.
+    writeFileSync(join(dir, 'flaky-build.md'), '---\nkind: reference\nwhen: when the build flakes\nwhy: first run fails\nsystem-prompt-visibility: preview\n---\nFirst run always fails; rerun once.\n');
     const block = buildContextIntro(meta.node_id);
     assert.match(block, /shared document store, not a task tracker/, 'still carries the base framing');
     assert.match(block, /refresh cycles/, 'orchestrator gets the across-cycles framing');
-    assert.match(block, /<memory>/, 'has a memory block');
-    // (a) the store renders just its pointer line under a `label · dir` header.
-    assert.ok(block.includes(`node-local · ${memoryDir(meta.node_id)}`), 'compact `label · dir` header');
-    assert.match(block, /- \[Flaky build\]\(flaky-build\.md\) — first run fails/, 'the live pointer line is inlined');
-    // (c) no `index:` line, no absolute index path, no inlined how-to boilerplate.
-    assert.ok(!block.includes('index:'), 'no index: substring');
-    assert.ok(!block.includes(memoryPath(meta.node_id)), 'no absolute index (MEMORY.md) path');
-    assert.ok(!block.includes('how-to in'), 'the index how-to boilerplate is NOT inlined');
+    assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
+    assert.match(block, /## References\n/, 'references block present');
+    assert.match(block, /### flaky-build\n/, 'node-local doc gets its ### sub-section');
+    assert.match(block, /when the build flakes, read this reference\. first run fails\./, 'preview rung renders the routing line');
+    // The index file itself never renders: no header comment, no pointer line, no path.
     assert.ok(!block.includes('# memory index'), 'the index header comment is NOT inlined');
+    assert.ok(!block.includes('- [Flaky build](flaky-build.md)'), 'index pointer lines are NOT inlined');
+    assert.ok(!block.includes(legacyIndexPath), 'no absolute index (MEMORY.md) path');
+    assert.ok(!block.includes('node-local · '), 'no label·dir stanza header');
     assert.match(block, /<\/crtr-context>/);
 });
-test('orchestrator bearings: a promoted node merges all THREE stores; template-only stores render (empty)', () => {
+test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-none node-local doc still surfaces as a ### title stub', () => {
+    // Bug-regression: review findings M1 + M6 — the three-store `label · dir`
+    // stanzas and (empty) markers are gone, and node-local docs are NOT filtered
+    // on rung: a migrated node-local reference defaults
+    // system-prompt-visibility: none and must still ride into ## References as
+    // its bare title (never its body).
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
-    promote(meta.node_id); // seeds user-global + project + node-local (all template-only)
+    promote(meta.node_id); // flip to orchestrator mode
+    const dir = memoryDir(meta.node_id);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'rung-none-fact.md'), '---\nkind: reference\n---\nbody that must not render at the none rung\n');
     const block = buildContextIntro(meta.node_id);
-    // Each scope present as a `label · dir` header.
-    assert.ok(block.includes(`user-global · ${userMemoryDir()}`), 'merges the user-global store');
-    assert.ok(block.includes(`project · ${projectMemoryDir('/tmp/work')}`), 'merges the project store');
-    assert.ok(block.includes(`node-local · ${memoryDir(meta.node_id)}`), 'merges the node-local store');
-    // (b) a template-only / not-yet-written store renders the (empty) marker.
-    assert.match(block, /user-global · .*\n\(empty\)/, 'template-only user store renders (empty)');
-    assert.equal(block.match(/\(empty\)/g)?.length, 3, 'all three template-only stores render (empty)');
-    // (c) no absolute index paths leak in.
-    assert.ok(!block.includes(userMemoryPath()), 'no user-global MEMORY.md path');
-    assert.ok(!block.includes(projectMemoryPath('/tmp/work')), 'no project MEMORY.md path');
-    // The type→store mapping is taught by the kernel; the block points at it.
-    assert.match(block, /type/, 'the block references the type that decides the store');
+    // No per-store stanza headers, no (empty) markers, no index paths.
+    assert.ok(!block.includes(`node-local · ${memoryDir(meta.node_id)}`), 'no node-local stanza header');
+    assert.ok(!block.includes('user-global · '), 'no user-global stanza header');
+    assert.ok(!block.includes('project · '), 'no project stanza header');
+    assert.doesNotMatch(block, /\(empty\)/, 'no (empty) markers');
+    assert.ok(!block.includes('MEMORY.md'), 'no MEMORY.md path in the block');
+    // M6: rung-none node-local doc surfaces as its title stub only.
+    assert.match(block, /### rung-none-fact\s*\n/, 'rung-none node-local doc surfaces as its title stub');
+    assert.ok(!block.includes('body that must not render'), 'none rung renders the title only, not the body');
 });
 test('promotion guidance delivers the orchestrator context-dir framing', () => {
     // A node spawns as a base worker (no orchestrator bearings). On promotion the
@@ -145,12 +153,18 @@ test('session_start injects the block as the first message of an empty session',
 test('session_start is idempotent across resume (skips if already in history)', () => {
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     process.env['CRTR_NODE_ID'] = meta.node_id;
-    // Restored session already carries the block → no duplicate injection.
+    // Restored session already carries OUR block (which names this node id) → no
+    // duplicate injection. The content matters: the guard is fork-aware and only
+    // skips when the present bearings name THIS node (a fork inherits the
+    // SOURCE's bearings, which name a different node — see canvas-context-intro
+    // tests), so a realistic resume entry must carry the real block content.
     const pi = makeFakePi();
     registerCanvasContextIntro(pi);
-    const entries = [{ type: 'custom_message', customType: CONTEXT_INTRO_CUSTOM_TYPE }];
+    const entries = [
+        { type: 'custom_message', customType: CONTEXT_INTRO_CUSTOM_TYPE, content: buildContextIntro(meta.node_id) },
+    ];
     pi.handler({ reason: 'resume' }, fakeCtx(entries));
-    assert.equal(pi.sent.length, 0, 'block already in history → skip');
+    assert.equal(pi.sent.length, 0, 'our own block already in history → skip');
 });
 test('session_start is inert when CRTR_NODE_ID is absent', () => {
     delete process.env['CRTR_NODE_ID'];

package/dist/core/__tests__/daemon-boot.test.js

@@ -64,10 +64,14 @@ test('never-booted node is marked dead and surfaced to the parent as urgent', as
     assert.equal(inbox[0].from, 'C');
     assert.match(inbox[0].label, /Spawn failed/);
 });
-// A node that HAD booted (pi_session_id set) then lost its window is a genuine
-// crash, not a boot failure — it is marked dead but NOT surfaced as a spawn
-// failure (no false alarm to the parent).
-test('a crash after boot is marked dead without a boot-failure push', async () => {
+// A node that HAD booted (pi_session_id set) then died mid-generation is a
+// genuine crash, not a boot failure. It is marked dead AND wakes the inbox-
+// waiting parent — but with a "child died" notice (surfaceChildDeath), NOT a
+// "Spawn failed" boot-failure pointer (surfaceBootFailure). The parent-wake
+// itself was added by main's b5abf6e (parent-wake on child death) and is locked
+// in by child-death-wake.test.ts; this test preserves the discriminating intent
+// — a crash is never surfaced as a false spawn-failure alarm.
+test('a crash after boot wakes the parent with a child-death notice, not a boot-failure push', async () => {
     createNode(node('P2', { kind: 'developer', lifecycle: 'resident' }));
     createNode(node('C2', {
         parent: 'P2',
@@ -85,7 +89,12 @@ test('a crash after boot is marked dead without a boot-failure push', async () =
     markBusy('C2');
     await superviseTick();
     assert.equal(getNode('C2').status, 'dead', 'crashed child is dead');
-    assert.equal(readInboxSince('P2').length, 0, 'a real crash does not push a boot-failure pointer');
+    const inbox = readInboxSince('P2');
+    assert.equal(inbox.length, 1, 'a genuine mid-run crash wakes the inbox-waiting parent (D-1 parent-wake)');
+    assert.equal(inbox[0].tier, 'urgent', 'mid-run crash is delivered as urgent');
+    assert.equal(inbox[0].from, 'C2');
+    assert.match(inbox[0].label, /died/i, 'the wake is a child-death notice (surfaceChildDeath), not silence');
+    assert.doesNotMatch(inbox[0].label, /Spawn failed/, 'a crash is NOT surfaced as a false boot-failure alarm');
     clearBusy('C2');
 });
 // A still-booting node whose window is alive must be left untouched — boot is

package/dist/core/__tests__/daemon-liveness.test.js

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { createNode, getNode, subscribe } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { appendInbox } from '../feed/inbox.js';
@@ -32,6 +32,17 @@ function deadPid() {
     // spawnSync has reaped it by the time it returns; pid may be on r.pid.
     return r.pid ?? 0x7ffffffe; // fall back to an implausibly-high pid
 }
+/** A pid that is ALIVE for the test's duration but expendable. Pane-gone
+ *  fixtures must NEVER use process.pid for an alive pi: the gone-pane zombie
+ *  sweep (b92082e) SIGKILLs a pane-gone node's live pid, which took the whole
+ *  test runner down with it. The daemon (or the after hook) reaps these. */
+const livePids = [];
+function disposableLivePid() {
+    const child = spawn('sleep', ['600'], { stdio: 'ignore', detached: true });
+    child.unref();
+    livePids.push(child.pid);
+    return child.pid;
+}
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-daemon-liveness-'));
     process.env['CRTR_HOME'] = home;
@@ -44,6 +55,14 @@ after(() => {
     closeDb();
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
+    for (const pid of livePids) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            /* already reaped by the daemon's zombie sweep — fine */
+        }
+    }
 });
 // ---------------------------------------------------------------------------
 // livenessVerdict — the pure grace-window decision
@@ -157,7 +176,7 @@ test('pane GONE while its old window is still alive → the gone-branch fires (c
             pane: dead,
             tmux_session: session,
             window,
-            pi_pid: process.pid, // alive — irrelevant once the pane reads gone
+            pi_pid: disposableLivePid(), // alive zombie — the gone-pane sweep SIGKILLs it
             pi_session_id: 'booted',
             intent: null,
         }));
@@ -172,7 +191,7 @@ test('pane GONE while its old window is still alive → the gone-branch fires (c
 // unconditional 'dead'. It routes on what the node was DOING at pane-kill time:
 //   • mid-generation (busy marker PRESENT)               → crash  ('dead')
 //   • finished its turn, awaiting nothing live           → finalize ('done')
-//   • finished its turn, still awaiting a LIVE child     → crash  ('dead'), for now
+//   • finished its turn, still awaiting a LIVE child     → release ('idle' + idle-release), revivable
 // (The mid-generation → dead leg is covered by node 'G' above.)
 // ---------------------------------------------------------------------------
 test('pane gone + booted + busy ABSENT + no live subscription → finalize (done): the pane was closed to dismiss a finished node', { skip: !hasTmux() }, async () => {
@@ -187,7 +206,7 @@ test('pane gone + booted + busy ABSENT + no live subscription → finalize (done
             pane: dead,
             tmux_session: session,
             window,
-            pi_pid: process.pid,
+            pi_pid: disposableLivePid(), // alive zombie — swept before finalize routing
             pi_session_id: 'booted',
             intent: null,
         }));
@@ -196,7 +215,7 @@ test('pane gone + booted + busy ABSENT + no live subscription → finalize (done
         assert.equal(getNode('FIN').status, 'done', 'a finished, unsubscribed node whose pane was closed finalizes to done');
     });
 });
-test('pane gone + booted + busy ABSENT but AWAITING a LIVE child → crash (dead), for now', { skip: !hasTmux() }, async () => {
+test('pane gone + booted + busy ABSENT but AWAITING a LIVE child → idle-release (revivable, NOT dead)', { skip: !hasTmux() }, async () => {
     await withLivePane('fin2', async (session, window) => {
         const sp = spawnSync('tmux', ['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${session}:${window}`, 'sleep 600'], { encoding: 'utf8' });
         const dead = (sp.stdout ?? '').trim();
@@ -207,15 +226,21 @@ test('pane gone + booted + busy ABSENT but AWAITING a LIVE child → crash (dead
             pane: dead,
             tmux_session: session,
             window,
-            pi_pid: process.pid,
+            pi_pid: deadPid(), // the user closed the pane → pi is dead
             pi_session_id: 'booted',
             intent: null,
         }));
         subscribe('PARENT', 'CHILD', true); // active subscription to a LIVE node
-        // Parent finished its turn (no busy marker) but is still awaiting a live
-        // child → NOT a finalize. Routes to crash ('dead') for now.
+        // REGRESSION: closing the pane of a waiting orchestrator must NOT kill it.
+        // PARENT finished its turn (no busy marker) but still awaits a live child, so
+        // a hard 'dead' would orphan the child's report. It routes to idle-release
+        // (revivable); the second pass revives it on the next inbox push. No inbox
+        // entry here, so it stays dormant (idle + idle-release) — revivable, not dead.
         await superviseTick();
-        assert.equal(getNode('PARENT').status, 'dead', 'a finished node still awaiting a live child crashes (dead), not finalizes');
+        const p = getNode('PARENT');
+        assert.equal(p.status, 'idle', 'a finished node still awaiting a live child is RELEASED, not killed');
+        assert.equal(p.intent, 'idle-release', 'routed to idle-release so a child push revives it');
+        assert.equal(p.window ?? null, null, 'the stale window ref is dropped');
     });
 });
 // ---------------------------------------------------------------------------

package/dist/core/__tests__/detach-focus.test.d.ts

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

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

@@ -0,0 +1,206 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/detach-focus.test.ts
+//
+// GAP CLOSE (flagship-lifecycle.test.ts coverage boundary): "node demote
+// --detach (A3: orphaned-focus-row hazard)". An END-TO-END test that drives the
+// REAL `crtr node demote --detach` verb (subprocess, AS the node) — the actual
+// Alt+C → D menu path — against a live fake-pi node genuinely FOCUSED in a user
+// viewport, and
+// proves the three things the A3 hazard is about:
+//   (a) lifecycle flips terminal IN PLACE,
+//   (b) the still-running pi's pane is RELOCATED to the backstage crtr session
+//       (the pi keeps generating off-screen, not killed),
+//   (c) the focus row it occupied is CLOSED — no orphaned/phantom viewport row
+//       lingering on the relocated %pane_id (Invariant P / Invariant F5).
+//
+// This is the harness-driven counterpart to placement-focus.test.ts's
+// `detachToBackground` unit (which calls the function directly): here the FLIP
+// and the detach both go through the real CLI leaf (node.ts nodeDemote →
+// setLifecycle), so the whole `crtr node demote --detach` wiring — the Alt+C → D
+// menu path — is exercised. Modeled on live-mutation.test.ts (harness +
+// `crtr node demote` + firstPaneOf) and
+// placement-focus.test.ts (user/back sessions + focus-row asserts).
+//
+// NOTE — the SIBLING focused-finish→manager-TAKEOVER path is NOT added here: the
+// harness mints its root via in-process createNode (never a real bootRoot — see
+// flagship S1), so a manager is always a paneless, never-booted row. Driving B
+// through agent_end's done-branch (h.finish) with such a manager would only ever
+// hit handFocusToManager's "live-but-paneless inline root → false" guard
+// (closeFocusToShell), never a genuine takeover; a LIVE-backstage or dormant
+// idle-release manager swap is unreachable through the harness. That swap is
+// unit-covered in placement-teardown.test.ts (MAJOR 1 + the dormant idle-release
+// case), so it is deliberately not re-driven here.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHarness, hasTmux } from './helpers/harness.js';
+import { setPresence, getNode } from '../canvas/canvas.js';
+import { openFocusRow, getFocusByNode, getFocusByPane, listFocuses } from '../canvas/focuses.js';
+import { closeDb } from '../canvas/db.js';
+import { markBusy } from '../runtime/busy.js';
+const SKIP = !hasTmux() ? 'tmux unavailable' : false;
+function sessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+function tmuxOut(args) {
+    return (spawnSync('tmux', args, { encoding: 'utf8' }).stdout ?? '').trim();
+}
+/** The first %pane_id of a tmux window (spawn records window+session, not pane). */
+function firstPaneOf(window) {
+    const r = spawnSync('tmux', ['list-panes', '-t', window, '-F', '#{pane_id}'], { encoding: 'utf8' });
+    if (r.status !== 0)
+        return null;
+    return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean)[0] ?? null;
+}
+/** A pane's CURRENT session/window (display-message on its durable %id). */
+function paneLoc(pane) {
+    const out = tmuxOut(['display-message', '-p', '-t', pane, '#{session_name}\t#{window_id}']);
+    const [session, window] = out.split('\t');
+    if (!session || !window)
+        return null;
+    return { session, window };
+}
+function paneSessionReal(pane) {
+    return tmuxOut(['display-message', '-p', '-t', pane, '#{session_name}']);
+}
+function paneExistsReal(pane) {
+    return tmuxOut(['display-message', '-p', '-t', pane, '#{pane_id}']) === pane;
+}
+// ===========================================================================
+// `crtr node demote --detach` on a FOCUSED node (A3 gap close; Alt+C → D).
+// ===========================================================================
+test('node demote --detach on a FOCUSED node: flips terminal, relocates the pane to the backstage, CLOSES the focus row (A3 — no orphaned focus row)', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-detach-focus' });
+    const user = `crtr-detach-user-${process.pid}-${Date.now().toString(36)}`;
+    try {
+        // A resident root + a live terminal child B (born into the backstage =
+        // h.session, the harness's CRTR_NODE_SESSION). B holds an active live sub
+        // to nothing extra — it just needs to be a live, focusable terminal node.
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        const b0 = h.node(B);
+        assert.equal(b0.lifecycle, 'terminal', 'B born terminal');
+        assert.equal(b0.status, 'active', 'B active after boot');
+        // Resolve B's live %pane_id from its window (the spawn path records only
+        // window+session; pane is null until a reconcile/focus).
+        const bPane = firstPaneOf(b0.window);
+        assert.ok(typeof bPane === 'string' && bPane !== '', 'B has a live pane');
+        // --- Put B into a USER viewport, FOCUSED. Create a separate user session
+        //     and break B's live pi pane out into it (the pi keeps running; the
+        //     %id survives the break), then anchor its presence + open a focus row.
+        //     This is the genuine "focused in a user pane" precondition — distinct
+        //     from the backstage (h.session) the detach will relocate it back to.
+        spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600'], { stdio: 'ignore' });
+        assert.equal(spawnSync('tmux', ['break-pane', '-d', '-a', '-s', bPane, '-t', `${user}:`]).status, 0, 'B pane broke out into the user viewport (pi kept alive)');
+        const moved = paneLoc(bPane);
+        assert.equal(moved?.session, user, 'B pane physically in the user session now');
+        assert.equal(paneExistsReal(bPane), true, "B's pi is still alive after the move");
+        closeDb();
+        setPresence(B, { pane: bPane, tmux_session: user, window: moved.window });
+        openFocusRow('f-detach', bPane, user, B);
+        assert.equal(getFocusByNode(B)?.focus_id, 'f-detach', 'precondition: B is FOCUSED in the user viewport');
+        // B must read as GENERATING for the backstage-park path: isGenerating now
+        // gates the break-pane (Bug 1 / Invariant P) on the mid-turn busy marker
+        // AND a live pi_pid. The boot only recorded pi_pid (session_start); no turn
+        // fired, so set the busy marker to model an agent genuinely mid-turn —
+        // otherwise the new gate would RELEASE B (the non-generating path below).
+        markBusy(B);
+        // --- Drive the REAL verb on the FOCUSED node. The subprocess inherits
+        //     CRTR_NODE_SESSION = h.session (the backstage), so detachToBackground
+        //     breaks the pane back into h.session.
+        const res = h.cli(B, ['node', 'demote', '--node', B, '--pane', bPane, '--detach']);
+        assert.equal(res.code, 0, `node demote --detach exit 0\n${res.stderr}`);
+        assert.match(res.stdout, /detached="true"/, `the agent was detached\n${res.stdout}`);
+        closeDb();
+        const b = getNode(B);
+        // (a) lifecycle flipped to terminal IN PLACE.
+        assert.equal(b.lifecycle, 'terminal', '(a) B lifecycle=terminal after the flip');
+        assert.equal(b.status, 'active', "(a) detach does NOT end the pi — B stays active");
+        // (b) the still-running pane was RELOCATED to the backstage crtr session
+        //     (NOT killed): the pi keeps generating off-screen.
+        assert.equal(paneExistsReal(bPane), true, "(b) B's pi keeps generating (pane alive, relocated not killed)");
+        assert.equal(paneSessionReal(bPane), h.session, '(b) B pane relocated to the backstage crtr session');
+        assert.equal(b.tmux_session, h.session, "(b) B's LOCATION followed the pane to the backstage");
+        // (c) the focus row is CLOSED — no orphaned/phantom viewport (A3 hazard).
+        assert.equal(getFocusByNode(B), null, '(c) B no longer occupies any focus (row CLOSED — Invariant P)');
+        assert.equal(getFocusByPane(bPane), null, '(c) NO phantom focus resolves on the relocated %id');
+        assert.equal(listFocuses().length, 0, '(c) no dangling focus rows remain');
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});
+// ===========================================================================
+// Bug 1 (Invariant P / detach-idle-node): `crtr node demote --detach` on a
+// NON-GENERATING focused node must NOT park it alive in the backstage — it must
+// be RELEASED to dormant and its pane reaped.
+//
+// The backstage holds ONLY generating-but-unfocused nodes (Invariant P).
+// detachToBackground used to break-pane to the backstage UNCONDITIONALLY, with no
+// generating-ness check: a resident root parked idle between turns (pi alive,
+// idle, NOT mid-turn) detached via Alt+C → D became unfocused + pi-alive-idle +
+// holding a backstage pane forever — nothing re-enters agent_end to release it
+// and, with no live subscription, nothing wakes it → a leaked live-idle pi that
+// never reaps. The fix gates the break-pane on isGenerating() and RELEASES a
+// non-generating node to dormant instead (mirrors retargetFocus's parked-viewer
+// release on focus-away).
+//
+// This drives the SAME real verb as the happy-path test above, but on a node
+// with NO busy marker (not mid-turn). isGenerating() = busy && pidAlive, so a
+// freshly-booted node (pi_pid recorded at session_start, no turn fired) reads as
+// NOT generating.
+// ===========================================================================
+test('node demote --detach on a NON-GENERATING focused node: RELEASES to dormant (idle + idle-release), reaps the pane, closes the focus row — NOT parked in the backstage (Bug 1 — Invariant P)', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-detach-idle' });
+    const user = `crtr-detach-idle-user-${process.pid}-${Date.now().toString(36)}`;
+    try {
+        // A resident root + a live terminal child B. B is freshly booted: pi alive
+        // (pi_pid recorded at session_start), status active, and — critically — NO
+        // busy marker, since no turn ever fired. It is parked idle, not mid-turn:
+        // exactly the non-generating occupant Bug 1 is about.
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        const b0 = h.node(B);
+        assert.equal(b0.status, 'active', 'B active after boot');
+        const bPane = firstPaneOf(b0.window);
+        assert.ok(typeof bPane === 'string' && bPane !== '', 'B has a live pane');
+        // --- Put B into a USER viewport, FOCUSED (same precondition as the happy
+        //     path), but DO NOT mark it busy: it stays NOT generating.
+        spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600'], { stdio: 'ignore' });
+        assert.equal(spawnSync('tmux', ['break-pane', '-d', '-a', '-s', bPane, '-t', `${user}:`]).status, 0, 'B pane broke out into the user viewport (pi kept alive)');
+        const moved = paneLoc(bPane);
+        assert.equal(moved?.session, user, 'B pane physically in the user session now');
+        assert.equal(paneExistsReal(bPane), true, "B's pi is alive (parked idle, not mid-turn)");
+        closeDb();
+        setPresence(B, { pane: bPane, tmux_session: user, window: moved.window });
+        openFocusRow('f-detach-idle', bPane, user, B);
+        assert.equal(getFocusByNode(B)?.focus_id, 'f-detach-idle', 'precondition: B is FOCUSED, NON-generating');
+        // --- Drive the REAL verb on the non-generating focused node.
+        const res = h.cli(B, ['node', 'demote', '--node', B, '--pane', bPane, '--detach']);
+        assert.equal(res.code, 0, `node demote --detach exit 0\n${res.stderr}`);
+        assert.match(res.stdout, /detached="true"/, `the agent was detached\n${res.stdout}`);
+        closeDb();
+        const b = getNode(B);
+        // (b) RELEASED to dormant — idle + intent='idle-release' (revivable via inbox
+        //     / re-focus), NOT left active in the backstage.
+        assert.equal(b.status, 'idle', '(b) B released to dormant (status idle)');
+        assert.equal(b.intent, 'idle-release', "(b) B's intent is idle-release (daemon revives on inbox)");
+        // (c) the pane is REAPED / presence nulled — NOT relocated to the backstage
+        //     crtr session. The leaked live-idle pi must be gone.
+        assert.equal(paneExistsReal(bPane), false, '(c) B pane reaped (NOT parked alive in the backstage)');
+        assert.equal(b.pane, null, "(c) B's presence pane is nulled");
+        assert.equal(b.tmux_session, null, "(c) B's presence session is nulled (NOT the backstage crtr session)");
+        // (a) the focus row is CLOSED — no orphaned/phantom viewport.
+        assert.equal(getFocusByNode(B), null, '(a) B no longer occupies any focus (row CLOSED — Invariant P)');
+        assert.equal(getFocusByPane(bPane), null, '(a) NO phantom focus resolves on the reaped %id');
+        assert.equal(listFocuses().length, 0, '(a) no dangling focus rows remain');
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

package/dist/core/__tests__/draw-style.test.d.ts

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