@crouton-kit/crouter 0.3.17 → 0.3.19

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

@@ -1,8 +1,8 @@
 import { type NodeRow, type FocusRow } from '../canvas/index.js';
-import { homeSessionOf } from './nodes.js';
-export { homeSessionOf };
+import { homeSessionOf, childBackstageOf } from './nodes.js';
+export { homeSessionOf, childBackstageOf };
 export type { FocusRow };
-export { piCommand, paneLocation, currentTmux, inTmux, ensureSession, openNodeWindow, focusWindow, windowAlive, windowOfPane, respawnPane, } from './tmux.js';
+export { piCommand, paneLocation, currentTmux, inTmux, ensureSession, openNodeWindow, splitWindow, focusWindow, windowAlive, windowOfPane, respawnPane, respawnPaneSync, setPaneOption, getPaneOption, paneCurrentPath, listLivePanes, } from './tmux.js';
 export type { RespawnPaneOpts } from './tmux.js';
 export { nodeSession } from './nodes.js';
 /** The focus a node occupies, or null. UNIQUE(node_id) ⇒ at most one. */
@@ -15,6 +15,16 @@ export declare function focusByPane(pane: string): FocusRow | null;
 export declare function focusedNodes(): Set<string>;
 /** Every focus row (every live viewport). */
 export declare function listFocuses(): FocusRow[];
