@crouton-kit/crouter 0.3.15 → 0.3.16

package/dist/builtin-personas/developer/orchestrator.md

@@ -4,7 +4,7 @@ roadmapSkill: development
 
 You are a **developer orchestrator** — a senior engineer who owns a feature-sized goal and delivers it by driving specialist children, never by writing the code yourself. Your children are `explore` (to map), `spec` (to specify), `plan` (to decompose), `developer` (to implement), and `review` (to validate). Keep them pointed at the right work with the right context, integrate what they return, and advance the goal phase by phase until it is genuinely done.
 
-Run the build as a delegation pipeline — spec → plan → implement → review → fix → validate — parallel wherever tasks are file-independent. Each phase clears a non-negotiable exit criterion before anything builds on it: implementation is done when it is **provably correct against the spec's acceptance criteria**, not when it compiles; review is done when an agent *other than the implementer* has read the diff and every Major and Critical finding is resolved; validation is done when the thing works end-to-end in the real runtime, exercised by something other than the code that produced it. Not every change earns the full pipeline — a one-line wrapper goes straight to implementation — but whatever phase you do run, it clears its bar.
+Before you shape the roadmap, read `crtr skill read development` for the roadmap shapes, development styles, and exit-criteria patterns for software goals. Run the build as a delegation pipeline — spec → plan → implement → review → fix → validate — parallel wherever tasks are file-independent. Each phase clears a non-negotiable exit criterion before anything builds on it: implementation is done when it is **provably correct against the spec's acceptance criteria**, not when it compiles; review is done when an agent *other than the implementer* has read the diff and every Major and Critical finding is resolved; validation is done when the thing works end-to-end in the real runtime, exercised by something other than the code that produced it. Not every change earns the full pipeline — a one-line wrapper goes straight to implementation — but whatever phase you do run, it clears its bar.
 
 Stay flexible, not waterfall. When a review exposes a flaw in the spec, re-delegate the **spec** phase — don't patch the implementation forward on a bad foundation. When an implementer reports unexpected complexity or a dependency the plan missed, fix the **plan** and re-delegate the affected tasks rather than asking the implementer to improvise. The bad phase is the one you re-run; patching downstream of a wrong upstream phase buries the flaw instead of removing it.
 

package/dist/builtin-personas/plan/orchestrator.md

@@ -8,6 +8,6 @@ Decompose by **domain seam, not raw size** — what forces a split is a boundary
 
 When you split, **synthesis is the load-bearing step — not the splitting.** As the only agent holding the whole picture, edit the part-plans into one coherent voice: resolve file-ownership conflicts, align naming and shared types across slices, and stress-test the seams no single sub-planner could see. Keep the master a small navigable index — a dependency task table over linked part-plans — because that is what forces the decomposition to be real instead of a flat dump.
 
-No consequential plan leaves your hands unreviewed. Fan out your plan-reviewer sub-kinds — the **requirements-coverage**, **pattern-consistency**, **code-smells**, **security**, and **architecture-fit** lenses in your spawnable menu — in parallel, then fold their findings back before you advance: a light plan folds one pass inside a single wake, a load-bearing one loops review → yield → revise → re-review across cycles until it is sound. Calibrate the roster to the stakes — a one-file wrapper change does not summon five lenses. Dispatch each reviewer with scope only — give it what to assess, never your own suspicions, so it finds problems independently instead of anchoring on your hint. Each reviewer reports findings, not verdicts; you decide what blocks, and a clean review is a valid and expected result.
+No consequential plan leaves your hands unreviewed. Fan out your plan-reviewer sub-kinds — the **requirements-coverage**, **pattern-consistency**, **code-smells**, **security**, and **architecture-fit** lenses in your spawnable menu — in parallel, then fold their findings back before you advance: a light plan folds one pass inside a single wake, a load-bearing one loops review → yield → revise → re-review across cycles until it is sound. Calibrate the roster to the stakes — a one-file wrapper change does not summon five lenses. Each reviewer reports findings, not verdicts; you decide what blocks, and a clean review is a valid and expected result.
 
 @include orchestration-kernel.md

package/dist/commands/chord.js

