@crouton-kit/crouter 0.3.25 → 0.3.27

package/dist/builtin-memory/internal/INDEX.md

@@ -0,0 +1,21 @@
+---
+kind: reference
+when-and-why-to-read: When you hit a question about how the crtr runtime itself works — how nodes and the canvas behave, where state lives on disk, or how the primitives compose into real systems — this index should be read because it routes you to the runtime's own operational documentation, so you act from the canonical model instead of inferring it from command help.
+short-form: internal/ is the runtime's self-documentation — operational guides to nodes/canvas and the storage tiers, plus worked example compositions. Open it when you need to understand how crtr works.
+system-prompt-visibility: preview
+file-read-visibility: none
+---
+
+# internal/ — how the crtr runtime works
+
+This directory is the runtime's **self-documentation**: operational references covering how crtr behaves, so any agent operating under it can route to the canonical model rather than reconstruct it from scattered `-h` output. It ships with crtr.
+
+Open this dir whenever a task turns on understanding the runtime itself. Contents:
+
+- **nodes-and-canvas** — the agent-runtime model: nodes on the canvas graph, spawn/delegate, the push/feed spine, lifecycle (mode + lifecycle axes), and revive (manual + daemon auto-revive).
+- **storage-tiers** — where every kind of state lives: the three tiers (scope root, per-cwd crouter root, canvas home) and their durability/ownership contracts.
+- **examples/** — worked compositions of the primitives into complete systems (the analogue of pi's `examples/` dir), e.g. the iMessage assistant node.
+
+Adjacent, outside this dir: authoring memory documents (kind, rungs, gates, routing line, the asked-to-remember workflow) is owned by `crtr memory write -h` — the authoring guide lives on the help-gate so it surfaces exactly when you write; making a persona (a custom `--kind`) is owned by the builtin **crouter-development/personas** skills.
+
+The individual files surface at `name` (their titles route; open the one the situation calls for); this index surfaces at `preview` so the dir announces when to come looking.

package/dist/builtin-memory/internal/examples/INDEX.md

@@ -0,0 +1,15 @@
+---
+kind: reference
+when-and-why-to-read: When you want a worked end-to-end composition of crouter primitives — not what one command does but how several combine into a real standing system — open this dir because it holds complete example builds, each verified against the actual runtime and OS mechanics.
+short-form: Worked examples composing crouter primitives into complete systems (like pi's examples/ dir). Currently — the iMessage assistant node.
+system-prompt-visibility: name
+file-read-visibility: none
+---
+
+# internal/examples/ — worked compositions of crouter primitives
+
+The other internal/ docs explain the primitives one at a time; this dir shows them composed into complete, buildable systems — the crtr analogue of pi's `examples/` directory. Each example is grounded: its OS-level mechanics and command contracts were verified before being written down.
+
+- **imessage-assistant** — an OpenClaw-style always-on assistant: resident root node with its own dir and persona, woken event-style by a launchd watcher via `node msg`, reading `chat.db` (with the attributedBody gotcha), replying via osascript, remembering people through project-scope memory.
+
+Add an example here when a composition was non-obvious enough that the next builder shouldn't have to re-derive it.

package/dist/builtin-memory/internal/examples/imessage-assistant.md

@@ -0,0 +1,100 @@
+---
+kind: reference
+when-and-why-to-read: When you are building a standing assistant node bridged to an external channel — iMessage, email, a chat service — this example should be read because it composes the crouter primitives (resident root node, custom persona, event-driven wake via node msg, project-scope memory) into a working OpenClaw-style design, with the macOS chat.db/osascript mechanics verified.
+short-form: Worked example — an always-on iMessage assistant built from crouter primitives. Resident root node + launchd watcher → node msg wakes + chat.db reads + osascript sends + substrate memory.
+system-prompt-visibility: name
+file-read-visibility: none
+---
+
+# Example: an iMessage assistant node (OpenClaw-style)
+
+A standing assistant that lives on the canvas, sleeps for free, wakes when a text arrives, reads the conversation, replies over iMessage, and accumulates memory about the people it talks to. Everything here composes existing primitives — no new runtime machinery.
+
+## The shape
+
+| Need | Primitive |
+|---|---|
+| Its own home | Dedicated dir (e.g. `~/assistants/imessage/`), node spawned with `--cwd` pinned there |
+| Always-on, never "finishes" | `--root` spawn → resident lifecycle; dormant between messages costs nothing |
+| Hears incoming texts | launchd watcher on `chat.db-wal` → `crtr node msg <id>` (event-driven; the spine delivers, the node never polls) |
+| Reads messages | sqlite against `~/Library/Messages/chat.db`, cursored by ROWID |
+| Sends replies | `osascript` → Messages.app |
+| Memory | Project-scope substrate (`~/assistants/imessage/.crouter/memory/`) for durable knowledge; context dir for the cursor |
+| Identity/behavior | A custom persona kind (see [[crouter-development/personas]]) |
+| Crash recovery | The daemon auto-revives dead nodes; the watcher's `node msg` also revives a dormant target on its own |
+
+## 1. Persona
+
+Define a kind (e.g. `imessage-assistant`) per [[crouter-development/personas]]. The persona body carries: who it speaks for, which senders it may auto-reply to (allowlist — never reply to arbitrary numbers), voice, the wake loop below, and the memory protocol (when to write a contact note vs. keep it in-thread). Behavior lives in the persona, not in the watcher.
+
+## 2. Spawn
+
+```bash
+mkdir -p ~/assistants/imessage
+crtr node new --root --kind imessage-assistant --cwd ~/assistants/imessage --name imessage <<'EOF'
+You are the standing iMessage assistant. Initialize: read your persona's wake loop, record the current chat.db max ROWID as your cursor, then go dormant. From now on a watcher wakes you via inbox message whenever iMessage activity lands.
+EOF
+```
+
+`--root` makes it independent and resident — top-level on the canvas, no parent to report to, never forced to finish. Add `--headless` if it shouldn't occupy a tmux window. Record the returned node id for the watcher.
+
+## 3. Wake: event-driven, not polled
+
+A trivial launchd agent watches the Messages write-ahead log and pokes the node's inbox. `node msg` revives a dormant target by itself, so the watcher is the *only* off-canvas piece.
+
+```xml
+<!-- ~/Library/LaunchAgents/com.user.imessage-watch.plist (key parts) -->
+<key>WatchPaths</key><array><string>/Users/YOU/Library/Messages/chat.db-wal</string></array>
+<key>ProgramArguments</key><array>
+  <string>/bin/zsh</string><string>-c</string>
+  <string>crtr node msg NODE_ID "iMessage activity — check chat.db since your cursor"</string>
+</array>
+```
+
+Multiple bursts while the node is mid-turn just append to its inbox and coalesce — no dedupe logic needed. Trust the runtime: do **not** also arm a recurring `node wake at` as a backstop. A self-scheduled wake is only the fallback if you choose not to run a watcher at all (pure polling — workable, but pays a window per tick and adds latency).
+
+## 4. Reading chat.db (the verified gotchas)
+
+- The process querying needs **Full Disk Access** (the node's shell inherits the terminal/launchd grant). Read-only — never write to chat.db.
+- Cursor on `message.ROWID`, persisted in the node's context dir (e.g. `context/cursor`); filter `is_from_me = 0`.
+- **On modern macOS `message.text` is often NULL** — the body lives in the `attributedBody` blob (NSAttributedString archive). Extract with:
+
+```python
+import re
+m = re.search(rb'NSString.{1,10}?\+?(.{1,200}?)\x86', attributed_body, re.S)
+text = m.group(1).decode('utf-8', 'ignore') if m else None
+```
+
+- Join for sender + thread:
+
+```sql
+SELECT m.ROWID, h.id AS sender, c.chat_identifier, m.text, m.attributedBody
+FROM message m
+JOIN handle h ON m.handle_id = h.ROWID
+JOIN chat_message_join cmj ON cmj.message_id = m.ROWID
+JOIN chat c ON c.ROWID = cmj.chat_id
+WHERE m.ROWID > :cursor AND m.is_from_me = 0
+ORDER BY m.ROWID;
+```
+
+## 5. Sending
+
+```bash
+osascript -e 'tell application "Messages" to send "reply text" to buddy "+15551234567" of (service 1 whose service type is iMessage)'
+```
+
+Group chats target the chat instead: `send "..." to chat id "iMessage;+;chat123..."` (the `chat.guid` column). First send prompts a one-time **Automation** permission grant for Messages.app.
+
+## 6. Memory
+
+Two tiers, matching [[internal/storage-tiers]]:
+
+- **Durable knowledge** → project-scope memory in the node's pinned dir (`~/assistants/imessage/.crouter/memory/`): one reference per contact/thread (who they are, open loops, tone), loaded by the substrate on the node's own boots. The persona instructs when to write/update these.
+- **Working state** → the node's context dir: the ROWID cursor, drafts, a running log.
+
+## The wake loop (persona-side)
+
+1. Wake on inbox message → read new rows past the cursor.
+2. Decide per message: reply (allowlisted + warranted), note silently, or ignore.
+3. Send via osascript; append anything durable to contact memory.
+4. Advance the cursor, end turn, go dormant. No wake armed — the watcher delivers the next event.

package/dist/builtin-memory/internal/nodes-and-canvas.md

@@ -0,0 +1,49 @@
+---
+kind: reference
+when-and-why-to-read: When you are operating the canvas — spawning or steering nodes, deciding how work reports up, recovering a dormant or crashed node, or reasoning about the daemon — this reference should be read because it is the operational model of nodes, the spine, lifecycle, and revive, so you drive the runtime correctly instead of inferring it from scattered command help.
+short-form: Operational model of the agent runtime — nodes on the canvas graph, spawn/delegate, the push/feed spine, lifecycle states, and revive (manual + daemon auto-revive).
+system-prompt-visibility: name
+file-read-visibility: none
+---
+
+# How nodes and the canvas work (operational)
+
+Every agent is a **node** in one directed graph (the **canvas**). Each node is an independent `pi` process in its own tmux window with its own context dir. The graph's edges are `subscribes_to` — the **spine** — and they decide who-wakes-whom.
+
+## Spawn & delegate
+
+`crtr node new "<task>" --kind <kind>` spawns a managed child in a background window and returns its id immediately; you **auto-subscribe** to it, so its finish wakes you. Delegating is the default move, not an optimization: a child's reading and tokens land in a fresh window and only the conclusion comes back, keeping your own context (the scarce resource) free for steering.
+
+- Match `--kind` to the work (`explore spec design plan developer review general`, plus any custom persona). See `node new -h`.
+- Fan **independent** units out as concurrent children — a wake with idle workers is wasted. Serialize only true dependencies; never let two live children edit the same files.
+- `--root` spawns an independent node you neither manage nor are woken by (e.g. one a human will drive).
+- Once you delegate a unit, don't also run it yourself — you'll be woken when it finishes.
+
+Navigate/steer: `node focus` (jump a node into your pane), `node cycle` (DFS-walk neighbors), `node msg` (direct-message any node at a wake tier, reviving a dormant target), `node subscribe`/`unsubscribe` (wire edges spawn didn't create). Survey with `canvas dashboard` (ASCII tree), `canvas browse` (interactive navigator), `node inspect list/show`, `canvas attention` (who's blocked on a human).
+
+## The push/feed spine
+
+Nothing is reported automatically — the feed contains only what a node **pushes**.
+
+- `push update` — routine progress; fans a lightweight pointer to subscribers, no forced wake.
+- `push urgent` — force-wakes every subscriber (you're blocked, scope changed, an error derails the plan).
+- `push final` — the ONLY way any node finishes: writes the canonical result, marks the node done, closes its window. Stopping without it is not finishing. (Guarded on a node working directly with a user — needs `--force` after they confirm.)
+
+A push fans a ~30-token **pointer** (a ref path), not the content; subscribers dereference lazily. When a subscriber push wakes you, **the wake message already IS the coalesced digest** — don't re-run `feed read` to "open" it (the cursor already advanced); dereference the refs that matter. `feed read` is for proactively polling *before* a wake; `feed peek` shows live state of the nodes below you without draining (use it to confirm workers are alive before you yield). An empty feed while workers run is normal.
+
+## Lifecycle
+
+Two orthogonal axes:
+
+- **mode**: base (a terminal worker — does one job in one window and ends) ↔ orchestrator (`node promote` — a long-lived, roadmap-holding coordinator that delegates phases and survives context refresh via `node yield`). Don't promote for work that fits one window.
+- **lifecycle**: terminal (owes a final up the spine, reaps when done) ↔ resident (`node lifecycle` / interactable — stays dormant, wakes on inbox/human, never forced to finish). `node demote` is the friendly flip-to-terminal-in-place.
+
+A dormant node has two wake triggers: an **inbox** message (push/msg) and the **clock** (`node wake` arms timed/recurring wakeups). To monitor your own children you arm nothing — you auto-subscribe on spawn, so their finish/crash/close wakes you; a deadline to chase a delegate is a belt-and-suspenders the runtime makes redundant.
+
+Tear-down: `node close` cascade-cancels a node + its exclusive subtree WITHOUT finishing (revivable, nothing deleted); `node recycle` finishes the agent in your pane and reboots a fresh root in place; `canvas prune` deletes terminal nodes past a TTL.
+
+## Revive & the daemon
+
+A dormant node (done/idle/dead/canceled) is reopened with `canvas revive` (resumes the saved conversation, or `--fresh` to restart clean). `reviveNode()` is the **only** sanctioned launcher of `pi --session` — it sets `CRTR_NODE_ID` + canvas extensions and runs `transition('revive')`, keeping the db row and pi session in lockstep. Never spawn `pi --session` raw, and never open a node by spawning pi directly — UIs go through `node focus` / `canvas revive`.
+
+The **daemon** (`crtrd`, managed via `canvas daemon start/stop/status`) is a thin supervisor: it polls pane + pi liveness ~every 2s and auto-revives nodes whose window exited. It does NOT host agents and does NOT auto-revive *canceled* nodes (reach for `canvas revive` for those). After rebuilding crouter's `dist/`, restart the daemon — it loads compiled code at start and never reloads it. Restarting is safe: it never signals running nodes.

package/dist/builtin-memory/internal/storage-tiers.md

@@ -0,0 +1,32 @@
+---
+kind: reference
+when-and-why-to-read: When you need to know where a piece of crtr state lives on disk — or you are adding a new kind of file and must decide where it belongs — this reference should be read because it names the three storage tiers and their durability/ownership contracts, so you put (or find) the file in the right place instead of scattering state.
+short-form: The three crtr storage tiers — scope root (durable user/repo content), per-cwd crouter root (per-project working artifacts), and canvas home (node-graph runtime state).
+system-prompt-visibility: name
+file-read-visibility: none
+---
+
+# Where everything lives (the three storage tiers)
+
+crtr state splits into three tiers, each with a distinct durability and ownership contract. This consolidates the contract for routing; for the precise resolver behavior consult the crouter sources (`src/core/scope.ts`, `src/core/artifact.ts`, `src/core/canvas/paths.ts`) and, in the crouter repo, the "Storage locations" section of its `CLAUDE.md`.
+
+## 1. Scope root — durable, user/repo-authored content
+
+`~/.crouter/` (user scope) or `<project>/.crouter/` (project scope). Resolved by the scope resolver (`src/core/scope.ts`). Holds: `skills/`, `plugins/`, `marketplaces/`, `memory/`, `config.json`. Persists across project changes; belongs to the user or the repo.
+
+## 2. Per-cwd crouter root — per-project working artifacts
+
+`~/.crouter/<mangled-cwd>/`, keyed on the originating cwd via `mangleCwd` (`src/core/artifact.ts`). Holds working artifacts like `interactions/` (humanloop decks for the `crtr human` bridge; `interactions/<id>/` holds `deck.json` / `run.json` / `response.json`).
+
+## 3. Canvas home — node-graph runtime state
+
+`~/.crouter/canvas/` (override with `CRTR_HOME`; see `src/core/canvas/paths.ts`). The agent-runtime state for the node graph:
+
+- `canvas.db` — sqlite (WAL) topology store: nodes + edges only. On-screen focus is the `focuses` table here (durable, keyed on tmux `%pane_id`).
+- `nodes/<node_id>/` — each node's durable state: `meta.json` (source of truth for the row), `context/` (roadmap.md, prompts, artifacts), `job/` (`log.jsonl`, `telemetry.json`), `reports/` (append-only `<ts>-<kind>.md` push history), `inbox.jsonl` (messages + coalesced feed), `transcript.jsonl`, `session.ptr` (pi session id).
+
+## The contributor rule
+
+Durable user content → **scope root**. Per-project working artifacts → **per-cwd crouter root**. Node-graph runtime state (topology, context, reports, inbox, telemetry) → **canvas home**.
+
+(The legacy `sessions/` graph and `$XDG_STATE_HOME/crtr/jobs/` tier were removed when the node/canvas runtime replaced the session/job model; node telemetry now lives in each node's `job/telemetry.json` under the canvas home.)

package/dist/clients/attach/attach-cmd.js

@@ -20,6 +20,9 @@ import { CustomEditor, getSelectListTheme, } from '@earendil-works/pi-coding-age
 import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { getNode } from '../../core/canvas/index.js';
+// tmux driver verbs only through placement (the §5.1 model-over-driver seam) —
+// never `core/runtime/tmux.js` directly.
+import { setPaneOption, currentTmux } from '../../core/runtime/placement.js';
 import { ChatView } from './chat-view.js';
 import { InputController } from './input-controller.js';
 import { applyTheme, createKeybindingsManager } from './config-load.js';
@@ -72,6 +75,28 @@ async function runAttach(nodeId, observer) {
             next: 'Check the node has a running headless broker.',
         });
     });
+    // Self-tag this pane with the node it now views so the host-agnostic
+    // `nodeInPane()` (node cycle/recycle/close/demote/lifecycle) resolves a
+    // broker-hosted node from its VIEWER pane — the broker engine runs detached
+    // (window=null), so a window→node lookup can't find it; this pane tag is the
+    // handle. Set AFTER the connect proves a broker is here, mirrors view-run's
+    // `@crtr_view` self-tag. Cleared on teardown so a stray tag can't outlive the
+    // viewer (best-effort; tmux-only).
+    const tagPane = process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    if (tagPane !== undefined && tagPane !== '') {
+        try {
+            setPaneOption(tagPane, '@crtr_node', nodeId);
+        }
+        catch { /* best-effort */ }
+    }
+    const clearPaneTag = () => {
+        if (tagPane !== undefined && tagPane !== '') {
+            try {
+                setPaneOption(tagPane, '@crtr_node', '');
+            }
+            catch { /* best-effort */ }
+        }
+    };
     // 1. Theme + keybindings FIRST — pi's components throw "Theme not initialized"
     //    otherwise (T5 contract). One KeybindingsManager feeds BOTH editor + input.
     applyTheme({ cwd: meta.cwd });
