@crouton-kit/crouter 0.3.28 → 0.3.30

package/dist/core/__tests__/full/broker-pane-resolution.test.js

@@ -20,11 +20,22 @@
 //     tears the broker down, and boots a fresh BROKER root the pane re-attaches
 //     to. LOCKED: the recycled node is finalized (done) and the fresh root is
 //     broker-hosted, not tmux.
+//
+// (3) Gap 3 (tests-lens MAJOR-1) — the §A.4 viewer-DEDUP, the headline new
+//     behavior of the broker-universal cut, had ZERO end-to-end coverage: a
+//     SECOND `node focus` on a node must REUSE/move its one viewer, never STACK a
+//     second. Only the DB UNIQUE(node_id)/GC layer was tested; `focus()` itself
+//     (placement.ts) was unexercised. LOCKED here over a REAL broker viewer: two
+//     `node focus` calls leave EXACTLY ONE viewer pane + ONE focus row for the
+//     node, the second reused IN PLACE (in_place=true). A focus() that always
+//     opened a fresh pane would yield two tagged panes (or crash on the UNIQUE
+//     constraint) — either way this goes RED.
 import { test, before, after } from 'node:test';
 import assert from 'node:assert/strict';
 import { spawnSync } from 'node:child_process';
 import { createHarness, hasTmux } from '../helpers/harness.js';
 import { closeDb } from '../../canvas/db.js';
+import { getFocusByNode, listFocuses } from '../../canvas/focuses.js';
 import { nodeInPane } from '../../../commands/node.js';
 import { recycleNode } from '../../runtime/recycle.js';
 let h;
