@crouton-kit/crouter 0.3.27 → 0.3.28

package/dist/core/runtime/broker.js

@@ -310,7 +310,7 @@ export async function runBroker(nodeId) {
         broadcast({ type: 'control_changed', controller_id: controllerId });
     };
     const buildSnapshot = () => ({
-        messages: session.messages,
+        messages: snapshotMessages(session),
         stats: session.getSessionStats(),
         state: {
             sessionId: session.sessionId,
@@ -907,6 +907,31 @@ export async function runBroker(nodeId) {
     }
 }
 // ---------------------------------------------------------------------------
+// snapshotMessages — the catch-up snapshot's ordered message history.
+//
+// The broker is the SOLE writer of the node's session `.jsonl`, so the session
+// manager's persisted tree (`buildSessionContext`) is the canonical, complete,
+// ordered history — byte-identical to what a dormant reader (crouter-web's static
+// normalizer) reconstructs from the same file. We serve THAT, NOT the agent's
+// live `session.messages` (`agent.state.messages`), because pi's recovery paths
+// mutate the live array away from the persisted history: auto-retry, context-
+// overflow recovery, and compaction each SLICE the errored/superseded assistant
+// message out of `state.messages` while DELIBERATELY keeping it on disk ("keep in
+// session for history", agent-session.js). So `session.messages` can OMIT — or, via
+// branch/compaction reshaping, reorder — a turn the `.jsonl` still holds. Pre-
+// close that drift is invisible (the live stream and the live array agree); after
+// a revive the welcome snapshot built from the reloaded array would diverge from
+// the on-disk history a dormant viewer just saw. Reconstructing from the session
+// manager makes the live snapshot == the persisted history (single source of
+// truth); the relayed live stream then continues from there.
+//
+// `AgentSession.sessionManager` is a public readonly field of the real pi SDK; the
+// fake-engine test fixture mirrors the same `sessionManager.buildSessionContext()`
+// surface, so this is a single path with no engine-capability fallback.
+export function snapshotMessages(session) {
+    return session.sessionManager.buildSessionContext().messages;
+}
+// ---------------------------------------------------------------------------
 // buildBrokerSession (plan T4 steps 2–4) — turn the launch recipe into a live
 // engine session via the pi SDK SERVICES path. Exported so the C3/C4 real-SDK
 // regression tests can drive the EXACT production wiring (not the mock).

package/dist/core/runtime/front-door.js

@@ -21,12 +21,19 @@ function isDir(p) {
         return false;
     }
 }
-/** Parse `[dir] [prompt]` positionals + `--name`/`--kind` flags out of the
- *  leftover tokens after the bare `crtr`. */
+/** The `--`flags the front door OWNS (everything else after a bare `crtr` is a
+ *  positional dir/prompt). A leading token in this set still boots a root —
+ *  without it, `crtr --headless` / `crtr --name X` would fall through to the
+ *  dispatcher and error as an unknown subcommand. */
+const FRONT_DOOR_FLAGS = new Set(['--name', '--kind', '--headless', '--no-headless']);
+/** Parse `[dir] [prompt]` positionals + the front-door flags out of the leftover
+ *  tokens after the bare `crtr`. `headless` is tri-state: `true`/`false` from an
+ *  explicit `--headless`/`--no-headless`, `undefined` to defer to the config. */
 function parseRootArgs(tokens) {
     let cwd = process.cwd();
     let name;
     let kind;
+    let headless;
     const positionals = [];
     for (let i = 0; i < tokens.length; i++) {
         const t = tokens[i];
@@ -36,6 +43,12 @@ function parseRootArgs(tokens) {
         else if (t === '--kind') {
             kind = tokens[++i];
         }
+        else if (t === '--headless') {
+            headless = true;
+        }
+        else if (t === '--no-headless') {
+            headless = false;
+        }
         else if (t.startsWith('--')) {
             // ignore unknown flags for the front door
         }
@@ -48,7 +61,7 @@ function parseRootArgs(tokens) {
         cwd = resolvePath(positionals.shift());
     }
     const prompt = positionals.length > 0 ? positionals.join(' ') : undefined;
-    return { cwd, prompt, name, kind };
+    return { cwd, prompt, name, kind, headless };
 }
 /** Env marker set on every pi the front door boots. Its presence means we are
  *  already inside a front-door-booted root, so a nested front-door launch must
@@ -79,14 +92,16 @@ export function maybeBootRoot(root, argv) {
     //   • bare `crtr`                  (no tokens)
     //   • `crtr <dir> [prompt]`        (first positional is an existing dir)
     //   • `crtr "multi word prompt"`   (first token contains whitespace)
-    // Anything else — a bare word like `job`, or a leading flag — is treated as a
-    // mistyped/removed subcommand and handed to the dispatcher, which errors with
-    // "unknown subcommand: <token>". Booting pi for such tokens is what let the
-    // renamed `agent`/`job` subcommands fork-bomb the front door.
+    //   • `crtr --headless` / `crtr --name X`  (a leading front-door flag)
+    // Anything else — a bare word like `job`, or an UNKNOWN leading flag — is
+    // treated as a mistyped/removed subcommand and handed to the dispatcher, which
+    // errors with "unknown subcommand: <token>". Booting pi for such tokens is what
+    // let the renamed `agent`/`job` subcommands fork-bomb the front door.
     if (first !== undefined) {
         const looksLikePrompt = /\s/.test(first);
         const looksLikeDir = !first.startsWith('-') && isDir(resolvePath(first));
-        if (!looksLikePrompt && !looksLikeDir)
+        const looksLikeFrontDoorFlag = FRONT_DOOR_FLAGS.has(first);
+        if (!looksLikePrompt && !looksLikeDir && !looksLikeFrontDoorFlag)
             return false;
     }
     // Unambiguous front-door launch → boot a resident root inline (exec pi in

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

@@ -308,12 +308,13 @@ export declare function recycleFocusPane(nodeId: string, pane: string, launch: R
  *      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.
+ *    - RUNNING backstage pane (a live pi — the normal multi-child state — OR a
+ *      pi still BOOTING because the daemon already revived the manager off the
+ *      `push final` before this handoff ran): the daemon never (re)revives it,
+ *      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: 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

package/dist/core/runtime/placement.js

@@ -28,7 +28,7 @@
 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 { paneExists, paneRunning, paneLocation, paneOfWindow, windowAlive, windowOfPane, ensureSession, openNodeWindow, respawnPaneSync, respawnPaneDetached, breakPaneToSession, splitWindow, swapPaneInPlace, setRemainOnExit, closePane, currentTmux, joinPane, selectLayout, setWindowOption, switchClient, selectWindow, } from './tmux.js';
 import { homeSessionOf, childBackstageOf, nodeSession, newNodeId, rootOfSpine } from './nodes.js';
 import { nodeDir } from '../canvas/paths.js';
 import { isBusy } from './busy.js';
@@ -808,12 +808,13 @@ export function recycleFocusPane(nodeId, pane, launch) {
  *      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.
+ *    - RUNNING backstage pane (a live pi — the normal multi-child state — OR a
+ *      pi still BOOTING because the daemon already revived the manager off the
+ *      `push final` before this handoff ran): the daemon never (re)revives it,
+ *      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: 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
@@ -840,11 +841,22 @@ export function handFocusToManager(focusId, managerId) {
     const mgr = getRow(managerId);
     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) {
+    // MAJOR 1 — manager with a RUNNING backstage pane → 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 it claims the frozen %m.
+    // Commit the occupant repoint only here, on a path that genuinely takes the
+    // pane. The gate is the PANE (`paneRunning`: exists + command running, i.e.
+    // not a remain-on-exit corpse), NOT `isPidAlive(mgr.pi_pid)` — the recorded
+    // pid is a STALE proxy in the lost-pane race: the finishing child's `push
+    // final` seeds the manager's inbox mid-turn, the daemon's second pass revives
+    // the still-unfocused manager BACKSTAGE before this agent_end runs, and the
+    // fresh pi records its pid only at session_start, seconds into boot. Gating on
+    // the old dead pid made this branch miss the booting manager, the dormant
+    // branch miss it too (revive already flipped it active), and the caller reap
+    // the user's viewport while the manager ran on invisibly backstage. A booting
+    // pane is as swappable as a live one — swap it in; only a frozen corpse
+    // (pane_dead=1) is excluded, preserving the dead-focus-pane guarantees.
+    if (mgr.pane != null && paneRunning(mgr.pane) && 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) {

package/dist/core/runtime/revive.js

@@ -23,6 +23,7 @@ import { reconcile, piCommand, respawnPane, } from './placement.js';
 import { hostFor } from './host.js';
 import { nodeSession, childBackstageOf, rootOfSpine } from './nodes.js';
 import { isPidAlive } from '../canvas/pid.js';
+import { clearInjectedDocs } from '../substrate/injected-store.js';
 // ---------------------------------------------------------------------------
 // resumeArgs — which session source a revive resumes from
 // ---------------------------------------------------------------------------
@@ -93,6 +94,10 @@ export function reviveNode(nodeId, opts) {
         // woke you"); every other reviveNode caller passes nothing → no block.
         const bearings = drainBearings(meta);
         inv = buildPiArgv(meta, { prompt: buildReviveKickoff(meta, bearings, opts.wakeReason) });
+        // Fresh (no-resume) revive starts a NEW transcript — reset the on-read doc
+        // dedup so the new conversation surfaces docs from scratch (a resume below
+        // would instead KEEP the persisted set, continuing the same transcript).
+        clearInjectedDocs(nodeId);
     }
     // Placement owns WHERE this revive lands (§1.4): resume into a live focus pane
     // if the node occupies one, else a fresh window in its home_session (the
@@ -140,6 +145,8 @@ export function reviveInPlace(nodeId, pane, respawn = respawnPane) {
     // A refresh-yield is a cycle too — advance the label's trailing N.
     meta.cycles = (meta.cycles ?? 0) + 1;
     updateNode(nodeId, { cycles: meta.cycles });
+    // Fresh re-exec → new transcript: reset the on-read doc dedup.
+    clearInjectedDocs(nodeId);
     // The node's LOCATION — the session its pane physically lives in. The re-exec
     // is IN PLACE (the pane never moves), so this is preserved unchanged below.
     const session = meta.tmux_session ?? nodeSession();
@@ -198,6 +205,8 @@ export function relaunchRootInPane(nodeId, pane) {
         throw new Error(`relaunchRootInPane: unknown node ${nodeId}`);
     }
     // No prompt, no resume → a brand-new root conversation at cycle 0.
+    // Brand-new transcript: reset the on-read doc dedup.
+    clearInjectedDocs(nodeId);
     const inv = buildPiArgv(meta, {});
     // Source CRTR_ROOT_SESSION from childBackstageOf, the same backstage rule as
     // reviveInPlace. relaunchRootInPane runs only on a root, whose children must

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

@@ -6,6 +6,11 @@ export interface BootRootOpts {
     name?: string;
     /** Optional starter prompt (bare `crtr` requires none). */
     prompt?: string;
+    /** Tri-state host selection: `true`/`false` from an explicit
+     *  `--headless`/`--no-headless`, `undefined` to defer to the `headless`
+     *  config default. When it resolves to broker, the front door boots a
+     *  DETACHED broker root and auto-attaches a viewer inline in this pane. */
+    headless?: boolean;
 }
 /** Create a root node and bring up its pi. Returns the node; for 'inline' this
  *  only returns after pi exits (it took over the terminal). */

package/dist/core/runtime/spawn.js

@@ -9,7 +9,10 @@
 //                INDEPENDENT resident root (no subscription back to the spawner,
 //                provenance via spawned_by) brought forefront for direct driving.
 import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
 import { FRONT_DOOR_ENV } from './front-door.js';
+import { readConfig } from '../config.js';
+import { jobDir } from '../canvas/paths.js';
 import { spawnNode, currentNodeContext, resolveBirthSession, nodeSession, rootOfSpine } from './nodes.js';
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
@@ -17,7 +20,7 @@ import { hasRoadmap, seedRoadmap } from './roadmap.js';
 import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
 import { installMenuBinding, installNavBindings, installViewNavBindings } from './tmux-chrome.js';
 import { setPresence, updateNode, getNode, fullName } from '../canvas/index.js';
-import { registerRootFocus, ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, focusWindow, } from './placement.js';
+import { registerRootFocus, ensureSession, openNodeWindow, piCommand, currentTmux, inTmux, focusWindow, waitForBrokerViewSocket, } from './placement.js';
 import { transition } from './lifecycle.js';
 import { headlessBrokerHost } from './host.js';
 import { ensureDaemon } from '../../daemon/manage.js';
@@ -31,6 +34,10 @@ export function bootRoot(opts) {
     }
     catch { /* daemon is best-effort */ }
     const kind = opts.kind ?? 'general';
+    // Host precedence: explicit --headless/--no-headless flag > config `headless`
+    // default > tmux. Mirrors `crtr node new`'s resolution (commands/node.ts).
+    const headless = opts.headless ?? readConfig('user').headless === true;
+    const hostKind = headless ? 'broker' : 'tmux';
     // A born-resident root starts in base mode; it earns the orchestrator persona
     // the first time it delegates (or on promotion). Resident lifecycle either way.
     const { launch } = buildLaunchSpec(kind, 'base', { lifecycle: 'resident', hasManager: false });
@@ -45,6 +52,7 @@ export function bootRoot(opts) {
         cwd: opts.cwd,
         name: opts.name ?? kind,
         parent: null,
+        hostKind,
         launch,
     });
     // Persist the spawning prompt as the goal so a fresh revive can re-read its
@@ -70,6 +78,15 @@ export function bootRoot(opts) {
         }
         catch { /* best-effort */ }
     }
