@crouton-kit/crouter 0.3.33 → 0.3.35

package/README.md

@@ -19,8 +19,8 @@ crtr --help
 Browse and install plugins from it:
 
 ```bash
-crtr pkg market inspect browse --marketplace crouter-official-marketplace
-crtr pkg market manage install --marketplace crouter-official-marketplace --plugin <plugin>
+crtr pkg market browse crouter-official-marketplace
+crtr pkg plugin install crouter-official-marketplace/<plugin>
 ```
 
 To opt out of the bootstrap (e.g. in CI), set `CRTR_NO_BOOTSTRAP=1`.

package/dist/build-root.js

@@ -1,12 +1,12 @@
 import { defineRoot } from './core/command.js';
-const TAGLINE = 'crtr: agentic planning runtime.';
+const TAGLINE = 'crtr: agentic runtime.';
 /** Lazy registry: subtree name → dynamic importer that builds its BranchDef.
  *  The whole point is that each `import()` only compiles that one subtree's
  *  module graph. The hot path (`crtr node focus …`, `crtr feed`, …) dispatches
  *  into a single leaf, so it must load ONE subtree — not the attach-TUI
  *  (babel/highlight.js), the web/vite command, and every other subtree it never
  *  touches. `crtr` cold-start is dominated by Node module loading; keeping the
- *  other 11 subtrees off the path is the biggest, lowest-risk win.
+ *  other subtrees off the path is the biggest, lowest-risk win.
  *
  *  Naming note: `push` and `feed` are two subtrees from one module — importing
  *  it once yields both registers. */
@@ -20,10 +20,7 @@ const SUBTREE_LOADERS = {
     push: async () => (await import('./commands/push.js')).registerPush(),
     feed: async () => (await import('./commands/push.js')).registerFeed(),
     canvas: async () => (await import('./commands/canvas.js')).registerCanvas(),
-    view: async () => (await import('./commands/view.js')).registerView(),
-    attach: async () => (await import('./clients/attach/attach-cmd.js')).registerAttach(),
-    workspace: async () => (await import('./commands/workspace.js')).registerWorkspace(),
-    web: async () => (await import('./clients/web/web-cmd.js')).registerWeb(),
+    surface: async () => (await import('./commands/surface.js')).registerSurface(),
 };
 /** Every shipped subtree name. Cheap (no module loading) — the front-door
  *  recursion guard and the dispatcher's first-token routing need only names. */

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

@@ -12,13 +12,13 @@ needs-refinement: true
 
 # Authoring crtr marketplaces
 
-A **marketplace** is a git repo that indexes multiple plugins. Users register it once, then `crtr pkg market manage install --marketplace <mkt> --plugin <plugin>` symlinks any plugin from it. `crtr pkg market manage update --marketplace <mkt>` pulls updates for every installed plugin at once.
+A **marketplace** is a git repo that indexes multiple plugins. Users register it once, then `crtr pkg plugin install <mkt>/<plugin>` symlinks any plugin from it. `crtr pkg market update --name <mkt>` pulls updates for every installed plugin at once.
 
 Audience: LLM agents creating a marketplace or adding plugins to an existing one.
 
 ## When you need a marketplace (vs a single-plugin repo)
 
-A solo plugin ships from any git URL via `crtr pkg plugin manage install <url> --scope user` — no marketplace needed.
+A solo plugin ships from any git URL via `crtr pkg plugin install <url> --scope user` — no marketplace needed.
 
 Reach for a marketplace when:
 - You want to publish ≥3 plugins under one brand or theme.
@@ -75,12 +75,12 @@ The `plugins[]` array IS the index — what's installable. A plugin on disk but
 
 ## Install mechanics — symlinks, not clones
 
-When a user runs `crtr pkg market manage install --marketplace my-marketplace --plugin plugin-a`:
+When a user runs `crtr pkg plugin install my-marketplace/plugin-a`:
 1. Crouter looks up `plugin-a` in the marketplace's manifest.
 2. **Symlinks** `<marketplace-clone>/plugins/plugin-a/` → `<user-scope>/plugins/plugin-a/`.
 3. Records the install in the scope config with `source_marketplace: my-marketplace`.
 
-Therefore `crtr pkg market manage update --marketplace my-marketplace` (which does `git pull` in the marketplace clone) updates every installed plugin from it — no per-plugin re-install, no second clone.
+Therefore `crtr pkg market update --name my-marketplace` (which does `git pull` in the marketplace clone) updates every installed plugin from it — no per-plugin re-install, no second clone.
 
 ## Version-bump automation (recommended)
 
