@crouton-kit/crouter 0.3.70 → 0.3.79

package/README.md

@@ -30,5 +30,5 @@ To opt out of the bootstrap (e.g. in CI), set `CRTR_NO_BOOTSTRAP=1`.
 The node runtime hosts the [pi coding agent](https://pi.dev) in each broker. To set your pi install up the way crouter's author runs it, add these to the `packages` array in `~/.pi/agent/settings.json` (neither ships with pi — you add them yourself):
 
 - **[pi-claude-oauth-adapter](https://github.com/minzique/dotfiles-agents/tree/main/packages/pi-claude-oauth-adapter)** — third-party npm package; Anthropic OAuth / Claude Code compatibility adapter for pi. Install with `"npm:pi-claude-oauth-adapter"`.
-- **[pi-personal-extensions](https://github.com/crouton-labs/pi-personal-extensions)** — the author's personal pi extensions (crtr help-gate, slash-command surfacing, provider rotation, frontmatter rules, statusline). Its README documents the full machine setup.
+- **pi-crtr-extensions** — crtr's engine-side pi extensions (crtr help-gate, slash-command surfacing, provider rotation, frontmatter rules, statusline). Bundled in this repo at `src/builtin-pi-packages/pi-crtr-extensions` and wired into `~/.pi/agent/settings.json` automatically by `crtr sys setup` — nothing to install separately.
 

package/dist/build-root.d.ts

@@ -9,8 +9,16 @@ export declare const SUBTREE_NAMES: string[];
  *  every valid child). This keeps every help/error surface byte-identical while
  *  the common leaf-dispatch path loads exactly one subtree. */
 export declare function resolveRoot(first: string | undefined): Promise<RootDef>;
-/** Assemble the full crtr command tree (all subtrees). Used for root -h, the
- *  unknown-path error, bare-root boot, and the listing-completeness test. Root
- *  owns only the tagline; every subtree declares its own root representation via
- *  its rootEntry. */
+/** Assemble the full crtr command tree: every core subtree plus any top-level
+ *  branches contributed by enabled command plugins. Used for root -h, the
+ *  unknown-path error, bare-root boot, front-door recognition, and the
+ *  listing-completeness test — i.e. only the FALLTHROUGH path, never the core
+ *  fast path (`resolveRoot` short-circuits a recognized core first token with
+ *  zero plugin I/O). Root owns only the tagline; every subtree (core or
+ *  external) declares its own root representation via its rootEntry.
+ *
+ *  Order is deterministic: core subtrees in declared order first, then accepted
+ *  external branches sorted by name (from discovery). Discovery is
+ *  invocation-local — no cache, no persistence — so plugin enable/update/remove
+ *  takes effect on the next invocation automatically. */
 export declare function buildRoot(): Promise<RootDef>;

package/dist/build-root.js

@@ -36,11 +36,30 @@ export async function resolveRoot(first) {
     }
     return buildRoot();
 }
-/** Assemble the full crtr command tree (all subtrees). Used for root -h, the
- *  unknown-path error, bare-root boot, and the listing-completeness test. Root
- *  owns only the tagline; every subtree declares its own root representation via
- *  its rootEntry. */
+/** Assemble the full crtr command tree: every core subtree plus any top-level
+ *  branches contributed by enabled command plugins. Used for root -h, the
+ *  unknown-path error, bare-root boot, front-door recognition, and the
+ *  listing-completeness test — i.e. only the FALLTHROUGH path, never the core
+ *  fast path (`resolveRoot` short-circuits a recognized core first token with
+ *  zero plugin I/O). Root owns only the tagline; every subtree (core or
+ *  external) declares its own root representation via its rootEntry.
+ *
+ *  Order is deterministic: core subtrees in declared order first, then accepted
+ *  external branches sorted by name (from discovery). Discovery is
+ *  invocation-local — no cache, no persistence — so plugin enable/update/remove
+ *  takes effect on the next invocation automatically. */
 export async function buildRoot() {
-    const subtrees = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
-    return defineRoot({ tagline: TAGLINE, globals: [], subtrees });
+    const core = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    // Dynamic import keeps command-plugin discovery/compose (and their
+    // resolver/manifest deps) OFF the hot leaf path's module graph — they load
+    // only here, on the fallthrough, matching this file's lazy-subtree rationale.
+    const [{ discoverCommandContributions }, { composeExternalSubtrees }] = await Promise.all([
+        import('./core/command-plugins/discovery.js'),
+        import('./core/command-plugins/compose.js'),
+    ]);
+    // Core always wins: a plugin claiming a core top-level name is skipped +
+    // recorded as an issue (surfaced via pkg plugin show / sys doctor).
+    const snapshot = discoverCommandContributions(new Set(SUBTREE_NAMES));
+    const external = composeExternalSubtrees(snapshot);
+    return defineRoot({ tagline: TAGLINE, globals: [], subtrees: [...core, ...external] });
 }

package/dist/builtin-memory/00-runtime-base.md

@@ -11,15 +11,6 @@ You are a **node** in a live agent graph (the crtr canvas). This section is your
 ## Identity
 You have a node id (`$CRTR_NODE_ID`), a context dir on disk, and a pi session as your vehicle. You are pinned to one working dir.
 
-## Delegating
-Hand any self-contained unit of work to a child instead of doing it inline — that keeps your own context window (your scarce resource) free for steering, and lets independent units run in parallel:
-
-    crtr node new "<task>" --kind <kind>     # `crtr node -h` lists the kinds + the delegate→feed loop
-
-You auto-subscribe to every child you spawn, so you're woken when it finishes; the wake message already carries the digest — dereference the reports that matter. Prefer delegating over grinding it out yourself.
-
-When the work depends on context you already hold — an explore report, a design, a spec, earlier findings — name those files by path in the task itself: a child starts blind and inherits only what you point it at, so unreferenced context you have is context it won't find.
-
 ## Reports vs artifacts
 Two different things, two different homes. A **report** (`crtr push`) is a spine event — keep it brief: the verdict or synthesis plus the absolute path to any artifact, never the full substance pasted in. An **artifact** (a spec, design, findings doc, anything worth re-reading or sharing) is a file you write to your context dir by absolute path — `$CRTR_CONTEXT_DIR/<name>.md`. Your working dir is the project, so a bare `context/...` lands in the repo, not your context dir; address artifacts with `$CRTR_CONTEXT_DIR` and report them by absolute path so the substance is on disk where any node can read it and the report stays a pointer.
 
@@ -30,6 +21,8 @@ Don't stall and don't guess at a decision a person should make:
 
     crtr human ask "<question>"
 
+ANY question aimed at the user goes through it, not just hard blocks — a question posed as prose in a reply or report pings nobody, while an ask lands on their screen and pushes the answer back to your inbox.
+
 ## When crtr itself misbehaves
 A `crtr` command that errors unexpectedly, hangs, churns, double-spawns, or contradicts its own `-h` is a harness bug — don't silently work around it. Run `crtr sys feedback` to report it (`-h` for how), then continue.
 
@@ -39,7 +32,7 @@ Two different moves; don't conflate them. **Promote** when the *shape* of the jo
     crtr node promote --kind <kind>     # `crtr node promote -h` — become a long-lived orchestrator now
     crtr node yield                     # `crtr node yield -h` — refresh into a clean window, carrying a note forward
 
-Don't promote or yield for work that fits one window — finish it with `crtr push final`.
+Don't promote or yield for work that fits one window — finish it with `crtr push final`. And never yield carrying an unasked question: put anything you're still wondering for the human through `crtr human ask` BEFORE you yield — an in-flight ask survives the refresh, and its answer wakes your fresh window like any child's report.
 
 ## Diagrams
 When structure would land faster as a picture than as prose — a flow, a state machine, a small architecture — write it as a ```mermaid fenced code block. The human's viewer renders it inline as a terminal diagram. Reach for it when the shape is the point, not for everything.

package/dist/builtin-memory/04-base-worker.md

@@ -0,0 +1,18 @@
+---
+kind: preference
+when-and-why-to-read: When a node runs in base mode, this preference should be read because base nodes own one bounded task and finish it hands-on rather than recursively passing the same assignment down the graph.
+system-prompt-visibility: content
+file-read-visibility: none
+gate: {mode: base}
+rationale: >-
+  A base security reviewer handed its entire assignment to another base security reviewer,
+  which repeated the move through a 35-node chain in under five minutes. The universal prompt
+  had said to delegate any self-contained work while no base-mode layer told sub-kinds to work
+  hands-on; exact sub-kind gating also meant plan/reviewers/security did not inherit plan/00-base.
+---
+
+## You are a hands-on worker
+
+Own the task you were given and complete it yourself in this window. Your scarce resource is task completion, not preserving your context for steering.
+
+Delegate only a genuinely independent subtask that can run in parallel while you continue owning the parent task. Each child gets a bounded outcome distinct from your whole assignment; passing the same task to another base node creates recursion instead of progress. When the goal itself needs decomposition or will not fit one window, become an orchestrator rather than building a chain of base workers.

package/dist/builtin-memory/04-orchestration-kernel.md

@@ -94,7 +94,7 @@ You own the goal; the human is a stakeholder, not your manager. They answer ques
 
 Engage (`crtr human ask`) when the goal is genuinely ambiguous and the codebase doesn't settle it, when you're choosing between approaches with real tradeoffs, when you've found something that changes scope or direction, when an action is irreversible or high-risk, or when finished work needs sign-off. Resolve autonomously — or delegate to an agent — anything mechanical: code review, convention compliance, plan feasibility, test verification, details within an approved scope.
 
-**Never yield while waiting on an ask.** Yielding tears down your window and the in-flight question with it, so you would wake to the same prompt with no answer and loop forever. While a decision is outstanding, stay resident and let it block; yield only once you have the answer or have other work to do.
+**Never yield holding an unasked question.** An in-flight `crtr human ask` survives a yield — the ask is its own node, and the answer is pushed to your inbox and wakes your fresh window like any child's report — so an outstanding decision is no reason to hold a bloated window open. What a yield *does* tear down is anything that lives only in your head: before you yield, put every open question through `crtr human ask`, and record in your roadmap what each pending answer settles, so the fresh window knows what to do with it when it arrives.
 
 ## Before you finish
 

package/dist/builtin-memory/crouter-development/plugins.md

@@ -1,10 +1,12 @@
 ---
 kind: knowledge
 when-and-why-to-read: When creating a crtr plugin, packaging memory docs for
-  distribution, or debugging install/resolution, this knowledge should be read.
+  distribution, adding top-level CLI commands via a command manifest, or
+  debugging install/resolution, this knowledge should be read.
 short-form: How to author a crtr plugin — plugin.json manifest, directory
-  layout, scopes, install mechanics, versioning. Use when creating a new plugin,
-  packaging memory docs for distribution, or debugging install/resolution.
+  layout, scopes, install mechanics, versioning, and command plugins (top-level
+  CLI commands via commands.json + one executable). Use when creating a plugin,
+  packaging memory docs, contributing commands, or debugging install/resolution.
 system-prompt-visibility: name
 file-read-visibility: none
 ---
@@ -39,7 +41,7 @@ If it's a one-off note for yourself, scope-owned memory docs are simpler. Promot
         └── <name>.md
 ```
 
-The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Sibling dirs (`rules/`, `agents/`, and future `commands/`, `hooks/`) hold the other artifact types.
+The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Sibling dirs (`rules/`, `agents/`, and future `hooks/`) hold the other artifact types. A plugin that contributes CLI commands adds a `commands.json` manifest plus its executable — see [Command plugins](#command-plugins).
 
 ## The manifest
 
@@ -65,6 +67,7 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 | `description` | yes | One sentence. |
 | `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin update --name <name>`. |
 | `owner` | optional | Author info. |
+| `commands` | optional | Plugin-root-relative path to a `commands.json` command manifest. Present ⇒ the plugin contributes top-level `crtr` commands — see [Command plugins](#command-plugins). |
 
 ## Scopes
 
@@ -150,13 +153,87 @@ Bad plugin scope:
 
 If your memory doc conceptually depends on another plugin's doc, link via `## Related` with `` `<plugin>/<doc>` ``. Don't fork content; link it.
 
+## Command plugins
+
+Beyond docs, a plugin may contribute **top-level `crtr` commands** — new noun branches with their own leaves. You declare one pointer in the manifest and ship one executable; crtr owns parsing, help, rendering, and errors, and direct-spawns your executable once per leaf invocation.
+
+### The manifest pointer
+
+Add `commands` to `plugin.json` — a plugin-root-relative path to one static manifest:
+
+```json
+{ "name": "crouter-infra", "version": "0.1.0", "description": "...", "commands": "commands.json" }
+```
+
+Only an installed, **enabled** plugin's `commands` manifest contributes. Discovery is per-invocation: enable/disable/update/remove takes effect on the very next `crtr` call — no daemon restart, no cache to clear.
+
+### commands.json shape
+
+```json
+{
+  "schemaVersion": 1,
+  "executable": "bin/cmd.js",
+  "mounts": [
+    { "parent": [], "node": { "kind": "branch", "name": "app", "...": "..." } }
+  ]
+}
+```
+
+- `schemaVersion` — exactly the integer `1`. Anything else rejects the whole manifest.
+- `executable` — plugin-root-relative path to the one command binary. Must resolve inside the plugin root, be a regular file, and carry the POSIX exec bit.
+- `mounts[]` — each `{ parent: [], node }`. v1 supports **top-level mounts only**: `parent` must be `[]`.
+
+Every top-level `node` is a **branch** (`kind: "branch"`) carrying a `rootEntry { concept, description, whenToUse }` — the representation crtr renders at root help. Branch children are nested branches (no rootEntry) or leaves. A leaf declares `params`, `output` (array of `{ name, type, required, constraint }`), `outputKind: "object"`, and a non-empty `effects` array. Params use crtr's public vocabulary — one positional max, long-form `flag`s (types `string|int|bool|path|enum`, `choices` for enum), `stdin`, `context-file`; kebab-case names, no aliases. The declaration mirrors crtr's stable help descriptors, not its internal TypeScript defs — no closures, no dynamic state, no renderers.
+
+### Execution: the trust boundary
+
+On explicit leaf invocation — **never on install, help, or discovery** — crtr direct-spawns your executable (no shell) with `--crtr-command-protocol 1`, the caller's cwd, and the full environment. Installed command plugins are **trusted local code running with the caller's authority**: crtr does not sandbox them, filter the environment, mint a credential, or interpret your backend's auth. Your executable owns authentication to its own backend. This is an execution trust boundary, not a sandbox — installed code can already read the caller's files, so env filtering would only imply a security guarantee that does not exist.
+
+### The protocol
+
+crtr writes exactly one JSON request to your executable's stdin:
+
+```json
+{
+  "protocolVersion": 1,
+  "command": ["app", "show"],
+  "input": { "appId": "app_123" },
+  "context": { "cwd": "/caller/cwd", "plugin": { "name": "crouter-infra", "version": "0.1.0", "scope": "project", "root": "/plugin/root" } }
+}
+```
+
+`input` keys are the parser's camelCase form; a declared `stdin` param arrives as an `input` string, not a second stream. Your executable writes exactly one JSON envelope to stdout and nothing else — diagnostics go to stderr:
+
+```json
+{ "protocolVersion": 1, "ok": true, "result": { "app_id": "app_123" } }
+{ "protocolVersion": 1, "ok": false, "error": { "code": "authentication_required", "message": "...", "field": "session", "next": "..." } }
+```
+
+`ok` is the source of truth (a valid envelope is honored regardless of exit code). crtr validates `result` against your declared `output` (top-level field presence + type) and renders it; `--json` mirrors the same object. An error envelope becomes a normal crtr error with your `code` — lowercase snake_case, never crtr-reserved `internal`, `unknown_path`, `command_collision`, or `plugin_protocol_error`. No envelope at all (invalid JSON, empty, extra stdout, output over 10 MiB, signal kill) becomes `plugin_protocol_error`.
+
+### Two rules that prevent silent breakage
+
+- **Generate `commands.json` from your command definitions — never hand-write it.** The manifest must stay in lockstep with the executable's actual command surface; a hand-maintained copy drifts, and a drifted param or output field surfaces as a validation issue or a `plugin_protocol_error` at invocation. Emit it from the same source your executable dispatches on.
+- **A required output field must be non-null.** The adapter treats an explicit `null` for a declared-required field as *absent* → `plugin_protocol_error`. If a value is genuinely optional, declare it `required: false`; if it's required, always return a real value.
+
+### Validating your command manifest
+
+crtr validates command manifests **statically — it never executes your binary** to check them:
+
+- `crtr pkg plugin show <name>` — inventories the manifest path, executable, accepted top-level command names, and every current validation issue (each with received/expected/next).
+- `crtr sys doctor` — validates the manifest + executable path for every effective command plugin and reports structured remediation (disable/update/remove). `--fix` never chmods or rewrites plugin content.
+- `crtr pkg plugin install` / `update` — report the accepted top-level commands and any issues in their result.
+
+A fixed manifest goes live on the next invocation; there is nothing to restart.
+
 ## Validation
 
 `crtr sys doctor` checks each plugin's manifest:
 - Manifest exists and is valid JSON.
 - Manifest `name` matches the directory name.
+- When the plugin declares `commands`, its command manifest + executable path are validated statically (never executed) — see [Command plugins](#command-plugins).
 
-`crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, both visibility rungs set. Run `crtr memory write -h` for the authoring + routing guide. Sibling artifact dirs (`rules/`, `agents/`, `commands/`, `hooks/`) are validated by their respective specs as those land.
+`crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, both visibility rungs set. Run `crtr memory write -h` for the authoring + routing guide. Other sibling artifact dirs (`rules/`, `agents/`, `hooks/`) are validated by their respective specs as those land.
 
 ## Cross-publishing with Claude Code
 

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

@@ -1,32 +1,16 @@
-# pi-personal-extensions
+# pi-crtr-extensions
 
-Personal [pi](https://pi.dev) package bundling my extensions and prompt templates,
-so they live in version control instead of loose in `~/.pi/agent/`.
+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.
 
-Installed as a local-path package in `~/.pi/agent/settings.json` (see below).
-
-## Setup on a fresh machine — the whole pi rig
-
-My pi install is four packages wired together through the `packages` array in
-`~/.pi/agent/settings.json`. None of these ship with pi; each is added explicitly.
-
-```jsonc
-{
-  "packages": [
-    "npm:pi-claude-oauth-adapter",                  // third-party npm: Anthropic OAuth / Claude-Code compat adapter
-    "../../Code/cli/sisyphus/pi-plugins/sisyphus",  // local: sisyphus orchestration prompts/skills
-    "../../Code/cli/pi-personal-extensions",        // local: THIS package
-    "../../Code/cli/pi-mode-switch"                 // local: Alt+M spec/plan/normal mode cycling
-  ],
-  "defaultProvider": "anthropic",
-  "defaultModel": "claude-opus-4-8",
-  "defaultThinkingLevel": "high",
-  "enableSkillCommands": true,
-  "steeringMode": "all",
-  "quietStartup": true,
-  "theme": "dark"
-}
-```
+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)) —
@@ -37,14 +21,9 @@ If you want Claude-subscription auth, you add this line yourself — it is not b
 OAuth login/refresh via `@earendil-works/pi-ai/oauth` to rotate across
 subscription credentials — that's a different mechanism, built in here.)
 
-For this package specifically, after cloning into `~/Code/cli/pi-personal-extensions`:
-
-```bash
-npm install                 # installs runtime deps (yaml)
-```
-
 `@earendil-works/pi-coding-agent` is a peer dependency provided by pi at runtime —
-do not install it locally.
+do not install it locally. The one runtime dep (`yaml`) is vendored under this
+directory's `node_modules/`.
 
 ## Contents