+    // HEADLESS front door: a broker root has NO engine pane — headlessBrokerHost
+    // launches a DETACHED broker that hosts the single engine + binds view.sock,
+    // opening no tmux window. So instead of exec'ing pi inline we boot the broker,
+    // wait for its socket, and auto-attach a VIEWER into THIS pane (the same
+    // `crtr attach` viewer focusBroker splits beside a caller). Presence stays
+    // null and NO focus row is registered — the viewer pane self-tags @crtr_node
+    // on connect, the handle node cycle/close/lifecycle resolve a broker by.
+    if (meta.host_kind === 'broker')
+        return bootRootBroker(meta, session, opts);
     // inline: the root's pi takes over THIS terminal, so its own window stays
     // where the user is (its tmux_session tracks that real pane so supervision
     // sees it alive). But its children spawn into the shared global session via
@@ -98,6 +115,50 @@ export function bootRoot(opts) {
     const r = spawnSync('pi', inv.argv, { stdio: 'inherit', env });
     process.exit(r.status ?? 0);
 }
+/** The headless front door (host_kind==='broker'): launch a detached broker for
+ *  this root, wait for its view.sock, then auto-attach a viewer INLINE in this
+ *  pane. Mirrors placement.focusBroker (ensure-broker → wait-socket → viewer)
+ *  but the viewer runs in the CURRENT pane (the front door owns it) rather than
+ *  a split beside a caller. Never returns — it exits with the viewer's status. */
+function bootRootBroker(meta, session, opts) {
+    // The shared backstage this subtree's descendants flow into (CRTR_ROOT_SESSION
+    // below). Mirrors the inline path; for a broker it is also the (moot) revive
+    // home — broker revive launches a detached process, ignoring the session.
+    updateNode(meta.node_id, { home_session: session });
+    const withSession = getNode(meta.node_id);
+    const inv = buildPiArgv(withSession, { prompt: opts.prompt });
+    // Authoritative backstage routing on the ENGINE's env (the broker host merges
+    // inv.env into the detached broker process), mirroring the inline pi env.
+    inv.env = { ...inv.env, CRTR_ROOT_SESSION: session, CRTR_SUBTREE: rootOfSpine(meta.node_id) };
+    // Launch the detached broker (it records its own pid as pi_pid via the
+    // stophook and binds view.sock). Returns placement all-null — no tmux window.
+    headlessBrokerHost.launch(meta.node_id, inv, { cwd: meta.cwd, name: fullName(meta), resuming: false });
+    // Close the cold-start race: the broker records its pid during extension bind,
+    // then opens view.sock LATER; attach connects once and exits "no broker" if we
+    // run it before listen(). Probe for an ACCEPTING socket before attaching. A
+    // timeout here does NOT mean the broker died — the engine is a resident root
+    // that keeps booting; we just can't attach yet, so point the user at re-focus.
+    if (!waitForBrokerViewSocket(meta.node_id)) {
+        process.stderr.write(`crtr: ${meta.node_id} is still starting its broker — it is running, but its viewer socket did not come up in time. ` +
+            `Re-focus the node to attach (\`crtr node focus ${meta.node_id}\`); see ${join(jobDir(meta.node_id), 'broker.log')} if it never appears.\n`);
+        process.exit(1);
+    }
+    // Auto-attach the VIEWER inline: re-invoke OUR OWN cli (process.execPath +
+    // its own execArgv + argv[1]) as `attach to <id>` so it needs no PATH `crtr`
+    // AND survives a loader-based launch (dev `tsx`/`--import` flags ride
+    // execArgv); stdio:'inherit' hands this pane to the viewer's raw-mode TUI.
+    // runAttach self-tags the pane @crtr_node on connect; ctrl+c/ctrl+d detaches
+    // and the broker engine runs on.
+    const entry = process.argv[1];
+    if (entry === undefined) {
+        process.stderr.write(`crtr: cannot resolve the crtr entrypoint to auto-attach; run \`crtr node focus ${meta.node_id}\`.\n`);
+        process.exit(1);
+    }
+    const r = spawnSync(process.execPath, [...process.execArgv, entry, 'attach', 'to', meta.node_id], {
+        stdio: 'inherit',
+    });
+    process.exit(r.status ?? 0);
+}
 /** Resolve a `--fork-from` value to the source pi gets as `--fork <path|id>`.
  *  A live node id resolves to its captured session FILE (absolute, cwd-immune),
  *  falling back to its bare session id; a path or partial uuid passes straight

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

@@ -96,6 +96,15 @@ export declare function paneLocation(pane: string): {
  *  liveness. We therefore require the echoed `#{pane_id}` to equal the requested
  *  pane: a live pane echoes its own id, a gone/bogus one yields empty. */
 export declare function paneExists(pane: string): boolean;