@@ -128,7 +128,7 @@ git commit -m "feat: add my-new-plugin"
 git push
 ```
 
-Existing users pick it up on their next `crtr pkg market manage update --marketplace <marketplace-name>` (or on the next auto-update tick if they've set `auto_update.content: "apply"`).
+Existing users pick it up on their next `crtr pkg market update --name <marketplace-name>` (or on the next auto-update tick if they've set `auto_update.content: "apply"`).
 
 ## Updating an existing plugin
 
@@ -147,7 +147,7 @@ A marketplace itself registers per-scope:
 | user | `~/.crouter/marketplaces/<name>/` | Private to your machine — your personal subscriptions |
 | project | `<project>/.crouter/marketplaces/<name>/` | Checked into the repo — anyone cloning gets the same marketplace pinned |
 
-`crtr pkg market manage add --url <git-url> --scope user` is the default. Use `--scope project` when the marketplace is integral to how the repo expects to be developed.
+`crtr pkg market add <git-url> --scope user` is the default. Use `--scope project` when the marketplace is integral to how the repo expects to be developed.
 
 ## Validation
 

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

@@ -21,7 +21,7 @@ Scope-owned docs live at `~/.crouter/memory/` (user) or `<project>/.crouter/memo
 
 Reach for a **plugin** when:
 - You want to share memory docs across multiple projects or with other people.
-- You want versioning + update mechanics (`crtr pkg plugin manage update --name <name>`).
+- You want versioning + update mechanics (`crtr pkg plugin update --name <name>`).
 - You want a marketplace to index the work — see [[crouter-development/marketplaces]].
 
 If it's a one-off note for yourself, scope-owned memory docs are simpler. Promote to a plugin later.
