@crouton-kit/crouter 0.3.25 → 0.3.26

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 (frontmatter, rungs, gates, the asked-to-remember workflow) is owned by the builtin **memory-authoring** skill; 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/builtin-memory/memory-authoring.md

@@ -0,0 +1,100 @@
+---
+kind: skill
+when-and-why-to-read: When you are about to write or update a memory document — including any time the user asks you to remember something — or need to debug why a document is (not) surfacing, this skill should be read because it tells you how to choose kind and scope, set the disclosure rungs and gate, size the body, and when to first ask the user a clarifying question.
+short-form: Author excellent memories — kind, scope, visibility rungs, gates, body sizing, and the asked-to-remember workflow.
+system-prompt-visibility: preview
+file-read-visibility: none
+---
+
+# Writing memories
+
+A memory is a markdown document whose frontmatter decides **when, where, and how much** of it loads into future agents. The body is the easy part; the craft is routing — deciding who sees it, at what moment, at what context cost. Every frontmatter choice below is a routing choice.
+
+## When asked to remember something
+
+1. **Write the routing line first.** Before storing anything, try to complete: *"When <circumstance>, this <kind> should be read because <payoff>."* If you cannot name the concrete situation a future agent will be in when this matters, you do not understand the memory yet — ask the user **one sharp question** instead of improvising. "Remember I like chicken" routes cleanly (food/meal decisions); "remember to be careful with the API" does not (which API? careful how? against what failure?) — that one needs clarifying before it becomes a memory. The routing line is a comprehension test.
+2. **Find before write.** `crtr memory find <topic>` for an existing doc; update it rather than minting a near-duplicate. Prefer growing `food-preferences` over creating `likes-chicken` — one document per recurring *circumstance*, not one per fact. Group related docs with path names (`area/topic`). Delete memories that turn out wrong.
+3. **Capture the why, not just the what.** Especially for corrections: record what was rejected and the reasoning. The why is what lets a future agent apply the rule to cases you never saw.
+4. **Don't store what's already recorded** — code structure, git history, CLAUDE.md content — or what only matters to this conversation. If asked to remember something the repo already records, ask what was non-obvious about it and store that instead.
+
+## Choosing kind
+
+- **skill** — how to *do* something (a playbook, a procedure you'd repeat).
+- **reference** — what is *true* or how something *works* (a fact about the user, a system's behavior, code docs).
+- **preference** — how to *behave* (a directive, a standing correction).
+
+The reference-vs-preference test: does it direct behavior ("always run lint after authoring") or inform the world-model ("Silas likes chicken", "the daemon never reloads dist/")? A correction usually yields a preference; a learned fact yields a reference; a repeatable procedure yields a skill.
+
+Kind sets sensible default rungs — the common case needs no visibility fields at all:
+
+| kind | at boot | on file-read |
+|---|---|---|
+| skill | name | none |
+| preference | preview | none |
+| reference | none | preview |
+
+## The two hooks — boot vs file-read
+
+There are exactly two moments a doc can surface. `system-prompt-visibility` governs **boot** (the system prompt); `file-read-visibility` governs **on-read** (when a related file is opened).
+
+- Behavior and procedure (preferences, skills) are relevant regardless of which file is open → surface at boot, stay out of file-read. That is what the defaults do.
+- Knowledge about code (references) belongs **next to the code**: put the doc in that directory's `.crouter/memory/` and it fires positionally when files under that directory are read — costing nothing at boot.
+- The exception that matters: a reference about a *person or a process* ("Silas's food preferences") has no code directory to anchor to, so positional triggering is meaningless — set `system-prompt-visibility: preview` so its routing line surfaces at boot instead.
+- `applies-to: <glob or list>` extends the on-read trigger beyond position for cross-cutting docs (e.g. a testing reference that should fire for `**/*.test.ts` anywhere).
+
+## Choosing the rung
+
+`none → name → preview → content`. Each rung up costs more of **every** future agent's context, paid at every boot or read, forever. Default down, not up.
+
+- **content** (full body injected): reserved for guidance that is BOTH always relevant AND ~one bullet's worth of text. Fail either test → preview. Situational guidance is preview *no matter how short*; long guidance is preview no matter how universal it feels.
+- **preview** (the one-sentence routing line): the workhorse. Costs one line; the body is read on demand.
+- **name** (title only): catalog-style docs whose name already routes (`api-reference`).
+- **none**: invisible except to `crtr memory find` — archival or narrowly specialized material.
+
+`short-form` is NOT a rung and never enters an agent's context (an agent handed a summary satisfices and skips the real read). It is the gist a human sees in `crtr memory list` — write it for them, and don't make it do routing work.
+
+## The routing line
+
+`when-and-why-to-read` is **read-routing, never content**: it answers when to open the doc and why the read pays — never why the content should be obeyed, and never a paraphrase of the content. A preview that gives away the gist defeats the ladder: the agent feels informed and skips the body. Shape: *"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 this single line alone whether to spend the read?
+
+## Gates — conditioning on who the agent is
+
+An optional `gate:` predicate makes the doc eligible only for nodes whose own config matches. Subject fields: `kind` (node role, free-form), `mode` (base|orchestrator), `lifecycle` (terminal|resident), `hasManager` (bool), `cwd`, `scope` (user|project), `orchestration.depth` (hops to the root orchestrator; root = 0). Matchers: scalar equality, list membership, or operator objects (`{gte: 2}`, `{in: […]}`, `{matches: "…"}`, `exists`, `contains`…), with `all`/`any`/`not` combinators.
+
+```yaml
+gate: { mode: orchestrator }               # only delegating managers
+gate: { orchestration.depth: { gte: 2 } }  # only substantial, scaled-up efforts
+```
+
+Default is no gate — always eligible; most docs want exactly that. An empty `gate: {}` is inert (never matches) — don't write it. A failing gate hides the doc from both hooks, but it stays findable by search.
+
+## Scope — where the file lives
+
+- **user** (`~/.crouter/memory/`): facts about the user, cross-project behavior. The chicken memory goes here.
+- **project** (`<dir>/.crouter/memory/`): anything about a codebase or workspace — and place it in the *specific directory* it describes (any directory can hold a `.crouter/`), so positional on-read fires precisely.
+- **builtin**: ships with crtr itself (contributed via `src/builtin-memory/` in the crouter repo) — docs every crtr agent should have.
+
+Resolution is project > user > builtin with leaf-name fallback (`read <leaf>` finds `area/<leaf>` when unambiguous), so a project doc can shadow a same-named user or builtin doc.
+
+## Mechanics worth knowing
+
+- **Directory entries**: 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 subtree** (`none` hides the whole dir). When a doc mysteriously isn't surfacing, check its ancestors' INDEX rungs and its gate.
+- **CLI**: `crtr memory list` (human inventory) · `read <name>` (names are path-derived, never file paths) · `find <query>` (search ignores gates and rungs) · `write` (author) · `lint` (validate after authoring). Run `-h` on a leaf before first use.
+
+## Body content
+
+Write for a stranger: a future session that shares none of this conversation. No "as discussed", no narration of how you learned it — state current truth, not the history of getting there. Keep the reasoning behind rules; cut everything else. Don't pad: a preference can legitimately be two sentences, and a skill should lead with decisions, not mechanism. A body behind `preview` may be long when it earns it, but every line still costs a reader who is mid-task — dense beats complete.
+
+## Worked example
+
+User says: *"remember that I like chicken."*
+
+```bash
+echo "Silas likes chicken." | crtr memory write food-preferences \
+  --kind reference --scope user \
+  --when-and-why-to-read "When you are choosing or recommending food, meals, or recipes for Silas, this reference should be read because it records his food preferences." \
+  --short-form "Silas's food likes/dislikes" \
+  --system-prompt-visibility preview
+```
+
+Reference (a fact, not a directive) · user scope (about the person, not a repo) · `preview` at boot (no code directory to anchor on-read) · named for the recurring circumstance, so future food facts append to the same doc. After authoring, validate: `crtr memory lint`.

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/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/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/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/package.json

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