@north-light/crouter 0.3.154

package/dist/builtin-memory/product.md

@@ -0,0 +1,80 @@
+---
+kind: knowledge
+when-and-why-to-read: When running a product-discovery effort, shaping a product roadmap, or deciding how to stage problem discovery, competitive teardown, and experience definition, this knowledge should be read so the real user need is tested before solution commitment and downstream specification starts from one evidence-grounded direction.
+short-form: Use when running a product-discovery effort or shaping a product roadmap. Covers the three-stage DISCOVER→GROUND→DEFINE methodology, the Mom Test discovery discipline, the four-risks ownership boundary vs the downstream spec, parallel teardown delegation, and what a finished product brief contains.
+system-prompt-visibility: name
+file-read-visibility: none
+gate:
+  kind:
+    imatches: '^product($|/)'
+needs-refinement: true
+---
+
+## The Three Stages
+
+A product-discovery effort runs in this order: **DISCOVER** → **GROUND** → **DEFINE**. GROUND and DEFINE interleave (you ground to inform the definition), but you do not commit a product direction in DEFINE until DISCOVER has cleared its gate. Each stage has a gate; you do not commit the next until the current one is met.
+
+### Stage 1 — Discover (problem-space)
+
+Discover is where you find the real need. A client arrives with a solution in their mouth and a problem in their gut; your job is to reach the problem. Treat the request as a hypothesis, not an order — work the **job-to-be-done**: what the user is hiring this product to accomplish (functional, emotional, and social dimensions), for whom, in what triggering moment, and what they do today instead and why it falls short.
+
+Run discovery with `crtr human ask` using the **Mom Test discipline**: ask about real, specific past behavior and concrete pain ("walk me through the last time you hit this"), never pitch your idea, and never ask hypothetical "would you use…" questions — they invite politeness, not truth. Real pain is validated by current workarounds, emotional language, and evidence of prior spend, not hypothetical enthusiasm. Earn every question: answer what you can yourself by tearing down existing products and reading the codebase first; only judgment-bearing, genuinely unresolved questions reach the human.
+
+Write each core need as a **JTBD statement** — `verb + object + context` ("minimize the time to capture a thought on the go") or `When [situation], I want to [motivation], so I can [outcome]` — across all three dimensions (functional, emotional, social); the emotional and social dimensions are the ones teams skip and are exactly what feed the experience work in Define. Structure the discovery output as an **opportunity solution tree** (Torres): one measurable **outcome** at the root, the **opportunities** (unmet needs/pains, sourced from real evidence) beneath it, and candidate **solutions** each tied to a specific opportunity, with the riskiest **assumptions** to test hanging off them. The tree's whole job is to forbid jumping from the outcome straight to a solution and to force more than one branch — it kills the single-track tunnel vision that order-taking produces.
+
+The request and the real job often diverge. When the asked-for feature does not serve the underlying job, say so and steer — building exactly what was asked when it won't meet the need is the central failure this role exists to prevent.
+
+Gate: the client confirms you have the real problem and the users right — restate the job without correction, and the requested feature is either validated as serving it or consciously redirected.
+
+### Stage 2 — Ground (competitive)
+
+Before committing a direction, study how comparable products solve the same job. This is not a feature survey — it is a teardown of the *experience*: interaction patterns, what each product gets right (borrow), where it fails its users (avoid), and where a new product could beat it (differentiate).
+
+Delegate one `product/teardown` child per comparable product and run them in parallel; each studies one product deeply against the job-to-be-done and returns a verdict. Integrate the teardowns yourself into a single **positioning stance** — borrow / avoid / differentiate — never a concatenation and never a copy. Inspiration becomes a defensible direction only when you can say why you are borrowing or rejecting each pattern *for this job*.
+
+Treat competitor patterns as hypotheses, not proven-optimal truth — their design may never have been tested. Do not chase feature parity; it is easily copied and commoditizes you. Instead find the **market orthodoxy** (what every comparable product does the same way), locate the customer-satisfaction gap that orthodoxy leaves open, and pick an opposite dimension that matters to a specific segment. Express the result as a positioning statement: **"Unlike [competitor], [product] provides [durable outcome] because [verifiable reason to believe]."** The reason must rest on something that *compounds* (proprietary data, domain depth, a unique posture), not a UI tweak or a vague "easier to use" claim.
+
+Gate: a positioning stance exists that names what you will borrow, what you will avoid, and how you will differentiate — on a dimension that compounds.
+
+### Stage 3 — Define (experience)
+
+Define commits the opinionated product direction. It produces: the **use cases** the product serves; **3–7 experience principles** (opinionated, prioritized — "instant over configurable", not platitudes); the **emotional target** ("using this should feel like…"); a **user journey** with its moments of truth — where the product must delight and where it must not fail; and a **product vision + North Star** that names the one outcome the product optimizes. Be opinionated: a definition that lists options without a recommendation has not done the consulting.
+
+Gate: the client aligns on the product direction and the experience — the feel, the use cases, and the vision.
+
+---
+
+## The Four Risks — What This Role Owns
+
+Every product idea carries four risks (Cagan): **value** (will anyone want it), **usability** (can they use it), **feasibility** (can we build it), **viability** (does it work for the business — brand, legal, economics). This role **owns value, usability, and experience**: discovering them and defining for them is the job. It **flags viability** when it surfaces (a direction that risks the brand, a legal exposure, an economics problem) but does not adjudicate it. It **defers feasibility** entirely to engineering — never let "is this buildable" narrow the product direction during discovery; that is the downstream spec and design work, and pre-empting it trades a clean problem for a brittle answer.
+
+Discovery exists to attack these risks *cheaply and early* — with the assumption inventory and small tests, not engineering cycles. Treat the opening problem statement as a set of unproven hypotheses: categorize the claims (behavioral / emotional / economic), rank them by risk, and surface the riskiest first — the ranked inventory is the explicit baton of what still needs validating.
+
+---
+
+## The Boundary With Spec — Where the Baton Passes
+
+This role stops at **the right product to build and how it should feel and look.** It does NOT write acceptance criteria, EARS requirements, user stories, API or data models, or pixel-level UI. Those belong to the downstream `spec` (buildable behavior, interfaces, edge cases) and `design` (architecture, UI structure) kinds.
+
+The baton handed to spec is four things: the **validated problem** (job, users, pain), the **experiential direction** (use cases, experience principles, emotional target, journey), the **competitive grounding** (positioning stance), and the **ranked open assumptions** the spec stage must resolve. A clean baton is a sharp *problem and direction*, not a half-written solution — pre-deciding the spec's job hands it an answer to verify instead of a problem to specify.
+
+---
+
+## What a Finished Product Brief Contains
+
+A product brief is lightweight, living, and decision-driving — not a heavy PRD. It is finished when a spec writer could derive what to build from it without re-discovering the user. It contains:
+
+- **Validated problem / opportunity** — the real job-to-be-done (functional, emotional, social), who has it, the pain, and what they do today.
+- **Use cases** — the concrete situations the product serves, in the user's terms.
+- **Experience definition** — 3–7 opinionated experience principles, the emotional target, and a user journey with its moments of truth (delight points and must-not-fail points).
+- **Competitive grounding + positioning** — what comparable products teach, and the borrow / avoid / differentiate stance.
+- **Product vision + North Star** — the one outcome the product optimizes, and the direction it implies.
+- **Ranked open assumptions** — the value/usability/experience bets the brief is making, risk-ranked, for the next stages to resolve.
+
+A brief that types the request back as a plan, lists options without a recommendation, or smuggles in acceptance criteria and UI specs is not finished. Surface unresolved discovery as ranked assumptions, never as silent guesses.
+
+---
+
+## Roadmap Shape for a Product Effort
+
+The goal section states the product being discovered and for whom. Scope assumptions record the audience and the job in scope and what is explicitly not. `## Strategy / phases` holds exactly three phases: Discover (gate: client confirms the real problem + users), Ground (gate: positioning stance exists), Define (gate: client aligns on direction + experience). The current phase carries a one-line status; completed phases are deleted, not summarized. Human-confirmed decisions and teardown findings fold into context files (`context/product-brief-*.md`, teardown reports), not the roadmap.