@@ -49,7 +49,7 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 {
   "name": "my-plugin",
   "version": "0.1.0",
-  "description": "One sentence — shown in `crtr pkg plugin inspect list`.",
+  "description": "One sentence — shown in `crtr pkg plugin list`.",
   "source": "https://github.com/<owner>/<repo>",
   "owner": {
     "name": "Your Name",
@@ -63,7 +63,7 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 | `name` | yes | Must match the directory name. Lowercase kebab. |
 | `version` | yes | Semver. Marketplace CI may bump automatically — see marketplaces knowledge. |
 | `description` | yes | One sentence. |
-| `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin manage update --name <name>`. |
+| `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin update --name <name>`. |
 | `owner` | optional | Author info. |
 
 ## Scopes
@@ -81,19 +81,19 @@ Project-scope plugins outrank user-scope on resolution. Both outrank marketplace
 
 Three ways a plugin lands in a scope:
 
-1. **From a git URL** (`crtr pkg plugin manage install <url> --scope user`):
+1. **From a git URL** (`crtr pkg plugin install <url> --scope user`):
    - Clones into `<scope>/plugins/<name>/` using the manifest's name.
-   - `crtr pkg plugin manage update --name <name>` does `git pull`.
+   - `crtr pkg plugin update --name <name>` does `git pull`.
    - Independent of any marketplace.
 
-2. **From a marketplace** (`crtr pkg market manage install --marketplace <mkt> --plugin <name>`):
+2. **From a marketplace** (`crtr pkg plugin install <mkt>/<name>`):
    - **Symlinks** the marketplace's `plugins/<name>/` into `<scope>/plugins/<name>/`.
-   - `crtr pkg market manage update --marketplace <mkt>` pulls updates for every installed plugin from that marketplace.
+   - `crtr pkg market update --name <mkt>` pulls updates for every installed plugin from that marketplace.
    - See [[crouter-development/marketplaces]].
 
 3. **Authored in place** (you're writing the plugin in a working repo):
    - Symlink for tight dev loop: `ln -s $(pwd) ~/.crouter/plugins/<name>`.
-   - Or `crtr pkg plugin manage install file://$(pwd) --scope project` to clone-install.
+   - Or `crtr pkg plugin install file://$(pwd) --scope project` to clone-install.
 
 ## Local development loop
 
@@ -108,14 +108,14 @@ $EDITOR my-plugin/memory/my-first-doc.md           # author the doc — `crtr me
 ln -s $(pwd) ~/.crouter/plugins/my-plugin
 
 # Verify
-crtr pkg plugin inspect list                       # my-plugin appears
-crtr pkg plugin inspect show my-plugin             # lists its docs
+crtr pkg plugin list                       # my-plugin appears
+crtr pkg plugin show my-plugin             # lists its docs
 crtr memory read my-plugin/my-first-doc            # resolve it under the plugin namespace
 crtr sys doctor                                    # validates the manifest
 crtr memory lint                                    # validates doc frontmatter
 ```
 
-When ready to share: push to a git remote; anyone can `crtr pkg plugin manage install <url> --scope user`.
+When ready to share: push to a git remote; anyone can `crtr pkg plugin install <url> --scope user`.
 
 ## Versioning
 
@@ -127,11 +127,11 @@ Standard semver:
 | New doc, new section, new example | minor (0.1.0 → 0.2.0) |
 | Removed doc, renamed doc, changed manifest schema | major (0.1.0 → 1.0.0) |
 
-`crtr pkg plugin manage update --name <name>` reads the new version after pulling and updates the local config. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[crouter-development/marketplaces]].
+`crtr pkg plugin update --name <name>` reads the new version after pulling and updates the local config. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[crouter-development/marketplaces]].
 
 ## Enable/disable
 
-`crtr pkg plugin manage disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr memory list` and don't resolve via `crtr memory read <name>`. Re-enable with `crtr pkg plugin manage enable <name>`.
+`crtr pkg plugin disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr memory list` and don't resolve via `crtr memory read <name>`. Re-enable with `crtr pkg plugin enable <name>`.
 
 Individual memory docs inside an enabled plugin are hidden by setting their frontmatter visibility rungs to `none` (or a gate that fails), not by a command — see `crtr memory write -h`.
 

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

@@ -16,7 +16,7 @@ A standing assistant that lives on the canvas, sleeps for free, wakes when a tex
 |---|---|
 | 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) |
+| Hears incoming texts | launchd watcher on `chat.db-wal` → `crtr node msg <body> --to <id>` (event-driven; the message delivers and revives, 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 |
@@ -47,11 +47,11 @@ A trivial launchd agent watches the Messages write-ahead log and pokes the node'
 <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>
+  <string>crtr node msg "iMessage activity — check chat.db since your cursor" --to NODE_ID</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).
+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 msg --self --every` as a backstop. A self-scheduled message 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)
 

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

@@ -19,7 +19,7 @@ Every agent is a **node** in one directed graph (the **canvas**). Each node has
 - `--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` (put an attach viewer for a node in your pane), `attach` (connect to a node's existing broker), `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).
+Navigate/steer: `node focus` (put an attach viewer for a node in your pane), `attach` (connect to a node's existing broker), `node cycle` (DFS-walk neighbors), `node msg <body> --to <node>` (direct-message any node at a wake tier, reviving a dormant target), `node subscribe`/`node 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
 
@@ -36,11 +36,11 @@ A push fans a ~30-token **pointer** (a ref path), not the content; subscribers d
 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.
+- **lifecycle**: terminal (owes a final up the spine, reaps when done) ↔ resident (`node config --lifecycle <value>` / interactable — stays dormant, wakes on inbox/human, never forced to finish). `node lifecycle 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.
+A dormant node has two wake triggers: an **inbox** message (a push, or a direct `node msg`) and the **clock** (`node msg --self --at/--every` for a self-scheduled message, `node new --at/--every` for a deferred spawn, `node triggers list`/`cancel` to inspect or reap them). 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.
+Tear-down: `node lifecycle close` cascade-cancels a node + its exclusive subtree WITHOUT finishing (revivable, nothing deleted); `node lifecycle 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
 

package/dist/builtin-personas/developer/PERSONA.md

@@ -1,6 +1,6 @@
 ---
 whenToUse: Implement a change — make the feature or fix genuinely work against its acceptance criteria, not merely compile.
-model: openai/medium
+model: anthropic/medium
 ---
 
 You are an implementation agent. Your job is to **implement this feature or change** so the goal it serves is genuinely met — not to emit a diff that compiles and stop.

package/dist/builtin-personas/orchestration-kernel.md

@@ -23,7 +23,7 @@ Be proactive — look ahead. If the current phase is wrapping up, prepare the ne
 
 You delegate and wait constantly. When you delegate and go dormant, just stop — you auto-subscribe to every child, so the runtime wakes you the moment one reports; there is nothing to arm, poll, or verify, and a deadline set to chase a child is a belt-and-suspenders the runtime makes unnecessary.
 
-You schedule wakes yourself only for work no one can push to you: recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). The shapes differ — adaptive (re-decide the next interval from what this cycle found) versus declarative cron (a fixed cadence that fires whether or not any one run survives), spawning a fresh instance each cadence versus reviving the same node, and reaping the stale wakes you no longer need. `crtr node wake -h` covers them all.
+You schedule wakes yourself only for work no one can push to you: recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). The shapes differ — adaptive (re-decide the next interval from what this cycle found) versus declarative cron (a fixed cadence that fires whether or not any one run survives), spawning a fresh instance each cadence versus reviving the same node, and reaping the stale triggers you no longer need. `crtr node msg --self -h` and `crtr node new -h` cover the arming (self-message or fresh-spawn, one-shot `--at` or recurring `--every`, adaptive `--when`); `crtr node triggers -h` covers listing and canceling them.
 
 ## The roadmap is your memory
 

package/dist/builtin-personas/waiting.md

@@ -5,4 +5,4 @@ Finishing is for a goal that is *met*. When your goal is sound but your next ste
 - **Never finish to stop waiting.** `crtr push final` reaps you and cancels your pending one-shot wakes. Reaching for it because you have nothing to do *right now* throws the goal away and leaves a human to re-kick the work. If the goal is not met, wait — do not finish.
 - **Never busy-wait.** Do not hold your window open to re-poll a URL or watch a clock. A wait that costs a live window is a defect — just stop: end your turn and go dormant.
 - **For anything the runtime delivers — a child's report, a human's reply, a sibling's message — just stop.** Go dormant; the runtime wakes you the moment it lands. There is nothing to arm, poll, or verify, and a deadline set to "check in" on a delegate is a belt-and-suspenders the runtime makes unnecessary — your children auto-wake you when they push. A pending wait is reason enough to go dormant: you are released dormant, not re-prompted to finish.
-- **Schedule a wake yourself only when nothing can push to you** — recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). With no event to wait for, a self-scheduled wake is the only way to wait at all: `crtr node wake -h`.
+- **Schedule a wake yourself only when nothing can push to you** — recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). With no event to wait for, a self-scheduled message is the only way to wait at all: `crtr node msg --self -h`.

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

