@crouton-kit/crouter 0.3.15 → 0.3.17

package/dist/core/__tests__/live-mutation.test.js

@@ -0,0 +1,341 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/live-mutation.test.ts
+//
+// AXIS: LIVE MUTATION of the 2×2 state vector (mode {base,orchestrator} ×
+// lifecycle {terminal,resident}) while a node is ACTIVE/LIVE — driven through
+// the REAL `crtr node lifecycle` / `node promote` / `node demote` CLI verbs
+// against a live fake-pi, with the REAL stophook / kickoff / daemon hooks doing
+// the work. Every assertion reads the canvas data layer and is checked against
+// the state-model ORACLE (mq1su40t .../state-model.md).
+//
+// This file is ADDITIVE and uses ONLY the public Harness API + a couple of pure
+// test-local helpers (noted below). It does not edit harness.ts / fake-pi-host.ts
+// or any production file.
+//
+// Coverage rationale (grep of src/core/__tests__/ before writing):
+//   • persona.test.ts        — UNIT-level personaDrift/transitionGuidance (pure
+//                              functions; no live pi, no turn_end firing).
+//   • stop-guard.test.ts      — UNIT-level evaluateStop (no live flip via CLI).
+//   • daemon-liveness.test.ts — superviseTick over BORN-terminal idle-release
+//                              rows (never a live lifecycle FLIP).
+//   • flagship-lifecycle      — B born terminal idle-releases; A born resident
+//                              stays live; promote+turn fires the steer ONCE.
+// GENUINELY MISSING (this file): the LIVE FLIP itself — flipping a running
+// node's lifecycle/mode through the real verb and proving the runtime behavior
+// (idle-release vs dormant; persona-ack recompose; the A4 boundary) changes
+// accordingly. None of the above drives `crtr node lifecycle` on a live node,
+// nor asserts persona_ack mutation across a live promote, nor the A4 loss site.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHarness, hasTmux } from './helpers/harness.js';
+const SKIP = !hasTmux() ? 'tmux unavailable' : false;
+function sessionExists(session) {
+    return spawnSync('tmux', ['has-session', '-t', session], { stdio: 'ignore' }).status === 0;
+}
+// --- pure test-local helpers (candidates to fold into harness.ts later) -----
+/** The injected entries delivered as a turn-boundary `steer`. */
+function steers(inj) {
+    return inj.filter((e) => e.deliverAs === 'steer');
+}
+/** A steer carrying the base→orchestrator orchestration guidance. */
+function orchestrationSteers(inj) {
+    return steers(inj).filter((e) => /ORCHESTRATOR/i.test(e.content));
+}
+/** Normalize the two persona axes off a NodeMeta for deepEqual. */
+function persona(m) {
+    return { mode: m.mode, lifecycle: m.lifecycle };
+}
+/** The first %pane_id of a tmux window. The spawn path records window+session
+ *  but NOT pane (spawn.ts: pane is null until a reconcile/focus), so a node's
+ *  live pane must be resolved from its window here. */
+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) LIFECYCLE FLIP — `crtr node lifecycle` on a LIVE node, both directions,
+//     observing the idle-release behavior change. A round-trip on ONE live
+//     node (terminal→resident→terminal) proves both directions faithfully:
+//     a flipped-resident node no longer idle-releases (stays live, daemon does
+//     NOT release it); flipped-terminal it idle-releases again on pi-death.
+// ===========================================================================
+test('live lifecycle flip: terminal→resident suppresses idle-release; resident→terminal restores it', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-live-life' });
+    try {
+        // A (resident root, data-layer) ─ B (base/terminal, live) ─ C (base/terminal, live).
+        // B holds an ACTIVE live subscription to C → a TERMINAL B that stops is
+        // legitimately 'awaiting' (stop-guard) and would idle-release. That live
+        // sub is the precondition that makes the resident-vs-terminal flip the
+        // ONLY variable.
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        const C = await h.spawnChild(B, 'a subtask');
+        {
+            const b = h.node(B);
+            assert.deepEqual(persona(b), { mode: 'base', lifecycle: 'terminal' }, 'B born base×terminal');
+            assert.equal(b.status, 'active', 'B active');
+            assert.equal(b.intent ?? null, null, 'B no intent');
+            assert.equal(h.status(C), 'active', 'C active — B holds a live sub to it');
+            assert.ok(h.subscriptions(B).some((s) => s.node_id === C && s.active), 'B subscribes_to C (active) — the awaiting precondition');
+        }
+        // --- FLIP 1: terminal → RESIDENT (live). Oracle §4: sets lifecycle + the
+        // launch spec, status/intent UNTOUCHED. ---
+        {
+            const res = h.cli(B, ['node', 'lifecycle', 'resident', '--node', B]);
+            assert.equal(res.code, 0, `lifecycle resident exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.lifecycle, 'resident', 'B → resident');
+            assert.equal(b.mode, 'base', 'mode UNCHANGED by a lifecycle flip (orthogonal axis)');
+            assert.equal(b.status, 'active', 'status UNTOUCHED by node lifecycle (oracle §4)');
+            assert.equal(b.intent ?? null, null, 'intent UNTOUCHED by node lifecycle (oracle §4)');
+        }
+        // B stops AS RESIDENT: agent_end runs the stop-guard, which keys on
+        // lifecycle==='resident' → 'dormant' → the handler does NOT shut pi down
+        // (oracle §3a). So B stays active, pi alive, pane held — it does NOT
+        // idle-release despite holding the same live sub that would release a
+        // terminal node.
+        await h.stop(B);
+        // MINOR-2: asserting a NON-event (B must NOT idle-release) cannot be a single
+        // immediate read — h.stop() resolves once agent_end is RECORDED, BEFORE the
+        // handler completes, so a regression where the resident 'dormant' branch
+        // wrongly ran transition('release') + ctx.shutdown() asynchronously would
+        // still observe the pre-release state and false-pass. Instead POLL-STABLE:
+        // sample repeatedly across a real settle (a daemon tick partway, so the
+        // handler + a full superviseTick have both run) and assert the invariant
+        // holds on EVERY sample. A regression that idle-releases within the window
+        // is caught the moment it flips.
+        {
+            const deadline = Date.now() + 2_000;
+            let ticked = false;
+            for (;;) {
+                const b = h.node(B);
+                assert.equal(b.status, 'active', 'resident B stays ACTIVE on stop (dormant, not released)');
+                assert.equal(b.intent ?? null, null, 'resident B has NO idle-release intent');
+                assert.equal(h.paneAlive(B), true, 'resident B keeps its live pi/pane (no shutdown)');
+                assert.equal(h.status(C), 'active', 'C untouched while B is dormant-resident');
+                // Drive a real daemon decision pass midway: a superviseTick sees B
+                // active + pane-alive + pid-alive → handleLiveWindow 'leave'. If the
+                // daemon wrongly released a resident node, the next sample catches it.
+                if (!ticked) {
+                    await h.tick();
+                    ticked = true;
+                }
+                if (Date.now() >= deadline)
+                    break;
+                await new Promise((r) => setTimeout(r, 100));
+            }
+        }
+        // --- FLIP 2: resident → TERMINAL (live), on the now-resident live node. ---
+        {
+            const res = h.cli(B, ['node', 'lifecycle', 'terminal', '--node', B]);
+            assert.equal(res.code, 0, `lifecycle terminal exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.lifecycle, 'terminal', 'B → terminal');
+            assert.equal(b.status, 'active', 'status still UNTOUCHED by the flip');
+            assert.equal(b.intent ?? null, null, 'intent still UNTOUCHED by the flip');
+        }
+        // B stops AS TERMINAL now: stop-guard sees terminal + an active live sub to
+        // C → 'awaiting' → transition('release') + ctx.shutdown(). idle/idle-release;
+        // pi dies; UNFOCUSED backstage pane closes (oracle §3b). The exact behavior
+        // the resident flip had suppressed.
+        await h.stop(B);
+        await h.waitForStatus(B, 'idle');
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'idle', 'terminal B idle-releases on stop');
+            assert.equal(b.intent, 'idle-release', 'intent=idle-release (transition release)');
+        }
+        await h.waitForPaneGone(B);
+        assert.equal(h.paneAlive(B), false, 'unfocused terminal B → pane closed on idle-release');
+        assert.equal(h.status(C), 'active', 'C still active while B sleeps');
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});
+// ===========================================================================
+// (b) MODE FLIP — promote: base → orchestrator on a LIVE node. The flip itself
+//     does NOT commit the persona ack; the turn_end injector recomposes (commits
+//     the ack + delivers the steer) on the next turn, and a second turn is a
+//     no-op (drift cleared). Flagship asserts the steer fires once; the NEW
+//     assertions here are the persona_ack MUTATION across the live flip and the
+//     idempotence — neither is covered elsewhere.
+// ===========================================================================
+test('live mode flip: promote base→orchestrator recomposes persona_ack at turn_end (and is idempotent)', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-live-mode' });
+    try {
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        {
+            const b = h.node(B);
+            assert.deepEqual(persona(b), { mode: 'base', lifecycle: 'terminal' }, 'B born base×terminal');
+            // Invariant 11: born acked to its own persona → no spurious drift turn 1.
+            assert.deepEqual(b.persona_ack, { mode: 'base', lifecycle: 'terminal' }, 'persona_ack born equal to the initial persona (invariant 11)');
+        }
+        // PROMOTE (live): mode→orchestrator, lifecycle UNCHANGED, status/intent
+        // untouched (no transition). Crucially promote does NOT commit the ack —
+        // the drift is left PENDING for the injector.
+        {
+            const res = h.cli(B, ['node', 'promote', '--kind', 'developer']);
+            assert.equal(res.code, 0, `promote exit 0\n${res.stderr}`);
+            const b = h.node(B);
+            assert.equal(b.mode, 'orchestrator', 'B → orchestrator');
+            assert.equal(b.lifecycle, 'terminal', 'lifecycle UNCHANGED (promote is mode-only)');
+            assert.equal(b.status, 'active', 'status untouched by promote');
+            assert.equal(b.intent ?? null, null, 'intent untouched by promote');
+            assert.deepEqual(b.persona_ack, { mode: 'base', lifecycle: 'terminal' }, 'promote does NOT commit the ack — drift left PENDING for the injector');
+        }
+        // A TURN fires turn_end: personaDrift base→orchestrator → inject the
+        // orchestration guidance as a STEER, then commitPersonaAck. agent_end then
+        // stalls (orchestrator, no live sub, no final) → reprompt → B stays alive.
+        const injBefore = h.injected(B).length;
+        await h.turn(B, 'orchestrating');
+        const fresh = await h.waitFor(() => {
+            const slice = h.injected(B).slice(injBefore);
+            return orchestrationSteers(slice).length > 0 ? slice : null;
+        }, { timeoutMs: 15_000, label: 'base→orchestrator steer at turn_end' });
+        assert.ok(orchestrationSteers(fresh).length >= 1, 'turn_end delivered the orchestration guidance as a steer');
+        {
+            const b = h.node(B);
+            assert.deepEqual(b.persona_ack, { mode: 'orchestrator', lifecycle: 'terminal' }, 'persona RECOMPOSE committed: persona_ack advanced to the new persona at turn_end');
+            assert.equal(b.status, 'active', 'B not stranded — reprompt keeps it alive');
+        }
+        // IDEMPOTENCE: a SECOND turn finds no drift (ack already committed) → NO
+        // new persona steer is injected.
+        const injBeforeSecond = h.injected(B).length;
+        await h.turn(B, 'orchestrating again');
+        const afterSecond = h.injected(B).slice(injBeforeSecond);
+        assert.equal(orchestrationSteers(afterSecond).length, 0, 'no fresh orchestration steer on the second turn — drift cleared (idempotent recompose)');
+        assert.equal(h.node(B).mode, 'orchestrator', 'B still orchestrator');
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});
+// ===========================================================================
+// (b) MODE FLIP — demote. ⚑ FLAG vs the task framing ("demote orchestrator back
+//     to base; assert the mode field changes"): the `node demote` verb does NOT
+//     flip the SAME live node's mode orchestrator→base. Per ORACLE §4 (which
+//     matches the code: demote.ts) it FINISHES the node (push final → done) and
+//     RECYCLES the pane into a FRESH general/base/resident root — a DIFFERENT
+//     node. The demoted node keeps mode=orchestrator (it is merely `done`).
+//     There is NO live verb that flips a node orchestrator→base, so the
+//     persona.ts `baseModeGuidance` (orchestrator→base) is effectively
+//     UNREACHABLE via live mutation. This test pins the real behavior so the
+//     contradiction is visible; production is NOT changed.
+// ===========================================================================
+test('node demote is FINISH+RECYCLE, not an orchestrator→base mode flip (current behavior vs task framing)', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-live-demote' });
+    try {
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        // Promote B so it is genuinely an orchestrator before we demote it.
+        assert.equal(h.cli(B, ['node', 'promote', '--kind', 'developer']).code, 0, 'promote B');
+        const b0 = h.node(B);
+        assert.equal(b0.mode, 'orchestrator', 'B is orchestrator before demote');
+        // Resolve B's live %pane_id from its window (the row's `pane` is null until
+        // a reconcile; the spawn path records only window+session).
+        const pane = firstPaneOf(b0.window);
+        assert.ok(typeof pane === 'string' && pane !== '', 'B has a live pane to recycle');
+        // DEMOTE via the real verb (TMUX_PANE is scrubbed from child env → pass --pane).
+        const res = h.cli(B, ['node', 'demote', '--node', B, '--pane', pane]);
+        assert.equal(res.code, 0, `demote exit 0\n${res.stderr}`);
+        // The leaf renders `<demoted ... finalized=".." new_root=".."/>` (not JSON).
+        assert.match(res.stdout, /<demoted /, `demote recycled the pane\n${res.stdout}`);
+        const newRoot = /new_root="([^"]+)"/.exec(res.stdout)?.[1];
+        const finalized = /finalized="true"/.test(res.stdout);
+        // ⚑ The demoted node is FINISHED, not mode-flipped.
+        {
+            const b = h.node(B);
+            assert.equal(b.status, 'done', 'demoted node → done (finished), NOT re-roled');
+            assert.equal(b.intent, 'done', 'intent=done (finalize), per the push-final path');
+            assert.equal(b.mode, 'orchestrator', '⚑ demoted node KEEPS mode=orchestrator — demote is NOT an orchestrator→base flip');
+            assert.ok(finalized, 'demote pushed a final for the node');
+        }
+        // The fresh root is a DIFFERENT, BASE×RESIDENT node — that is where "base"
+        // comes from, not a mutation of B.
+        assert.ok(typeof newRoot === 'string' && newRoot !== B, 'a fresh root (≠ B) was minted');
+        {
+            const fresh = h.node(newRoot);
+            assert.deepEqual(persona(fresh), { mode: 'base', lifecycle: 'resident' }, 'recycled root is born base×resident (general)');
+            // Born acked to its own persona → it will never see an orchestrator→base
+            // drift steer: that persona path is unreachable through live mutation.
+            assert.deepEqual(fresh.persona_ack, { mode: 'base', lifecycle: 'resident' }, 'fresh root born acked base×resident — no orchestrator→base drift will ever fire');
+        }
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});
+// ===========================================================================
+// (b) A4 BOUNDARY — promote-then-yield emits a steer that is discarded. The
+//     oracle/flagship boundary: the base→orchestrator guidance lands as a STEER
+//     only if a turn_end fires while the drift is pending. A `node yield` on a
+//     base node auto-promotes (mode→orchestrator, ack NOT committed) and its
+//     agent_end goes STRAIGHT to reviveInPlace (b') with NO preceding turn_end —
+//     so the only steer-delivery site (turn_end) is BYPASSED. Two deterministic
+//     facts pin the boundary, both confirmed by direct observation:
+//       (1) NO orchestration STEER is ever delivered (the LOSS).
+//       (2) The ack is silently advanced base→orchestrator at the refresh DRAIN
+//           (reviveInPlace→drainBearings→commitPersonaAck), NOT via a steer — so
+//           neither this turn nor (per A4) the fresh revive re-offers it as a
+//           steer; the guidance survives only in the kickoff PROMPT it built.
+//     ⚑ FLAGGED (not fixed): the in-place refresh of this LARGE pending-drift
+//        kickoff prompt did NOT complete a fresh fake-pi boot in the harness (it
+//        stayed at 1 boot, intent=refresh, ack=orchestrator, pane alive) — a
+//        base→orchestrator yield's giant <persona-transition> kickoff pushed
+//        through respawn-pane did not bring up the fresh vehicle. Whether a real
+//        edge (oversized argv through respawn-pane) or a harness artifact, it is
+//        out of scope to fix; this test asserts only the deterministic boundary.
+// ===========================================================================
+test('A4: a base→orchestrator yield with no preceding turn_end loses the orchestration STEER (ack advances silently at the refresh drain)', { skip: SKIP, timeout: 120_000 }, async () => {
+    const h = await createHarness({ sessionPrefix: 'crtr-live-a4' });
+    try {
+        const A = h.spawnRoot('resident root');
+        const B = await h.spawnChild(A, 'do the work', { kind: 'developer' });
+        assert.deepEqual(persona(h.node(B)), { mode: 'base', lifecycle: 'terminal' }, 'B born base×terminal');
+        const injBefore = h.injected(B).length;
+        // `crtr node yield` (base → auto-promote → intent=refresh). INTERMEDIATE
+        // state, BEFORE any agent_end: mode flipped, ack NOT yet committed (the
+        // turn_end injector has not run), intent=refresh, drift PENDING.
+        const y = h.cli(B, ['node', 'yield', 'refresh against the roadmap']);
+        assert.equal(y.code, 0, `node yield exit 0\n${y.stderr}`);
+        {
+            const b = h.node(B);
+            assert.equal(b.mode, 'orchestrator', 'yield auto-promoted base→orchestrator');
+            assert.equal(b.intent, 'refresh', 'intent=refresh set by the yield');
+            assert.deepEqual(b.persona_ack, { mode: 'base', lifecycle: 'terminal' }, 'ack STILL base — promote/yield never commits it; only an injector does');
+        }
+        // Fire the stop: agent_end sees intent=refresh → (b') reviveInPlace, whose
+        // drainBearings commits the ack synchronously BEFORE the respawn. NO
+        // turn_end fires this turn, so the turn_end steer site is bypassed.
+        await h.stop(B);
+        // (2) The ack is silently advanced to orchestrator at the refresh DRAIN —
+        // not by any steer. (waitFor: the agent_end handler runs after h.stop
+        // observes the recorded event.)
+        await h.waitFor(() => {
+            const a = h.node(B)?.persona_ack;
+            return a?.mode === 'orchestrator' && a?.lifecycle === 'terminal';
+        }, { timeoutMs: 20_000, label: 'persona_ack advanced at the refresh drain (not via a steer)' });
+        assert.deepEqual(h.node(B).persona_ack, { mode: 'orchestrator', lifecycle: 'terminal' }, 'ack committed base→orchestrator by drainBearings during reviveInPlace');
+        // (1) ⚑ LOSS site: across the whole yield→refresh, NO orchestration
+        // guidance was ever delivered as a turn-boundary STEER (the only steer
+        // site, turn_end, never ran). The ack moved without the agent ever being
+        // steered with the new-role guidance — it survives only in the kickoff
+        // prompt drainBearings built for the (here, non-booting) fresh vehicle.
+        assert.equal(orchestrationSteers(h.injected(B).slice(injBefore)).length, 0, '⚑ A4: no orchestration STEER delivered — the turn_end injector was bypassed by the yield');
+    }
+    finally {
+        const session = h.session;
+        await h.dispose();
+        assert.equal(sessionExists(session), false, 'isolated session killed — no stray');
+    }
+});

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