+/** The on-screen viewport a human-in-the-loop prompt raised by `nodeId` should
+ *  surface into: the HIGHEST FOCUSED node of nodeId's graph — the focused node
+ *  closest to the graph root, i.e. the session/window the user is actually
+ *  watching this work in. Walks nodeId's spine to its root, enumerates the whole
+ *  tree root-first (`view` is BFS ⇒ shallowest first), and returns the focus row
+ *  of the first node that occupies a viewport. null when nothing in the graph is
+ *  on screen — the caller then surfaces in the user's attached pane rather than
+ *  the backstage node session. PURE (db reads only): no tmux probe, so the pane
+ *  may be stale; the caller liveness-checks before targeting it. */
+export declare function graphSurfaceTarget(nodeId: string): FocusRow | null;
 /** The cached LOCATION as stored on a node row: the authoritative `pane` handle
  *  plus its derived window/session cache. */
 export interface CachedLocation {
@@ -145,8 +155,10 @@ export declare function reviveTarget(focus: FocusRow | null, focusPaneAlive: boo
  *      nothing else. That is the structural bug-kill.
  *
  *  `setPresence` (the one atomic LOCATION write) records where the node landed.
- *  CRTR_ROOT_SESSION is forced to `homeSession` in BOTH branches so the node's
- *  children always flow to the backstage, never into the focus session. */
+ *  CRTR_ROOT_SESSION is forced to the node's children-backstage (childBackstageOf)
+ *  in BOTH branches so the node's children always flow to the backstage, never
+ *  into the focus session — and, for a front-door ROOT, never into the user
+ *  session its own pane adopted. */
 export declare function reviveIntoPlacement(nodeId: string, launch: ReviveLaunch): PlacementResult;
 /** Relocate a node's still-running agent to the background `crtr` session,
  *  freeing the foreground pane WITHOUT killing the pi. `break-pane` moves the
@@ -156,7 +168,15 @@ export declare function reviveIntoPlacement(nodeId: string, launch: ReviveLaunch
  *  CURRENT location, §2.4) and again after (presence FOLLOWS the move). No-op
  *  (false) when there is no live pane to relocate or tmux refuses the break.
  *  `pane` is the authoritative node pane the caller acts on (the Alt+C menu's
- *  `#{pane_id}`); falls back to the node's durable handle. */
+ *  `#{pane_id}`); falls back to the node's durable handle.
+ *
+ *  Invariant P gate (Bug 1): the backstage holds ONLY generating-but-unfocused
+ *  nodes. A node that is NOT mid-turn (e.g. a resident root parked idle between
+ *  turns, detached via Alt+C → D) must never be parked there as a live-idle pi —
+ *  nothing would re-enter agent_end to release it and, with no live subscription,
+ *  nothing would wake it, so it would hold a backstage pane forever, reaped by
+ *  nothing. Such a node is RELEASED to dormant instead (mirrors the parked-viewer
+ *  release on focus-away in retargetFocus). */
 export declare function detachToBackground(nodeId: string, pane?: string): boolean;
 /** A reviver: resume a DORMANT node into its backstage placement (a fresh `crtr`
  *  window via reviveIntoPlacement). Injected so placement.ts need not import
@@ -267,20 +287,28 @@ export declare function recycleFocusPane(nodeId: string, pane: string, launch: R
 /** §1.6 lifecycle successor — hand a truly-done focused node's viewport to its
  *  manager. Repoints the focus row `focusId` to `managerId` (a DB swap of the
  *  occupant). Two takeover realizations, split on the manager's liveness:
- *    - DORMANT manager (dead pi): the row repoint is all this does; the manager,
- *      woken by the finished node's `push final` landing in its inbox, is revived
- *      by the external daemon INTO this node's now-frozen focus pane
- *      (remain-on-exit), where reviveIntoPlacement's focus-pane branch resumes it
- *      in place — no new window, no taint. (UNCHANGED — the canonical takeover.)
+ *    - DORMANT manager (dead pi) — ONLY when it is idle + idle-release: the row
+ *      repoint is all this does; the manager, woken by the finished node's `push
+ *      final` landing in its inbox, is revived by the external daemon INTO this
+ *      node's now-frozen focus pane (remain-on-exit), where reviveIntoPlacement's
+ *      focus-pane branch resumes it in place — no new window, no taint. A dormant
+ *      manager that is NOT idle-release (done/dead/canceled, or idle with another
+ *      intent) is one the daemon will NEVER revive, so this returns false WITHOUT
+ *      repointing — the caller then disarms the freeze (see below).
  *    - LIVE manager (pi alive in the backstage, the normal multi-child state):
  *      the daemon never revives it (it only respawns dead-pi nodes), so we must
  *      bring it into the viewport SYNCHRONOUSLY here — swap its backstage pane
  *      into the focus slot (MAJOR 1). Otherwise the manager runs off-screen
  *      forever while %m sits orphaned in the viewport and the focus row lies
  *      about LOCATION.
- *  Returns false — the caller closes the focus (Q1) — when there is no manager,
- *  the manager IS this node, or the manager already occupies another viewport
- *  (UNIQUE node_id: do NOT move it, §1.6 edge).
+ *  Returns false — the caller closes the focus (Q1: closeFocusToShell disarms
+ *  remain-on-exit so the pane REAPS on exit) — whenever NO successor will claim
+ *  the frozen pane: no manager, the manager IS this node, the manager already
+ *  occupies another viewport (UNIQUE node_id: do NOT move it, §1.6 edge), the
+ *  manager row is missing, or it is a dormant manager the daemon won't revive
+ *  (not idle-release) / a live-but-paneless inline root. It does NOT repoint the
+ *  occupant on any false path — repointing while returning false would strand the
+ *  pane frozen forever with no reaper (the dead-focus-pane bug).
  *
  *  Why the live swap is NOT the forbidden self-saw: `swap-pane -d` only EXCHANGES
  *  two panes' slot positions; it never respawns or kills the finishing node's own

package/dist/core/runtime/placement.js

@@ -25,18 +25,22 @@
 // The robustness contract: a manual `move-pane`/`join-pane`/`break-pane` must
 // NEVER read as a node death. Liveness is pane-existence, not window-existence,
 // and reconcile makes crtr follow a move instead of fighting it.
-import { getRow, getRowByPane, getNode, setPresence, openDb, openFocusRow, setFocusOccupant, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, setFocusPane, listFocuses as listFocusRows, } from '../canvas/index.js';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { getRow, getRowByPane, getNode, setPresence, openDb, openFocusRow, setFocusOccupant, closeFocusRow, getFocusByNode, getFocusByPane, getFocusById, setFocusPane, listFocuses as listFocusRows, view, } from '../canvas/index.js';
 import { paneExists, paneLocation, paneOfWindow, windowAlive, windowOfPane, ensureSession, openNodeWindow, respawnPaneSync, respawnPaneDetached, breakPaneToSession, splitWindow, swapPaneInPlace, setRemainOnExit, closePane, currentTmux, joinPane, selectLayout, setWindowOption, switchClient, selectWindow, } from './tmux.js';
-import { homeSessionOf, nodeSession, newNodeId } from './nodes.js';
+import { homeSessionOf, childBackstageOf, nodeSession, newNodeId, rootOfSpine } from './nodes.js';
+import { nodeDir } from '../canvas/paths.js';
 import { isBusy } from './busy.js';
+import { isPidAlive } from '../canvas/pid.js';
 import { transition } from './lifecycle.js';
 // Re-export the durable REVIVE-HOME read so placement is the one front door for
 // "where does this node live."
-export { homeSessionOf };
+export { homeSessionOf, childBackstageOf };
 // Placement is the sanctioned model-over-driver (§2.1): non-placement runtime /
 // command modules that legitimately need a raw driver verb get it from here, so
 // the §5.1 lint can hold "only placement.ts / tmux-chrome.ts import tmux.ts".
-export { piCommand, paneLocation, currentTmux, inTmux, ensureSession, openNodeWindow, focusWindow, windowAlive, windowOfPane, respawnPane, } from './tmux.js';
+export { piCommand, paneLocation, currentTmux, inTmux, ensureSession, openNodeWindow, splitWindow, focusWindow, windowAlive, windowOfPane, respawnPane, respawnPaneSync, setPaneOption, getPaneOption, paneCurrentPath, listLivePanes, } from './tmux.js';
 export { nodeSession } from './nodes.js';
 // ---------------------------------------------------------------------------
 // Focus reads (Step 4) — COMPOSE over the canvas focuses table (§2.3/§4).
@@ -71,6 +75,27 @@ export function focusedNodes() {
 export function listFocuses() {
     return listFocusRows();
 }
+// ---------------------------------------------------------------------------
+// Graph → focus routing (for surfacing human-in-the-loop prompts)
+// ---------------------------------------------------------------------------
+/** The on-screen viewport a human-in-the-loop prompt raised by `nodeId` should
+ *  surface into: the HIGHEST FOCUSED node of nodeId's graph — the focused node
+ *  closest to the graph root, i.e. the session/window the user is actually
+ *  watching this work in. Walks nodeId's spine to its root, enumerates the whole
+ *  tree root-first (`view` is BFS ⇒ shallowest first), and returns the focus row
+ *  of the first node that occupies a viewport. null when nothing in the graph is
+ *  on screen — the caller then surfaces in the user's attached pane rather than
+ *  the backstage node session. PURE (db reads only): no tmux probe, so the pane
+ *  may be stale; the caller liveness-checks before targeting it. */
+export function graphSurfaceTarget(nodeId) {
+    const root = rootOfSpine(nodeId);
+    for (const id of [root, ...view(root)]) {
+        const f = getFocusByNode(id);
+        if (f !== null && f.pane !== null)
+            return f;
+    }
+    return null;
+}
 /** PURE reconciliation decision (§2.4) — unit-testable without a live tmux.
  *  Given the cached row LOCATION and what tmux currently reports, decide the
  *  presence patch. Mirrors the pure-core/impure-shell split (cf. `livenessVerdict`
@@ -209,8 +234,10 @@ export function reviveTarget(focus, focusPaneAlive, homeSession) {
  *      nothing else. That is the structural bug-kill.
  *
  *  `setPresence` (the one atomic LOCATION write) records where the node landed.
- *  CRTR_ROOT_SESSION is forced to `homeSession` in BOTH branches so the node's
- *  children always flow to the backstage, never into the focus session. */
+ *  CRTR_ROOT_SESSION is forced to the node's children-backstage (childBackstageOf)
+ *  in BOTH branches so the node's children always flow to the backstage, never
+ *  into the focus session — and, for a front-door ROOT, never into the user
+ *  session its own pane adopted. */
 export function reviveIntoPlacement(nodeId, launch) {
     // §2.4 — follow any manual pane move before acting.
     reconcile(nodeId);
@@ -218,9 +245,12 @@ export function reviveIntoPlacement(nodeId, launch) {
     const focusPaneAlive = focus !== null && focus.pane !== null && paneExists(focus.pane);
     const homeSession = homeSessionOf(nodeId);
     const decision = reviveTarget(focus, focusPaneAlive, homeSession);
-    // The node's children always spawn into the backstage (homeSession), never the
-    // focus session — force it regardless of which branch the node itself takes.
-    const env = { ...launch.env, CRTR_ROOT_SESSION: homeSession };
+    // The node's children always spawn into the backstage, never the focus session
+    // — force it regardless of which branch the node itself takes. childBackstageOf
+    // is home_session for a managed child but `nodeSession()` for a root (whose
+    // home_session may be a user session it adopted), so a refreshed front-door
+    // root never re-points its subtree into the user's session.
+    const env = { ...launch.env, CRTR_ROOT_SESSION: childBackstageOf(nodeId), CRTR_SUBTREE: rootOfSpine(nodeId) };
     if (decision.kind === 'focus-pane') {
         // F3: resume the pi INTO the live focus pane, in its CURRENT session (Q4 —
         // reconcileFocus follows a user move of the focus pane). No new window.
@@ -263,7 +293,15 @@ export function reviveIntoPlacement(nodeId, launch) {
  *  CURRENT location, §2.4) and again after (presence FOLLOWS the move). No-op
  *  (false) when there is no live pane to relocate or tmux refuses the break.
  *  `pane` is the authoritative node pane the caller acts on (the Alt+C menu's
- *  `#{pane_id}`); falls back to the node's durable handle. */
+ *  `#{pane_id}`); falls back to the node's durable handle.
+ *
+ *  Invariant P gate (Bug 1): the backstage holds ONLY generating-but-unfocused
+ *  nodes. A node that is NOT mid-turn (e.g. a resident root parked idle between
+ *  turns, detached via Alt+C → D) must never be parked there as a live-idle pi —
+ *  nothing would re-enter agent_end to release it and, with no live subscription,
+ *  nothing would wake it, so it would hold a backstage pane forever, reaped by
+ *  nothing. Such a node is RELEASED to dormant instead (mirrors the parked-viewer
+ *  release on focus-away in retargetFocus). */
 export function detachToBackground(nodeId, pane) {
     reconcile(nodeId);
     const row = getRow(nodeId);
@@ -276,6 +314,28 @@ export function detachToBackground(nodeId, pane) {
     // follows the right pane.
     if (row.pane !== target)
         setPresence(nodeId, { pane: target });
+    // Invariant P (Bug 1): a node that is NOT mid-turn must never be parked in the
+    // backstage as a live-idle pi (it would hold a backstage pane forever, reaped
+    // by nothing). Detaching such a node RELEASES it to dormant instead: close its
+    // focus, then — crash-safety, as in retargetFocus's release path — flip it to
+    // dormant (idle + intent='idle-release', revivable via inbox / re-focus) and
+    // null its LOCATION BEFORE reaping the pane, so a daemon tick can never catch a
+    // window-gone live node mid-reap and race to revive it. Unlike retargetFocus's
+    // outgoingDisposition (which keeps a RESIDENT node warm on focus-away), detach
+    // is a deliberate let-go: a non-generating node is released regardless of
+    // lifecycle. The status guard skips the transition for a done/dead/canceled
+    // node ('release' is legal only from active|idle) — it still reaps + nulls.
+    if (!isGenerating(nodeId)) {
+        const f = focusOf(nodeId);
+        if (f !== null)
+            closeFocusRow(f.focus_id);
+        if (row.status === 'active' || row.status === 'idle')
+            transition(nodeId, 'release');
+        setPresence(nodeId, { pane: null, tmux_session: null, window: null });
+        closePane(target);
+        return true;
+    }
+    // Generating → park in the backstage, keep running off-screen.
     const session = nodeSession();
     ensureSession(session, row.cwd);
     const ok = breakPaneToSession(target, session);
@@ -304,18 +364,6 @@ function holderId(focusId) {
 function newFocusId() {
     return `f-${newNodeId()}`;
 }
-/** signal-0 liveness probe for a pi pid (mirrors the daemon's isPidAlive). */
-function pidAlive(pid) {
-    if (pid == null)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (e) {
-        return e.code === 'EPERM';
-    }
-}
 /** Is a focus's OUTGOING occupant still GENERATING (a live pi actually MID-TURN)?
  *  A still-generating node is moved to backstage by a retarget (F2 — it keeps
  *  running off-screen); a holder / done / dormant / merely-parked node has its
@@ -327,7 +375,7 @@ function pidAlive(pid) {
  *  pid between turns; pid-alive would misclassify it as "doing work" and leave
  *  it stuck backstaged-active forever. `isBusy` is true only inside a turn, so a
  *  parked viewer reads as not-generating and is released to dormant on
- *  focus-away. The AND with `pidAlive` makes a stale marker (a pi that crashed
+ *  focus-away. The AND with `isPidAlive` makes a stale marker (a pi that crashed
  *  mid-turn) harmless. */
 function isGenerating(nodeId) {
     const row = getRow(nodeId);
@@ -335,7 +383,7 @@ function isGenerating(nodeId) {
         return false;
     if (row.status !== 'active' && row.status !== 'idle')
         return false;
-    return isBusy(nodeId) && pidAlive(row.pi_pid);
+    return isBusy(nodeId) && isPidAlive(row.pi_pid);
 }
 export function outgoingDisposition(o) {
     if (!o.exists)
@@ -535,6 +583,18 @@ export function focus(nodeId, opts) {
     const meta = getNode(nodeId);
     if (meta === null)
         return { focused: false, session: null, inPlace: false, revived: false };
+    // ── Phase-4 broker-focus opt-in (headless-broker model) ────────────────────
+    // A broker node has NO engine pane: headlessBrokerHost.launch spawns a
+    // DETACHED broker that hosts the single engine + binds view.sock, opening no
+    // tmux window. So focus cannot swap an engine pane into the caller's viewport
+    // — there is none. It instead (a) ensures the broker/engine is ALIVE via the
+    // sanctioned reviver, then (b) opens a tmux pane running the VIEWER
+    // `crtr attach to <id>`, which connects to view.sock. The viewer NEVER
+    // launches the engine (the one-writer invariant) — placement does, here. This
+    // is an ISOLATED opt-in BESIDE the engine-in-pane path: it fires ONLY for
+    // host_kind==='broker', so the tmux-host placement below stays byte-identical.
+    if (meta.host_kind === 'broker')
+        return focusBroker(nodeId, meta, opts);
     const callerPane = opts.pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
     if (callerPane === undefined || callerPane === '') {
         // Not in tmux — no viewport to swap into. Reconcile and report status.
@@ -564,6 +624,105 @@ export function focus(nodeId, opts) {
     }
     return retargetFocus(f.focus_id, nodeId, opts.revive);
 }
+const BROKER_FOCUS_SOCKET_WAIT_MS = 30_000;
+const BROKER_FOCUS_SOCKET_RETRY_MS = 100;
+/** Synchronously wait until a broker's view.sock accepts a connection. `focus()`
+ *  is sync today (the command layer calls it directly), so the readiness probe
+ *  lives in a short child Node process that can use async net events while this
+ *  process blocks in `spawnSync`. Success proves more than file existence: it is
+ *  robust to a stale leftover socket that the launching broker has not unlinked
+ *  yet, because only an accepting listener exits 0. */
+function waitForBrokerViewSocket(nodeId) {
+    const sockPath = join(nodeDir(nodeId), 'view.sock');
+    const probe = `
+const net = require('node:net');
+const sockPath = process.argv[1];
+const deadline = Date.now() + Number(process.argv[2]);
+const delay = Number(process.argv[3]);
+function attempt() {
+  let socket;
+  let settled = false;
+  const finish = (ok) => {
+    if (settled) return;
+    settled = true;
+    if (socket !== undefined) socket.destroy();
+    if (ok) process.exit(0);
+    if (Date.now() >= deadline) process.exit(1);
+    setTimeout(attempt, delay);
+  };
+  try {
+    socket = net.createConnection(sockPath);
+  } catch {
+    finish(false);
+    return;
+  }
+  socket.once('connect', () => finish(true));
+  socket.once('error', () => finish(false));
+  socket.setTimeout(delay, () => finish(false));
+}
+attempt();
+`;
+    const r = spawnSync(process.execPath, ['--input-type=commonjs', '-e', probe, sockPath, String(BROKER_FOCUS_SOCKET_WAIT_MS), String(BROKER_FOCUS_SOCKET_RETRY_MS)], {
+        stdio: 'ignore',
+        timeout: BROKER_FOCUS_SOCKET_WAIT_MS + 1_000,
+        // Keep the probe deterministic: NODE_OPTIONS like --input-type=module or
+        // --inspect-brk can break/hang a tiny `node -e` readiness check.
+        env: { ...process.env, NODE_OPTIONS: '' },
+    });
+    return r.status === 0;
+}
+/** Phase-4 broker-focus (headless-broker model) — open an attached VIEWER pane
+ *  for a node whose engine runs in a DETACHED broker (host_kind==='broker'), the
+ *  small opt-in beside the engine-in-pane path. Two steps:
+ *    (a) ENSURE THE BROKER (engine) IS ALIVE via the sanctioned launcher — the
+ *        injected reviver (reviveNode → headlessBrokerHost.launch). A broker's
+ *        liveness IS its recorded pid (headlessBrokerHost.isAlive ===
+ *        isPidAlive(pi_pid)); reviveNode's double-revive guard makes this
+ *        idempotent: already-alive → no-op, dead → launch ONE detached broker —
+ *        never a second engine. The VIEWER never does this; placement does.
+ *    (b) OPEN THE VIEWER PANE — after a bounded view.sock readiness wait (closes
+ *        the cold-start race against attach's single connect), split a pane
+ *        beside the caller running exactly the VIEWER command `crtr attach to
+ *        <id>`, which connects to view.sock and renders/drives the live engine.
+ *
+ *  No FOCUS ROW is registered: a broker viewer pane is NOT an engine pane (the
+ *  engine lives in the detached broker; pi_pid is the broker's), so it stays out
+ *  of the focuses table / reconcile / retargetFocus, which track engine-in-pane
+ *  swap semantics. (Repeated focus thus stacks viewers — accepted for the Phase-4
+ *  opt-in; the Phase-5 default-swap owns any viewer dedup.) Reaches no engine
+ *  launcher directly (placement must not import revive.ts/host.ts — a cycle):
+ *  step (a) goes through the injected `revive`, step (b) through the existing
+ *  splitWindow driver verb. `--new-pane` is moot — a broker focus is ALWAYS a
+ *  fresh viewer pane — so the flag is ignored. */
+function focusBroker(nodeId, meta, opts) {
+    const callerPane = opts.pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    if (callerPane === undefined || callerPane === '') {
+        // crtr is tmux-only: no viewport to open and no non-tmux fallback.
+        return { focused: false, session: null, inPlace: false, revived: false };
+    }
+    // (a) Ensure the broker is alive (idempotent). Capture prior liveness so the
+    //     FocusResult reports whether THIS focus had to launch it.
+    const wasAlive = isPidAlive(getNode(nodeId)?.pi_pid ?? null);
+    opts.revive(nodeId);
+    const revived = !wasAlive;
+    // Close the cold-start race: a freshly launched broker records pid during
+    // extension bind, then opens view.sock later; attach connects once and exits
+    // "no broker" if we split before listen(). Probe for an ACCEPTING socket (not
+    // mere path existence) before opening the viewer pane.
+    if (!waitForBrokerViewSocket(nodeId)) {
+        return { focused: false, session: null, inPlace: false, revived };
+    }
+    // Propagate CRTR_HOME so the viewer resolves the SAME canvas home (and thus
+    // the right view.sock) under a non-default override; otherwise an empty env
+    // (the split inherits the tmux server env, like every other crtr chrome pane).
+    const crtrHome = process.env['CRTR_HOME'];
+    const env = crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
+    // Node ids are shell-safe identifiers (base36-ts + hex); no quoting needed.
+    const pane = splitWindow(callerPane, { cwd: meta.cwd, env, command: `crtr attach to ${nodeId}` });
+    if (pane === null)
+        return { focused: false, session: null, inPlace: false, revived };
+    return { focused: true, session: paneLocation(pane)?.session ?? null, inPlace: false, revived };
+}
 /** Register the caller's CURRENT pane as a focus so a `node focus`/`cycle` from a
  *  pane that isn't yet a viewport retargets IN PLACE. Occupied by whatever node
  *  sits in the pane now (`callerNode`, else resolved by pane→row), or a HOLDER
@@ -625,20 +784,28 @@ export function recycleFocusPane(nodeId, pane, launch) {
 /** §1.6 lifecycle successor — hand a truly-done focused node's viewport to its
  *  manager. Repoints the focus row `focusId` to `managerId` (a DB swap of the
  *  occupant). Two takeover realizations, split on the manager's liveness:
- *    - DORMANT manager (dead pi): the row repoint is all this does; the manager,
- *      woken by the finished node's `push final` landing in its inbox, is revived
- *      by the external daemon INTO this node's now-frozen focus pane
- *      (remain-on-exit), where reviveIntoPlacement's focus-pane branch resumes it
- *      in place — no new window, no taint. (UNCHANGED — the canonical takeover.)
+ *    - DORMANT manager (dead pi) — ONLY when it is idle + idle-release: the row
+ *      repoint is all this does; the manager, woken by the finished node's `push
+ *      final` landing in its inbox, is revived by the external daemon INTO this
+ *      node's now-frozen focus pane (remain-on-exit), where reviveIntoPlacement's
+ *      focus-pane branch resumes it in place — no new window, no taint. A dormant
+ *      manager that is NOT idle-release (done/dead/canceled, or idle with another
+ *      intent) is one the daemon will NEVER revive, so this returns false WITHOUT
+ *      repointing — the caller then disarms the freeze (see below).
  *    - LIVE manager (pi alive in the backstage, the normal multi-child state):
  *      the daemon never revives it (it only respawns dead-pi nodes), so we must
  *      bring it into the viewport SYNCHRONOUSLY here — swap its backstage pane
  *      into the focus slot (MAJOR 1). Otherwise the manager runs off-screen
  *      forever while %m sits orphaned in the viewport and the focus row lies
  *      about LOCATION.
- *  Returns false — the caller closes the focus (Q1) — when there is no manager,
- *  the manager IS this node, or the manager already occupies another viewport
- *  (UNIQUE node_id: do NOT move it, §1.6 edge).
+ *  Returns false — the caller closes the focus (Q1: closeFocusToShell disarms
+ *  remain-on-exit so the pane REAPS on exit) — whenever NO successor will claim
+ *  the frozen pane: no manager, the manager IS this node, the manager already
+ *  occupies another viewport (UNIQUE node_id: do NOT move it, §1.6 edge), the
+ *  manager row is missing, or it is a dormant manager the daemon won't revive
+ *  (not idle-release) / a live-but-paneless inline root. It does NOT repoint the
+ *  occupant on any false path — repointing while returning false would strand the
+ *  pane frozen forever with no reaper (the dead-focus-pane bug).
  *
  *  Why the live swap is NOT the forbidden self-saw: `swap-pane -d` only EXCHANGES
  *  two panes' slot positions; it never respawns or kills the finishing node's own
@@ -654,19 +821,42 @@ export function handFocusToManager(focusId, managerId) {
         return false;
     if (getFocusByNode(managerId) !== null)
         return false; // manager already focused elsewhere
-    setFocusOccupant(focusId, managerId);
-    // MAJOR 1 — LIVE backstage manager → swap it into the focus slot now. DORMANT
-    // managers (no live pane / dead pi) fall through unchanged: the daemon revives
-    // them into the frozen %m async.
     const mgr = getRow(managerId);
-    if (mgr !== null && mgr.pane != null && isNodePaneAlive(mgr) && pidAlive(mgr.pi_pid) && f.pane != null) {
+    if (mgr === null)
+        return false; // no row to hand to
+    // MAJOR 1 — LIVE backstage manager → swap it into the focus slot NOW. The
+    // daemon never revives a live node (it only respawns dead-pi nodes), so this
+    // synchronous swap is the ONLY way a live manager claims the frozen %m. Commit
+    // the occupant repoint only here, on a path that genuinely takes the pane.
+    if (mgr.pane != null && isNodePaneAlive(mgr) && isPidAlive(mgr.pi_pid) && f.pane != null) {
+        setFocusOccupant(focusId, managerId);
         const focusLoc = paneLocation(f.pane); // F2's window/session — the slot mgr swaps INTO (%m is currently there)
         if (swapPaneInPlace(mgr.pane, f.pane) && focusLoc !== null) {
             setFocusPane(f.focus_id, mgr.pane, focusLoc.session); // re-anchor the focus row to mgr's pane (now in F2)
             setPresence(managerId, { pane: mgr.pane, tmux_session: focusLoc.session, window: focusLoc.window });
         }
+        return true; // took focus (live swap) — caller doesn't disarm
     }
-    return true; // still "took focus" — caller doesn't close
+    // DORMANT manager → it can only enter the frozen %m via crtrd.superviseTick's
+    // SECOND PASS, which revives a node ONLY when status==='idle' && intent===
+    // 'idle-release' (AND pi dead + unseen inbox). We mirror just status+intent: the
+    // other two are guaranteed by lifecycle invariants — every transition(_,
+    // 'release') site kills pi immediately, so idle-release ⟹ pi-dead; and the
+    // `push --final` that drove us into this done-branch just seeded the manager's
+    // inbox. (If a future idle-release path ever leaves pi LIVE, revisit this.)
+    // Mirror that predicate EXACTLY: a done/dead/
+    // canceled, an idle-but-not-idle-release, or a live-but-paneless (inline root)
+    // manager will NEVER be brought into this pane. Repointing for one of those
+    // makes the caller SKIP closeFocusToShell ⇒ remain-on-exit stays ON ⇒ the pane
+    // freezes forever with no reaper (the dead-focus-pane bug). So ONLY repoint +
+    // return true when the daemon will genuinely revive it; otherwise return false
+    // WITHOUT repointing so the caller disarms the freeze and the pane reaps on exit
+    // (§1.6 flow (b), close-out-completely).
+    const daemonWillRevive = mgr.status === 'idle' && mgr.intent === 'idle-release';
+    if (!daemonWillRevive)
+        return false;
+    setFocusOccupant(focusId, managerId); // repoint only; the daemon revives mgr INTO the frozen %m
+    return true;
 }
 /** Q1 close-to-shell for a truly-done focused node with no successor (§1.6 /
  *  flow (b)): close its focus row and DISARM the pane's

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

@@ -6,12 +6,6 @@ export interface PromoteResult {
     roadmapPath: string;
     /** Absolute path to the node's goal doc (context/initial-prompt.md). */
     goalPath: string;
-    /** Absolute path to the node-local memory index (context/memory/MEMORY.md). */
-    memoryPath: string;
-    /** Absolute path to the user-global memory index (<crtrHome>/memory/MEMORY.md). */
-    userMemoryPath: string;
-    /** Absolute path to the project memory index (<crtrHome>/projects/<key>/memory/MEMORY.md). */
-    projectMemoryPath: string;
 }
 /** Promote a node to an orchestrator (mode→orchestrator), optionally
  *  specializing its kind (e.g. a `general` worker becoming a

package/dist/core/runtime/promote.js

@@ -4,7 +4,7 @@
 //   1. Promotion → mode flips to orchestrator (mid-turn). This call flips the
 //      node's mode and (optionally) its KIND, REWRITES its launch spec to that
 //      kind's orchestrator persona (so the next revive comes back as that
-//      orchestrator), and seeds a roadmap scaffold + the three memory stores.
+//      orchestrator), and seeds a roadmap scaffold.
 //      The transition guidance the node needs is injected CENTRALLY by the
 //      persona injector (runtime/persona.ts) at the turn boundary — promote()
 //      itself no longer returns or hand-emits guidance.
@@ -22,7 +22,6 @@ import { getNode, updateNode } from '../canvas/index.js';
 import { transition } from './lifecycle.js';
 import { buildLaunchSpec } from './launch.js';
 import { hasRoadmap, seedRoadmap, roadmapPath } from './roadmap.js';
-import { seedMemory, memoryPath, seedUserMemory, userMemoryPath, seedProjectMemory, projectMemoryPath, } from './memory.js';
 import { readGoal, goalPath } from './kickoff.js';
 /** Promote a node to an orchestrator (mode→orchestrator), optionally
  *  specializing its kind (e.g. a `general` worker becoming a
@@ -58,13 +57,6 @@ export function promote(nodeId, opts = {}) {
         seedRoadmap(nodeId, goal !== null && goal.trim() !== '' ? { goal: goal.trim() } : {});
         roadmapWritten = true;
     }
-    // Seed all three scoped memory stores alongside the roadmap — user-global,
-    // project (keyed off this node's cwd), and node-local. Each is a durable,
-    // refresh-surviving artifact; each guarded so a re-seed never clobbers an
-    // evolved memory.
-    seedUserMemory();
-    seedProjectMemory(node.cwd);
-    seedMemory(nodeId);
     // Flip mode→orchestrator + kind + launch spec. Lifecycle is independent:
     // only set resident when the caller asked for it (the common self-promotion
     // stays terminal/orchestrator — it still reports up + reaps).
@@ -79,9 +71,6 @@ export function promote(nodeId, opts = {}) {
         roadmapWritten,
         roadmapPath: roadmapPath(nodeId),
         goalPath: goalPath(nodeId),
-        memoryPath: memoryPath(nodeId),
-        userMemoryPath: userMemoryPath(),
-        projectMemoryPath: projectMemoryPath(node.cwd),
     };
 }
 /** Request a refresh-yield: discard in-memory context and revive fresh against

package/dist/core/runtime/{demote.d.ts → recycle.d.ts}

@@ -1,7 +1,7 @@
-export interface DemoteResult {
+export interface RecycleResult {
     /** True when the pane was recycled (a fresh root respawned in it). */
-    demoted: boolean;
-    /** True when a `final` report was pushed for the demoted node. */
+    recycled: boolean;
+    /** True when a `final` report was pushed for the recycled node. */
     finalized: boolean;
     /** The fresh root node booted into the pane, or null on failure. */
     newRoot: string | null;
@@ -10,5 +10,5 @@ export interface DemoteResult {
 }
 /** Finish `nodeId` and recycle its pane into a fresh root. `callerPane` is the
  *  tmux pane the agent occupies (the Alt+C menu passes it as `#{pane_id}`).
- *  Best-effort; `demoted:false` when there is no pane to act on. */
-export declare function demoteNode(nodeId: string, callerPane?: string): Promise<DemoteResult>;
+ *  Best-effort; `recycled:false` when there is no pane to act on. */
+export declare function recycleNode(nodeId: string, callerPane?: string): Promise<RecycleResult>;

package/dist/core/runtime/{demote.js → recycle.js}

@@ -1,6 +1,6 @@
-// demote.ts — the "graduate this agent" action behind `crtr node demote`.
+// recycle.ts — the "finalize + reboot this pane" action behind `crtr node recycle`.
 //
-// Demote finishes the agent occupying a tmux pane and recycles that pane for
+// Recycle FINALIZES the agent occupying a tmux pane and recycles that pane for
 // fresh work, in three steps:
 //
 //   1. Finalize — push the agent's last surfaced message as a `final` report so
@@ -8,6 +8,10 @@
 //   2. Close    — kill the agent's pi (respawn-pane -k tears it down in place).
 //   3. Recycle  — boot a fresh resident root in that same pane (a new `crtr`).
 //
+// NOT to be confused with `node demote` (flip-to-terminal IN PLACE, which keeps
+// the agent focused and running): recycle ENDS this agent and boots a brand-new
+// resident root here.
+//
 // The agent's real conversation lives inside pi (not on disk), so the final
 // body is its newest report (which, on a natural stop, IS its last assistant
 // message) — falling back to a short note when it never reported.
@@ -16,10 +20,11 @@ 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, nodeSession } from './nodes.js';
+import { spawnNode, nodeSession, rootOfSpine } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { FRONT_DOOR_ENV } from './front-door.js';
 import { focusOf, recycleFocusPane, piCommand, paneLocation } from './placement.js';
+import { hostFor } from './host.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. */
@@ -49,18 +54,18 @@ function lastReportBody(nodeId) {
 }
 /** Finish `nodeId` and recycle its pane into a fresh root. `callerPane` is the
  *  tmux pane the agent occupies (the Alt+C menu passes it as `#{pane_id}`).
- *  Best-effort; `demoted:false` when there is no pane to act on. */
-export async function demoteNode(nodeId, callerPane) {
+ *  Best-effort; `recycled:false` when there is no pane to act on. */
+export async function recycleNode(nodeId, callerPane) {
     const meta = getNode(nodeId);
     if (meta === null)
-        return { demoted: false, finalized: false, newRoot: null, delivered: [] };
+        return { recycled: false, finalized: false, newRoot: null, delivered: [] };
     const pane = callerPane ?? process.env['TMUX_PANE'];
     if (pane === undefined || pane === '') {
-        return { demoted: false, finalized: false, newRoot: null, delivered: [] };
+        return { recycled: false, finalized: false, newRoot: null, delivered: [] };
     }
     // 1. Finalize — fan the agent's last message out as a `final`, mark it done.
     const body = lastReportBody(nodeId) ||
-        `Closed via demote — no final summary was authored by ${meta.name}.`;
+        `Closed via recycle — no final summary was authored by ${meta.name}.`;
     let delivered = [];
     let finalized = false;
     try {
@@ -69,6 +74,17 @@ export async function demoteNode(nodeId, callerPane) {
         finalized = true;
     }
     catch { /* recycle the pane even if the report failed */ }
+    // A broker node has NO tmux pane, so recycleFocusPane below (respawn-pane -k)
+    // never kills its engine — route its teardown through the Host seam so the
+    // broker PROCESS exits and releases the sole .jsonl writer (mirrors the T12
+    // close.ts/reset.ts fix; review reuse MINOR-3). Status is already flipped done
+    // by pushFinal above (crash-safe order: the daemon won't revive a done node).
+    if (meta.host_kind === 'broker') {
+        try {
+            hostFor(meta).teardown(nodeId);
+        }
+        catch { /* best-effort */ }
+    }
     // Capture M's focus viewport (if any) BEFORE nulling — the fresh root inherits
     // it (the SAME focus row + pane). The demoted node no longer holds a pane: it is
     // being reclaimed.
@@ -93,7 +109,7 @@ export async function demoteNode(nodeId, callerPane) {
         parent: null,
         launch,
     });
-    // REVIVE-HOME: a demote-recycled root's durable revive target is the session
+    // REVIVE-HOME: a recycled root's durable revive target is the session
     // of the pane it was recycled into (the one place home_session is rewritten
     // after birth). Falls back to the backstage when the pane can't be located.
     updateNode(root.node_id, { home_session: loc?.session ?? nodeSession() });
@@ -107,9 +123,9 @@ export async function demoteNode(nodeId, callerPane) {
     }
     const fresh = getNode(root.node_id);
     const inv = buildPiArgv(fresh);
-    const env = { ...inv.env, CRTR_ROOT_SESSION: nodeSession(), [FRONT_DOOR_ENV]: '1' };
+    const env = { ...inv.env, CRTR_ROOT_SESSION: nodeSession(), CRTR_SUBTREE: rootOfSpine(root.node_id), [FRONT_DOOR_ENV]: '1' };
     const ok = recycleFocusPane(root.node_id, pane, {
         command: piCommand(inv.argv), env, cwd: meta.cwd, name: fullName(fresh), resuming: false,
     });
-    return { demoted: ok, finalized, newRoot: root.node_id, delivered };
+    return { recycled: ok, finalized, newRoot: root.node_id, delivered };
 }