package/dist/builtin-memory/spec.md

@@ -0,0 +1,98 @@
+---
+kind: knowledge
+when-and-why-to-read: When running a specification effort, shaping a spec
+  roadmap, or deciding how to stage design and requirements work, this knowledge
+  should be read so gaps in design intent surface before planning and downstream
+  behavior is testable without inherited blind spots.
+short-form: Use when running a specification effort, shaping a spec roadmap, or
+  deciding how to stage design and requirements work. Covers the three-stage
+  shape→design→requirements methodology, when to delegate design to a child
+  node, the isolation principle behind the design/requirements split, and what a
+  finished spec contains.
+system-prompt-visibility: name
+file-read-visibility: none
+gate:
+  kind:
+    imatches: '^spec($|/)'
+needs-refinement: true
+---
+
+## The Three Stages
+
+A specification effort runs in exactly this order: **SHAPE** → **DESIGN** → **REQUIREMENTS**. Do not collapse them, skip ahead, or run them in parallel. Each stage has a gate; the next stage starts only when that gate is met.
+
+### Stage 1 — Shape
+
+Shape is the discovery stage — the one place this effort is genuinely interactive. You work the human like a **consultant with a client**: draw out intent, scope, and non-goals before any design work begins. The deliverable is not an artifact — it is a shared mental model sufficient to write a sharp design brief.
+
+Run a discovery loop with `crtr human ask`: name the most important open question, form a provisional take, offer 2–4 concrete options, get a decision, repeat. Two rules keep it sharp. **Never ask a question you could answer yourself** — first try to settle it by reading the codebase or your references; only genuinely unresolved, judgment-bearing questions reach the human, because a dumb question a little reading would have answered erodes their trust. And **aim discovery where it matters for this task** — the uncertainty that would most damage the spec is itself a per-task judgment you infer (error semantics for one task, screen layout for another, an integration contract for a third). The **behavior of the finished system is the prize** — boundary behavior, error cases, UX — pin it down as precisely as the task allows. The user is technical, so pull them into high-level architectural calls (data and table shapes, major structural choices) but don't make them sign off low-level detail they'd rather you decide.
+
+Track these turns carefully. The shape stage is done when: (1) 3–7 named components or functional areas are identified, (2) the user's intent can be restated without correction, and (3) no unresolved contradictions remain between the user's goal and the existing codebase. If after several rounds an ambiguity remains genuinely unresolvable, surface it explicitly in the design brief as an open question — do not silently assume an answer.
+
+Gate: human confirms readiness to proceed to design.
+
+### Stage 2 — Design
+
+Design produces the blueprint: components and their topology, end-to-end flows, files and directories affected, locked decisions, and open questions resolved. The altitude is infra/services — no function signatures, no algorithm descriptions, no implementation ordering. Design answers "what shape does this take?" — planning answers "how is it built?"
+
+Small or simple design work (one surface, clear scope, few components) can be done by a single `design`-kind child node. Large or complex design work — multi-surface features, multiple interacting subsystems, significant architectural choices — must be delegated to a **design orchestrator** (a `design`-kind node created directly with `--mode orchestrator`), which decomposes the design internally and returns a finished artifact. The trigger for spawning a design orchestrator rather than a base design node: if the design effort has more than one distinct phase or more than ~5 interacting components, use an orchestrator.
+
+Gate: human approves the rendered design artifact.
+
+### Stage 3 — Requirements
+
+Requirements are derived from the finished, approved design. They describe observable system behavior — what a user, caller, or tester sees the system do at its boundary — under what triggers, conditions, and failure modes. Each requirement is written in EARS format (WHEN/WHILE/IF/WHERE + SHALL). Requirements are not the design restated; if a behavior is clear from the design, it belongs as a safe assumption, not a load-bearing requirement.
+
+Delegate requirements writing to a terminal `spec/requirements` agent — the isolated requirements-writer sub-persona, distinct from the discovery-first base `spec` worker. Pass it the rendered design text only. Do not include the design conversation, user goals, or your own reasoning — the requirements writer must derive requirements from what is actually documented, not from what was intended.
+
+Gate: human reviews and approves all load-bearing requirements; no `rejected` or unresolved `draft` items remain.
+
+---
+
+## The Design/Requirements Split — Why Isolation Matters
+
+Requirements written by the same context that argued out the design carry that context's blind spots. If the design left a behavior ambiguous and the design author filled it in mentally, requirements derived from that same mental state will encode the assumption without surfacing it for review. Written by a fresh context against the rendered design document alone, ambiguous points surface as gaps in `agentNotes` rather than silently-inherited assumptions.
+
+The isolation is structural, not stylistic. The requirements writer receives: the rendered design text and an output path. Nothing else. No user goal, no exploration findings, no conversation history. If something the user "intended" is not written in the design, it does not appear in the requirements — and that absence becomes visible, which is the desired outcome.
+
+---
+
+## The Yield-Between-Runs Rule
+
+After the design is approved, the spec orchestrator runs `crtr node yield` before starting requirements work. This is mandatory, not optional.
+
+Why: the design conversation fills context with reasoning about tradeoffs, rejected alternatives, and design intent. That context biases delegation — it causes the orchestrator to frame the requirements task with assumptions from the design discussion. After yielding, the orchestrator revives fresh against `context/roadmap.md`, which records the finished design artifact path. It reads the design artifact cold and delegates the requirements work from that clean window, anchored on the rendered design rather than on the design conversation.
+
+The roadmap must record the design artifact path and the current stage before yielding. On revive, the first action is to read `context/roadmap.md`, confirm the design is landed, and delegate requirements work.
+
+---
+
+## Roadmap Shape for a Spec Effort
+
+When shaping the roadmap at the start, structure it as follows. The goal section states what is being specified and for whom. Scope assumptions record what is in scope and what is not — a non-goal stated here propagates to every child without restating it. `## Strategy / phases` holds exactly three phases: Shape (gate: human sign-off), Design (gate: design artifact approved), Requirements (gate: all requirements approved). The current phase carries a one-line status of where it stands; completed phases are deleted, not summarized.
+
+After yield-and-revive, `## Strategy / phases` plus `## Active context` must let the fresh orchestrator orient in one pass without reading any child reports: the current phase's status line names what's in flight and which gate it's waiting on, and `## Active context` lists the design artifact and any other live context-file paths. Human-confirmed decisions and design detail fold into those context files, not the roadmap.
+
+---
+
+## Delegating Design: Base Node vs. Orchestrator
+
+Spawn a base `design` node (terminal) when: the design surface is bounded, one component or subsystem, no multi-phase structure required. The node produces `context/design.md` and `context/design.json` and returns.
+
+Spawn a `design` orchestrator (resident) when: the feature spans multiple subsystems, has distinct implementation phases that need separate design treatment, or the design effort is itself likely to fill one context window before it's finished. Create it directly as an orchestrator — `crtr node new --kind design --mode orchestrator` — rather than spawning a base design node and counting on it to promote itself once it discovers the surface is too big; self-promotion is unreliable, and a node born an orchestrator is strictly more capable than one hoping to become one. Pass it the shape brief as its goal; it owns the decomposition and integration internally and reports a finished design artifact when done.
+
+In either case, the spec orchestrator waits for the design to land and the human to approve it before proceeding.
+
+---
+
+## What a Finished Spec Contains
+
+A finished spec is precise enough that a planner can produce an implementation task breakdown without guessing intent. It contains:
+
+- **Behavior** — what the system does at its external boundary, organized by functional area, written in EARS format.
+- **Non-goals** — what is explicitly out of scope, so planners and implementers don't expand into it.
+- **Interfaces / inputs / outputs** — the data shapes and interaction contracts (at semantic-type level, not TypeScript declarations).
+- **Edge cases** — the failure modes, boundary conditions, and unusual states that must be handled, surfaced explicitly rather than left to the implementer to discover.
+- **Acceptance criteria** — per-requirement, testable conditions: "given input X, observe output Y" or "given state X, observe behavior Y."
+
+A spec that requires the reader to infer intent, assume behavior, or resolve design questions is not finished. If those gaps remain at the end of Stage 3, surface them explicitly as open questions before pushing final.