@@ -218,6 +243,7 @@ async function runAttach(nodeId, observer) {
         if (tornDown)
             return;
         tornDown = true;
+        clearPaneTag();
         removeKeyListener();
         // A clean detach tells the broker to drop this viewer (the engine runs on);
         // on broker-gone the socket is already dead, so skip `bye`.

package/dist/commands/memory/write.js

@@ -10,6 +10,14 @@ export const writeLeaf = defineLeaf({
     help: {
         name: 'memory write',
         summary: 'create or update memory/<name>.md at the resolved scope from frontmatter flags + a stdin body',
+        guide: 'The body is the easy part; the craft is ROUTING — every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, forever, so default each rung DOWN.\n\n' +
+            'Pick the kind. skill = how to DO something (a repeatable procedure/playbook); reference = what is TRUE or how something WORKS (a fact about the user, a system\u2019s behavior, code docs); preference = how to BEHAVE (a directive, a standing correction). The test that splits the close pair: does it DIRECT behavior ("always lint after authoring" \u2192 preference) or INFORM the world-model ("Silas likes chicken", "the daemon never reloads dist/" \u2192 reference)? A correction yields a preference, a learned fact a reference, a repeatable procedure a skill.\n\n' +
+            'Set the rungs (none < name < preview < content). Kind sets sensible defaults, so the common case needs no visibility flags at all: skill \u2192 name at boot; preference \u2192 preview at boot; reference \u2192 preview on-read, nothing at boot. Reserve `content` (full body injected) for guidance that is BOTH always-relevant AND ~one bullet long \u2014 fail either test and it is `preview`. Situational guidance is `preview` no matter how short; long guidance is `preview` no matter how universal it feels.\n\n' +
+            'Choose the hook \u2014 boot vs file-read. There are exactly two moments a doc can surface. Behavior and procedure (preferences, skills) are relevant whatever file is open \u2192 surface at boot. Knowledge about code (references) belongs NEXT TO the code: put the file in that directory\u2019s .crouter/memory/ and it fires positionally when files there are read, costing nothing at boot. The exception that matters: a reference about a PERSON or PROCESS has no code directory to anchor to, so on-read triggering is meaningless \u2014 set --system-prompt-visibility preview so its routing line surfaces at boot instead.\n\n' +
+            'Write the routing line (--when-and-why-to-read) FIRST, before storing anything: "When <circumstance the agent is in>, this <kind> should be read because <what the read buys>." The test: can a stranger mid-task decide from that one line alone whether to spend the read? If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user ONE sharp question instead of improvising. ("Remember I like chicken" routes cleanly \u2192 food/meal decisions; "be careful with the API" does not \u2192 which API, careful how, against what failure?) And NEVER paraphrase the advice in the routing line \u2014 a preview that gives away the gist makes every future agent skip the real read. BAD: "\u2026because it carries the placement policy \u2014 -h first, memory only for dev-mode material." GOOD: "\u2026because it carries the standing placement policy."\n\n' +
+            'Find before write. `crtr memory find <topic>` first; grow ONE doc per recurring circumstance rather than minting near-duplicates \u2014 extend `food-preferences`, do not create `likes-chicken`. Group related docs with path names (area/topic). Do not store what is already recorded (code structure, git history, CLAUDE.md) or what only matters to this conversation.\n\n' +
+            'Body: write for a STRANGER \u2014 a future session that shares none of this conversation. State current truth, not the history of getting there (no "as discussed"). Keep the reasoning behind a rule and cut everything else; dense beats complete, since every line costs a mid-task reader.\n\n' +
+            'Gate (--gate, optional): a predicate making the doc eligible only for nodes whose own config matches (e.g. `{ mode: orchestrator }` or `{ orchestration.depth: { gte: 2 } }`); a failing gate hides it from both hooks but it stays findable by search. Default is no gate \u2014 most docs want exactly that. After authoring, validate with `crtr memory lint`.',
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived identity (e.g. `topic` or `area/topic`) → memory/<name>.md at the resolved scope. Updated in place if it already exists, otherwise created.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: true, constraint: 'Document kind.' },

package/dist/commands/memory.js

@@ -20,7 +20,7 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — skills, references, preferences',
-            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. Append `-h` at any leaf for its full schema.',
+            model: '`list` for a human inventory of what is stored — one line per document, the only surface that shows short-form. `read` (leaf) loads one document body by name, resolved project > user > builtin with leaf-name fallback; --frontmatter keeps the YAML header. `find` when you do not yet know which document applies — it ranks by relevance over name/when/why/short-form, --body to also weigh bodies, --grep for an exact regex over bodies. `write` creates or updates memory/<name>.md at a scope from frontmatter flags + a body piped on stdin. `lint` strict-parses the whole bounded corpus and fails on any invalid frontmatter — run it after authoring. A directory may carry an `INDEX.md` with the same frontmatter schema as any doc; the dir then renders as one entry at the INDEX\'s rung, and that rung is a ceiling for its whole subtree (`none` hides the dir) — when a doc mysteriously is not surfacing, check its ancestors\' INDEX rungs and its gate. Append `-h` at any leaf for its full schema, and `crtr memory write -h` for the authoring guide.',
         },
         children: [listLeaf, readLeaf, findLeaf, writeLeaf, lintLeaf],
     });

