@crouton-kit/crouter 0.3.28 → 0.3.30

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

@@ -1,297 +0,0 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/placement-teardown.test.ts
-//
-// STEP 7 of the placement/focus migration: the lifecycle-successor + teardown
-// verbs (§1.6/§2.3, flow (e)). Two PURE surfaces (no tmux — pane ids below are
-// 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 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';
-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 { createNode, getNode } from '../../canvas/canvas.js';
-import { openFocusRow, getFocusByNode, getFocusById } from '../../canvas/focuses.js';
-import { closeDb } from '../../canvas/db.js';
-import { handFocusToManager, tearDownNode } from '../../runtime/placement.js';
-let home;
-function node(id, over = {}) {
-    return {
-        node_id: id,
-        name: id,
-        created: new Date().toISOString(),
-        cwd: '/tmp/work',
-        kind: 'developer',
-        mode: 'base',
-        lifecycle: 'terminal',
-        status: 'active',
-        ...over,
-    };
-}
-function hasTmux() {
-    return spawnSync('tmux', ['-V'], { stdio: 'ignore' }).status === 0;
-}
-function tmuxOut(args) {
-    return (spawnSync('tmux', args, { encoding: 'utf8' }).stdout ?? '').trim();
-}
-function paneSession(pane) {
-    return tmuxOut(['display-message', '-p', '-t', pane, '#{session_name}']);
-}
-function windowCount(session) {
-    return tmuxOut(['list-windows', '-t', session, '-F', '#{window_id}']).split('\n').filter((s) => s !== '').length;
-}
-before(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-placement-teardown-'));
-    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'];
-});
-// ---------------------------------------------------------------------------
-// handFocusToManager (pure DB) — §1.6 manager-takeover + its three false-guards.
-// ---------------------------------------------------------------------------
-test('handFocusToManager: dormant idle-release manager → TAKEOVER (repoints the row, returns true)', () => {
-    openFocusRow('f', '%m', 'Sa', 'M');
-    // 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
-    // return value and the occupant assert fail.
-});
-test('handFocusToManager: managerId null → false, occupant UNCHANGED', () => {
-    openFocusRow('f', '%m', 'Sa', 'M');
-    assert.equal(handFocusToManager('f', null), false, 'no manager → caller must close the focus');
-    assert.equal(getFocusById('f')?.node_id, 'M', 'occupant unchanged');
-    // Non-vacuous: an impl that skipped the null guard would either return true or
-    // setFocusOccupant(f, null) → NOT NULL violation; the clean false + unchanged
-    // occupant fail against both.
-});
-test('handFocusToManager: manager IS the focus occupant → false (no self-handoff)', () => {
-    openFocusRow('f', '%m', 'Sa', 'M');
-    assert.equal(handFocusToManager('f', 'M'), false, 'handing a node its own focus is a no-op false');
-    assert.equal(getFocusById('f')?.node_id, 'M', 'occupant unchanged');
-    // Non-vacuous: an impl missing the `managerId === f.node_id` guard would return
-    // true.
-});
-test('handFocusToManager: manager already focused ELSEWHERE → false, neither focus moved (UNIQUE node_id)', () => {
-    openFocusRow('fM', '%m', 'Sa', 'M');
-    openFocusRow('fMgr', '%g', 'Sb', 'mgr'); // mgr already occupies its own viewport
-    assert.equal(handFocusToManager('fM', 'mgr'), false, 'a busy manager is not moved — caller closes');
-    assert.equal(getFocusById('fM')?.node_id, 'M', "M's focus is not handed over");
-    assert.equal(getFocusByNode('mgr')?.focus_id, 'fMgr', "mgr's other focus is untouched");
-    // Non-vacuous: an impl missing the already-focused guard would setFocusOccupant
-    // (fM, mgr) → UNIQUE(node_id) violation (mgr already in fMgr), so the expected
-    // clean false + both rows intact fail.
-});
-// ---------------------------------------------------------------------------
-// MAJOR 1 — the LIVE-vs-DORMANT manager split inside handFocusToManager.
-// ---------------------------------------------------------------------------
-test('handFocusToManager: LIVE backstage manager → swaps its pane INTO the focus slot (MAJOR 1)', { skip: !hasTmux() }, () => {
-    // Two real sessions: `user` (the viewport %m sits frozen in) + `back` (where
-    // the manager's pi runs live, the normal multi-child state). The swap is a
-    // real tmux op, so this needs a live server (gated like the other §5.2 tests).
-    const user = `crtr-hfm-user-${process.pid}`;
-    const back = `crtr-hfm-back-${process.pid}`;
-    spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600']);
-    spawnSync('tmux', ['new-session', '-d', '-s', back, '-c', '/tmp', 'sleep 600']);
-    try {
-        const userWindow = tmuxOut(['list-windows', '-t', user, '-F', '#{window_id}']).split('\n')[0];
-        const backWindow = tmuxOut(['list-windows', '-t', back, '-F', '#{window_id}']).split('\n')[0];
-        const focusPane = tmuxOut(['display-message', '-p', '-t', `${user}:${userWindow}`, '#{pane_id}']); // M's frozen focus pane (%m, the viewport)
-        const mgrPane = tmuxOut(['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${back}:${backWindow}`, 'sleep 600']); // mgr's LIVE backstage pane
-        createNode(node('M', { pane: focusPane, tmux_session: user, window: userWindow, status: 'done' }));
-        createNode(node('mgr', { pane: mgrPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid }));
-        openFocusRow('f', focusPane, user, 'M');
-        const userWinsBefore = windowCount(user);
-        assert.equal(handFocusToManager('f', 'mgr'), true, 'a LIVE manager takes the focus');
-        // Pure-DB takeover (also covered ungated above): occupant repointed M → mgr.
-        assert.equal(getFocusByNode('mgr')?.focus_id, 'f', 'the manager occupies the focus row');
-        assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies it');
-        // The synchronous swap (MAJOR 1): the focus row re-anchors to mgr's pane,
-        // which has physically moved into the user viewport; the old focus pane (%m)
-        // swapped down into the backstage slot; mgr's presence is the OLD focus slot.
-        assert.equal(getFocusById('f')?.pane, mgrPane, 'focus row re-anchored to the manager pane (swap)');
-        assert.equal(paneSession(mgrPane), user, 'the manager pane physically moved into the user viewport');
-        assert.equal(getNode('mgr').window, userWindow, 'manager presence window == the OLD focus slot window');
-        assert.equal(getNode('mgr').tmux_session, user, 'manager presence session == the viewport');
-        assert.equal(paneSession(focusPane), back, '%m (the dead node\'s pane) swapped DOWN into the backstage slot');
-        assert.equal(windowCount(user), userWinsBefore, 'no new user window — a swap, not an open (screen position invariant)');
-        // Non-vacuous: the pre-MAJOR-1 impl only repointed the occupant and deferred
-        // the physical revive to the daemon — but the daemon revives ONLY dormant
-        // managers, so a LIVE one is never brought in. That impl leaves the focus row
-        // pane == focusPane, mgrPane still in `back`, %m frozen in the viewport, and
-        // mgr's presence at the backstage — every swap assert above fails against it.
-    }
-    finally {
-        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
-        spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
-    }
-});
-// ---------------------------------------------------------------------------
-// BUG REGRESSION (lost focus pane on the push-final race): a focused child's
-// `crtr push final` seeds its manager's inbox MID-TURN; the daemon's second pass
-// can revive the dormant manager BACKSTAGE (the focus row still points at the
-// child) before the child's agent_end runs this handoff. At that point the
-// manager is status='active' with a real backstage pane whose pi is still
-// BOOTING — its recorded pi_pid is the OLD dead pid (the fresh pi records its
-// pid only at session_start). Pre-fix, MAJOR 1 gated on isPidAlive(pi_pid), so
-// it missed the booting manager; the dormant branch missed it too (no longer
-// idle-release) → handFocusToManager returned false → the stophook disarmed the
-// freeze and the USER'S VIEWPORT PANE REAPED while the manager ran on invisibly
-// backstage — the "pane gets lost" bug. The gate is now the PANE itself
-// (paneRunning: exists + command running), which a booting pi satisfies.
-// ---------------------------------------------------------------------------
-test('handFocusToManager (BUG REGRESSION): just-revived manager (RUNNING pane, STALE dead pi_pid) → swap, not reap', { skip: !hasTmux() }, () => {
-    const user = `crtr-hfm-race-user-${process.pid}`;
-    const back = `crtr-hfm-race-back-${process.pid}`;
-    spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600']);
-    spawnSync('tmux', ['new-session', '-d', '-s', back, '-c', '/tmp', 'sleep 600']);
-    try {
-        const userWindow = tmuxOut(['list-windows', '-t', user, '-F', '#{window_id}']).split('\n')[0];
-        const backWindow = tmuxOut(['list-windows', '-t', back, '-F', '#{window_id}']).split('\n')[0];
-        const focusPane = tmuxOut(['display-message', '-p', '-t', `${user}:${userWindow}`, '#{pane_id}']);
-        // The manager's backstage pane: a RUNNING command (the booting pi stand-in).
-        const mgrPane = tmuxOut(['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${back}:${backWindow}`, 'sleep 600']);
-        createNode(node('M', { pane: focusPane, tmux_session: user, window: userWindow, status: 'done' }));
-        // The just-revived state: active (transition 'revive'), intent cleared, but
-        // pi_pid NOT yet re-recorded — dead/stale (revive deliberately leaves it).
-        createNode(node('mgr', { pane: mgrPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: null }));
-        openFocusRow('f', focusPane, user, 'M');
-        assert.equal(handFocusToManager('f', 'mgr'), true, 'a booting just-revived manager takes the focus — the pane is what matters, not the stale pid');
-        assert.equal(getFocusByNode('mgr')?.focus_id, 'f', 'the manager occupies the focus row');
-        assert.equal(getFocusById('f')?.pane, mgrPane, 'focus row re-anchored to the manager pane (swap happened)');
-        assert.equal(paneSession(mgrPane), user, 'the booting manager pane physically moved into the user viewport');
-        // Non-vacuous: the pre-fix isPidAlive(mgr.pi_pid) gate fails on pi_pid=null →
-        // returns false without repointing → every assert above fails, and the caller
-        // would have reaped the user's pane.
-    }
-    finally {
-        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
-        spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
-    }
-});
-test('handFocusToManager: manager pane is a FROZEN remain-on-exit corpse (pane_dead=1) → false, no swap (dead-focus-pane guarantee holds under the pane gate)', { skip: !hasTmux() }, async () => {
-    const user = `crtr-hfm-corpse-user-${process.pid}`;
-    const back = `crtr-hfm-corpse-back-${process.pid}`;
-    spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600']);
-    spawnSync('tmux', ['new-session', '-d', '-s', back, '-c', '/tmp', 'sleep 600']);
-    try {
-        const userWindow = tmuxOut(['list-windows', '-t', user, '-F', '#{window_id}']).split('\n')[0];
-        const backWindow = tmuxOut(['list-windows', '-t', back, '-F', '#{window_id}']).split('\n')[0];
-        const focusPane = tmuxOut(['display-message', '-p', '-t', `${user}:${userWindow}`, '#{pane_id}']);
-        // A short-lived command frozen by remain-on-exit → pane EXISTS but pane_dead=1.
-        const mgrPane = tmuxOut(['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${back}:${backWindow}`, 'sleep 0.2']);
-        spawnSync('tmux', ['set-option', '-p', '-t', mgrPane, 'remain-on-exit', 'on'], { stdio: 'ignore' });
-        // Wait until tmux reports the pane dead (frozen corpse), bounded.
-        for (let i = 0; i < 50; i++) {
-            if (tmuxOut(['display-message', '-p', '-t', mgrPane, '#{pane_dead}']) === '1')
-                break;
-            await new Promise((r) => setTimeout(r, 100));
-        }
-        assert.equal(tmuxOut(['display-message', '-p', '-t', mgrPane, '#{pane_dead}']), '1', 'precondition: the manager pane is a frozen corpse');
-        createNode(node('M', { pane: focusPane, tmux_session: user, window: userWindow, status: 'done' }));
-        createNode(node('mgr', { pane: mgrPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: null }));
-        openFocusRow('f', focusPane, user, 'M');
-        assert.equal(handFocusToManager('f', 'mgr'), false, 'a corpse pane never claims the viewport — caller disarms + reaps');
-        assert.equal(getFocusByNode('mgr'), null, 'occupant NOT repointed (no stranded frozen focus)');
-        assert.equal(getFocusById('f')?.node_id, 'M', 'M still occupies the focus → caller runs closeFocusToShell');
-        // Non-vacuous: a gate of bare paneExists (existence without pane_dead) would
-        // swap the corpse into the viewport and return true — both asserts fail.
-    }
-    finally {
-        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
-        spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
-    }
-});
-test('handFocusToManager: DORMANT idle-release manager (dead pane) → occupant repointed, NO swap, focus pane UNCHANGED', () => {
-    openFocusRow('f', '%focus', 'Suser', 'M');
-    // 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');
-    // The split: with no physical swap, the focus row stays anchored on the ORIGINAL
-    // frozen focus pane (the pane the daemon will respawn the manager INTO) and the
-    // manager's backstage presence is left untouched.
-    assert.equal(getFocusById('f')?.pane, '%focus', 'focus row pane NOT re-anchored to the manager pane (no swap)');
-    assert.equal(getNode('mgr').pane, '%mgr-dead', 'manager presence pane unchanged');
-    assert.equal(getNode('mgr').window, '@wb', 'manager presence window unchanged (never moved into a viewport)');
-    // Non-vacuous: an impl that re-anchored the focus row to the manager pane in
-    // the DB (or wrote the manager's presence to the viewport) regardless of a real
-    // physical swap would set f.pane='%mgr-dead' and mgr.window=the focus window —
-    // both asserts fail. Proves the swap gates on PANE LIVENESS, not merely on the
-    // 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', () => {
-    createNode(node('M', { pane: null, window: null }));
-    openFocusRow('fM', null, 'Sa', 'M'); // M occupies a focus row
-    tearDownNode('M');
-    assert.equal(getFocusByNode('M'), null, 'the focus row M occupied is closed');
-    const m = getNode('M');
-    assert.equal(m.pane ?? null, null, 'pane nulled');
-    assert.equal(m.window ?? null, null, 'window nulled');
-    assert.equal(m.tmux_session ?? null, null, 'session nulled');
-    // Non-vacuous: an impl that skips closeFocusRow leaves fM → getFocusByNode('M')
-    // is non-null.
-});

package/dist/core/__tests__/home-session.test.js

@@ -1,186 +0,0 @@
-// Run with: node --import tsx/esm --test src/core/__tests__/home-session.test.ts
-//
-// STEP 1 of the placement/focus migration: the durable REVIVE-HOME field.
-// `home_session` separates a node's revive target from its live LOCATION so a
-// later step can kill the focus taint. This step only ADDS + POPULATES +
-// DEFAULTS the field — no behavior change. Covers:
-//   - home_session round-trips through meta.json (it IS durable identity)
-//   - the birth-session decision (`resolveBirthSession`) for the child /
-//     inline-root / --root cases each site sets home_session from
-//   - recycle + relaunch (pane-recycle) births populate home_session
-//   - a legacy meta with NO home_session defaults to tmux_session ?? nodeSession()
-import { test, before, after, beforeEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { createNode, getNode, updateNode } from '../canvas/canvas.js';
-import { nodeMetaPath } from '../canvas/paths.js';
-import { closeDb } from '../canvas/db.js';
-import { resolveBirthSession, homeSessionOf, childBackstageOf } from '../runtime/nodes.js';
-import { nodeSession } from '../runtime/nodes.js';
-import { relaunchRoot } from '../runtime/reset.js';
-import { recycleNode } from '../runtime/recycle.js';
-let home;
-function node(id, over = {}) {
-    return {
-        node_id: id,
-        name: id,
-        created: new Date().toISOString(),
-        cwd: '/tmp/work',
-        kind: 'general',
-        mode: 'base',
-        lifecycle: 'resident',
-        status: 'active',
-        ...over,
-    };
-}
-/** Make ensureDaemon (called by recycleNode) a no-op by faking a live daemon
- *  pidfile pointing at THIS test process — so no real daemon is ever spawned. */
-function fakeLiveDaemon() {
-    writeFileSync(join(home, 'crtrd.pid'), String(process.pid), 'utf8');
-}
-before(() => {
-    home = mkdtempSync(join(tmpdir(), 'crtr-homesession-'));
-    process.env['CRTR_HOME'] = home;
-});
-beforeEach(() => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-    delete process.env['CRTR_ROOT_SESSION'];
-    delete process.env['CRTR_NODE_SESSION'];
-});
-after(() => {
-    closeDb();
-    rmSync(home, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
-    delete process.env['CRTR_ROOT_SESSION'];
-    delete process.env['CRTR_NODE_SESSION'];
-});
-// ---------------------------------------------------------------------------
-// Persistence: home_session is DURABLE IDENTITY (meta.json), round-tripped by
-// createNode / getNode / updateNode — and NOT a runtime field.
-// ---------------------------------------------------------------------------
-test('home_session round-trips through meta.json and the hydrated view', () => {
-    createNode(node('n', { home_session: 'crtr', tmux_session: 'user-sess', window: '@1' }));
-    // On disk: meta.json carries home_session (identity), NOT the runtime LOCATION.
-    const raw = JSON.parse(readFileSync(nodeMetaPath('n'), 'utf8'));
-    assert.equal(raw['home_session'], 'crtr', 'home_session persisted to meta.json (durable identity)');
-    assert.ok(!('tmux_session' in raw), 'tmux_session stays a runtime field, not in meta.json');
-    // Hydrated view returns it; the live LOCATION is independent.
-    const m = getNode('n');
-    assert.equal(m?.home_session, 'crtr', 'getNode hydrates home_session');
-    assert.equal(m?.tmux_session, 'user-sess', 'home_session is distinct from the live LOCATION');
-});
-test('updateNode patches home_session (the demote rewriter path) and preserves it', () => {
-    createNode(node('n', { home_session: 'crtr' }));
-    updateNode('n', { home_session: 'recycled-sess' });
-    assert.equal(getNode('n')?.home_session, 'recycled-sess', 'home_session rewritten by updateNode');
-    // An unrelated identity patch leaves home_session intact (RMW round-trip).
-    updateNode('n', { description: 'a-handle' });
-    assert.equal(getNode('n')?.home_session, 'recycled-sess', 'home_session survives an unrelated identity edit');
-});
-// ---------------------------------------------------------------------------
-// The legacy / back-compat DEFAULT: a meta with no home_session reads back
-// tmux_session ?? nodeSession().
-// ---------------------------------------------------------------------------
-test('homeSessionOf: a present home_session is returned verbatim', () => {
-    createNode(node('n', { home_session: 'home-sess', tmux_session: 'live-sess' }));
-    assert.equal(homeSessionOf('n'), 'home-sess', 'the stored revive-home wins over the live LOCATION');
-});
-test('homeSessionOf: legacy meta (no home_session) defaults to tmux_session', () => {
-    createNode(node('legacy', { tmux_session: 'live-sess' }));
-    assert.equal(getNode('legacy')?.home_session, undefined, 'no home_session on a legacy node');
-    assert.equal(homeSessionOf('legacy'), 'live-sess', 'defaults to the last live LOCATION');
-});
-test('homeSessionOf: legacy meta with no LOCATION either defaults to nodeSession()', () => {
-    createNode(node('legacy', { tmux_session: null }));
-    assert.equal(homeSessionOf('legacy'), nodeSession(), 'falls through to the shared backstage');
-});
-test('homeSessionOf: the backstage default honors CRTR_NODE_SESSION', () => {
-    process.env['CRTR_NODE_SESSION'] = 'my-backstage';
-    createNode(node('legacy'));
-    assert.equal(homeSessionOf('legacy'), 'my-backstage', 'nodeSession() default is env-overridable');
-});
-test('homeSessionOf: unknown node falls back to the backstage', () => {
-    assert.equal(homeSessionOf('ghost'), nodeSession());
-});
-// ---------------------------------------------------------------------------
-// childBackstageOf — the session a node's CHILDREN spawn into (their
-// CRTR_ROOT_SESSION). REGRESSION for the front-door-root subtree-exile bug:
-// a refreshed inline root (home_session = a USER session it adopted) was
-// sourcing children's CRTR_ROOT_SESSION from home_session, so every yield
-// re-pointed its entire subtree into the user's working session. A root's
-// children must always flow to the shared backstage `nodeSession()`, never the
-// user session, while a managed child's children inherit its backstage
-// home_session. (Bug: node mq2u219p spawned all 13 children into `cli`.)
-// ---------------------------------------------------------------------------
-test('childBackstageOf: a managed child uses its backstage home_session', () => {
-    // A child's home_session is ALWAYS the backstage it was born into; its live
-    // tmux_session may be a user session (focus taint) but must NOT leak to kids.
-    createNode(node('child', { parent: 'p', home_session: 'crtr', tmux_session: 'user-sess' }));
-    assert.equal(childBackstageOf('child'), 'crtr', 'children inherit the backstage, not the tainted LOCATION');
-});
-test('childBackstageOf: a front-door ROOT routes children to the backstage, NOT its adopted user session', () => {
-    // The bug: an inline root adopts the user's session as home_session ('cli').
-    // Sourcing children's CRTR_ROOT_SESSION from home_session exiled the whole
-    // subtree into 'cli' on every refresh-yield. A root (parent === null) must
-    // route children to nodeSession() instead.
-    createNode(node('root', { parent: null, home_session: 'cli', tmux_session: 'cli' }));
-    assert.equal(childBackstageOf('root'), nodeSession(), "a root's children flow to the backstage");
-    assert.notEqual(childBackstageOf('root'), 'cli', 'NEVER the user session the root pane adopted');
-});
-test('childBackstageOf: a root honors CRTR_NODE_SESSION for the backstage', () => {
-    process.env['CRTR_NODE_SESSION'] = 'my-backstage';
-    createNode(node('root', { parent: null, home_session: 'cli' }));
-    assert.equal(childBackstageOf('root'), 'my-backstage', 'the backstage default is env-overridable');
-});
-test('childBackstageOf: unknown node falls back to the backstage', () => {
-    assert.equal(childBackstageOf('ghost'), nodeSession());
-});
-// ---------------------------------------------------------------------------
-// The birth-session decision each site sets home_session from. Pure, so the
-// child / inline-root / --root births are testable without a live tmux (the
-// real spawnChild/bootRoot are tmux + pi + process.exit coupled).
-// ---------------------------------------------------------------------------
-test('birth: a managed child homes to the shared backstage (nodeSession), never a user session', () => {
-    // No CRTR_ROOT_SESSION inherited, not adopting the caller.
-    assert.equal(resolveBirthSession({ adoptCaller: false, here: { session: 'user-sess' }, rootSession: undefined }), nodeSession(), 'a child ignores the caller session and homes to crtr');
-});
-test('birth: a managed child inherits CRTR_ROOT_SESSION as its backstage', () => {
-    assert.equal(resolveBirthSession({ adoptCaller: false, here: null, rootSession: 'crtr-subtree' }), 'crtr-subtree', 'the inherited root session is the child backstage');
-});
-test('birth: an independent --root inside tmux homes to the caller current session', () => {
-    assert.equal(resolveBirthSession({ adoptCaller: true, here: { session: 'user-sess' }, rootSession: 'crtr' }), 'user-sess', 'a --root adopts the caller session where the spawner is working');
-});
-test('birth: a --root NOT inside tmux falls back to the backstage', () => {
-    assert.equal(resolveBirthSession({ adoptCaller: true, here: null, rootSession: undefined }), nodeSession(), 'no caller session → the backstage');
-});
-test('birth: the inline front door (bootRoot) homes to its adopted session', () => {
-    // bootRoot adopts the caller session when inside tmux, else nodeSession().
-    assert.equal(resolveBirthSession({ adoptCaller: true, here: { session: 'term-sess' }, rootSession: undefined }), 'term-sess', 'inline root adopts the terminal it took over');
-    assert.equal(resolveBirthSession({ adoptCaller: true, here: null, rootSession: undefined }), nodeSession(), 'inline root with no tmux homes to the backstage');
-});
-// ---------------------------------------------------------------------------
-// Pane-recycle births populate home_session. relaunchRoot (option C) is fully
-// unit-testable (injected respawn, no tmux); recycleNode runs to completion with
-// no tmux (respawn dispatch just fails) once the daemon spawn is neutralized.
-// ---------------------------------------------------------------------------
-test('relaunch birth: the fresh root homes to the recycled pane session', () => {
-    createNode(node('root', { parent: null, lifecycle: 'resident', tmux_session: 'crtr', window: '@7' }));
-    // No live tmux → paneLocation(pane) is null → loc falls back to the old root's
-    // tmux_session ('crtr'); home_session must adopt it.
-    const res = relaunchRoot('root', 'test-pane', { relaunchRootInPane: () => { } });
-    assert.ok(res !== null, 'relaunchRoot minted a fresh root');
-    assert.equal(getNode(res.newNodeId)?.home_session, 'crtr', 'fresh root homes to the recycled pane session');
-});
-test('recycle birth: the recycled root populates home_session (backstage when no pane location)', async () => {
-    createNode(node('M', { parent: null, lifecycle: 'resident', tmux_session: 'crtr', window: '@3' }));
-    fakeLiveDaemon(); // createNode ensured the home dir; now neutralize ensureDaemon
-    // No live tmux → paneLocation('%0') is null → home_session defaults to the
-    // backstage. The respawn dispatch fails (no tmux), but the fresh root is still
-    // born — and must carry a populated home_session.
-    const res = await recycleNode('M', '%0');
-    assert.ok(res.newRoot !== null, 'recycle minted a fresh root');
-    assert.equal(getNode(res.newRoot)?.home_session, nodeSession(), 'recycled root homes to the backstage');
-});