@crouton-kit/crouter 0.3.24 → 0.3.26

package/dist/core/__tests__/context-intro.test.js

@@ -1,6 +1,6 @@
 // Tests for the <crtr-context> bearings preamble:
-//   1. Worker and orchestrator bearings carry the `## References` block
-//      (substrate reference docs + node-local docs as `###` sub-sections).
+//   1. Worker and orchestrator bearings carry the `<references>` block
+//      (substrate reference docs + node-local docs as a file tree).
 //      Orchestrators add the across-cycles framing; promotion delivers that
 //      same orchestrator context-dir framing to a node that spawned base.
 //   2. canvas-context-intro injects the block as its own session message at
@@ -34,10 +34,10 @@ after(() => {
     delete process.env['CRTR_HOME'];
     delete process.env['CRTR_NODE_ID'];
 });
-test('worker bearings: base framing + ## References block, NO across-cycles framing', () => {
+test('worker bearings: base framing + <references> block, NO across-cycles framing', () => {
     // Bug-regression: review finding M1 — buildContextBearings renders the
-    // ## References block (renderReferencesBlock): ## References + ### <name>
-    // sub-sections. This test locks in that contract.
+    // <references> block (renderReferencesBlock): a kind-wrapped file tree of
+    // reference docs. This test locks in that contract.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     // Seed a node-local substrate doc so the ## References block is non-empty.
     const dir = memoryDir(meta.node_id);
@@ -46,21 +46,25 @@ test('worker bearings: base framing + ## References block, NO across-cycles fram
     const block = buildContextIntro(meta.node_id);
     assert.match(block, new RegExp(`<crtr-context dir="${contextDir(meta.node_id)}">`));
     assert.match(block, /shared document store, not a task tracker/, 'base = shared docs, not tasks');
-    // Reference content renders ONLY as ## References + ### sub-sections.
+    // Reference content renders ONLY as the <references> file-tree block.
     assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
     // Per-store stanza headers (label · dir) never appear.
     assert.doesNotMatch(block, /user-global · /, 'no user-global label·dir stanza');
     assert.doesNotMatch(block, /node-local · /, 'no node-local label·dir stanza');
     // No (empty) placeholder marker.
     assert.doesNotMatch(block, /\(empty\)/, 'no (empty) placeholder');
-    assert.match(block, /## References\n\n###/, '## References followed by ### sub-sections');
+    assert.match(block, /<references>/, '<references> block present');
+    assert.match(block, /\nreferences\n/, 'tree headed by the `references` root label');
+    // The node-local preview-rung doc renders as a tree entry with a `# read when:`
+    // routing line (verbatim previewLine output).
+    assert.match(block, /test-ref {2}# read when: When testing, this reference should be read because it is a regression fixture\./, 'node-local preview doc renders its routing line');
     // A terminal worker must NOT carry the orchestrator across-cycles framing.
     assert.doesNotMatch(block, /refresh cycles/, 'no across-cycles framing for a terminal worker');
     assert.match(block, /<\/crtr-context>/);
 });
-test('orchestrator bearings: across-cycles framing + node-local substrate docs ride into ## References; a non-substrate .md file is never inlined', () => {
-    // Bug-regression: review finding M1 — buildContextBearings renders ## References.
-    // Node-local substrate docs render as ### sub-sections at their rung; a
+test('orchestrator bearings: across-cycles framing + node-local substrate docs ride into <references>; a non-substrate .md file is never inlined', () => {
+    // Bug-regression: review finding M1 — buildContextBearings renders <references>.
+    // Node-local substrate docs render as tree entries at their rung; a
     // non-substrate .md file (no frontmatter `kind`) never surfaces.
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     promote(meta.node_id); // flip to orchestrator mode — the across-cycles gate
@@ -75,9 +79,8 @@ test('orchestrator bearings: across-cycles framing + node-local substrate docs r
     assert.match(block, /shared document store, not a task tracker/, 'still carries the base framing');
     assert.match(block, /refresh cycles/, 'orchestrator gets the across-cycles framing');
     assert.doesNotMatch(block, /<memory>/, 'no <memory> block');
-    assert.match(block, /## References\n/, 'references block present');
-    assert.match(block, /### flaky-build\n/, 'node-local doc gets its ### sub-section');
-    assert.match(block, /When the build flakes, this reference should be read because the first run fails\./, 'preview rung renders the routing line');
+    assert.match(block, /<references>/, 'references block present');
+    assert.match(block, /flaky-build {2}# read when: When the build flakes, this reference should be read because the first run fails\./, 'node-local doc renders as a tree entry with its routing line');
     // The non-substrate file never renders: no header line, no pointer line, no path.
     assert.ok(!block.includes('# memory index'), 'the index header comment is NOT inlined');
     assert.ok(!block.includes('- [Flaky build](flaky-build.md)'), 'index pointer lines are NOT inlined');
@@ -85,12 +88,12 @@ test('orchestrator bearings: across-cycles framing + node-local substrate docs r
     assert.ok(!block.includes('node-local · '), 'no label·dir stanza header');
     assert.match(block, /<\/crtr-context>/);
 });
-test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-none node-local doc still surfaces as a ### title stub', () => {
-    // Bug-regression: review findings M1 + M6 — the ## References block carries no
+test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-none node-local doc still surfaces as a bare-name tree entry', () => {
+    // Bug-regression: review findings M1 + M6 — the <references> block carries no
     // per-store `label · dir` stanzas or (empty) markers, and node-local docs are
     // NOT filtered on rung: a migrated node-local reference defaults
-    // system-prompt-visibility: none and must still ride into ## References as
-    // its bare title (never its body).
+    // system-prompt-visibility: none and must still ride into <references> as
+    // its bare name (floored to the `name` rung; never its body).
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
     promote(meta.node_id); // flip to orchestrator mode
     const dir = memoryDir(meta.node_id);
@@ -103,9 +106,9 @@ test('orchestrator bearings: no per-store stanzas or (empty) markers; a rung-non
     assert.ok(!block.includes('project · '), 'no project stanza header');
     assert.doesNotMatch(block, /\(empty\)/, 'no (empty) markers');
     assert.ok(!block.includes('MEMORY.md'), 'no MEMORY.md path in the block');
-    // M6: rung-none node-local doc surfaces as its title stub only.
-    assert.match(block, /### rung-none-fact\s*\n/, 'rung-none node-local doc surfaces as its title stub');
-    assert.ok(!block.includes('body that must not render'), 'none rung renders the title only, not the body');
+    // M6: rung-none node-local doc surfaces as a bare-name tree entry only.
+    assert.match(block, /─ rung-none-fact\n/, 'rung-none node-local doc surfaces as a bare-name tree entry');
+    assert.ok(!block.includes('body that must not render'), 'none rung renders the name only, not the body');
 });
 test('promotion guidance delivers the orchestrator context-dir framing', () => {
     // A node spawns as a base worker (no orchestrator bearings). On promotion the

package/dist/core/__tests__/full/broker-pane-resolution.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/full/broker-pane-resolution.test.js

@@ -0,0 +1,84 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/full/broker-pane-resolution.test.ts
+//
+// REGRESSION — broker-hosted nodes were second-class in the tmux command
+// surface (audit: findings-headless-default.md, Gaps 1 + 2). Two real bugs,
+// both observable only with a REAL tmux pane, so this is a FULL-tier test.
+//
+// (1) Gap 1 — `nodeInPane()` (src/commands/node.ts) resolved a pane via
+//     window→node ONLY. A broker engine runs DETACHED with window=null, and its
+//     on-screen presence is a `crtr attach` VIEWER pane, so the window lookup
+//     never found it: `node cycle`/`recycle`/`close`/`demote`/`lifecycle` all
+//     broke when the current pane was a broker viewer. The fix has attach
+//     self-tag its pane `@crtr_node=<id>` and nodeInPane resolve that tag first.
+//     LOCKED: an untagged pane over a broker resolves undefined (the bug); the
+//     SAME pane, once tagged, resolves the broker (the fix).
+//
+// (2) Gap 2 — `recycleNode()` (src/core/runtime/recycle.ts) always respawned the
+//     pane into a fresh TMUX pi root, even for a broker node — silently turning
+//     the viewer pane into a tmux engine and dropping out of the broker host
+//     model. The fix preserves host_kind: recycling a broker node finalizes it,
+//     tears the broker down, and boots a fresh BROKER root the pane re-attaches
+//     to. LOCKED: the recycled node is finalized (done) and the fresh root is
+//     broker-hosted, not tmux.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHarness, hasTmux } from '../helpers/harness.js';
+import { closeDb } from '../../canvas/db.js';
+import { nodeInPane } from '../../../commands/node.js';
+import { recycleNode } from '../../runtime/recycle.js';
+let h;
+let root;
+before(async () => {
+    h = await createHarness({ sessionPrefix: 'crtr-brkpane' });
+    root = h.spawnRoot('host root');
+});
+after(async () => {
+    if (h !== undefined)
+        await h.dispose();
+});
+/** Split a throwaway pane in the harness session; return its %id. */
+function makePane() {
+    const r = spawnSync('tmux', ['split-window', '-d', '-t', h.session, '-P', '-F', '#{pane_id}', 'sleep 100000'], { encoding: 'utf8' });
+    const pane = (r.stdout ?? '').trim();
+    assert.ok(pane.startsWith('%'), `expected a %pane_id, got "${pane}" (stderr: ${r.stderr})`);
+    return pane;
+}
+function tagPane(pane, value) {
+    spawnSync('tmux', ['set-option', '-p', '-t', pane, '@crtr_node', value], { stdio: 'ignore' });
+}
+test('Gap 1 — nodeInPane resolves a broker node from its tagged viewer pane (undefined when untagged)', async (t) => {
+    if (!hasTmux())
+        return t.skip('tmux unavailable');
+    const broker = await h.spawnHeadlessChild(root, 'broker worker');
+    closeDb();
+    assert.equal(h.node(broker).host_kind, 'broker', 'spawned a broker-hosted node');
+    assert.equal(h.node(broker).window ?? null, null, 'broker engine has window=null (paneless)');
+    const viewer = makePane();
+    // BUG REPRODUCTION: an untagged pane over a broker is invisible — no node owns
+    // this pane's window, and a broker has no window to find, so resolution fails.
+    closeDb();
+    assert.equal(nodeInPane(viewer), undefined, 'untagged viewer pane → broker is invisible (the bug)');
+    // FIX: the viewer self-tag (`@crtr_node`) is the broker's pane handle.
+    tagPane(viewer, broker);
+    closeDb();
+    assert.equal(nodeInPane(viewer), broker, 'tagged viewer pane → resolves the broker (the fix)');
+    // A stale tag pointing at a DONE node is ignored (must be live: active/idle).
+    spawnSync('tmux', ['kill-pane', '-t', viewer], { stdio: 'ignore' });
+});
+test('Gap 2 — recycle preserves the broker host: finalizes the node, boots a fresh BROKER root', async (t) => {
+    if (!hasTmux())
+        return t.skip('tmux unavailable');
+    const broker = await h.spawnHeadlessChild(root, 'broker to recycle');
+    const viewer = makePane();
+    tagPane(viewer, broker);
+    closeDb();
+    assert.equal(nodeInPane(viewer), broker, 'precondition: viewer resolves the broker');
+    const res = await recycleNode(broker, viewer);
+    closeDb();
+    assert.equal(h.node(broker).status, 'done', 'recycled broker node is finalized (done)');
+    assert.ok(res.newRoot, 'a fresh root was spawned');
+    const fresh = h.node(res.newRoot);
+    assert.equal(fresh.host_kind, 'broker', 'fresh root PRESERVES the broker host (not a tmux pi root)');
+    assert.equal(fresh.parent ?? null, null, 'fresh root is a root (parent=null)');
+});

package/dist/core/__tests__/memory-resolver.test.js

@@ -10,8 +10,15 @@
 // resolved. The fix taught findMemoryMatches to resolve `<plugin>/<rest>` against
 // each enabled plugin's pluginMemoryDir, native-before-plugin precedence kept.
 //
-// This test FAILS on the pre-fix code (the two fully-qualified reads throw
-// notFound) and PASSES on the current code.
+// Follow-up bug (same seat): the `<plugin>/<rest>` branch required a non-empty
+// rest (`if (slash <= 0) continue`), so a BARE plugin name never tried the
+// plugin-root INDEX.md — `read claude-godot-prompter` / `read ai` returned
+// not_found even though `<plugin>/INDEX` and `<plugin>/<child>` resolved. The
+// fix resolves a bare plugin name to `<plugin>/memory/INDEX.md`, mirroring the
+// native bare-dir-name -> INDEX.md contract, native-before-plugin kept.
+//
+// This test FAILS on the pre-fix code (the fully-qualified and bare-plugin-name
+// reads throw notFound) and PASSES on the current code.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/memory-resolver.test.ts
 import { test, before, after } from 'node:test';
@@ -48,6 +55,9 @@ before(() => {
     writeFileSync(join(pluginMem, 'widget.md'), doc('plugin-widget'));
     writeFileSync(join(pluginMem, 'area', 'zone.md'), doc('plugin-zone'));
     writeFileSync(join(pluginMem, 'shared.md'), doc('plugin-shared'));
+    // Plugin-root INDEX.md: a BARE plugin name must resolve this (mirrors the
+    // native bare-dir-name -> INDEX.md contract for the plugin mount root).
+    writeFileSync(join(pluginMem, 'INDEX.md'), doc('plugin-root-index'));
     // Explicitly enable the plugin in config (default is enabled, but be robust).
     writeFileSync(join(scopeRoot, 'config.json'), JSON.stringify({ plugins: { [PLUGIN]: { enabled: true } } }));
     // Point the scope resolver at the fixture: project scope is found by walking
@@ -78,6 +88,15 @@ test('the bare leaf still resolves via last-segment fallback', () => {
     const d = resolveMemoryDoc('widget');
     assert.equal(d.name, `${PLUGIN}/widget`);
 });
+test('bare plugin name resolves the plugin-root INDEX.md', () => {
+    // Regression: findMemoryMatches skipped the plugin branch for a bare name
+    // (`if (slash <= 0) continue`), so a bare plugin name never tried the
+    // plugin-root INDEX.md and returned not_found — even though `<plugin>/INDEX`
+    // resolved. The fix resolves the bare mount root to <plugin>/memory/INDEX.md.
+    const d = resolveMemoryDoc(PLUGIN);
+    assert.equal(d.name, PLUGIN);
+    assert.ok(d.path.endsWith(join('plugins', PLUGIN, 'memory', 'INDEX.md')));
+});
 test('native doc wins over a plugin doc of the same canonical name', () => {
     // native-before-plugin precedence: findMemoryMatches checks scopeMemoryDir
     // before pluginMemoryDir, so the native shadow at memory/fixplug/shared.md

package/dist/core/memory-resolver.js

@@ -111,24 +111,29 @@ function findMemoryMatches(name, scope) {
                 continue;
             }
         }
-        // Plugin memory dir: a fully-qualified `<plugin>/<rest>` name resolves
-        // against that enabled plugin's memory/ tree (the `<pluginName>/` mount
-        // that listAllMemoryDocs enumerates — `read` must resolve what `list` shows).
+        // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
+        // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
+        // enumerates — `read` must resolve what `list` shows). A BARE plugin name
+        // (no slash) resolves the plugin-root INDEX.md, mirroring the native
+        // bare-dir-name -> INDEX.md contract for the plugin mount root.
         const slash = name.indexOf('/');
-        if (slash <= 0)
-            continue;
-        const pluginName = name.slice(0, slash);
-        const rest = name.slice(slash + 1);
+        const pluginName = slash > 0 ? name.slice(0, slash) : name;
+        const rest = slash > 0 ? name.slice(slash + 1) : '';
         for (const p of listInstalledPlugins(s)) {
             if (!p.enabled || p.name !== pluginName)
                 continue;
             const pdir = pluginMemoryDir(p);
-            const ppath = join(pdir, ...rest.split('/')) + '.md';
-            if (pathExists(ppath)) {
-                matches.push(loadMemoryDoc(name, s, ppath));
-                break;
+            if (rest) {
+                const ppath = join(pdir, ...rest.split('/')) + '.md';
+                if (pathExists(ppath)) {
+                    matches.push(loadMemoryDoc(name, s, ppath));
+                    break;
+                }
             }
-            const pindex = join(pdir, ...rest.split('/'), 'INDEX.md');
+            // Bare name -> <plugin>/memory/INDEX.md; slashed name -> dir INDEX.
+            const pindex = rest
+                ? join(pdir, ...rest.split('/'), 'INDEX.md')
+                : join(pdir, 'INDEX.md');
             if (pathExists(pindex)) {
                 matches.push(loadMemoryDoc(name, s, pindex));
                 break;

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

@@ -56,6 +56,6 @@ export declare function buildWakeBearings(origin: WakeOrigin): string;
  *  any copied-in persona) followed by the `<crtr-context>` bearings block. Base
  *  framing rides for EVERY node; the across-cycles context-dir note is added
  *  ONLY for an orchestrator (by mode) — the one node whose dir a future cycle
- *  resumes from. The `## References` block carries the substrate reference docs
+ *  resumes from. The `<references>` block carries the substrate reference docs
  *  + node-local docs. */
 export declare function buildContextBearings(nodeId: string): string;

package/dist/core/runtime/bearings.js

@@ -19,7 +19,7 @@
 // one place other nodes on the canvas can read from, so it is for documents
 // worth a shared reference, NOT a task tracker, and NOT a "future memory-wiped
 // you" stash (a terminal worker has no future cycle — that framing only makes
-// sense once a node is a resident orchestrator). The `## References` block
+// sense once a node is a resident orchestrator). The `<references>` block
 // (substrate reference docs + node-local docs) rides into the context message.
 //
 // Orchestrator addendum (gated on orchestrator MODE): the dir ALSO survives
@@ -145,7 +145,7 @@ export function buildWakeBearings(origin) {
  *  any copied-in persona) followed by the `<crtr-context>` bearings block. Base
  *  framing rides for EVERY node; the across-cycles context-dir note is added
  *  ONLY for an orchestrator (by mode) — the one node whose dir a future cycle
- *  resumes from. The `## References` block carries the substrate reference docs
+ *  resumes from. The `<references>` block carries the substrate reference docs
  *  + node-local docs. */
 export function buildContextBearings(nodeId) {
     const identity = buildIdentityAssertion(nodeId);

package/dist/core/runtime/broker.js

@@ -746,8 +746,10 @@ export async function runBroker(nodeId) {
                 break;
             }
             case 'get_commands': {
-                if (notController(client, 'list commands'))
-                    break;
+                // OBSERVERS may call this: the merged command inventory is static
+                // (extensions + templates + skills + builtins) and drives nothing in the
+                // engine, so it is not a controller-gated op. The web bridge fetches it on
+                // its observer-by-default upstream connection to populate the palette.
                 // The merged command list rides in ack.detail as JSON (the foundation's
                 // AckFrame.detail field) — the viewer (T6) JSON.parses it when for ===
                 // 'get_commands'. Keeps every command op a uniform ack reply.

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

@@ -15,8 +15,8 @@ export declare const CANVAS_VIEW_PATH: string;
  *  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), doc-substrate (the unified document
- *  substrate's two hooks: ## Skills + ## Preferences at boot, on-read context
- *  injection), commands (the /promote slash-command), resume (the /resume-node
+ *  substrate's two hooks: <skills> + <preferences> + <memory-guidance> at boot,
+ *  on-read context injection), commands (the /promote slash-command), resume (the /resume-node
  *  whole-canvas picker → `crtr node focus`), view (the /view popup → `crtr
  *  view pick` / `crtr view run <name>`).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it

package/dist/core/runtime/launch.js

@@ -42,8 +42,8 @@ export const CANVAS_VIEW_PATH = resolveExtension('canvas-view');
  *  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), doc-substrate (the unified document
- *  substrate's two hooks: ## Skills + ## Preferences at boot, on-read context
- *  injection), commands (the /promote slash-command), resume (the /resume-node
+ *  substrate's two hooks: <skills> + <preferences> + <memory-guidance> at boot,
+ *  on-read context injection), commands (the /promote slash-command), resume (the /resume-node
  *  whole-canvas picker → `crtr node focus`), view (the /view popup → `crtr
  *  view pick` / `crtr view run <name>`).
  *  All self-gate on CRTR_NODE_ID. goal-capture precedes passive-context so it

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

@@ -266,6 +266,19 @@ export declare function focus(nodeId: string, opts: {
     callerNode?: string;
     revive: Reviver;
 }): FocusResult;
+/** 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. */
+export declare function waitForBrokerViewSocket(nodeId: string): boolean;
+/** Env for a `crtr attach` VIEWER pane (the focusBroker split AND recycle's
+ *  re-attach respawn): 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 pane inherits the tmux server env, like every other crtr
+ *  chrome pane). One helper so the two viewer-pane sites can't drift. */
+export declare function viewerSplitEnv(): Record<string, string>;
 /** Tear a node off its placement (close/reset teardown, §2.3, flow (e)).
  *  Reconcile first (follow a manual move / backfill a legacy pane), close the
  *  focus row it occupies (if any), kill its pane (pane-keyed via the durable

package/dist/core/runtime/placement.js

@@ -307,6 +307,18 @@ export function detachToBackground(nodeId, pane) {
     const row = getRow(nodeId);
     if (row === null)
         return false;
+    // A broker node has NO engine pane — it is ALREADY headless, so the only thing
+    // on screen is a `crtr attach` VIEWER pane. "Detach" (the Alt+C → D let-go)
+    // therefore means "stop foregrounding it": close the viewer pane and leave the
+    // broker running untouched. The engine-in-pane relocate/release below would
+    // mis-anchor the live engine row to the viewer pane and (when idle) flip a
+    // LIVE broker to idle-release — corrupting state. Never reach it for a broker.
+    if (row.host_kind === 'broker') {
+        const viewer = pane ?? null;
+        if (viewer !== null && paneExists(viewer))
+            return closePane(viewer);
+        return false;
+    }
     const target = pane ?? row.pane;
     if (target === null || !paneExists(target))
         return false;
@@ -632,7 +644,7 @@ const BROKER_FOCUS_SOCKET_RETRY_MS = 100;
  *  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) {
+export function waitForBrokerViewSocket(nodeId) {
     const sockPath = join(nodeDir(nodeId), 'view.sock');
     const probe = `
 const net = require('node:net');
@@ -712,17 +724,21 @@ function focusBroker(nodeId, meta, opts) {
     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}` });
+    const pane = splitWindow(callerPane, { cwd: meta.cwd, env: viewerSplitEnv(), 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 };
 }
+/** Env for a `crtr attach` VIEWER pane (the focusBroker split AND recycle's
+ *  re-attach respawn): 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 pane inherits the tmux server env, like every other crtr
+ *  chrome pane). One helper so the two viewer-pane sites can't drift. */
+export function viewerSplitEnv() {
+    const crtrHome = process.env['CRTR_HOME'];
+    return crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
+}
 /** 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

package/dist/core/runtime/recycle.js

@@ -23,7 +23,7 @@ import { pushFinal } from '../feed/feed.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 { focusOf, recycleFocusPane, piCommand, paneLocation, respawnPaneSync, setPaneOption, waitForBrokerViewSocket, viewerSplitEnv } 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
@@ -74,12 +74,14 @@ export async function recycleNode(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
+    // A broker node's pane is a VIEWER (`crtr attach`), not its engine: the engine
+    // is the detached broker process, so respawn-pane -k below would only kill the
+    // viewer, never the engine. Route 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') {
+    const isBroker = meta.host_kind === 'broker';
+    if (isBroker) {
         try {
             hostFor(meta).teardown(nodeId);
         }
@@ -93,7 +95,12 @@ export async function recycleNode(nodeId, callerPane) {
         setPresence(nodeId, { pane: null, window: null, tmux_session: null });
     }
     catch { /* best-effort */ }
-    // 2 + 3. Recycle — boot a fresh resident root in the SAME pane.
+    // 2 + 3. Recycle — boot a fresh resident root for the SAME pane, PRESERVING
+    // the recycled node's host model: a tmux node recycles into a tmux root in the
+    // pane; a broker node recycles into a fresh BROKER root the pane re-attaches to
+    // (broker-is-the-host — the viewer pane stays a viewer, never becomes an engine
+    // pane). Without preserving host_kind, recycling a broker node from its viewer
+    // would silently respawn the viewer into a tmux pi root.
     try {
         ensureDaemon();
     }
@@ -108,6 +115,7 @@ export async function recycleNode(nodeId, callerPane) {
         name: 'general',
         parent: null,
         launch,
+        hostKind: isBroker ? 'broker' : 'tmux',
     });
     // 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
@@ -123,9 +131,56 @@ export async function recycleNode(nodeId, callerPane) {
     }
     const fresh = getNode(root.node_id);
     const inv = buildPiArgv(fresh);
-    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,
-    });
+    // CRTR_ROOT_SESSION/CRTR_SUBTREE route the fresh root's children to the
+    // backstage (both consumers below read this one authoritative env). FRONT_DOOR
+    // is added per-consumer: the tmux command const adds it; the broker host sets
+    // it itself, so the broker branch omits it.
+    inv.env = { ...inv.env, CRTR_ROOT_SESSION: nodeSession(), CRTR_SUBTREE: rootOfSpine(root.node_id) };
+    const ok = isBroker
+        ? recycleBrokerViewer(fresh, pane, inv)
+        : recycleTmuxRoot(root.node_id, pane, {
+            command: piCommand(inv.argv),
+            env: { ...inv.env, [FRONT_DOOR_ENV]: '1' },
+            cwd: meta.cwd,
+            name: fullName(fresh),
+        });
     return { recycled: ok, finalized, newRoot: root.node_id, delivered };
 }
+/** Recycle a TMUX root into `pane`: respawn-pane -k boots the fresh pi engine in
+ *  place. Clears any stale `@crtr_node` viewer tag first — a prior `crtr attach`
+ *  in this pane may have left one (tmux pane options survive respawn-pane), and
+ *  since nodeInPane checks the tag BEFORE the window, a stale tag would shadow
+ *  the real window→node lookup for the fresh tmux engine now in the pane. */
+function recycleTmuxRoot(nodeId, pane, launch) {
+    try {
+        setPaneOption(pane, '@crtr_node', '');
+    }
+    catch { /* best-effort */ }
+    return recycleFocusPane(nodeId, pane, { ...launch, resuming: false });
+}
+/** Recycle a BROKER root into `pane`: the fresh root is broker-hosted, so its
+ *  engine runs in a DETACHED broker, not the pane. Birth-launch that broker via
+ *  the Host seam (mirrors spawnChild's birth path — the host records its pid),
+ *  wait for its view.sock to accept, then respawn the pane in place to the VIEWER
+ *  `crtr attach to <root>`. The pane stays a viewer (attach self-tags it
+ *  `@crtr_node`); it never hosts the engine. Returns false (recycle reports the
+ *  pane was not respawned) when the broker never serves — the fresh root row
+ *  still exists, broker-hosted, for the daemon to revive. */
+function recycleBrokerViewer(fresh, pane, inv) {
+    hostFor(fresh).launch(fresh.node_id, inv, { cwd: fresh.cwd, name: fullName(fresh), resuming: false });
+    if (!waitForBrokerViewSocket(fresh.node_id))
+        return false;
+    // Clear the finalized node's stale `@crtr_node` tag before respawn (symmetry
+    // with recycleTmuxRoot) so the tag never names a done node during the gap
+    // before the new `crtr attach` re-tags on connect. Node ids are shell-safe
+    // identifiers; no quoting needed.
+    try {
+        setPaneOption(pane, '@crtr_node', '');
+    }
+    catch { /* best-effort */ }
+    // SYNC respawn: the recycle command runs as a SEPARATE CLI process (the viewer
+    // runs `crtr attach`, a TUI — it never execs recycle), so we are NOT respawning
+    // our own pane and can confirm the respawn actually landed (the honest exit
+    // status), unlike the tmux path which often recycles the caller's own pane.
+    return respawnPaneSync({ pane, cwd: fresh.cwd, env: viewerSplitEnv(), command: `crtr attach to ${fresh.node_id}` });
+}

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

@@ -19,10 +19,3 @@ export declare function buildCeilingIndex(docs: SubstrateDoc[]): Map<string, Sub
  *  ceiling: min(own rung, each ancestor INDEX's rung). A `none` ancestor INDEX
  *  hides the whole subtree (min with none = none). */
 export declare function effectiveRung(doc: SubstrateDoc, ceil: Map<string, SubstrateDoc>, surface: Surface): Rung;
-/** Apply ceilings to a doc list for a surface: each doc gets its effective rung
- *  on `surface` written back into that field, and INDEX docs are renamed to
- *  their dir entry. Returns NEW objects only where something changed (cheap,
- *  preserves identity for untouched docs). Does NOT drop `none`-rung docs — the
- *  caller filters per surface (boot drops them; node-local intentionally keeps
- *  them). */
-export declare function applyCeilings(docs: SubstrateDoc[], surface: Surface): SubstrateDoc[];

package/dist/core/substrate/ceiling.js

@@ -69,19 +69,3 @@ export function effectiveRung(doc, ceil, surface) {
     }
     return rung;
 }
-/** Apply ceilings to a doc list for a surface: each doc gets its effective rung
- *  on `surface` written back into that field, and INDEX docs are renamed to
- *  their dir entry. Returns NEW objects only where something changed (cheap,
- *  preserves identity for untouched docs). Does NOT drop `none`-rung docs — the
- *  caller filters per surface (boot drops them; node-local intentionally keeps
- *  them). */
-export function applyCeilings(docs, surface) {
-    const ceil = buildCeilingIndex(docs);
-    return docs.map((d) => {
-        const rung = effectiveRung(d, ceil, surface);
-        const name = displayName(d.name);
-        if (rung === d[surface] && name === d.name)
-            return d;
-        return { ...d, [surface]: rung, name };
-    });
-}

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

@@ -3,7 +3,7 @@ export type { DocKind, Rung, GatePredicate, SubstrateSchema, SubstrateDoc } from
 export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
 export type { NodeConfigSubject } from './subject.js';
 export { gatePasses } from './gate.js';
-export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, applyCeilings, } from './ceiling.js';
+export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';
 export type { Surface } from './ceiling.js';
-export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock } from './render.js';
+export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock, renderMemoryGuidance, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';

package/dist/core/substrate/index.js

@@ -14,6 +14,6 @@ KIND_DEFAULT_RUNGS,
 parseSubstrateFrontmatter, parseSubstrateDoc, previewLine, } from './schema.js';
 export { scopeForCwd, spineDepth, assembleNodeSubject } from './subject.js';
 export { gatePasses } from './gate.js';
-export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, applyCeilings, } from './ceiling.js';
-export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock } from './render.js';
+export { INDEX_NAME, isIndexName, indexDirOf, displayName, buildCeilingIndex, effectiveRung, } from './ceiling.js';
+export { renderSkillsSection, renderPreferencesSection, renderReferencesBlock, renderMemoryGuidance, } from './render.js';
 export { renderOnReadDocs } from './on-read.js';