@@ -1,12 +1,11 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/placement-focus.test.ts
 //
 // STEP 6 of the placement/focus migration: retargetFocus / openFocus / focus +
-// remain-on-exit + root-boot focus #1 + the focus.ptr bridge staying consistent.
+// remain-on-exit + root-boot focus #1.
 //
 // Two proof tiers (mirrors placement-revive.test.ts):
-//   1. PURE (no tmux): outgoingDisposition (backstage-vs-kill) and the focus.ptr
-//      dual-write bridge piggybacking on a real focus row WITHOUT clobbering it
-//      (the Step-6 bridge fix). Each is provably non-vacuous (a wrong impl fails).
+//   1. PURE (no tmux): outgoingDisposition (backstage-vs-kill). Provably
+//      non-vacuous (a wrong impl fails).
 //   2. Gated real-tmux: the hot-swap itself — screen position invariant (ZERO new
 //      user windows), the two post-swap LOCATIONs, outgoing backstaged (still
 //      generating) vs reaped (dormant), the Q5 vacate-old-focus path, openFocus
@@ -15,16 +14,15 @@
 //      a live server; gated {skip:!hasTmux()} like §5.2.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, existsSync, unlinkSync } from 'node:fs';
+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, setPresence } from '../canvas/canvas.js';
 import { openFocusRow, getFocusByNode, getFocusById, listFocuses, } from '../canvas/focuses.js';
 import { closeDb } from '../canvas/db.js';