@@ -21,7 +21,7 @@ import { execFile } from 'node:child_process';
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { readConfig } from '../core/config.js';
-import { sendKeysEnter } from '../core/runtime/tmux.js';
+import { sendKeysEnter } from '../core/runtime/tmux-chrome.js';
 import { nodeInPane } from './node.js';
 import { getNode, subscribersOf, subscriptionsOf, view, fullName, } from '../core/canvas/index.js';
 const pexec = promisify(execFile);

package/dist/commands/human/shared.js

@@ -6,7 +6,7 @@ import { countPanesInCurrentWindow, spawnAndDetach, shellQuote } from '../../cor
 export const DECK_SCHEMA_HINT = 'Deck must match the humanloop deck schema: {title?, ' +
     'source?:{sessionName?,askedBy?,blockedSince?}, ' +
     'interactions:[{id,title,subtitle?,(body?|bodyPath?),options:[{id,label,' +
-    'description?,shortcut?}],multiSelect?,allowFreetext?,freetextLabel?,' +
+    'description?}],multiSelect?,allowFreetext?,freetextLabel?,' +
     "kind?:'notify'|'validation'|'decision'|'context'|'error'}]}.";
 export function resolveMaxPanes() {
     return readConfig('user').max_panes_per_window;

package/dist/commands/node.js

@@ -11,10 +11,9 @@ import { promote, requestYield } from '../core/runtime/promote.js';
 import { writeYieldMessage } from '../core/runtime/kickoff.js';
 import { reviveNode } from '../core/runtime/revive.js';
 import { demoteNode } from '../core/runtime/demote.js';
-import { detachToBackground, focus as placementFocus } from '../core/runtime/placement.js';
+import { detachToBackground, focus as placementFocus, windowAlive, windowOfPane, currentTmux } from '../core/runtime/placement.js';
 import { buildLaunchSpec } from '../core/runtime/launch.js';
 import { closeNode } from '../core/runtime/close.js';
-import { windowAlive, windowOfPane, currentTmux } from '../core/runtime/tmux.js';
 import { appendInbox } from '../core/feed/inbox.js';
 import { availableKinds } from '../core/personas/index.js';
 import { getNode, updateNode, listNodes, subscribe, unsubscribe, subscriptionsOf, subscribersOf, readContextTokens, } from '../core/canvas/index.js';

package/dist/commands/tmux-spread.js

@@ -10,13 +10,12 @@
 // meta.{tmux_session,window} goes stale — `windowAlive` would then report it
 // dormant and the daemon would spuriously revive it. After each join we
 // re-derive the child's location from its (stable) pane id and updateNode it,
-// mirroring the swap fix-up in presence.ts.
+// mirroring the swap fix-up in placement.ts.
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
 import { readConfig } from '../core/config.js';
 import { reviveNode } from '../core/runtime/revive.js';
-import { isNodePaneAlive, spreadNode } from '../core/runtime/placement.js';
-import { inTmux } from '../core/runtime/tmux.js';
+import { isNodePaneAlive, spreadNode, inTmux } from '../core/runtime/placement.js';
 import { nodeInPane } from './node.js';
 import { getNode, subscriptionsOf } from '../core/canvas/index.js';
 export const tmuxSpreadLeaf = defineLeaf({

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

@@ -140,8 +140,8 @@ test('Step 7: closing a FOCUSED node closes its focus row + nulls its pane (tear
     openFocusRow('fN', '%x', 'Sa', 'N');
     closeNode('N');
     // tearDownNode closes the focus row the node occupied and nulls its LOCATION.
-    // Non-vacuous: pre-Step-7 close used closeWindow/setFocus('') and never touched
-    // the focuses table, so getFocusByNode('N') would still return fN.
+    // Non-vacuous: pre-Step-7 close used closeWindow and never touched the focuses
+    // table, so getFocusByNode('N') would still return fN.
     assert.equal(getFocusByNode('N'), null, 'focus row closed by tearDownNode');
     assert.equal(getNode('N').pane ?? null, null, 'pane nulled (pane-keyed teardown)');
     assert.equal(getNode('N').status, 'canceled', 'node canceled as before');

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

@@ -1,9 +1,8 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/focuses.test.ts
 //
-// STEP 4 of the placement/focus migration: the `focuses` table + canvas setters
-// + placement reads + the transitional focus.ptr dual-write bridge. Purely
-// ADDITIVE: the table is populated in lockstep with the legacy `focus.ptr`, but
-// nothing reads it as authority yet (that switch is Step 6). Covers:
+// The `focuses` table (canvas.db, migration v6) + its canvas setters + the
+// placement reads that compose over them. The table is the CANONICAL focus store
+// — there is no focus.ptr file and no dual-write bridge. Covers:
 //   - migration v6 adds `focuses` to a fresh db (and a legacy v5 db migrates up);
 //     idempotent / forward-only on re-run + re-open
 //   - canvas setters/reads round-trip: open / setOccupant / setPane / close;
@@ -13,23 +12,17 @@
 //   - independent focus rows don't contend
 //   - placement focusOf / isFocused / focusByPane / focusedNodes / listFocuses
 //     agree with the rows
-//   - dual-write: setFocus populates the table; getFocus falls back to the table
-//     when focus.ptr is absent; setFocus('') clears both
 import { test, before, beforeEach, after } 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 { DatabaseSync } from 'node:sqlite';
 import { openFocusRow, setFocusOccupant, setFocusPane, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, listFocuses, } from '../canvas/focuses.js';
 import { openDb, closeDb, migrate, MIGRATIONS } from '../canvas/db.js';
-import { canvasDbPath, ensureHome, crtrHome } from '../canvas/paths.js';
+import { canvasDbPath, ensureHome } from '../canvas/paths.js';
 import { focusOf, isFocused, focusByPane, focusedNodes, listFocuses as placementListFocuses, } from '../runtime/placement.js';
-import { setFocus, getFocus } from '../runtime/presence.js';
 let home;
-// Saved/restored so the bridge always exercises its deterministic no-tmux path
-// regardless of whether the suite is run from inside a tmux session.
-let savedTmux;
 function userVersion(db) {
     return db.prepare('PRAGMA user_version').get().user_version;
 }
@@ -39,8 +32,6 @@ function tableNames(db) {
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-focuses-'));
     process.env['CRTR_HOME'] = home;
-    savedTmux = process.env['TMUX'];
-    delete process.env['TMUX'];
 });
 beforeEach(() => {
     closeDb();
@@ -50,8 +41,6 @@ after(() => {
     closeDb();
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
-    if (savedTmux !== undefined)
-        process.env['TMUX'] = savedTmux;
 });
 // ---------------------------------------------------------------------------
 // Migration v6 — the additive `focuses` table.
@@ -205,55 +194,3 @@ test('placement focus reads agree with the focus rows', () => {
     assert.deepEqual(focusedNodes(), new Set(['A', 'B']));
     assert.deepEqual(placementListFocuses().map((f) => f.node_id), ['A', 'B']);
 });
-// ---------------------------------------------------------------------------
-// Dual-write bridge — setFocus populates the table; getFocus falls back to the
-// table when focus.ptr is absent; setFocus('') clears both.
-// ---------------------------------------------------------------------------
-function focusPtrPath() {
-    return join(crtrHome(), 'focus.ptr');
-}
-test('setFocus populates the focuses table in lockstep with focus.ptr', () => {
-    openDb();
-    setFocus('A');
-    assert.equal(getFocus(), 'A', 'focus.ptr reads back');
-    const row = getFocusByNode('A');
-    assert.ok(row, 'a canonical focus row mirrors the current focus');
-    assert.equal(row?.node_id, 'A');
-    assert.equal(isFocused('A'), true, 'placement.isFocused agrees');
-    assert.deepEqual(focusOf('A')?.node_id, 'A', 'placement.focusOf agrees with getFocus');
-    // Re-focusing a different node re-points the SAME canonical row (no stray rows,
-    // UNIQUE(node_id) upheld).
-    setFocus('B');
-    assert.equal(getFocus(), 'B');
-    assert.equal(getFocusByNode('A'), null, 'the old occupant is dropped');
-    assert.equal(getFocusByNode('B')?.node_id, 'B');
-    assert.equal(listFocuses().length, 1, 'still exactly one canonical row');
-});
-test('getFocus falls back to the table when focus.ptr is absent', () => {
-    openDb();
-    setFocus('A'); // writes both focus.ptr and the canonical row
-    // Simulate a missing pointer (a writer that reached only the table, or a lost
-    // file): delete focus.ptr and confirm getFocus recovers the focus from the row.
-    if (existsSync(focusPtrPath()))
-        unlinkSync(focusPtrPath());
-    assert.equal(getFocus(), 'A', 'getFocus recovers the focus from the table');
-});
-test("setFocus('') clears both the pointer and the canonical focus row", () => {
-    openDb();
-    setFocus('A');
-    assert.equal(getFocus(), 'A');
-    assert.ok(getFocusByNode('A'), 'precondition: row present');
-    setFocus('');
-    assert.equal(getFocus(), null, 'getFocus is null after clear (ptr empty, no row)');
-    assert.equal(getFocusByNode('A'), null, 'the canonical row was closed');
-    assert.deepEqual(listFocuses(), [], 'no focus rows remain');
-});
-test('a focus row written directly (no focus.ptr) is visible through getFocus + placement', () => {
-    openDb();
-    // A writer that reached only the table (the canonical bridge row), with no
-    // focus.ptr on disk at all.
-    openFocusRow('__focus_ptr__', null, null, 'X');
-    assert.ok(!existsSync(focusPtrPath()), 'precondition: no focus.ptr file');
-    assert.equal(getFocus(), 'X', 'getFocus falls back to the canonical row');
-    assert.equal(isFocused('X'), true);
-});

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

@@ -18,7 +18,7 @@ import { createNode, getNode, updateNode } from '../canvas/canvas.js';
 import { nodeMetaPath } from '../canvas/paths.js';
 import { closeDb } from '../canvas/db.js';
 import { resolveBirthSession, homeSessionOf } from '../runtime/nodes.js';
-import { nodeSession } from '../runtime/tmux.js';
+import { nodeSession } from '../runtime/nodes.js';
 import { relaunchRoot } from '../runtime/reset.js';
 import { demoteNode } from '../runtime/demote.js';
 let home;

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,14 @@
 //      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';
 let home;
 let savedTmux;
 function node(id, over = {}) {
@@ -75,29 +72,6 @@ test('outgoingDisposition: a HOLDER / vanished node (no row) → KILL (never bac
     assert.deepEqual(outgoingDisposition({ exists: false, generating: false }), { 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');
-});
-// ---------------------------------------------------------------------------
 // 2. Gated real-tmux: the hot-swap. Two isolated sessions: `user` (the user's
 // terminal) + `back` (stand-in for the backstage `crtr`). Panes run `sleep`,
 // never a real pi; node pi_pid is set explicitly to control "generating".
@@ -168,7 +142,7 @@ 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 () => {
@@ -242,3 +216,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.
 });

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

@@ -11,10 +11,10 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode, getNode, subscribe, subscriptionsOf, view, listNodes, } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
+import { getFocusByNode, openFocusRow } from '../canvas/focuses.js';
 import { reportsDir, inboxPath, contextDir } from '../canvas/paths.js';
 import { roadmapPath } from '../runtime/roadmap.js';
 import { relaunchRoot, handleNewSession, markCleanExitDone, reapDescendants, } from '../runtime/reset.js';
-import { getFocus } from '../runtime/presence.js';
 import { renderForest } from '../canvas/render.js';
 let home;
 function node(id, over = {}) {
@@ -79,6 +79,7 @@ test('relaunchRoot parks the old root (done, edges intact, no wipe) and mints a
     createNode(node('grand', { parent: 'child' }));
     subscribe('root', 'child', true);
     subscribe('child', 'grand', true);
+    openFocusRow('fRoot', '%root', 'crtr', 'root'); // the old root occupies focus #1
     // Working state on the old root that parking must PRESERVE (no wipe).
     writeFileSync(roadmapPath('root'), '# Roadmap\nold goal\n');
     writeFileSync(inboxPath('root'), '{"ts":"x","from":"child","tier":"normal","kind":"update","label":"hi"}\n');
@@ -122,7 +123,9 @@ test('relaunchRoot parks the old root (done, edges intact, no wipe) and mints a
     assert.equal(fresh?.window, '@7');
     assert.ok(fresh?.launch, 'a fresh base launch spec was written');
     assert.equal(readdirSync(contextDir(newId)).length, 0, 'fresh empty context dir');
-    assert.equal(getFocus(), newId, 'focus follows content to the new root');
+    // Focus follows content: the focus row the old root held now shows the new root.
+    assert.equal(getFocusByNode(newId)?.focus_id, 'fRoot', 'focus row repointed to the new root');
+    assert.equal(getFocusByNode('root'), null, 'old root no longer occupies the focus');
 });
 // ---------------------------------------------------------------------------
 // #1b — handleNewSession success branch: root WITH a pane routes to relaunch
@@ -138,6 +141,7 @@ test('handleNewSession on a root with a pane returns path:relaunch + parks old,
     }));
     createNode(node('child', { parent: 'root' }));
     subscribe('root', 'child', true);
+    openFocusRow('fRoot', '%root', 'crtr', 'root'); // the old root occupies focus #1
     const respawn = okRespawn();
     const res = handleNewSession('root', 'newsess', 'test-pane', { relaunchRootInPane: respawn.fn });
     // The policy router's success return shape: relaunch + a fresh new node id.
@@ -156,7 +160,7 @@ test('handleNewSession on a root with a pane returns path:relaunch + parks old,
     assert.equal(fresh?.parent, null, 'new node is a root');
     assert.equal(fresh?.status, 'active', 'fresh root active');
     assert.equal(fresh?.spawned_by, 'root', 'audit-only successor link to old root');
-    assert.equal(getFocus(), res.newNodeId, 'focus follows to the fresh root');
+    assert.equal(getFocusByNode(res.newNodeId)?.focus_id, 'fRoot', 'focus row repointed to the fresh root');
 });
 // ---------------------------------------------------------------------------
 // #2 — handleNewSession on a non-root → session-id refresh only
@@ -238,6 +242,7 @@ test('a respawn dispatch failure rolls the whole transaction back and degrades t
         tmux_session: 'crtr',
         window: '@3',
     }));
+    openFocusRow('fRoot', '%root', 'crtr', 'root'); // the old root occupies focus #1
     const respawn = throwingRespawn();
     const res = handleNewSession('root', 'newsess', 'test-pane', { relaunchRootInPane: respawn.fn });
     assert.equal(res.path, 'reset-root', 'degraded to in-place reset');
@@ -256,7 +261,8 @@ test('a respawn dispatch failure rolls the whole transaction back and degrades t
     assert.deepEqual(actives, ['root'], 'only the old root is active — no zombie');
     assert.equal(listNodes({ status: ['dead'] }).length, 0, 'no dead zombie — new node row rolled back');
     assert.equal(listNodes().length, 1, 'only the old root row exists — the mint was fully undone');
-    assert.equal(getFocus(), 'root', 'focus restored to the old root');
+    // The focus repoint was INSIDE the txn, so ROLLBACK restored the old occupant.
+    assert.equal(getFocusByNode('root')?.focus_id, 'fRoot', 'focus row restored to the old root (rollback undid the repoint)');
 });
 // ---------------------------------------------------------------------------
 // #7 — markCleanExitDone guard table (termination rule)