@@ -47,6 +58,43 @@ function makePane() {
 function tagPane(pane, value) {
     spawnSync('tmux', ['set-option', '-p', '-t', pane, '@crtr_node', value], { stdio: 'ignore' });
 }
+/** Parse `crtr`'s human-list stdout (`- key: value` lines) into a map. */
+function parseList(stdout) {
+    const out = {};
+    for (const line of stdout.split('\n')) {
+        const m = /^- ([^:]+):\s*(.*)$/.exec(line.trim());
+        if (m)
+            out[m[1].trim()] = m[2].trim();
+    }
+    return out;
+}
+/** Read a pane's `@crtr_node` option ('' when unset / pane gone). */
+function paneTag(pane) {
+    const r = spawnSync('tmux', ['show-options', '-p', '-v', '-t', pane, '@crtr_node'], { encoding: 'utf8' });
+    return (r.stdout ?? '').trim();
+}
+/** Every pane in the harness session whose `@crtr_node` tag names `id` — the live
+ *  on-screen viewer panes for that node. A correct dedup keeps this at exactly 1. */
+function taggedViewerPanes(session, id) {
+    const r = spawnSync('tmux', ['list-panes', '-s', '-t', session, '-F', '#{pane_id} #{@crtr_node}'], { encoding: 'utf8' });
+    return (r.stdout ?? '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.endsWith(` ${id}`))
+        .map((l) => l.split(' ')[0]);
+}
+/** Wait until the attach client running in `pane` has self-tagged it `@crtr_node=id`
+ *  (the tag is set on CONNECT, not synchronously by openViewerWindow — the second
+ *  focus's reuse branch keys on it, so the test must let attach connect first). */
+async function waitForTag(pane, id, timeoutMs = 15_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (paneTag(pane) === id)
+            return;
+        await new Promise((r) => setTimeout(r, 150));
+    }
+    throw new Error(`viewer pane ${pane} never tagged @crtr_node=${id} within ${timeoutMs}ms`);
+}
 test('Gap 1 — nodeInPane resolves a broker node from its tagged viewer pane (undefined when untagged)', async (t) => {
     if (!hasTmux())
         return t.skip('tmux unavailable');
@@ -82,3 +130,45 @@ test('Gap 2 — recycle preserves the broker host: finalizes the node, boots a f
     assert.equal(fresh.host_kind, 'broker', 'fresh root PRESERVES the broker host (not a tmux pi root)');
     assert.equal(fresh.parent ?? null, null, 'fresh root is a root (parent=null)');
 });
+test('Gap 3 — a second `node focus` REUSES the one viewer (in place), never stacks a second pane/row', async (t) => {
+    if (!hasTmux())
+        return t.skip('tmux unavailable');
+    const broker = await h.spawnHeadlessChild(root, 'broker to focus twice');
+    closeDb();
+    assert.equal(h.node(broker).host_kind, 'broker', 'precondition: broker-hosted node');
+    // A caller pane in the harness session to focus BESIDE (the user's pane the
+    // viewer splits next to). The viewer lands in this same session, so the SECOND
+    // focus's reuse takes the in-session NAVIGATE path (in_place), not the
+    // cross-session MOVE path.
+    const caller = makePane();
+    // FOCUS #1 — a managed child boots with NO viewer (spawn no longer auto-opens
+    // one), so this OPENS the broker's single viewer beside the caller.
+    const f1 = h.cli(broker, ['node', 'focus', broker, '--pane', caller]);
+    assert.equal(f1.code, 0, `first focus exit 0\n${f1.stderr}`);
+    assert.equal(parseList(f1.stdout).focused, 'true', 'first focus brought the viewer on screen');
+    closeDb();
+    const row1 = getFocusByNode(broker);
+    assert.ok(row1 !== null && row1.pane !== null, 'focus #1 registered one viewer focus row');
+    const pane1 = row1.pane;
+    assert.equal(listFocuses().filter((f) => f.node_id === broker).length, 1, 'exactly ONE focus row for the node after focus #1');
+    // Let the attach client connect + self-tag the pane BEFORE the second focus —
+    // the reuse branch keys on `@crtr_node`; without the tag focus() would (correctly)
+    // treat the row as stale and open fresh. This wait is a test-timing concern, not
+    // a product gap (in real use the second focus is a much-later user action).
+    await waitForTag(pane1, broker);
+    assert.deepEqual(taggedViewerPanes(h.session, broker), [pane1], 'exactly ONE tagged viewer pane on screen after focus #1');
+    // FOCUS #2 — the headline dedup: the node already has a live, tagged viewer in
+    // the caller's session, so focus NAVIGATES to it (no new pane), never stacks.
+    const f2 = h.cli(broker, ['node', 'focus', broker, '--pane', caller]);
+    assert.equal(f2.code, 0, `second focus exit 0\n${f2.stderr}`);
+    const f2out = parseList(f2.stdout);
+    assert.equal(f2out.focused, 'true', 'second focus also on screen');
+    assert.equal(f2out.in_place, 'true', 'second focus REUSED the viewer in place (navigate, no new pane)');
+    // The invariant: STILL exactly one viewer pane + one focus row, the SAME pane.
+    closeDb();
+    const row2 = getFocusByNode(broker);
+    assert.ok(row2 !== null, 'the node still has its viewer focus row after focus #2');
+    assert.equal(row2.pane, pane1, 'focus #2 reused the SAME viewer pane (not a fresh one)');
+    assert.equal(listFocuses().filter((f) => f.node_id === broker).length, 1, 'STILL exactly ONE focus row for the node after focus #2 (never stacked a second)');
+    assert.deepEqual(taggedViewerPanes(h.session, broker), [pane1], 'STILL exactly ONE tagged viewer pane after focus #2 (reused, not stacked)');
+});

package/dist/core/__tests__/full/cascade-close.test.js

@@ -14,7 +14,13 @@
 // MIDDLE node with a live sideways-sibling subtree. This test fills exactly that
 // gap: it builds a real tree, closes the middle, and proves the reap is EXACTLY
 // the closed node's own subtree — nothing above (the ancestor) or sideways (a
-// sibling subtree) is touched, and real panes actually die.
+// sibling subtree) is touched, and the real broker engines actually die.
+//
+// VIEWER MODEL (a09b71f): a managed child boots as a detached headless BROKER
+// with NO viewer pane on spawn (a viewer is opened on demand via `node focus`).
+// So "the node is up" is broker-engine liveness — its recorded `pi_pid` is alive
+// — NOT pane presence. close tears that broker engine down (headlessBrokerHost
+// .teardown over view.sock), so we assert pid liveness, not panes.
 //
 // The tree (covers BOTH required shapes in one topology):
 //
@@ -47,6 +53,7 @@ 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 { isPidAlive } from '../../canvas/pid.js';
 function sessionExists(session) {
     return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
 }
@@ -72,7 +79,8 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
         {
             for (const id of [B, C, D, E, S, G]) {
                 assert.equal(h.status(id), 'active', `${id} active before close`);
-                assert.equal(h.paneAlive(id), true, `${id} has a live pane before close`);
+                const pid = h.node(id).pi_pid;
+                assert.ok(pid != null && isPidAlive(pid), `${id} broker engine alive before close`);
             }
             assert.equal(h.status(A), 'active', 'A (root) active before close');
             // Spine: A→{B,S}, B→{C,D}, C→{E}, S→{G} (all active spawn-seed edges).
@@ -124,12 +132,17 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
             assert.deepEqual({ status: e.status, intent: e.intent ?? null }, { status: 'canceled', intent: null }, "deepest reaped descendant E: (status,intent) === ('canceled', null)");
         }
         // ===================================================================
-        // ASSERT 2 — real panes destroyed for the ENTIRE subtree (invariant 12-ish:
-        // a torn-down node owns no pane). tearDownNode killed each real tmux pane.
+        // ASSERT 2 — broker ENGINE torn down for the ENTIRE subtree (the real
+        // "node is up" invariant now: a closed node owns no live broker process).
+        // close → headlessBrokerHost.teardown shut each broker down over view.sock.
         // ===================================================================
         for (const id of subtree) {
-            await h.waitForPaneGone(id);
-            assert.equal(h.paneAlive(id), false, `${id} real pane destroyed by close`);
+            await h.waitFor(() => {
+                const pid = h.node(id)?.pi_pid ?? null;
+                return pid === null || !isPidAlive(pid);
+            }, { label: `${id} broker engine torn down by close` });
+            const pid = h.node(id)?.pi_pid ?? null;
+            assert.ok(pid === null || !isPidAlive(pid), `${id} broker engine destroyed by close`);
         }
         // ===================================================================
         // ASSERT 3 — EXCLUSIVE-SUBTREE OWNERSHIP: nothing ABOVE (A) and nothing
@@ -153,10 +166,11 @@ test('cascade close: middle-node close reaps EXACTLY its subtree (canceled), anc
             assert.equal(added[0].from, B, 'the new entry is from the closed child B');
             assert.match(added[0].label, /closed/i, 'the new entry tells A its child B was closed');
         }
-        // Sideways subtree S→G — wholly alive: status active AND real panes alive.
+        // Sideways subtree S→G — wholly alive: status active AND broker engine alive.
         for (const id of sideways) {
             assert.equal(h.status(id), 'active', `${id} (sideways) still active — not reaped`);
-            assert.equal(h.paneAlive(id), true, `${id} (sideways) real pane still alive`);
+            const pid = h.node(id).pi_pid;
+            assert.ok(pid != null && isPidAlive(pid), `${id} (sideways) broker engine still alive`);
         }
         // The strong "EXACTLY its own subtree" closure: every node in the graph is
         // either in B's subtree (canceled) or untouched (active) — no over-reach.

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

@@ -1,204 +1,101 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/detach-focus.test.ts
+// Run with: node --import tsx/esm --test src/core/__tests__/full/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).
+// `crtr node demote --detach` on a node with a live viewer (Alt+C → D).
 //
-// 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).
+// BROKER-CUT ADAPTATION (taste/broker-is-the-host, 2026-06-10): every node is a
+// detached headless broker. After a09b71f a managed child opens NO viewer on
+// spawn — a viewer is opened on demand via `node focus`, registering its
+// `crtr attach` VIEWER pane in the focuses table. The engine is NOT in a pane, so the
+// pre-cut "relocate the still-running pi pane to the backstage" behavior —
+// detachToBackground's engine break-pane/release path, and its isGenerating()
+// gate that released a non-generating node to dormant — is DELETED. The Bug-1
+// non-generating-release test that locked that gate is deleted with it (the
+// behavior no longer exists; nothing to invent coverage for).
 //
-// 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.
+// What SURVIVES and is locked here: `node demote --detach` flips the node
+// terminal IN PLACE and CLOSES its viewer pane + focus row, leaving the broker
+// ENGINE running untouched (reconnectable by a later `focus`). This drives the
+// REAL verb (subprocess, AS the node) — the actual Alt+C → D menu path — against
+// a live broker node genuinely focused in a viewer pane, and proves:
+//   (a) lifecycle flips terminal in place,
+//   (b) the broker engine keeps running (pi_pid alive, unchanged — NOT killed),
+//   (c) the viewer pane is closed + its focus row dropped (no orphaned/phantom
+//       viewport row — Invariant P / F5).
 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 { getNode } from '../../canvas/canvas.js';
+import { getFocusByNode, getFocusByPane, listFocuses } from '../../canvas/focuses.js';
 import { closeDb } from '../../canvas/db.js';
-import { markBusy } from '../../runtime/busy.js';
+import { isPidAlive } from '../../canvas/pid.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;
+    return ((spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_id}'], { encoding: 'utf8' }).stdout ?? '').trim() ===
+        pane);
+}
+// Split a throwaway pane in the harness session; return its %id. The caller pane
+// `node focus` opens the viewer beside (a09b71f: spawn no longer auto-opens one).
+function makePane(session) {
+    const r = spawnSync('tmux', ['split-window', '-d', '-t', session, '-P', '-F', '#{pane_id}', 'sleep 100000'], { encoding: 'utf8' });
+    const pane = (r.stdout ?? '').trim();
+    assert.ok(pane.startsWith('%'), `expected a %pane_id, got "${pane}" (stderr: ${r.stderr})`);
+    return pane;
 }
 // ===========================================================================
-// `crtr node demote --detach` on a FOCUSED node (A3 gap close; Alt+C → D).
+// `crtr node demote --detach` on a node with a live viewer (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 () => {
+test('node demote --detach: flips terminal in place, CLOSES the viewer pane + focus row, broker engine keeps running', { 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.
+        // A resident root + a live terminal child B. spawnChild launches B's broker
+        // but opens NO viewer (a09b71f) — so B has no focus row yet.
         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");
+        const brokerPid = b0.pi_pid;
+        assert.ok(brokerPid != null && isPidAlive(brokerPid), 'B broker engine alive before detach');
+        // Put B genuinely "on screen": `node focus` opens its one `crtr attach`
+        // VIEWER pane beside a caller pane in the harness session, registering the
+        // viewer focus row (§A.3) — the on-demand viewer the detach then tears down.
+        const caller = makePane(h.session);
+        const focusRes = h.cli(B, ['node', 'focus', B, '--pane', caller]);
+        assert.equal(focusRes.code, 0, `node focus B exit 0\n${focusRes.stderr}`);
+        // The viewer pane is the node's on-screen presence (the focuses row `focus`
+        // registered) — NOT a node-row pane (a broker carries null placement).
         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']);
+        const viewerRow = getFocusByNode(B);
+        assert.ok(viewerRow !== null && viewerRow.pane !== null, 'B has a registered viewer focus row');
+        const viewerPane = viewerRow.pane;
+        assert.equal(paneExistsReal(viewerPane), true, 'B viewer pane is live on screen');
+        // --- Drive the REAL verb on the focused node (the Alt+C → D menu path). ---
+        const res = h.cli(B, ['node', 'demote', '--node', B, '--pane', viewerPane, '--detach']);
         assert.equal(res.code, 0, `node demote --detach exit 0\n${res.stderr}`);
-        assert.match(res.stdout, /relocated to the background/, `the agent was detached\n${res.stdout}`);
+        assert.match(res.stdout, /viewer closed \(broker still running off-screen\)/, `the viewer was closed\n${res.stdout}`);
         closeDb();
         const b = getNode(B);
-        // (a) lifecycle flipped to terminal IN PLACE.
+        // (a) lifecycle flipped to terminal IN PLACE (it was already terminal; the
+        //     demote is idempotent on lifecycle — the point is it does not end B).
         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(b.status, 'active', '(a) detach does NOT end the node — B stays active');
+        // (b) the broker ENGINE keeps running — detach closes only the viewer, never
+        //     the engine (the one-host invariant: the engine was never in a pane).
+        assert.equal(b.pi_pid, brokerPid, "(b) B's broker pid is UNCHANGED (engine not killed/respawned)");
+        assert.equal(isPidAlive(brokerPid), true, '(b) B broker engine still alive off-screen');
+        // (c) the viewer pane is CLOSED and its focus row dropped — no orphaned /
+        //     phantom viewport (A3 hazard / Invariant P).
+        await h.waitForPaneGone(B);
+        assert.equal(paneExistsReal(viewerPane), false, '(c) B viewer pane closed');
         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(getFocusByPane(viewerPane), null, '(c) NO phantom focus resolves on the closed viewer %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, /relocated to the background/, `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__/helpers/harness.d.ts

@@ -33,14 +33,11 @@ export interface HarnessOpts {
     /** HEADLESS mode: drive ONLY broker-hosted (paneless) nodes. When set the
      *  harness does NOT gate on tmux, does NOT eagerly create the isolated tmux
      *  session, and skips the per-pane `set-environment` seeding — nothing in a
-     *  headless run opens a window. CRTR_NODE_SESSION is still set to the isolated
-     *  name (and dispose still kill-sessions it) because `spawnChild` in spawn.ts
-     *  calls `ensureSession()` UNCONDITIONALLY to record each node's durable
-     *  `home_session` revive target — even a broker birth, which then ignores it.
-     *  So `node new --headless` may LAZILY create that one isolated session as a
-     *  side effect, but never a window/pane; the broker boots detached, supervised
-     *  by pid. Headless tests must use `spawnHeadlessChild`, never `spawnChild`
-     *  (which opens a real window). See createHeadlessHarness(). */
+     *  headless run opens a window. CRTR_NODE_SESSION/CRTR_ROOT_SESSION are still
+     *  scrubbed/restored for env hygiene, but no longer route placement: a managed
+     *  child opens NO viewer (it boots a detached broker, supervised by pid), and a
+     *  --root opens one viewer in the caller's current session. Headless tests must
+     *  use `spawnHeadlessChild`, never `spawnChild`. See createHeadlessHarness(). */
     headless?: boolean;
 }
 export interface SpawnOpts {
@@ -66,6 +63,7 @@ export interface FabricateOpts {
     intent?: ExitIntent;
     pi_pid?: number | null;
     pi_session_id?: string | null;
+    pi_session_file?: string | null;
     id?: string;
 }
 export interface Harness {
@@ -80,7 +78,6 @@ export interface Harness {
     turn(nodeId: string, text?: string): Promise<void>;
     stop(nodeId: string, reason?: 'stop' | 'length' | 'aborted' | 'error'): Promise<void>;
     finish(nodeId: string, finalText: string): Promise<void>;
-    yieldNode(nodeId: string, note: string): Promise<void>;
     tick(now?: number): Promise<void>;
     awaitBoot(nodeId: string, o?: {
         minCount?: number;