package/dist/commands/node.d.ts

@@ -4,11 +4,20 @@ import { type BranchDef } from '../core/command.js';
  *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
  *  the child's result. */
 export declare function childFollowUp(spawnerId: string | undefined): string;
-/** The live node occupying a tmux pane (pane → window → node), or undefined.
- *  Defaults to $TMUX_PANE / the caller's current pane when `pane` is omitted —
- *  shared by `node recycle` / `node demote` / `node lifecycle` / `node close` /
- *  `node cycle`, all of which act on "the agent in front of you". Exported for
- *  the `canvas chord` / `canvas tmux-spread` leaves,
- *  which resolve the active pane's node the same way. */
+/** The live node "in front of you" in a tmux pane, HOST-AGNOSTIC. Defaults to
+ *  $TMUX_PANE / the caller's current pane when `pane` is omitted — shared by
+ *  `node recycle` / `node demote` / `node lifecycle` / `node close` / `node
+ *  cycle`, and the `canvas chord` / `canvas tmux-spread` leaves.
+ *
+ *  Two resolutions, tried in order:
+ *    1. VIEWER pane (broker host): a `crtr attach` viewer self-tags its pane with
+ *       the node it views (`@crtr_node`). A broker engine runs DETACHED with
+ *       window=null, so the window→node lookup never finds it — the pane tag is
+ *       the only handle. Checked FIRST because the tag is pane-precise, whereas a
+ *       window is shared: a viewer SPLIT beside a tmux engine pane sits in that
+ *       engine's window, so window→node would mis-resolve to the engine.
+ *    2. ENGINE pane (tmux host): the node owns this pane's window.
+ *  A stale tag (attach SIGKILLed without clearing) is ignored — the tagged node
+ *  must still be live (active/idle); recycle clears it on the tmux respawn path. */
 export declare function nodeInPane(pane?: string): string | undefined;
 export declare function registerNode(): BranchDef;