+/** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
+ *  Distinguishes a pane genuinely hosting a process — a live pi, or a pi still
+ *  BOOTING whose pid hasn't been recorded yet — from a remain-on-exit corpse
+ *  frozen after exit (`pane_dead` = 1). Node panes run pi as the pane command
+ *  (openNodeWindow / respawn-pane), never a shell, so pane-running ⟹ a pi (or
+ *  its respawn) occupies it. The probe handFocusToManager's live-swap gates on:
+ *  the recorded `pi_pid` is a stale proxy in the just-revived window (the new pi
+ *  records its pid only at session_start), but the pane itself never lies. */
+export declare function paneRunning(pane: string): boolean;
 /** Every live pane id on the server (`list-panes -a`), as a Set for membership
  *  probes. Returns null when tmux is unreachable (no server / transient failure)
  *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,

package/dist/core/runtime/tmux.js

@@ -191,6 +191,18 @@ export function paneExists(pane) {
     const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}']);
     return r.ok && r.stdout === pane;
 }
+/** Does this pane exist AND have its command still RUNNING (`#{pane_dead}` = 0)?
+ *  Distinguishes a pane genuinely hosting a process — a live pi, or a pi still
+ *  BOOTING whose pid hasn't been recorded yet — from a remain-on-exit corpse
+ *  frozen after exit (`pane_dead` = 1). Node panes run pi as the pane command
+ *  (openNodeWindow / respawn-pane), never a shell, so pane-running ⟹ a pi (or
+ *  its respawn) occupies it. The probe handFocusToManager's live-swap gates on:
+ *  the recorded `pi_pid` is a stale proxy in the just-revived window (the new pi
+ *  records its pid only at session_start), but the pane itself never lies. */
+export function paneRunning(pane) {
+    const r = tmux(['display-message', '-p', '-t', pane, '#{pane_id}\t#{pane_dead}']);
+    return r.ok && r.stdout === `${pane}\t0`;
+}
 /** Every live pane id on the server (`list-panes -a`), as a Set for membership
  *  probes. Returns null when tmux is unreachable (no server / transient failure)
  *  so callers can tell "no panes" apart from "can't tell" — a GC pass must skip,

package/dist/core/spawn.d.ts

@@ -1,4 +1,18 @@
+/** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
+ *  gate for the human surface — see tmuxServerReachable. A headless-broker child
+ *  strips TMUX/TMUX_PANE (broker.ts, anti-stophook-hijack) yet can still drive
+ *  the canvas tmux server, so gating the surface on this wrongly starves broker
+ *  nodes of human-in-the-loop. */
 export declare function isInTmux(): boolean;