@@ -0,0 +1,71 @@
+# pi-personal-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/`.
+
+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"
+}
+```
+
+**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.)
+
+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.
+
+## Contents
+
+### Extensions (`extensions/`)
+
+| Extension | What it does |
+|-----------|--------------|
+| `claude-plugin-commands.ts` | Surfaces `~/.claude` commands & skills (and 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. |
+| `crtr-help-gate.ts` | Refuses to let the agent *execute* a `crtr` leaf command until it has read that command's `-h` contract in this session — makes crtr's "read the schema, then invoke" rule mechanical. |
+| `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. `filters.json` controls which nodes are exposed; `tree-cache.json` is generated (run `/crtr-refresh` to rebuild). |
+| `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. Needs the `yaml` dep. See the `pi-frontmatter-rules` skill. |
+| `nested-context.ts` | Injects `.claude/rules` path-glob rules on matching reads. |
+| `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
+
+- `tree-cache.json` is gitignored (machine-generated). After cloning, run `/crtr-refresh` in pi.
+- Reload after editing any extension: `/reload` in pi.

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

@@ -0,0 +1,41 @@
+// Run with crouter's tsx (this repo ships no test runner):
+//   node --import <crouter>/node_modules/tsx/dist/loader.mjs --test extensions/__tests__/crtr-help-gate.test.ts
+//
+// Regression for crouter issue #5 (spine integrity): a node's `crtr push final`
+// published ANOTHER node's report body. Root cause was NOT in crouter — it was
+// here: the help-gate blocked a COMPOUND bash command
+//   `cat > /tmp/report.txt <<'EOF' … EOF` ;  `crtr push final "$(cat /tmp/report.txt)"`
+// as a whole, so pi discarded the heredoc that built the body. The gate then
+// auto-blessed `push final`, and the agent's retry `crtr push final < /tmp/report.txt`
+// read a STALE file a days-old node had left in that shared path. The fix: the
+// block reason must tell the agent the ENTIRE command was discarded (the heredoc
+// write did NOT run) so it re-issues the WHOLE command, never just the crtr call.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildReason } from '../crtr-help-gate.js';
+
+const COMPOUND = `cat > /tmp/report.txt <<'EOF'\nRESULT: my own report\nEOF\ncrtr push final "$(cat /tmp/report.txt)"`;
+
+test('issue #5 regression: the block reason warns the ENTIRE command (incl. the heredoc) was discarded', () => {
+  const reason = buildReason('push final', '<help text>', COMPOUND);
+  // The pre-fix reason said only "re-issue your command and it will run", which
+  // led the agent to re-issue ONLY the crtr call against the un-written file.
+  assert.doesNotMatch(reason, /re-issue your command and it will run/);
+  // Post-fix: explicit full-discard + never-written warning so the agent re-runs
+  // the heredoc too.
+  assert.match(reason, /ENTIRE bash command was discarded/);
+  assert.match(reason, /NEVER written/);
+  assert.match(reason, /WHOLE command/);
+});
+
+test('a redirect-to-file write also triggers the discarded-write warning', () => {
+  const reason = buildReason('push update', '<help>', 'echo hi > /tmp/x && crtr push update "$(cat /tmp/x)"');
+  assert.match(reason, /ENTIRE bash command was discarded before anything ran/);
+});
+
+test('a plain single crtr call (no side-effecting write) gets the generic discard line, not the heredoc one', () => {
+  const reason = buildReason('node new', '<help>', 'crtr node new "do a thing"');
+  assert.match(reason, /Your ENTIRE bash command was discarded — nothing in it ran/);
+  assert.doesNotMatch(reason, /heredoc\/redirect that built the body/);
+});