package/dist/builtin-memory/wedged-child-on-runaway-bash.md

@@ -0,0 +1,34 @@
+---
+kind: knowledge
+when-and-why-to-read: When a node is marked wedged or remains active without progress while its inbox accumulates, this reference should be read so recovery restores progress without losing context or killing the wrong process.
+short-form: a child stuck mid-turn (runaway bash, or a stalled broker with no subprocess) is AUTO-DETECTED by the daemon (⚠ wedged + a doctrine wake) — kill the subprocess if one exists; if none, the daemon SIGTERM-kicks the broker and automatically starts a fresh recovery cycle
+system-prompt-visibility: none
+file-read-visibility: preview
+---
+
+A base node can wedge INDEFINITELY on a single runaway bash command (classic: `grep -rln "..." /` — a recursive grep from filesystem root that scans all of disk and never returns; also any unbounded find/scan over `/` or a network mount). The node's pi turn is blocked waiting on the bash call, so it never `push`es and never finishes.
+
+**Detection is automatic (crtrd, issue #110).** The daemon's supervision tick corroborates two signals on every live/busy node: the busy-marker heartbeat (re-touched on every tool start/stream/end and turn end) gone quiet for 20+ minutes, AND the broker's whole process tree (broker pid + every descendant) reading near-zero CPU. Only when BOTH hold does it fire — routine long tool calls that are genuinely still producing output or burning CPU never trip it. On a 'wedged' verdict the daemon records a `daemon→node`/`wedged` Fault (the local canvas graph and browse UI show ⚠ "wedged · needs you", the same surface provider-fault stalls use) and fans a doctrine wake to the node's subscribers — ONE notice per wedge episode, not a repeat every tick. In the local browse UI, the hanging-node recovery action runs `node lifecycle revive <id> --now`; there is no hanging filter on `node inspect list`.
+
+**Remediation branches on whether the tree has a descendant (issue #119):**
+
+- **A subprocess exists (the common case)** — a runaway bash/find/grep is the likely cause. The daemon does NOT touch the engine here; you kill the subprocess yourself (see below).
+- **No subprocess exists** — the broker pid stands alone in its own tree (the engine itself stalled, e.g. mid a `model_change`, with nothing a human could kill). The daemon performs the ONLY remaining remediation itself: it SIGTERMs the broker (the same on-demand kick `node lifecycle revive --now` does). The surviving `job/busy` marker proves the process died mid-turn, so its exit-policy job starts a fresh cycle on the saved session tree. That cycle automatically receives the normal roadmap/feed/context kickoff; it does not reopen the dead turn at an idle prompt, and no manual nudge is required.
+
+**Why it used to be invisible to the orchestrator:** the wake spine only fires on a child's push/finalize/crash. A child wedged *mid-turn* does none of those — its row stays `status=active` and the dashboard shows it `●` working. Before #110, the parent got no wake at all, so an entire wave could stall for hours looking healthy; cli-verbs-B2 sat wedged ~2h14m on a `grep /` before a safety-deadline inspection caught it. The daemon-side detection above closes that gap; you should no longer need to notice a wedge by elapsed-time vibes alone — but if you do (the daemon hasn't caught up yet, or the wedge is younger than its grace window), the manual inspection below still works.
+
+## Subprocess case: kill the runaway command
+
+**How to inspect further / confirm:** `tmux capture-pane -p -t <pane>` shows the live turn (look for `Elapsed NNNNs ⠼ Working...` on one bash command); `pgrep -P <pi_pid>` + `ps -axo pid,ppid,etime,command` reveals the runaway subprocess and how long it's run.
+
+**How to apply:** kill the runaway SUBPROCESS, not the node — `kill <grep_pid>`. The bash call then returns and the pi turn resumes on its own, no context lost, no respawn. (Killing the bash `-c` wrapper can orphan the grep; kill the actual scanner PID. A pipeline `grep / | head` resumes fastest if you kill the first-stage grep — the pipe closes and bash proceeds.) Then notify the OWNING orchestrator (deferred tier) so it steers the child to completion and knows the lost time — the doctrine wake above already does this automatically for a detected wedge, but do it yourself if you found the wedge before the daemon did. Related: the `revive-stuck-orchestrator` doc covers the orchestrator-level false-finish failure mode.
+
+## No-subprocess case: broker wedged mid-stream (`streaming:true` stuck)
+
+The wedge can outlive any subprocess, or exist with none at all. A node (including a top-level **resident orchestrator**, not just a child) can sit stuck with the canvas snapshot showing `streaming: true` and a stale `last_activity` for **days**, while the broker pid is alive but doing nothing (0% CPU) and NO subprocess exists to kill — the engine deadlocked mid-stream (often right after a bash call returned, or after a `model_change`) and never closed the turn. Tells: `job/busy` lockfile present with an old mtime, `job/telemetry.json` `updated_at` frozen, `job/broker.log` stopped growing, inbox piling up (`queued (N)` in the dashboard) because the turn never ends. The `busy` marker alone is harmless (it is always AND-ed with `pidAlive`, so a stale one from a dead pid is ignored) — do not bother deleting it.
+
+**This is now the daemon's own remediation (issue #119) — it auto-kicks the broker for you.** If it hasn't caught up yet (younger than the wedge grace, or the daemon was down), do it manually:
+
+1. `kill -TERM <broker_pid>` — the wedged broker. Confirm it dies (`ps -p <pid>`) and that no orphan subprocess lingers (`ps -o pid,ppid,command | awk '$2==<pid>'`).
+2. The **daemon auto-resumes** it within ~20s on the saved session — a fresh broker pid appears (`node inspect show`), `status=active`, `intent=null`, `view.sock` accepts connections. (No manual `node lifecycle revive` needed if the daemon is up; do it manually only if it doesn't come back.)
+3. **The daemon starts the replacement as a fresh recovery cycle** — the stale `job/busy` marker distinguishes an interrupted turn from an idle crash, so the daemon selects `resume:false`. The saved session tree remains on disk, while the new cycle re-orients from `context/roadmap.md`, feed, reports, and context automatically. Confirm success by watching `telemetry.json` `updated_at` go current and the node run tools again. A manual `--tier critical` message is now only a fallback if the replacement broker itself fails to boot or provider access is still unhealthy.

package/dist/builtin-pi-packages/pi-crtr-extensions/README.md

@@ -0,0 +1,47 @@
+# pi-crtr-extensions
+
+crtr's engine-side [pi](https://pi.dev) package — the extensions and prompt
+templates every pi engine (including crouter's brokers) loads. This directory,
+inside the crouter tree, is the canonical and only copy; it ships in crouter's
+`dist/builtin-pi-packages/pi-crtr-extensions` and `crtr sys setup` wires that
+path into the `packages` array of `~/.pi/agent/settings.json` (alongside the
+bundled `pi-mode-switch`) — there is nothing to clone or install separately.
+
+The package is excluded from crouter's tsc compile unit; pi loads the `.ts`
+sources directly with its own loader. Imports may reach from here into
+crouter's compiled core (e.g. `lib/subscription-state.ts` imports the model
+ladder from `../../../types.js`), never the other direction.
+
+**Does the OAuth plugin ship with pi? No.** `pi-claude-oauth-adapter` is a
+third-party npm package ([minzique/dotfiles-agents](https://github.com/minzique/dotfiles-agents/tree/main/packages/pi-claude-oauth-adapter)) —
+"Anthropic OAuth / Claude Code compatibility adapter for Pi." pi installs it
+from npm because of the `npm:` prefix; it lands in `~/.pi/agent/npm/node_modules/`.
+If you want Claude-subscription auth, you add this line yourself — it is not bundled.
+(Separately, *this* package's `provider-rotation.ts` extension does its own
+OAuth login/refresh via `@earendil-works/pi-ai/oauth` to rotate across
+subscription credentials — that's a different mechanism, built in here.)
+
+`@earendil-works/pi-coding-agent` is a peer dependency provided by pi at runtime —
+do not install it locally. The one runtime dep (`yaml`) is vendored under this
+directory's `node_modules/`.
+
+## Contents
+
+### Extensions (`extensions/`)
+
+| Extension | What it does |
+|-----------|--------------|
+| `claude-plugin-commands.ts` | Surfaces commands and skills from `~/.claude`, the cwd, every project in the selected crouter profile, and installed plugins as pi slash commands with arg/shell-block execution. Writes shims to `~/.pi/agent/.plugin-command-shims/`. Skips any name pi already serves natively from `~/.pi/agent/prompts/` (e.g. crtr exports a slash command to both `~/.claude/commands` and `~/.pi/agent/prompts`), so the shim never collides with the native prompt. |
+| `crouter-help.ts` | Help integration for the `crtr` CLI. |
+| `provider-rotation.ts` | Subscription credential rotation across Anthropic / OpenAI-Codex: does its own OAuth login/refresh, rotates on rate-limits, falls back across the model ladder. Registers `/provider-sub <provider> <list\|add\|select\|rm>`. |
+| `crtr-commands/` | Auto-generates a slash command per `crtr` CLI node. The tree is derived in-process from crtr's own `buildRoot()` (no subprocesses, no cache on disk); `filters.json` controls which nodes are exposed. |
+| `sysprompt-window.ts` | Registers `/sysprompt`, which runs `crtr sys sysprompt --window` without injecting the prompt into context. |
+| `frontmatter-rules/` | Injects `.pi/rules/*.md` whose `when:` frontmatter matches a read markdown file. `.claude/rules` are migrated into substrate docs with `applies-to` via `crtr sys sync project-guidance`. Needs the `yaml` dep. See the `pi-frontmatter-rules` skill. |
+| `statusline.ts` | Custom status line. |
+| `strip-skills-docs.ts` | Trims skill docs from context. |
+
+(`/plan` and `/spec` mode commands live in the separate `pi-mode-switch` package, not here.)
+
+## Notes
+
+- Reload after editing any extension: `/reload` in pi.

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/__tests__/claude-plugin-commands.test.ts

@@ -0,0 +1,49 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import extension, { projectClaudeDirs } from "../claude-plugin-commands.ts";
+
+test("native Markdown slash commands omit author comments before Pi sends them", async () => {
+  const root = mkdtempSync(join(tmpdir(), "claude-plugin-commands-"));
+  try {
+    const prompts = join(root, ".pi", "prompts");
+    mkdirSync(prompts, { recursive: true });
+    writeFileSync(join(prompts, "comment-regression.md"), "---\ndescription: test\n---\n\n<!-- private author note -->\nDo $ARGUMENTS.\n```html\n<!-- literal -->\n```\n");
+
+    const handlers: Array<(event: any, ctx: any) => Promise<any>> = [];
+    extension({ on(event: string, handler: any) { if (event === "input") handlers.push(handler); } } as any);
+
+    let text = "/comment-regression topic";
+    for (const handler of handlers) {
+      const result = await handler({ source: "interactive", text }, { cwd: root });
+      if (result.action === "transform") text = result.text;
+    }
+
+    assert.equal(text, "Do topic.\n```html\n<!-- literal -->\n```");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("projectClaudeDirs widens discovery to profile projects while keeping cwd first and deduplicated", () => {
+  const root = mkdtempSync(join(tmpdir(), "claude-plugin-commands-"));
+  try {
+    const current = join(root, "current");
+    const nestedCwd = join(current, "packages", "app");
+    const profiled = join(root, "profiled");
+    const currentClaude = join(current, ".claude");
+    const profiledClaude = join(profiled, ".claude");
+
+    mkdirSync(join(current, ".git"), { recursive: true });
+    mkdirSync(join(currentClaude, "commands"), { recursive: true });
+    mkdirSync(nestedCwd, { recursive: true });
+    mkdirSync(join(profiled, ".git"), { recursive: true });
+    mkdirSync(join(profiledClaude, "skills"), { recursive: true });
+
+    assert.deepEqual(projectClaudeDirs(nestedCwd, [profiled, current]), [currentClaude, profiledClaude]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/__tests__/crtr-commands.test.ts

@@ -0,0 +1,93 @@
+// Regression for the 2026-07-27 "new nodes time out" outage: this extension
+// used to discover the crtr surface at BROKER BOOT by spawning one `crtr X -h`
+// subprocess per node and caching the result next to its own install dir. Every
+// `npm run build` wiped that cache out of the dist brokers load, so the next
+// boot blocked >30s on the crawl and the daemon's readiness reaper SIGTERMed
+// the young broker — dead node, request_timeout. Setup must therefore spawn
+// NOTHING: the tree is derived in-process from crtr's own buildRoot().
+import { after, before, test } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+const EXTENSION_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "crtr-commands");
+
+let mod: typeof import("../crtr-commands/index.ts");
+
+before(async () => {
+  mod = await import("../crtr-commands/index.ts");
+});
+
+test("enumerateCommands walks the in-memory tree, skipping hidden and internal nodes", () => {
+  const root = {
+    kind: "root" as const,
+    subtrees: [
+      {
+        kind: "branch" as const,
+        name: "node",
+        children: [
+          { kind: "leaf" as const, name: "new", description: "create a node" },
+          { kind: "leaf" as const, name: "_internal" },
+          { kind: "leaf" as const, name: "secret", tier: "hidden" },
+          {
+            kind: "branch" as const,
+            name: "wait",
+            children: [{ kind: "leaf" as const, name: "deadline" }],
+          },
+        ],
+      },
+      { kind: "branch" as const, name: "buried", tier: "hidden", children: [{ kind: "leaf" as const, name: "leaf" }] },
+    ],
+  };
+
+  const paths = mod.enumerateCommands(root).map((n) => n.path.join(":"));
+  assert.deepEqual(paths, ["node", "node:new", "node:wait", "node:wait:deadline"]);
+  assert.equal(mod.enumerateCommands(root).find((n) => n.path.join(":") === "node:new")?.description, "create a node");
+});
+
+test("filters match a node and its descendants; exclude wins over include", () => {
+  assert.equal(mod.isAllowed("node:new", { include: ["node"], exclude: [] }), true);
+  assert.equal(mod.isAllowed("push:final", { include: ["node"], exclude: [] }), false);
+  assert.equal(mod.isAllowed("node:new", { include: ["node"], exclude: ["node:new"] }), false);
+  assert.equal(mod.isAllowed("anything", {}), true);
+});
+
+test("setup spawns no subprocess and writes no cache, and disables itself when crtr's dist is unlocatable", async () => {
+  const fakeBin = mkdtempSync(join(tmpdir(), "crtr-commands-path-"));
+  const spawnLog = join(fakeBin, "spawned.log");
+  // A `crtr` on PATH with no runtime next to it: resolution fails, so setup
+  // must register nothing. If setup ever shells out again, this records it.
+  writeFileSync(join(fakeBin, "crtr"), `#!/bin/sh\necho "$@" >> ${spawnLog}\n`, "utf8");
+  chmodSync(join(fakeBin, "crtr"), 0o755);
+  const before = new Set(readdirSync(EXTENSION_DIR));
+  const savedPath = process.env.PATH;
+  process.env.PATH = fakeBin;
+
+  const registered: string[] = [];
+  const statuses: string[] = [];
+  const listeners: Record<string, (e: unknown, ctx: unknown) => Promise<void>> = {};
+  const pi = {
+    registerCommand: (name: string) => registered.push(name),
+    on: (event: string, handler: (e: unknown, ctx: unknown) => Promise<void>) => {
+      listeners[event] = handler;
+    },
+    sendMessage: () => {},
+  };
+
+  try {
+    await mod.default(pi as never);
+    await listeners.session_start?.(undefined, {
+      ui: { setStatus: (_k: string, v: string) => statuses.push(v), notify: () => {} },
+    });
+  } finally {
+    process.env.PATH = savedPath;
+    rmSync(fakeBin, { recursive: true, force: true });
+  }
+
+  assert.equal(existsSync(spawnLog), false, "setup must not spawn `crtr` subprocesses");
+  assert.deepEqual(readdirSync(EXTENSION_DIR).filter((f) => !before.has(f)), [], "setup must write nothing to disk");
+  assert.deepEqual(registered, []);
+  assert.deepEqual(statuses, ["crtr-commands off"]);
+});

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/__tests__/memory-slash-commands.test.ts

@@ -0,0 +1,194 @@
+import { after, before, test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+let dir: string;
+let mod: typeof import("../memory-slash-commands.ts");
+let extensionDefault: typeof import("../memory-slash-commands.ts").default;
+
+function writeDoc(relPath: string, frontmatter: string, body: string): string {
+  const full = join(dir, relPath);
+  writeFileSync(full, `---\n${frontmatter}\n---\n\n${body}`, "utf8");
+  return full;
+}
+
+before(async () => {
+  dir = mkdtempSync(join(tmpdir(), "memory-slash-commands-"));
+  mod = await import("../memory-slash-commands.ts");
+  extensionDefault = mod.default;
+});
+
+after(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+test("slashCommandName renders a nested path name with `:`, leaves a flat name unchanged", () => {
+  assert.equal(mod.slashCommandName("research-alpha"), "research-alpha");
+  assert.equal(mod.slashCommandName("taste/foo"), "taste:foo");
+  assert.equal(mod.slashCommandName("a/b/c"), "a:b:c");
+});
+
+test("discoverSlashDocs only registers docs frontmatter-flagged slash: true", async () => {
+  const flagged = writeDoc("flagged.md", "kind: knowledge\nslash: true", "flagged body");
+  const unflagged = writeDoc("unflagged.md", "kind: knowledge", "unflagged body");
+  const explicitFalse = writeDoc("explicit-false.md", "kind: knowledge\nslash: false", "explicit false body");
+
+  mod.__setListMemoryDocsForTest(async () => [
+    { name: "flagged", path: flagged, short_form: "Flagged command", is_dir: false },
+    { name: "unflagged", path: unflagged, short_form: "Unflagged document", is_dir: false },
+    { name: "explicit-false", path: explicitFalse, short_form: "Explicitly disabled", is_dir: false },
+  ]);
+
+  const docs = await mod.discoverSlashDocs();
+  assert.deepEqual(docs, [{ name: "flagged", commandName: "flagged", description: "Flagged command" }]);
+
+  mod.__setListMemoryDocsForTest(undefined);
+});
+
+test("discoverSlashDocs skips directory INDEX entries", async () => {
+  const dirIndex = writeDoc("dir-index.md", "kind: knowledge\nslash: true", "index body");
+
+  mod.__setListMemoryDocsForTest(async () => [{ name: "taste/", path: dirIndex, short_form: "Index", is_dir: true }]);
+
+  assert.deepEqual(await mod.discoverSlashDocs(), []);
+  mod.__setListMemoryDocsForTest(undefined);
+});
+
+// Regression guard: `crtr memory list --json` already returns docs in scope
+// precedence order (project > profile > user > builtin); a doc identity that
+// resolves higher-precedence (first occurrence) must win even when a
+// lower-precedence doc of the SAME name is also slash-flagged.
+test("discoverSlashDocs respects scope precedence — first occurrence of a name wins, even if only the lower-precedence one is slash-flagged", async () => {
+  const projectDoc = writeDoc("project-shadow.md", "kind: knowledge", "project version, not flagged");
+  const userDoc = writeDoc("user-shadow.md", "kind: knowledge\nslash: true", "user version, flagged");
+
+  mod.__setListMemoryDocsForTest(async () => [
+    { name: "shadow", path: projectDoc, short_form: "Project", is_dir: false }, // project — comes first, wins identity
+    { name: "shadow", path: userDoc, short_form: "User", is_dir: false }, // user — same name, shadowed
+  ]);
+
+  // The project doc wins the identity and it isn't flagged, so no command registers.
+  assert.deepEqual(await mod.discoverSlashDocs(), []);
+  mod.__setListMemoryDocsForTest(undefined);
+});
+
+test("discoverSlashDocs silently skips a doc it fails to read", async () => {
+  mod.__setListMemoryDocsForTest(async () => [{ name: "missing", path: join(dir, "does-not-exist.md"), short_form: "Missing", is_dir: false }]);
+  assert.deepEqual(await mod.discoverSlashDocs(), []);
+  mod.__setListMemoryDocsForTest(undefined);
+});
+
+test("composeSlashPrompt substitutes every $ARGUMENTS occurrence and adds no header when the body uses it", () => {
+  const body = "Topic: $ARGUMENTS\n\nGo research $ARGUMENTS thoroughly.";
+  const result = mod.composeSlashPrompt("research-alpha", "  agent memory systems  ", body);
+  assert.equal(result, "Topic: agent memory systems\n\nGo research agent memory systems thoroughly.");
+  assert.ok(!result.includes("You invoked"));
+});
+
+test("composeSlashPrompt substitutes $ARGUMENTS with an empty string when no args were given", () => {
+  const body = "Topic: $ARGUMENTS";
+  const result = mod.composeSlashPrompt("research-alpha", "", body);
+  assert.equal(result, "Topic: ");
+  assert.ok(!result.includes("You invoked"));
+});
+
+test("composeSlashPrompt falls back to a header + full body when $ARGUMENTS is absent, args given", () => {
+  const body = "Do the thing.";
+  const result = mod.composeSlashPrompt("my-doc", "some topic", body);
+  assert.match(result, /^You invoked \/my-doc with: some topic/);
+  assert.ok(result.endsWith("Do the thing."));
+  assert.ok(result.includes(body));
+});
+
+test("composeSlashPrompt falls back to a no-args header + full body when $ARGUMENTS is absent, no args given", () => {
+  const body = "Do the thing.";
+  const result = mod.composeSlashPrompt("my-doc", "   ", body);
+  assert.match(result, /^You invoked \/my-doc with no arguments\./);
+  assert.ok(result.endsWith("Do the thing."));
+});
+
+test("registers deterministic expansion metadata and submission consumes that exact expansion", async () => {
+  const flagged = writeDoc("live.md", "kind: knowledge\nslash: true", "stale body on disk");
+  mod.__setListMemoryDocsForTest(async () => [{ name: "live", path: flagged, short_form: "Live command description", is_dir: false }]);
+
+  let readCalls: string[] = [];
+  mod.__setReadMemoryDocForTest(async (name: string) => {
+    readCalls.push(name);
+    return "Topic: $ARGUMENTS";
+  });
+
+  const registered = new Map<string, { description?: string; handler: (args: string, ctx: any) => Promise<void> }>();
+  const sent: any[] = [];
+  const pi = {
+    registerCommand(name: string, options: any) {
+      registered.set(name, options);
+    },
+    sendMessage(message: any, options: any) {
+      sent.push({ message, options });
+    },
+  } as any;
+
+  await extensionDefault(pi);
+
+  assert.ok(registered.has("live"));
+  const command = registered.get("live")! as typeof registered extends Map<string, infer T> ? T & { expansion: unknown } : never;
+  assert.equal(command.description, "Live command description");
+  assert.deepEqual(command.expansion, {
+    kind: "memory-slash",
+    commandName: "live",
+    body: "Topic: $ARGUMENTS",
+  });
+  assert.deepEqual(readCalls, ["live"]); // registration captures the disclosed body once
+
+  const ctx = { ui: { notify() {} } };
+  await command.handler("some topic", ctx);
+
+  assert.deepEqual(readCalls, ["live"]); // handler reuses the disclosed expansion
+  assert.equal(sent.length, 1);
+  assert.equal(sent[0].options.triggerTurn, true);
+  assert.equal(sent[0].message.content, "Topic: some topic");
+
+  mod.__setListMemoryDocsForTest(undefined);
+  mod.__setReadMemoryDocForTest(undefined);
+});
+
+test("a command whose registration read fails has no preview metadata and notifies on invoke", async () => {
+  const flagged = writeDoc("broken.md", "kind: knowledge\nslash: true", "body");
+  mod.__setListMemoryDocsForTest(async () => [{ name: "broken", path: flagged, short_form: "Broken command", is_dir: false }]);
+  mod.__setReadMemoryDocForTest(async () => {
+    throw new Error("boom");
+  });
+
+  const registered = new Map<string, { handler: (args: string, ctx: any) => Promise<void> }>();
+  const sent: any[] = [];
+  const notified: any[] = [];
+  const pi = {
+    registerCommand(name: string, options: any) {
+      registered.set(name, options);
+    },
+    sendMessage(message: any, options: any) {
+      sent.push({ message, options });
+    },
+  } as any;
+
+  await extensionDefault(pi);
+  assert.equal((registered.get("broken") as any).expansion, undefined);
+  const ctx = {
+    ui: {
+      notify(msg: string, level: string) {
+        notified.push({ msg, level });
+      },
+    },
+  };
+  await registered.get("broken")!.handler("", ctx);
+
+  assert.equal(sent.length, 0);
+  assert.equal(notified.length, 1);
+  assert.equal(notified[0].level, "error");
+  assert.match(notified[0].msg, /boom/);
+
+  mod.__setListMemoryDocsForTest(undefined);
+  mod.__setReadMemoryDocForTest(undefined);
+});