+/** Is the canvas tmux SERVER reachable? The canvas runs on the DEFAULT tmux
+ *  socket (no -L/-S in core/runtime/tmux.ts), so any `crtr` child — including a
+ *  headless-broker child that has deleted its own $TMUX — can split panes into
+ *  it. The human surface gates on THIS (can I reach the server to open a pane
+ *  the user is watching?), not on the caller's $TMUX. `list-clients` exits 0
+ *  whenever a server is up (even with zero attached clients) and non-zero when
+ *  no server is running — the true "no tmux to surface into" case that should
+ *  degrade to the inbox-drain follow-up. */
+export declare function tmuxServerReachable(): boolean;
 export declare function shellQuote(s: string): string;
 /** Count panes in a tmux window (0 outside tmux / on error). With `targetPane`,
  *  counts the window THAT pane lives in (the placement decision must reflect the

package/dist/core/spawn.js

@@ -3,13 +3,30 @@
 // A small set of tmux primitives used by the `human` command tree to put the
 // humanloop TUI in a detached pane: spawnAndDetach (open a pane running a given
 // command), countPanesInCurrentWindow (placement decision), plus shellQuote and
-// isInTmux. The canvas runtime has its own one-window-per-node machinery in
-// core/runtime/tmux.ts; this module is only the pane-split path the human TUI
-// needs.
+// tmuxServerReachable. The canvas runtime has its own one-window-per-node
+// machinery in core/runtime/tmux.ts; this module is only the pane-split path the
+// human TUI needs.
 import { spawnSync } from 'node:child_process';
+/** Does THIS process sit inside a tmux client (its own $TMUX is set)? NOT the
+ *  gate for the human surface — see tmuxServerReachable. A headless-broker child
+ *  strips TMUX/TMUX_PANE (broker.ts, anti-stophook-hijack) yet can still drive
+ *  the canvas tmux server, so gating the surface on this wrongly starves broker
+ *  nodes of human-in-the-loop. */
 export function isInTmux() {
     return Boolean(process.env.TMUX);
 }