package/dist/commands/node.js

@@ -15,7 +15,7 @@ import { newNodeId } from '../core/runtime/nodes.js';
 import { readRoadmap } from '../core/runtime/roadmap.js';
 import { parseWhen, parseCadence, cadenceDisplay } from '../core/wake.js';
 import { recycleNode } from '../core/runtime/recycle.js';
-import { detachToBackground, focus as placementFocus, windowAlive, windowOfPane, currentTmux } from '../core/runtime/placement.js';
+import { detachToBackground, focus as placementFocus, windowAlive, windowOfPane, currentTmux, getPaneOption } from '../core/runtime/placement.js';
 import { buildLaunchSpec } from '../core/runtime/launch.js';
 import { closeNode } from '../core/runtime/close.js';
 import { appendInbox } from '../core/feed/inbox.js';
@@ -311,15 +311,32 @@ function nodeByWindow(win) {
     }
     return undefined;
 }
-/** The live node occupying a tmux pane (pane → window → node), or undefined.
- *  Defaults to $TMUX_PANE / the caller's current pane when `pane` is omitted —
- *  shared by `node recycle` / `node demote` / `node lifecycle` / `node close` /
- *  `node cycle`, all of which act on "the agent in front of you". Exported for
- *  the `canvas chord` / `canvas tmux-spread` leaves,
- *  which resolve the active pane's node the same way. */
+/** The live node "in front of you" in a tmux pane, HOST-AGNOSTIC. Defaults to
+ *  $TMUX_PANE / the caller's current pane when `pane` is omitted — shared by
+ *  `node recycle` / `node demote` / `node lifecycle` / `node close` / `node
+ *  cycle`, and the `canvas chord` / `canvas tmux-spread` leaves.
+ *
+ *  Two resolutions, tried in order:
+ *    1. VIEWER pane (broker host): a `crtr attach` viewer self-tags its pane with
+ *       the node it views (`@crtr_node`). A broker engine runs DETACHED with
+ *       window=null, so the window→node lookup never finds it — the pane tag is
+ *       the only handle. Checked FIRST because the tag is pane-precise, whereas a
+ *       window is shared: a viewer SPLIT beside a tmux engine pane sits in that
+ *       engine's window, so window→node would mis-resolve to the engine.
+ *    2. ENGINE pane (tmux host): the node owns this pane's window.
+ *  A stale tag (attach SIGKILLed without clearing) is ignored — the tagged node
+ *  must still be live (active/idle); recycle clears it on the tmux respawn path. */
 export function nodeInPane(pane) {
     const resolvePane = pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
-    const win = resolvePane !== undefined && resolvePane !== '' ? windowOfPane(resolvePane) : null;
+    if (resolvePane === undefined || resolvePane === '')
+        return undefined;
+    const tagged = getPaneOption(resolvePane, '@crtr_node');
+    if (tagged !== undefined && tagged !== '') {
+        const m = getNode(tagged);
+        if (m !== null && (m.status === 'active' || m.status === 'idle'))
+            return tagged;
+    }
+    const win = windowOfPane(resolvePane);
     return win !== null ? nodeByWindow(win) : undefined;
 }
 const nodeRecycle = defineLeaf({
@@ -360,8 +377,15 @@ const nodeRecycle = defineLeaf({
         return { recycled: res.recycled, node_id: id, finalized: res.finalized, delivered: res.delivered.length, new_root: res.newRoot ?? undefined };
     },
     render: (r) => {
-        if (r['recycled'] !== true)
+        if (r['recycled'] !== true) {
+            // A broker recycle that finalized + spawned a fresh root but whose new
+            // broker never served its socket: the state DID change (node finished, root
+            // born), only the viewer re-attach failed — say so, don't call it a no-op.
+            if (r['finalized'] === true && r['new_root']) {
+                return `Finished ${r['node_id']} and spawned a fresh broker root (${r['new_root']}), but its viewer did not attach — the new broker did not come up. Re-focus the root to view it.`;
+            }
             return `Recycle failed for ${r['node_id'] ?? '?'} — not in tmux, or no agent in this pane.`;
+        }
         const lines = [`Recycled the pane — finished ${r['node_id']}.`, `- finalized: ${r['finalized']}`];
         if (r['finalized'] === true)
             lines.push(`- delivered: ${r['delivered']}`);

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/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/naming.d.ts

@@ -6,17 +6,13 @@ export declare function sanitizeSessionName(raw: string): string;
 /** Local fallback: derive a name straight from the prompt (no pi call). Drops
  *  stop-words, takes the first few content words. */
 export declare function slugFromPrompt(prompt: string): string;
-/** Synchronously ask pi for a 3-8 word kebab name for `prompt`. Blocks up to
- *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
- *  output) falls back to a local slug. Returns '' only for an empty prompt. */
-export declare function generateSessionName(prompt: string): string;
 /** Asynchronously generate a name for `prompt` and persist it to the node's
  *  meta as `description` — only if the node has none yet (so a later message
  *  never clobbers it). Non-blocking: safe to call from inside a live pi event
  *  loop. Best-effort; swallows all errors.
  *
  *  `onNamed` (optional) fires with the freshly-persisted meta the moment the
- *  name lands — the bare-root path passes a callback that calls
+ *  name lands — the canvas-goal-capture naming hook passes a callback that calls
  *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
  *  same session, instead of waiting for the next revive/cycle. */
 export declare function generateAndPersistName(nodeId: string, prompt: string, onNamed?: (meta: NodeMeta) => void): void;

package/dist/core/runtime/naming.js

@@ -6,19 +6,16 @@
 // the first prompt by asking pi headlessly (`pi -p`), persisted on the node's
 // meta so it survives revives and shows in every cycle.
 //
-// Two entry points:
-//   • generateSessionName  — synchronous (spawnSync). For the CLI spawn paths
-//     (spawnChild / bootRoot) that run outside any pi event loop, where a brief
-//     block before launching the worker is fine and lets the FIRST pi session
-//     already carry the name.
-//   • generateAndPersistName — async (execFile, non-blocking). For the bare-root
-//     case where the prompt only arrives as the first interactive message inside
-//     a live pi process; it must never block the event loop. Persists the name
-//     to meta so the label picks it up on the next cycle.
+// One entry point: generateAndPersistName — async (execFile, non-blocking).
+// Naming happens INSIDE the named node's own pi process, off the first real
+// message (the kickoff task or a human's first line), never on the spawn path:
+// blocking spawn on an LLM round-trip used to freeze the caller's terminal for
+// 2-3s on every `crtr node new`. The headless namer runs with --no-extensions,
+// so it loads no canvas hooks and can never recurse into another spawn/name.
 //
-// Both are best-effort: a failed/slow/garbled pi call falls back to a local slug
-// of the prompt, so a node always gets a sane name.
-import { spawnSync, execFile } from 'node:child_process';
+// Best-effort: a failed/slow/garbled pi call falls back to a local slug of the
+// prompt, so a node always gets a sane name.
+import { execFile } from 'node:child_process';
 import { getNode, updateNode } from '../canvas/index.js';
 /** Cap on prompt text fed to the namer — a name needs only the gist. */
 const PROMPT_CAP = 2000;
@@ -97,30 +94,27 @@ function nameArgs(prompt) {
     argv.push(nameUserPrompt(prompt));
     return argv;
 }
-/** Synchronously ask pi for a 3-8 word kebab name for `prompt`. Blocks up to
- *  NAME_TIMEOUT_MS; on any failure (non-zero exit, timeout, empty/garbled
- *  output) falls back to a local slug. Returns '' only for an empty prompt. */
-export function generateSessionName(prompt) {
-    const body = (prompt ?? '').trim();
-    if (body === '')
-        return '';
-    try {
-        const r = spawnSync('pi', nameArgs(body), {
-            encoding: 'utf8',
-            timeout: NAME_TIMEOUT_MS,
-            // Don't inherit a TUI; capture stdout only.
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
-        if (r.status === 0 && typeof r.stdout === 'string') {
-            const name = sanitizeSessionName(r.stdout);
-            if (name !== '')
-                return name;
+/** Ask pi headlessly for a kebab-case name for `body`, async. Resolves to the
+ *  sanitized name, or '' on any failure (non-zero exit, timeout, empty/garbled
+ *  output) so the caller can fall back to a local slug. Owns the subprocess
+ *  mechanics — crucially it hands pi an immediate stdin EOF: `pi -p` reads
+ *  stdin, and execFile's default stdin is an OPEN pipe that never closes, so
+ *  without this pi blocks waiting for EOF and the call exits non-zero (the
+ *  regression that silently lost every LLM name to the slug fallback). */
+function headlessName(body) {
+    return new Promise((resolve) => {
+        try {
+            const child = execFile('pi', nameArgs(body), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
+                if (err || typeof stdout !== 'string')
+                    return resolve('');
+                resolve(sanitizeSessionName(stdout));
+            });
+            child.stdin?.end(); // immediate EOF — see the doc above
         }
-    }
-    catch {
-        // fall through to slug
-    }
-    return slugFromPrompt(body);
+        catch {
+            resolve('');
+        }
+    });
 }
 /** Asynchronously generate a name for `prompt` and persist it to the node's
  *  meta as `description` — only if the node has none yet (so a later message
@@ -128,7 +122,7 @@ export function generateSessionName(prompt) {
  *  loop. Best-effort; swallows all errors.
  *
  *  `onNamed` (optional) fires with the freshly-persisted meta the moment the
- *  name lands — the bare-root path passes a callback that calls
+ *  name lands — the canvas-goal-capture naming hook passes a callback that calls
  *  pi.setSessionName(editorLabel(meta)) so the LIVE editor label updates in the
  *  same session, instead of waiting for the next revive/cycle. */
 export function generateAndPersistName(nodeId, prompt, onNamed) {
@@ -150,17 +144,7 @@ export function generateAndPersistName(nodeId, prompt, onNamed) {
             // best-effort
         }
     };
-    try {
-        execFile('pi', nameArgs(body), { encoding: 'utf8', timeout: NAME_TIMEOUT_MS }, (err, stdout) => {
-            if (err || typeof stdout !== 'string') {
-                persist(slugFromPrompt(body));
-                return;
-            }
-            const name = sanitizeSessionName(stdout);
-            persist(name !== '' ? name : slugFromPrompt(body));
-        });
-    }
-    catch {
-        persist(slugFromPrompt(body));
-    }
+    void headlessName(body).then((name) => {
+        persist(name !== '' ? name : slugFromPrompt(body));
+    });
 }

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/runtime/spawn.js

@@ -14,7 +14,6 @@ import { spawnNode, currentNodeContext, resolveBirthSession, nodeSession, rootOf
 import { buildLaunchSpec, buildPiArgv } from './launch.js';
 import { writeGoal } from './kickoff.js';
 import { hasRoadmap, seedRoadmap } from './roadmap.js';
-import { generateSessionName } from './naming.js';
 import { buildIdentityAssertion, buildWakeBearings } from './bearings.js';
 import { installMenuBinding, installNavBindings, installViewNavBindings } from './tmux-chrome.js';
 import { setPresence, updateNode, getNode, fullName } from '../canvas/index.js';
@@ -35,19 +34,16 @@ export function bootRoot(opts) {
     // 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 });
-    // A root opened WITH a prompt gets its editor name now (so the first pi
-    // session already carries it). A bare root has no prompt yet — the
-    // goal-capture extension names it from the first message (async, next cycle).
-    const description = opts.prompt !== undefined && opts.prompt.trim() !== ''
-        ? generateSessionName(opts.prompt)
-        : undefined;
+    // Born WITHOUT a name. Naming is async + event-driven: the canvas-goal-capture
+    // extension names the node from its FIRST real message (the kickoff prompt or
+    // a human's first line) inside its own pi process, via a headless `pi -p`.
+    // Never block the front door on an LLM round-trip.
     const meta = spawnNode({
         kind,
         mode: 'base',
         lifecycle: 'resident',
         cwd: opts.cwd,
         name: opts.name ?? kind,
-        description,
         parent: null,
         launch,
     });
@@ -162,14 +158,15 @@ export function spawnChild(opts) {
     // independent root sits top-of-spine with nobody to push to. Mirrors the
     // `parent` set below (root ? null : spawner), so hasManager === parent!==null.
     const { launch } = buildLaunchSpec(opts.kind, mode, { lifecycle, hasManager: !root, model: opts.model });
-    // Name the worker from its task now, so its first editor label carries it.
+    // Born WITHOUT a name — the canvas-goal-capture extension names it async from
+    // its first message (the kickoff task) inside its own pi process, so spawn
+    // never blocks on the LLM naming round-trip (the 2-3s freeze it used to cost).
     const meta = spawnNode({
         kind: opts.kind,
         mode,
         lifecycle,
         cwd: opts.cwd,
         name: opts.name ?? opts.kind,
-        description: generateSessionName(opts.prompt),
         // A root has no spine parent (top-level, nobody subscribes); it still
         // records spawned_by=spawner when a node (not a human shell) spawned it.
         // A child's parent IS its manager.

package/dist/core/substrate/render.js

@@ -237,12 +237,22 @@ function renderChildren(dir, childPrefix, lines) {
     });
 }
 /** Build the file tree for a kind's eligible docs, headed by `rootLabel`.
- *  Returns '' when there are no docs at all (the empty-tree contract). */
+ *  Returns '' when there are no docs at all (the empty-tree contract).
+ *
+ *  `docs` arrives in precedence order (project > user > builtin, node-local last)
+ *  WITHOUT cross-scope dedup — `listAllMemoryDocs` returns every scope's hit for
+ *  a path-derived name and leaves first-wins dedup to the caller. So a name
+ *  present in two scopes is deduped here (first occurrence wins); otherwise it
+ *  would render as two identical sibling lines and double-count into `[+N more]`. */
 function buildTree(docs, rootLabel) {
     if (docs.length === 0)
         return '';
     const root = newDir('');
+    const seen = new Set();
     for (const d of docs) {
+        if (seen.has(d.name))
+            continue; // first-wins cross-scope dedup
+        seen.add(d.name);
         if (isIndexName(d.name)) {
             const dir = ensureDir(root, indexDirOf(d.name));
             if (dir.index === null)

package/dist/index.d.ts

@@ -1 +1,19 @@
-export {};
+export { spawnChild } from './core/runtime/spawn.js';
+export type { SpawnChildOpts, SpawnChildResult } from './core/runtime/spawn.js';
+export { reviveNode } from './core/runtime/revive.js';
+export type { ReviveResult } from './core/runtime/revive.js';
+export { closeNode } from './core/runtime/close.js';
+export type { CloseNodeResult } from './core/runtime/close.js';
+export { appendInbox } from './core/feed/inbox.js';
+export type { InboxEntry, InboxTier, InboxKind } from './core/feed/inbox.js';
+export { getNode, listNodes } from './core/canvas/canvas.js';
+export { nodeDir } from './core/canvas/paths.js';
+export type { NodeMeta, NodeRow, NodeStatus, Lifecycle, Mode, } from './core/canvas/types.js';
+export { asksForNodes, asksAcrossCanvas } from './core/canvas/attention.js';
+export type { AskEntry } from './core/canvas/attention.js';
+export { readTelemetry, readContextTokens } from './core/canvas/telemetry.js';
+export type { Telemetry } from './core/canvas/telemetry.js';
+export { ViewSocketClient, BrokerUnavailableError } from './clients/attach/view-socket.js';
+export { encodeFrame, FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, BROKER_READ_CAPS, } from './core/runtime/broker-protocol.js';
+export type { FrameDecoderCaps, BrokerSnapshot, ClientRole, WelcomeFrame, ControlChangedFrame, AckFrame, ErrorFrame, ExtensionUIRequestFrame, BrokerToClient, HelloFrame, PromptFrame, SteerFrame, FollowUpFrame, AbortFrame, RequestControlFrame, ReleaseControlFrame, ByeFrame, ShutdownFrame, SetModelFrame, CycleModelFrame, SetThinkingLevelFrame, SetAutoRetryFrame, SetAutoCompactionFrame, CompactFrame, NewSessionFrame, SwitchSessionFrame, ForkFrame, SetSessionNameFrame, GetCommandsFrame, NavigateTreeFrame, ReloadFrame, ExportFrame, ClientToBroker, RpcExtensionUIRequest, RpcExtensionUIResponse, ExtensionUIResponseFrame, } from './core/runtime/broker-protocol.js';
+export type { SessionStats } from '@earendil-works/pi-coding-agent';

package/dist/index.js

@@ -1 +1,26 @@
-export {};
+// @crouton-kit/crouter — the sanctioned library surface (design D1).
+//
+// This barrel is the ONLY supported way to import crouter as a library; the
+// `exports` map gates off deep subpath imports, so consumers (notably
+// @crouton-kit/crouter-web) depend on exactly the symbols re-exported here.
+// Everything below is a stable, server-facing surface: runtime control that
+// keeps the canvas-row ⇄ pi-session lockstep guarantees, read-only canvas/
+// telemetry queries, and the broker socket client + wire protocol. Nothing
+// internal (CLI plumbing, helpers) is exported. This module has no load-time
+// side effects and no circular imports — keep it that way.
+// ── Runtime control ──────────────────────────────────────────────────────
+// Sanctioned launchers/mutators. reviveNode is the ONLY sanctioned launcher of
+// `pi --session`; spawnChild's host is chosen via `hostKind: 'tmux' | 'broker'`.
+export { spawnChild } from './core/runtime/spawn.js';
+export { reviveNode } from './core/runtime/revive.js';
+export { closeNode } from './core/runtime/close.js';
+export { appendInbox } from './core/feed/inbox.js';
+// ── Canvas reads ─────────────────────────────────────────────────────────
+export { getNode, listNodes } from './core/canvas/canvas.js';
+export { nodeDir } from './core/canvas/paths.js';
+export { asksForNodes, asksAcrossCanvas } from './core/canvas/attention.js';
+export { readTelemetry, readContextTokens } from './core/canvas/telemetry.js';
+// ── Broker client ────────────────────────────────────────────────────────
+export { ViewSocketClient, BrokerUnavailableError } from './clients/attach/view-socket.js';
+// ── Broker wire protocol (codec + frame/protocol types) ──────────────────
+export { encodeFrame, FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, BROKER_READ_CAPS, } from './core/runtime/broker-protocol.js';

package/dist/pi-extensions/canvas-goal-capture.js

@@ -3,13 +3,23 @@
 // Loaded into every canvas node's pi process via the node's launch.extensions
 // list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
 //
-// A node spawned with a prompt has its goal persisted at birth (writeGoal in
-// spawn.ts). A bare root (`crtr` with no prompt) starts goal-less — its mandate
-// only arrives when the human types their first message. This extension closes
-// that gap: on the FIRST interactive user message, if the node has no goal yet,
-// it persists that message as context/initial-prompt.md. Subsequent messages
-// never clobber it (captureGoalIfAbsent is guarded), and a fresh-revive kickoff
-// prompt is skipped via its sentinel so it can never be mistaken for a mandate.
+// Two first-message jobs, both keyed off the node's first real `input` event:
+//
+//   1. Goal capture (bare roots). A node spawned with a prompt has its goal
+//      persisted at birth (writeGoal in spawn.ts). A bare root (`crtr` with no
+//      prompt) starts goal-less — its mandate only arrives when the human types
+//      their first message; this persists that as context/initial-prompt.md.
+//      Guarded so later messages never clobber it.
+//
+//   2. Naming (every node). Naming is async + event-driven — it does NOT run on
+//      the spawn path (that blocking LLM call froze the caller's terminal for
+//      2-3s on every spawn). On the first real message, if the node has no name
+//      yet, ask pi headlessly (async, non-blocking) for a kebab-case name and
+//      live-update the editor label. The first message may be a human's line OR
+//      a delegated child's kickoff task — naming off the agent prompt is fine.
+//
+// Both skip extension-injected messages (inbox wakes, steering) and the
+// fresh-revive kickoff (its sentinel), so neither is mistaken for a first input.
 //
 // Pure observation — it writes the goal file as a side effect and always lets
 // the message through unchanged (returns nothing ⇒ continue). Registered before
@@ -20,7 +30,7 @@
 // crouter's own tsc build without a dep on the pi packages.
 import { captureGoalIfAbsent, REVIVE_KICKOFF_SENTINEL } from '../core/runtime/kickoff.js';
 import { generateAndPersistName } from '../core/runtime/naming.js';
-import { editorLabel } from '../core/canvas/index.js';
+import { editorLabel, getNode } from '../core/canvas/index.js';
 /**
  * Register the goal-capture handler on `pi`.
  *
@@ -34,26 +44,32 @@ export function registerCanvasGoalCapture(pi) {
             const nodeId = process.env['CRTR_NODE_ID'];
             if (nodeId === undefined || nodeId.trim() === '')
                 return; // not a canvas node
-            // Only a genuine human-typed prompt seeds the mandate — never an RPC or an
-            // extension-injected message (inbox wakes, steering nudges, kickoffs).
-            if (event.source !== 'interactive')
-                return;
             const text = (event.text ?? '').trim();
             if (text === '')
                 return;
-            // A fresh-revive kickoff is delivered as the launch prompt; never let it
-            // masquerade as the user's first mandate.
+            // Never seed a mandate or a name from an extension-injected message (inbox
+            // wakes, steering nudges) or a fresh-revive kickoff (the node is already
+            // named). Both would otherwise masquerade as the node's first real input.
+            if (event.source === 'extension')
+                return;
             if (text.startsWith(REVIVE_KICKOFF_SENTINEL))
                 return;
-            // First mandate for a bare root: persist it as the goal, and ask pi
-            // (async, non-blocking) to name the session from it. The name lands on
-            // meta.description; the onNamed callback pushes the new editor label into
-            // THIS live session via setSessionName, so it updates immediately instead
-            // of only on the next cycle.
-            if (captureGoalIfAbsent(nodeId, text)) {
-                generateAndPersistName(nodeId, text, (meta) => {
+            // Goal capture is bare-root only: a delegated child already had its goal
+            // persisted at birth (writeGoal), so only a genuine human-typed prompt
+            // seeds a mandate here.
+            if (event.source === 'interactive')
+                captureGoalIfAbsent(nodeId, text);
+            // Naming: name the node from its FIRST real message — a human's first line
+            // OR a delegated child's kickoff task (naming off the agent prompt is
+            // fine) — whenever it has no name yet. Async headless `pi -p` with no
+            // canvas extensions, so it never recurses into another spawn/name. The
+            // onNamed callback live-updates THIS session's label instead of waiting
+            // for the next cycle. The unnamed-guard keeps it to one call per node.
+            const meta = getNode(nodeId);
+            if (meta !== null && (meta.description ?? '').trim() === '') {
+                generateAndPersistName(nodeId, text, (named) => {
                     try {
-                        pi.setSessionName?.(editorLabel(meta));
+                        pi.setSessionName?.(editorLabel(named));
                     }
                     catch { /* best-effort */ }
                 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.25",
+  "version": "0.3.27",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",