-import { crtrHome } from '../canvas/paths.js';
-import { outgoingDisposition, retargetFocus, openFocus, focus as placementFocus, registerRootFocus, focusByPane, } from '../runtime/placement.js';
-import { setFocus, getFocus } from '../runtime/presence.js';
+import { outgoingDisposition, retargetFocus, openFocus, focus as placementFocus, registerRootFocus, focusByPane, detachToBackground, } from '../runtime/placement.js';
+import { markBusy, isBusy } from '../runtime/busy.js';
 let home;
 let savedTmux;
 function node(id, over = {}) {
@@ -61,41 +59,27 @@ after(() => {
         process.env['TMUX'] = savedTmux;
 });
 // ---------------------------------------------------------------------------
-// 1a. PURE: outgoingDisposition — backstage (still generating) vs kill.
+// 1a. PURE: outgoingDisposition — the 4-field truth table (kill / backstage /
+// release). Each branch is provably non-vacuous (a wrong impl fails).
 // ---------------------------------------------------------------------------
-test('outgoingDisposition: a still-generating node → BACKSTAGE (F2: keeps running off-screen)', () => {
-    assert.deepEqual(outgoingDisposition({ exists: true, generating: true }), { kind: 'backstage' });
-});
-test('outgoingDisposition: a dormant/done node → KILL (Invariant P: not-focused + not-generating ⇒ no pane)', () => {
-    assert.deepEqual(outgoingDisposition({ exists: true, generating: false }), { kind: 'kill' });
-});
 test('outgoingDisposition: a HOLDER / vanished node (no row) → KILL (never backstaged)', () => {
     // A wrong impl that backstaged a holder would leak a sleep pane into crtr.
-    assert.deepEqual(outgoingDisposition({ exists: false, generating: true }), { kind: 'kill' });
-    assert.deepEqual(outgoingDisposition({ exists: false, generating: false }), { kind: 'kill' });
+    assert.deepEqual(outgoingDisposition({ exists: false, live: false, resident: false, generating: false }), { kind: 'kill' });
+    assert.deepEqual(outgoingDisposition({ exists: false, live: true, resident: true, generating: true }), { kind: 'kill' });
 });
-// ---------------------------------------------------------------------------
-// 1b. PURE: the focus.ptr dual-write bridge PIGGYBACKS on a real focus row
-// (Step-6 fix) — setFocus must NOT clobber the pane-correct row retargetFocus
-// wrote. The OLD bridge closed `existing` unconditionally, replacing the real
-// row with a `__focus_ptr__` row; asserting the focus_id survives fails it.
-// ---------------------------------------------------------------------------
-test('focus.ptr bridge: setFocus piggybacks on a REAL focus row (never clobbers it)', () => {
-    // Simulate a real row written by retargetFocus/openFocus (a non-bridge id).
-    openFocusRow('real-f', '%a', 'Suser', 'A');
-    setFocus('A'); // the consistency mirror retargetFocus calls at the end
-    assert.equal(getFocus(), 'A', 'focus.ptr names the node');
-    const row = getFocusByNode('A');
-    assert.ok(row, 'A still occupies a focus');
-    assert.equal(row?.focus_id, 'real-f', 'the REAL row survived (not replaced by a bridge row)');
-    assert.equal(row?.pane, '%a', 'the pane-correct row is intact');
-    assert.equal(listFocuses().length, 1, 'no duplicate bridge row was inserted (UNIQUE node_id)');
-});
-test('focus.ptr bridge: a plain setFocus (no real row) still creates the bridge row + getFocus reads it', () => {
-    setFocus('Z');
-    if (existsSync(join(crtrHome(), 'focus.ptr')))
-        unlinkSync(join(crtrHome(), 'focus.ptr'));
-    assert.equal(getFocus(), 'Z', 'getFocus falls back to the canonical bridge row when the ptr is gone');
+test('outgoingDisposition: a done/dead node (not live) → KILL (Invariant P: not-focused + not-live ⇒ no pane)', () => {
+    assert.deepEqual(outgoingDisposition({ exists: true, live: false, resident: false, generating: false }), { kind: 'kill' });
+});
+test('outgoingDisposition: a RESIDENT node (editor/root) → BACKSTAGE (human-driven, NEVER despawned on focus-away)', () => {
+    // Resident wins even when NOT mid-turn — a wrong impl here KILLS the user\'s editor.
+    assert.deepEqual(outgoingDisposition({ exists: true, live: true, resident: true, generating: false }), { kind: 'backstage' });
+    assert.deepEqual(outgoingDisposition({ exists: true, live: true, resident: true, generating: true }), { kind: 'backstage' });
+});
+test('outgoingDisposition: a still-generating terminal worker → BACKSTAGE (F2: keeps running off-screen)', () => {
+    assert.deepEqual(outgoingDisposition({ exists: true, live: true, resident: false, generating: true }), { kind: 'backstage' });
+});
+test('outgoingDisposition: a PARKED terminal viewer (live, not mid-turn) → RELEASE (despawn to dormant — the stuck-green fix)', () => {
+    assert.deepEqual(outgoingDisposition({ exists: true, live: true, resident: false, generating: false }), { kind: 'release' });
 });
 // ---------------------------------------------------------------------------
 // 2. Gated real-tmux: the hot-swap. Two isolated sessions: `user` (the user's
@@ -147,9 +131,11 @@ test('retargetFocus: outgoing GENERATING → backstaged; the viewport stays put
     await withSessions('gen', async ({ user, back, userWindow, backWindow }) => {
         const focusPane = livePane(user, userWindow); // R's focus pane (the viewport)
         const backPane = livePane(back, backWindow); // A's live backstage pane
-        // R is the outgoing occupant, generating (a live pi_pid). A is incoming.
-        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        // R is the outgoing occupant, generating: a terminal worker MID-TURN (live
+        // pi_pid AND the busy marker set). A is incoming.
+        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', lifecycle: 'terminal', pi_pid: process.pid, home_session: back }));
         createNode(node('A', { pane: backPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        markBusy('R'); // R is genuinely mid-turn (isGenerating = busy && pidAlive)
         openFocusRow('f1', focusPane, user, 'R');
         const userBefore = windowIds(user).length;
         const res = retargetFocus('f1', 'A', NOREVIVE);
@@ -168,21 +154,47 @@ test('retargetFocus: outgoing GENERATING → backstaged; the viewport stays put
         assert.equal(paneExistsReal(focusPane), true, 'R\'s pane is alive (NOT reaped — it is still generating)');
         assert.equal(paneSession(focusPane), back, 'R\'s pane physically moved to the backstage');
         assert.equal(getNode('R').tmux_session, back, 'R\'s LOCATION session is the backstage');
-        assert.equal(getFocus(), 'A', 'focus.ptr followed the retarget');
+        assert.equal(focusByPane(backPane)?.node_id, 'A', 'the focus row tracks A after the retarget');
     });
 });
-test('retargetFocus: outgoing DORMANT (no live pi) → its now-backstage pane is REAPED (Invariant P)', { skip: !hasTmux() }, async () => {
+test('retargetFocus: outgoing DONE/dead (not live) → its now-backstage pane is REAPED (Invariant P)', { skip: !hasTmux() }, async () => {
     await withSessions('kill', async ({ user, back, userWindow, backWindow }) => {
         const focusPane = livePane(user, userWindow);
         const backPane = livePane(back, backWindow);
-        // R is NOT generating (pi_pid null) → its pane must be reaped after the swap.
-        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: null, home_session: back }));
+        // R is NOT live (status done) → the KILL path: its pane must be reaped after
+        // the swap, with NO lifecycle transition.
+        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'done', pi_pid: null, home_session: back }));
         createNode(node('A', { pane: backPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
         openFocusRow('f1', focusPane, user, 'R');
         retargetFocus('f1', 'A', NOREVIVE);
         assert.equal(getFocusByNode('A')?.focus_id, 'f1', 'A took the viewport');
         assert.equal(paneSession(backPane), user, 'A\'s pane is in the viewport');
-        assert.equal(paneExistsReal(focusPane), false, 'R\'s now-backstage pane was KILLED (dormant ⇒ no pane)');
+        assert.equal(paneExistsReal(focusPane), false, 'R\'s now-backstage pane was KILLED (not live ⇒ no pane)');
+        assert.equal(getNode('R').status, 'done', 'R stays done (KILL does not transition status)');
+        assert.equal(getNode('R').pane, null, 'R\'s LOCATION was nulled (Invariant P)');
+        assert.equal(getNode('R').tmux_session, null);
+    });
+});
+test('retargetFocus: outgoing PARKED terminal viewer (live pi, NOT mid-turn) → RELEASED to dormant (status idle, pane reaped) — the stuck-green fix', { skip: !hasTmux() }, async () => {
+    await withSessions('park', async ({ user, back, userWindow, backWindow }) => {
+        const focusPane = livePane(user, userWindow);
+        const backPane = livePane(back, backWindow);
+        // R is a terminal node revived only for VIEWING: live pi (pidAlive) but NOT
+        // mid-turn (no busy marker). It was the stuck-green bug: misread as
+        // generating, backstaged, and left status='active' forever. It must instead
+        // be RELEASED to dormant.
+        createNode(node('R', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', lifecycle: 'terminal', pi_pid: process.pid, home_session: back }));
+        createNode(node('A', { pane: backPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+        assert.equal(isBusy('R'), false, 'precondition: R is parked between turns (not mid-turn)');
+        openFocusRow('f1', focusPane, user, 'R');
+        retargetFocus('f1', 'A', NOREVIVE);
+        assert.equal(getFocusByNode('A')?.focus_id, 'f1', 'A took the viewport');
+        assert.equal(paneSession(backPane), user, 'A\'s pane is in the viewport');
+        // The fix: focus-away flips R back to dormant (idle + idle-release) and reaps
+        // its pane — so the editor stops drawing it green/active.
+        assert.equal(getNode('R').status, 'idle', 'R was RELEASED back to dormant (no longer stuck active/green)');
+        assert.equal(getNode('R').intent, 'idle-release', 'R carries idle-release so the daemon revives it on its inbox');
+        assert.equal(paneExistsReal(focusPane), false, 'R\'s now-backstage pane was REAPED (parked viewer ⇒ no pane)');
         assert.equal(getNode('R').pane, null, 'R\'s LOCATION was nulled (Invariant P)');
         assert.equal(getNode('R').tmux_session, null);
     });
@@ -242,3 +254,51 @@ test('focus front-door: round-trip open(register #1) → retarget in place → t
         assert.equal(focusByPane(aPane)?.node_id, 'A', 'the focus row tracks A\'s pane');
     });
 });
+// ---------------------------------------------------------------------------
+// Regression guards (review findings on HEAD=ccc3ee2): a detach/failed-open must
+// not leave a dangling focus row or an orphan viewport pane (Invariant P / F4).
+// ---------------------------------------------------------------------------
+test('detachToBackground: a FOCUSED node sent to the backstage CLOSES its focus row (Invariant P — no phantom viewport)', { skip: !hasTmux() }, async () => {
+    await withSessions('detach', async ({ user, back, userWindow }) => {
+        const prev = process.env['CRTR_NODE_SESSION'];
+        process.env['CRTR_NODE_SESSION'] = back; // detach relocates into THIS backstage session
+        try {
+            const focusPane = livePane(user, userWindow); // the node's foreground viewport pane
+            createNode(node('N', { pane: focusPane, tmux_session: user, window: userWindow, status: 'active', pi_pid: process.pid, home_session: back }));
+            openFocusRow('f1', focusPane, user, 'N'); // N is the focus occupant
+            assert.equal(getFocusByNode('N')?.focus_id, 'f1', 'precondition: N is focused');
+            const ok = detachToBackground('N', focusPane);
+            assert.equal(ok, true, 'the break to the backstage succeeded');
+            // The fix: N is now generating-but-UNFOCUSED, so its focus row is CLOSED.
+            assert.equal(getFocusByNode('N'), null, 'N no longer occupies any focus (row CLOSED — Invariant P)');
+            assert.equal(focusByPane(focusPane), null, 'NO phantom focus resolves on the relocated pane (%id survives the break)');
+            assert.equal(listFocuses().length, 0, 'no dangling focus rows remain');
+            // The pi keeps running — the pane is alive, just moved off-screen.
+            assert.equal(paneExistsReal(focusPane), true, 'N\'s pi keeps generating (pane alive, relocated not killed)');
+            assert.equal(paneSession(focusPane), back, 'N\'s pane physically moved to the backstage session');
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env['CRTR_NODE_SESSION'];
+            else
+                process.env['CRTR_NODE_SESSION'] = prev;
+        }
+    });
+});
+test('focus --new-pane: a FAILED retarget reaps the holder pane + focus row (no orphan viewport — F4/Invariant P)', { skip: !hasTmux() }, async () => {
+    await withSessions('newpane-fail', async ({ user, userWindow }) => {
+        const callerPane = livePane(user, userWindow); // the caller's pane we split beside
+        createNode(node('D', { status: 'active', pi_pid: null })); // D is DORMANT — no live pane
+        const winBefore = windowIds(user).length;
+        const panesIn = (s, w) => tmuxOut(['list-panes', '-t', `${s}:${w}`, '-F', '#{pane_id}']).split('\n').filter((x) => x !== '').length;
+        const panesBefore = panesIn(user, userWindow);
+        // A reviver that does NOTHING → D stays dormant, retargetFocus finds no live
+        // pin and returns focused:false. The just-opened holder must be reaped.
+        const noopRevive = () => { };
+        const res = placementFocus('D', { pane: callerPane, newPane: true, revive: noopRevive });
+        assert.equal(res.focused, false, 'D could not be placed → the --new-pane focus failed');
+        assert.equal(listFocuses().length, 0, 'the just-opened focus row was REAPED (no phantom)');
+        assert.equal(panesIn(user, userWindow), panesBefore, 'the holder split pane was REAPED (no leaked sleep pane)');
+        assert.equal(windowIds(user).length, winBefore, 'no window leaked');
+    });
+});

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

@@ -9,8 +9,7 @@
 //     not-already-focused manager; false (caller closes the focus) in each of the
 //     three guard cases. Each guard is asserted distinctly.
 //   • tearDownNode(nodeId) — close/reset teardown: close the focus row it
-//     occupies, null its LOCATION, and clear focus.ptr when it was the current
-//     focus.
+//     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';
@@ -21,7 +20,6 @@ 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';
-import { setFocus, getFocus } from '../runtime/presence.js';
 let home;
 function node(id, over = {}) {
     return {
@@ -166,18 +164,15 @@ test('handFocusToManager: DORMANT manager (dead pane) → occupant repointed, NO
 // ---------------------------------------------------------------------------
 // tearDownNode (pure DB; no tmux — pane is null so closePane never runs).
 // ---------------------------------------------------------------------------
-test('tearDownNode: closes the focus row, nulls the LOCATION, and clears focus.ptr', () => {
+test('tearDownNode: closes the focus row M occupied and nulls its LOCATION', () => {
     createNode(node('M', { pane: null, window: null }));
-    openFocusRow('fM', null, 'Sa', 'M');
-    setFocus('M'); // M is the current focus.ptr
+    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');
-    const cur = getFocus();
-    assert.ok(cur === null || cur === '', 'focus.ptr cleared (M was the current focus)');
     // Non-vacuous: an impl that skips closeFocusRow leaves fM → getFocusByNode('M')
-    // is non-null; one that skips the setFocus('') clear leaves focus.ptr at 'M'.
+    // is non-null.
 });