+/** Is the canvas tmux SERVER reachable? The canvas runs on the DEFAULT tmux
+ *  socket (no -L/-S in core/runtime/tmux.ts), so any `crtr` child — including a
+ *  headless-broker child that has deleted its own $TMUX — can split panes into
+ *  it. The human surface gates on THIS (can I reach the server to open a pane
+ *  the user is watching?), not on the caller's $TMUX. `list-clients` exits 0
+ *  whenever a server is up (even with zero attached clients) and non-zero when
+ *  no server is running — the true "no tmux to surface into" case that should
+ *  degrade to the inbox-drain follow-up. */
+export function tmuxServerReachable() {
+    const r = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], { encoding: 'utf8' });
+    return r.status === 0;
+}
 export function shellQuote(s) {
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
@@ -34,7 +51,7 @@ export function countPanesInCurrentWindow() {
  *  output on an unresolvable pane, so test for non-empty stdout, not just `.ok`.
  *  False outside tmux / on error. */
 export function paneAlive(pane) {
-    if (!isInTmux() || !/^%\d+$/.test(pane))
+    if (!/^%\d+$/.test(pane))
         return false;
     const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_id}'], {
         encoding: 'utf8',
@@ -46,7 +63,7 @@ export function paneAlive(pane) {
  *  specify pane here"); only split-window -t takes a pane. null outside tmux /
  *  on a bad pane id / on error / empty. */
 export function paneWindowTarget(pane) {
-    if (!isInTmux() || !/^%\d+$/.test(pane))
+    if (!/^%\d+$/.test(pane))
         return null;
     const r = spawnSync('tmux', ['display-message', '-p', '-t', pane, '#{session_name}:#{window_index}'], { encoding: 'utf8' });
     if (r.status !== 0)
@@ -59,8 +76,6 @@ export function paneWindowTarget(pane) {
  *  to surface a human prompt in the user's view when nothing in the asking
  *  node's graph is focused. null outside tmux / no client / on error. */
 export function attachedClientPane() {
-    if (!isInTmux())
-        return null;
     const clients = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], {
         encoding: 'utf8',
     });
@@ -102,10 +117,15 @@ export function scheduleKillCurrentPane(delaySeconds) {
  * as soon as the new pane is up; does NOT wait for the command to finish.
  */
 export function spawnAndDetach(opts) {
-    if (!isInTmux()) {
+    // Gate on the CANVAS tmux server's reachability, NOT the caller's $TMUX. A
+    // headless-broker child strips its own $TMUX (broker.ts) but the canvas server
+    // is on the default socket, so `split-window -t <pane>` against a resolved
+    // target pane (resolveHumanTarget) works fine from it. Only a genuine
+    // no-server case degrades to the inbox-drain follow-up.
+    if (!tmuxServerReachable()) {
         return {
             status: 'not-in-tmux',
-            message: 'handoff requires tmux (TMUX env var not set)',
+            message: 'handoff requires a reachable tmux server',
         };
     }
     const splitArgs = [];

package/dist/core/substrate/index.d.ts

@@ -1,4 +1,4 @@
-export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, KIND_DEFAULT_RUNGS, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
+export { KINDS, isDocKind, RUNGS, rungRank, rungAtLeast, FALLBACK_RUNG, parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
 export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
 export type { NodeConfigSubject } from './subject.js';

package/dist/core/substrate/index.js

@@ -1,15 +1,15 @@
 // substrate/ — the unified document-substrate keystone: the frontmatter schema,
-// the 4-rung visibility ladder, the kind→default-rungs table, the node-config
-// subject assembly, and gate evaluation. Pure + well-typed; the shared base the
-// CLI verbs, boot render, on-read render, and migrator all build on. See
-// design-substrate.md §4/§9 + plan-substrate.md §2.
+// the 4-rung visibility ladder, the node-config subject assembly, and gate
+// evaluation. Pure + well-typed; the shared base the CLI verbs, boot render,
+// on-read render, and migrator all build on. See design-substrate.md §4 +
+// plan-substrate.md §2.
 export { 
 // kinds
 KINDS, isDocKind, 
 // ladder
 RUNGS, rungRank, rungAtLeast, 
-// defaults
-KIND_DEFAULT_RUNGS, 
+// fallback floor
+FALLBACK_RUNG, 
 // parse + render-shared helpers
 parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';

package/dist/core/substrate/injected-store.d.ts

@@ -0,0 +1,10 @@
+/** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
+ *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
+ *  has not yet surfaced any on-read doc). */
+export declare function loadInjectedDocs(nodeId: string): Set<string>;
+/** Persist a node's on-read dedup set. Called after each read that surfaced a
+ *  new doc, so the grown set survives a later dormancy. */
+export declare function saveInjectedDocs(nodeId: string, seen: Set<string>): void;
+/** Drop a node's persisted dedup set. Called by the launch paths that start a
+ *  FRESH transcript, so the new conversation surfaces docs from scratch. */
+export declare function clearInjectedDocs(nodeId: string): void;

package/dist/core/substrate/injected-store.js

@@ -0,0 +1,55 @@
+// injected-store.ts — durable per-node dedup set for on-read doc injection.
+//
+// The on-read substrate hook (canvas-doc-substrate.ts → renderOnReadDocs) dedups
+// so a given doc surfaces at most once per conversation. That set USED to live
+// only in the pi process heap, cleared on session_start. But a node's logical
+// session — the .jsonl transcript — spans MULTIPLE pi processes: a dormancy →
+// revive(resume) cycle exits the old process and launches a fresh `pi --session`
+// that REUSES the same transcript. The fresh process started with an empty set,
+// so any doc already injected before dormancy got injected AGAIN on the next
+// read — the "fires a second time per session" bug.
+//
+// This module persists the set to `nodes/<id>/injected-docs.json` so the resumed
+// process rehydrates it and skips docs already present in the transcript. The
+// launch paths that begin a FRESH transcript (reviveNode resume=false,
+// reviveInPlace, relaunchRootInPane — all in runtime/revive.ts) call
+// clearInjectedDocs(), so a new conversation starts with an empty set.
+//
+// All ops are best-effort: a failed read/write degrades to a possible re-inject,
+// never a crash — a dedup miss must never break a read or a revive.
+import { readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { injectedDocsPath } from '../canvas/paths.js';
+/** Rehydrate a node's on-read dedup set from disk. Returns an empty set when the
+ *  file is absent, unreadable, or malformed (a fresh transcript, or a node that
+ *  has not yet surfaced any on-read doc). */
+export function loadInjectedDocs(nodeId) {
+    try {
+        const arr = JSON.parse(readFileSync(injectedDocsPath(nodeId), 'utf8'));
+        if (!Array.isArray(arr))
+            return new Set();
+        return new Set(arr.filter((x) => typeof x === 'string'));
+    }
+    catch {
+        return new Set();
+    }
+}
+/** Persist a node's on-read dedup set. Called after each read that surfaced a
+ *  new doc, so the grown set survives a later dormancy. */
+export function saveInjectedDocs(nodeId, seen) {
+    try {
+        writeFileSync(injectedDocsPath(nodeId), JSON.stringify([...seen]));
+    }
+    catch {
+        // best-effort — a failed persist only risks a re-inject, never a crash
+    }
+}
+/** Drop a node's persisted dedup set. Called by the launch paths that start a
+ *  FRESH transcript, so the new conversation surfaces docs from scratch. */
+export function clearInjectedDocs(nodeId) {
+    try {
+        rmSync(injectedDocsPath(nodeId), { force: true });
+    }
+    catch {
+        // ignore — absence is the desired state anyway
+    }
+}

package/dist/core/substrate/schema.d.ts

@@ -11,10 +11,7 @@ export declare function rungRank(r: Rung): number;
 /** Does rung `r` disclose at least as much as `min`? — e.g.
  *  `rungAtLeast(doc.systemPromptVisibility, 'name')` ⇒ "shows at boot at all". */
 export declare function rungAtLeast(r: Rung, min: Rung): boolean;
-export declare const KIND_DEFAULT_RUNGS: Record<DocKind, {
-    systemPrompt: Rung;
-    fileRead: Rung;
-}>;
+export declare const FALLBACK_RUNG: Rung;
 /** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
  *  the node-config subject. Typed loosely on purpose — the matcher engine owns
  *  validation; structurally it is a field→matcher map with optional
@@ -63,10 +60,11 @@ export interface SubstrateDoc extends SubstrateSchema {
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
- *  document and cannot be classified or defaulted. Tolerant of every other
- *  imperfection (a missing `when-and-why-to-read` defaults to '', a bad rung
- *  falls back to the kind default), so a renderer mapping over many docs never
- *  throws. Authoring-time enforcement of the field lives in `crtr memory lint`. */
+ *  document and cannot be classified. Tolerant of every other imperfection (a
+ *  missing `when-and-why-to-read` defaults to '', a missing/bad rung falls back
+ *  to the neutral floor `none`), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of these fields lives in `crtr memory
+ *  write` (on create) and `crtr memory lint`. */
 export declare function parseSubstrateFrontmatter(fm: Record<string, unknown> | null): SubstrateSchema | null;
 /** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
  *  resolver's name/scope/path/body). Returns `null` for a non-substrate doc