package/dist/core/__tests__/tmux-surface.test.js

@@ -10,9 +10,9 @@
 //      redesign kills. This guards the bug's blast radius and should pass today.
 //
 //   2. The §5.1 "only placement.ts / tmux-chrome.ts import tmux.ts" lint guard
-//      (SKIPPED — warn only this step): placement.ts does not exist yet and many
-//      modules still import the driver directly, so this CANNOT pass until the
-//      migration completes. It flips to a hard assertion in Step 8.
+//      (ENFORCED as of Step 8): every other module reaches the driver through
+//      placement's re-exports or the tmux-chrome seam, so the only direct
+//      importers are placement.ts + tmux-chrome.ts (tmux.ts itself excluded).
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
@@ -71,11 +71,10 @@ test('§2.2 driver invariant: every placement verb in tmux.ts passes an explicit
     assert.ok(found >= 4, `expected to scan ≥4 placement verbs, saw ${found}`);
 });
 // ---------------------------------------------------------------------------
-// Lint guard — §5.1. WARN ONLY this step. Skipped because it cannot pass yet:
-// placement.ts (the sole sanctioned importer) does not exist, and the driver is
-// still imported directly by the runtime/daemon/command/stophook modules the
-// migration has not yet routed through placement. Step 8 deletes the skip and
-// turns the body into the enforced boundary.
+// Lint guard — §5.1, ENFORCED. The driver (tmux.ts) is imported ONLY by
+// placement.ts (the sanctioned model-over-driver, which re-exports the verbs
+// other modules need) and the tmux-chrome.ts chrome seam. Every other module —
+// runtime, daemon, commands, stophook, AND tests — must route through those.
 // ---------------------------------------------------------------------------
 /** Every `.ts` file under `src` (recursively), excluding nothing. */
 function allTsFiles(dir) {
@@ -97,7 +96,7 @@ function importsDriver(file) {
     // `tmux-spread.js` are NOT matched). Covers `from '...'` and `import('...')`.
     return [...src.matchAll(/(?:from|import\s*\()\s*'([^']+)'/g)].some((m) => basename(m[1]) === 'tmux.js');
 }
-test('§5.1 lint: only placement.ts / tmux-chrome.ts import the tmux driver', { skip: 'WARN-ONLY in Step 2 — placement.ts does not exist yet and many modules still import tmux.ts directly. Step 8 flips this to a hard error.' }, () => {
+test('§5.1 lint: only placement.ts / tmux-chrome.ts import the tmux driver', () => {
     const offenders = allTsFiles(SRC_ROOT)
         .filter((f) => !ALLOWED_IMPORTERS.has(basename(f)))
         .filter(importsDriver)

package/dist/core/canvas/db.js

@@ -196,9 +196,8 @@ function addPaneColumn(db) {
  *  viewport (Q7 widens canvas.db from "topology" to "topology + focuses"). Each
  *  row is anchored on the durable tmux `%pane_id`; `session` is a derived cache
  *  reconciled from the pane; `node_id` is UNIQUE so a node occupies at most one
- *  focus (Q5). Additive, forward-only — nothing reads it as authority yet (Step 4
- *  populates it in lockstep with the legacy `focus.ptr` via a transitional
- *  dual-write; the switch to table-as-authority lands in Step 6). */
+ *  focus (Q5). The focuses table is the CANONICAL focus store — there is no
+ *  focus.ptr file and no dual-write bridge; placement writes focus rows directly. */
 function addFocusesTable(db) {
     db.exec(`
 CREATE TABLE IF NOT EXISTS focuses (

package/dist/core/canvas/focuses.d.ts

@@ -15,8 +15,8 @@ export declare function closeFocusRow(focus_id: string): void;
 export declare function getFocusByNode(node_id: string): FocusRow | null;
 /** The focus realized by a given pane (`%id`), or null. */
 export declare function getFocusByPane(pane: string): FocusRow | null;
-/** A focus by its stable id, or null. (Used by the transitional focus.ptr
- *  dual-write bridge to read back its single canonical row; removed in Step 8.) */
+/** A focus by its stable id, or null. Used by placement to read a row back by id
+ *  (handFocusToManager / retargetFocus / registerRootFocus). */
 export declare function getFocusById(focus_id: string): FocusRow | null;
 /** Every focus row, ordered by id. */
 export declare function listFocuses(): FocusRow[];

package/dist/core/canvas/focuses.js

@@ -4,7 +4,8 @@
 // "topology + focuses", so the focus-row SQL lives here beside the node+edge
 // model, never in the runtime layer. A FOCUS is one durable on-screen viewport
 // bound to one node; the table is PLURAL (many focuses across windows/sessions),
-// the generalization of the old single `focus.ptr`.
+// the generalization of the old single focus pointer. It is the CANONICAL focus
+// store — there is no focus.ptr file and no dual-write bridge.
 //
 // placement.ts COMPOSES over these atomic setters/reads (the same way it calls
 // setPresence) — it never runs raw focus SQL itself.
@@ -66,8 +67,8 @@ export function getFocusByPane(pane) {
         .get(pane);
     return r ? focusFrom(r) : null;
 }
-/** A focus by its stable id, or null. (Used by the transitional focus.ptr
- *  dual-write bridge to read back its single canonical row; removed in Step 8.) */
+/** A focus by its stable id, or null. Used by placement to read a row back by id
+ *  (handFocusToManager / retargetFocus / registerRootFocus). */
 export function getFocusById(focus_id) {
     const r = openDb()
         .prepare('SELECT * FROM focuses WHERE focus_id = ?')

package/dist/core/canvas/types.d.ts

@@ -168,7 +168,7 @@ export interface Edge {
 /** A FOCUS row as stored in the `focuses` table (canvas.db, migration v6): one
  *  durable on-screen viewport the user looks at, bound to one node. Plural —
  *  many focuses live at once across windows and sessions (the plural
- *  generalization of the old single `focus.ptr`). Anchored on the durable tmux
+ *  generalization of the old single focus pointer). Anchored on the durable tmux
  *  `%pane_id`; `session` is a derived cache reconciled from the pane. `node_id`
  *  is UNIQUE — a node occupies at most one focus (Q5). */
 export interface FocusRow {

package/dist/core/runtime/close.js

@@ -130,8 +130,8 @@ export function closeNode(rootId) {
             transition(id, 'cancel');
             // 2) Tear the node off its placement (pane-keyed): close any focus row it
             //    occupies, kill its PANE (the window closes once its last pane goes, so
-            //    sibling nodes the user co-located in one window survive), null its
-            //    LOCATION, and clear focus.ptr if it was the current focus.
+            //    sibling nodes the user co-located in one window survive), and null its
+            //    LOCATION (closing the focus row is the record — no pointer to clear).
             tearDownNode(id);
             // 3) Leave the resume notice AFTER the watcher is gone, so it survives.
             appendInbox(id, {

package/dist/core/runtime/demote.js

@@ -16,12 +16,10 @@ import { join } from 'node:path';
 import { getNode, setPresence, updateNode, setFocusOccupant, fullName } from '../canvas/index.js';
 import { reportsDir } from '../canvas/paths.js';
 import { pushFinal } from '../feed/feed.js';
-import { spawnNode } from './nodes.js';
+import { spawnNode, nodeSession } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
-import { piCommand, paneLocation, nodeSession } from './tmux.js';
 import { FRONT_DOOR_ENV } from './front-door.js';
-import { getFocus, setFocus } from './presence.js';
-import { focusOf, recycleFocusPane } from './placement.js';
+import { focusOf, recycleFocusPane, piCommand, paneLocation } from './placement.js';
 import { ensureDaemon } from '../../daemon/manage.js';
 /** The agent's most recent surfaced message: the newest reports/*.md body with
  *  its YAML frontmatter stripped. Empty string when the node never reported. */
@@ -104,12 +102,9 @@ export async function demoteNode(nodeId, callerPane) {
     if (f !== null) {
         try {
             setFocusOccupant(f.focus_id, root.node_id);
-            setFocus(root.node_id);
         }
         catch { /* best-effort */ }
     }
-    else if (getFocus() === nodeId)
-        setFocus('');
     const fresh = getNode(root.node_id);
     const inv = buildPiArgv(fresh);
     const env = { ...inv.env, CRTR_ROOT_SESSION: nodeSession(), [FRONT_DOOR_ENV]: '1' };

package/dist/core/runtime/launch.d.ts

@@ -6,12 +6,14 @@ export declare const CANVAS_GOAL_CAPTURE_PATH: string;
 export declare const CANVAS_PASSIVE_CONTEXT_PATH: string;
 export declare const CANVAS_CONTEXT_INTRO_PATH: string;
 export declare const CANVAS_COMMANDS_PATH: string;
+export declare const CANVAS_RESUME_PATH: string;
 /** The canvas extensions every node loads, in order: stophook (routing +
  *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
  *  graph chrome), goal-capture (persist the first user message as the goal),
  *  passive-context (drain passive backlog as pre-text on the next message),
  *  context-intro (inject the <crtr-context> bearings block as its own session
- *  message, once per brand-new chat), commands (the /promote slash-command).
+ *  message, once per brand-new chat), commands (the /promote slash-command),
+ *  resume (the /resume-node whole-canvas picker → `crtr node focus`).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it
  *  reads the raw user text. */
 export declare const CANVAS_EXTENSIONS: string[];