@north-light/crouter 0.3.154

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

@@ -0,0 +1,68 @@
+import { afterEach, test } from "node:test";
+import assert from "node:assert/strict";
+import type { Model } from "@earendil-works/pi-ai";
+
+import { buildStatuslineFooterLine } from "../statusline.ts";
+
+const previousCycles = process.env.CRTR_CYCLES;
+
+afterEach(() => {
+	if (previousCycles === undefined) delete process.env.CRTR_CYCLES;
+	else process.env.CRTR_CYCLES = previousCycles;
+});
+
+function model(id: string): Model<"anthropic-messages"> {
+	return {
+		id,
+		name: id,
+		api: "anthropic-messages",
+		provider: "anthropic",
+		baseUrl: "https://api.anthropic.com",
+		reasoning: false,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 0,
+		maxTokens: 0,
+	};
+}
+
+function makeCtx(overrides: Partial<Parameters<typeof buildStatuslineFooterLine>[1]> = {}) {
+	return {
+		cwd: "/Users/silasrhyneer/Code/cli/crouter",
+		model: model("claude-opus-4-8"),
+		getContextUsage() {
+			return { tokens: 42 };
+		},
+		...overrides,
+	} as Parameters<typeof buildStatuslineFooterLine>[1];
+}
+
+function makeFooterData(subscription = "provider-rotation: personal") {
+	return {
+		getGitBranch() {
+			return "main";
+		},
+		getExtensionStatuses() {
+			return new Map(subscription ? [["provider-rotation", subscription]] : []);
+		},
+	};
+}
+
+test("renders the footer clusters in order and keeps cwd/git right-aligned", () => {
+	process.env.CRTR_CYCLES = "3";
+	const line = buildStatuslineFooterLine(120, makeCtx(), makeFooterData(), { staged: 0, modified: 0, untracked: 0, conflicts: 0, ahead: 0, behind: 0, stashed: 0 });
+
+	assert.match(line, /^claude-opus-4-8 · provider-rotation: personal · 42 tokens · ↻3\s+crouter \(main ✓\)$/);
+});
+
+test("omits empty subscription and missing cycle, and preserves the spacer on narrow widths", () => {
+	delete process.env.CRTR_CYCLES;
+	const wide = buildStatuslineFooterLine(120, makeCtx(), makeFooterData(""), { staged: 0, modified: 0, untracked: 0, conflicts: 0, ahead: 0, behind: 0, stashed: 0 });
+	assert.match(wide, /^claude-opus-4-8 · 42 tokens\s+crouter \(main ✓\)$/);
+	assert.doesNotMatch(wide, /provider-rotation/);
+	assert.doesNotMatch(wide, /↻/);
+
+	const narrow = buildStatuslineFooterLine(22, makeCtx({ model: model("a-very-long-model-name") }), makeFooterData(""), { staged: 0, modified: 0, untracked: 0, conflicts: 0, ahead: 0, behind: 0, stashed: 0 });
+	assert.match(narrow, /\s+crouter \(main ✓\)$/);
+	assert.doesNotMatch(narrow, /[A-Za-z]crouter \(main ✓\)$/);
+});

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

@@ -0,0 +1,492 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { truncateTail, formatSize, DEFAULT_MAX_LINES, DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
+import {
+  readFileSync,
+  readdirSync,
+  existsSync,
+  statSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  realpathSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep, dirname } from "node:path";
+import { loadProfileManifest } from "../../../core/profiles/manifest.js";
+import { stripMarkdownComments } from "../../../core/runtime/command-expansion.js";
+
+// ---------------------------------------------------------------------------
+// claude-plugin-commands: surfaces Claude Code commands AND skills as pi slash
+// commands, with Claude's `plugin:command` namespacing AND full runtime
+// behavior: `$1/$ARGUMENTS` argument substitution and `!`cmd` / ```! shell
+// execution.
+//
+// Sources scanned (commands from `commands/`, skills from `skills/`):
+//   - User:    ~/.claude/commands, ~/.claude/skills
+//   - Project: <ancestor>/.claude/commands|skills from cwd and every project in
+//              the selected crouter profile, with cwd taking precedence
+//   - Plugins: <installPath>/commands|skills for each installed plugin
+//
+// Names: commands and skills are namespaced by their path under the source
+// root, joined with `:` (e.g. `git-smart:commit`, `skill:headless`,
+// `skill:grove:configuration`). Skills all carry a leading `skill:`; plugin
+// entries are additionally prefixed with the plugin name.
+//
+// Two pieces:
+//   1. Shim files (for discovery/autocomplete). A flat dir of namespaced .md
+//      files, e.g. `git-smart:commit.md`, contributed via `resources_discover`.
+//      Frontmatter is sanitized so pi's strict YAML parser doesn't drop them.
+//   2. An `input` hook (the real execution). Pi's built-in template expansion
+//      substitutes $ARGUMENTS but never runs the `!`git ...`` context blocks
+//      Claude commands depend on. So we intercept `/<plugin>:<command> args`
+//      BEFORE expansion, read the ORIGINAL source file, substitute args, run
+//      the embedded shell, and `transform` the input to the resolved text.
+//      Shell-execution logic mirrors @juicesharp/rpiv-args.
+// ---------------------------------------------------------------------------
+
+const HOME = homedir();
+const CLAUDE = join(HOME, ".claude");
+const USER_COMMANDS = join(CLAUDE, "commands");
+const USER_SKILLS = join(CLAUDE, "skills");
+const INSTALLED = join(CLAUDE, "plugins", "installed_plugins.json");
+const SHIM_DIR = join(HOME, ".pi", "agent", ".plugin-command-shims");
+const PI_PROMPTS = join(HOME, ".pi", "agent", "prompts");
+const PROJECT_PI_PROMPTS = ".pi/prompts";
+
+const INCLUDE_ALL_SCOPES = true;
+const EXCLUDE_NAMES = new Set(["claude.md", "agents.md", "readme.md", "index.md"]);
+
+type Kind = "command" | "skill";
+type IndexRecord = { file: string; kind: Kind; baseDir: string };
+
+// name -> original source. Built alongside the shims; consulted by the input
+// hook to find the file to expand+execute (and how to frame it).
+const commandIndex = new Map<string, IndexRecord>();
+
+type InstallRecord = { scope?: string; installPath?: string; projectPath?: string };
+type InstalledPlugins = { plugins?: Record<string, InstallRecord[]> };
+type Shim = { name: string; target: string; kind: Kind; baseDir: string };
+
+// ---- discovery ------------------------------------------------------------
+
+function collectCommands(root: string, prefix: string[], rel: string[], out: Shim[]): void {
+  if (!existsSync(root)) return;
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const lower = e.name.toLowerCase();
+    if (e.isFile() && lower.endsWith(".md") && !EXCLUDE_NAMES.has(lower)) {
+      const name = [...prefix, ...rel, e.name.slice(0, -3)].join(":");
+      out.push({ name, target: join(root, e.name), kind: "command", baseDir: root });
+    } else if (e.isDirectory() && !e.name.startsWith(".")) {
+      collectCommands(join(root, e.name), prefix, [...rel, e.name], out);
+    }
+  }
+}
+
+// Skills are directories containing SKILL.md. A directory WITHOUT a SKILL.md is
+// a grouping dir we recurse into; once SKILL.md is found we stop (its subdirs
+// are scripts/references/assets). Name mirrors collectCommands: path segments
+// from the skills root, joined with `:`.
+function collectSkills(root: string, prefix: string[], rel: string[], out: Shim[]): void {
+  if (!existsSync(root)) return;
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith(".")) continue;
+    const dir = join(root, e.name);
+    const skillFile = join(dir, "SKILL.md");
+    if (existsSync(skillFile)) {
+      const name = [...prefix, ...rel, e.name].join(":");
+      out.push({ name, target: skillFile, kind: "skill", baseDir: dir });
+    } else {
+      collectSkills(dir, prefix, [...rel, e.name], out);
+    }
+  }
+}
+
+// Ancestor `.claude` dirs from one project pointer up to (and including) its
+// git root, skipping the user-level ~/.claude (handled separately).
+function ancestorClaudeDirs(pointer: string): string[] {
+  const out: string[] = [];
+  let cur = resolve(pointer);
+  while (true) {
+    const claude = join(cur, ".claude");
+    if (resolve(claude) !== resolve(CLAUDE)) {
+      try {
+        if (existsSync(claude) && statSync(claude).isDirectory()) out.push(claude);
+      } catch {
+        /* ignore */
+      }
+    }
+    if (existsSync(join(cur, ".git"))) break; // stop at git root
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return out;
+}
+
+function canonicalDir(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+
+/** Every project `.claude` directory visible to this engine. The cwd pointer
+ *  and its ancestors come first; selected-profile project pointers widen the
+ *  search without letting a duplicate profile entry displace the local copy. */
+export function projectClaudeDirs(cwd: string, profileProjectDirs: readonly string[]): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const pointer of [cwd, ...profileProjectDirs]) {
+    for (const claude of ancestorClaudeDirs(pointer)) {
+      const key = canonicalDir(claude);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(claude);
+    }
+  }
+  return out;
+}
+
+function selectedProfileProjects(): string[] {
+  const profileId = process.env["CRTR_PROFILE_ID"] ?? "";
+  if (profileId === "") return [];
+  try {
+    return loadProfileManifest(profileId).manifest.projects;
+  } catch {
+    // A deleted or invalid selected profile must not hide cwd-local commands.
+    return [];
+  }
+}
+
+function cwdInProject(cwd: string, projectPath: string): boolean {
+  const a = resolve(cwd);
+  const b = resolve(projectPath);
+  return a === b || a.startsWith(b + sep);
+}
+
+// Installed plugins as { name, installPath } pairs (scope-filtered).
+function pluginDirs(cwd: string): { name: string; installPath: string }[] {
+  if (!existsSync(INSTALLED)) return [];
+  let data: InstalledPlugins;
+  try {
+    data = JSON.parse(readFileSync(INSTALLED, "utf8")) as InstalledPlugins;
+  } catch {
+    return [];
+  }
+  const out: { name: string; installPath: string }[] = [];
+  for (const [key, records] of Object.entries(data.plugins ?? {})) {
+    const name = key.split("@")[0];
+    for (const rec of records ?? []) {
+      if (!rec.installPath) continue;
+      if (!INCLUDE_ALL_SCOPES && rec.scope === "project") {
+        if (!rec.projectPath || !cwdInProject(cwd, rec.projectPath)) continue;
+      }
+      out.push({ name, installPath: rec.installPath });
+    }
+  }
+  return out;
+}
+
+function dirIf(p: string): boolean {
+  try {
+    return existsSync(p) && statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Quote frontmatter scalar values pi's strict YAML would misread (leading
+// flow/indicator chars), so the shim still loads into autocomplete.
+function sanitizeFrontmatter(content: string): string {
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) return content;
+  const nl = content.indexOf("\n");
+  const rest = content.slice(nl + 1);
+  const end = rest.search(/^---\s*$/m);
+  if (end === -1) return content;
+  const block = rest.slice(0, end);
+  const after = rest.slice(end);
+  const RISKY = new Set(["[", "]", "{", "}", ",", "&", "*", "!", "@", "`", "%", "?"]);
+  const fixed = block
+    .split("\n")
+    .map((line) => {
+      const m = line.match(/^([A-Za-z0-9_-]+):[ \t]+(.+?)\s*$/);
+      if (!m) return line;
+      const [, key, value] = m;
+      if (value[0] === '"' || value[0] === "'" || !RISKY.has(value[0])) return line;
+      const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      return `${key}: "${escaped}"`;
+    })
+    .join("\n");
+  return content.slice(0, nl + 1) + fixed + after;
+}
+
+// Prompt stems pi already loads natively from ~/.pi/agent/prompts. A shim of
+// the same name collides with the native prompt (pi keeps the prompt, skips the
+// shim, and warns), so we never emit one. This happens because crtr exports its
+// slash commands to BOTH ~/.claude/commands and ~/.pi/agent/prompts; without
+// this, we'd re-shim the claude copy back into pi on top of the native prompt.
+function nativePiPromptStems(): Set<string> {
+  const out = new Set<string>();
+  try {
+    for (const e of readdirSync(PI_PROMPTS, { withFileTypes: true })) {
+      if (e.isFile() && e.name.toLowerCase().endsWith(".md")) out.add(e.name.slice(0, -3));
+    }
+  } catch {
+    /* ignore */
+  }
+  return out;
+}
+
+function buildShims(cwd: string): string {
+  const shims: Shim[] = [];
+  const nativeStems = nativePiPromptStems();
+  const projectDirs = projectClaudeDirs(cwd, selectedProfileProjects());
+  const plugins = pluginDirs(cwd);
+
+  // Commands: user, project ancestors, then plugins.
+  collectCommands(USER_COMMANDS, [], [], shims);
+  for (const cd of projectDirs) collectCommands(join(cd, "commands"), [], [], shims);
+  for (const p of plugins) {
+    const cmds = join(p.installPath, "commands");
+    if (dirIf(cmds)) collectCommands(cmds, [p.name], [], shims);
+  }
+
+  // Skills: user, project ancestors, then plugins. All namespaced under
+  // `skill:` so they group separately from commands in autocomplete.
+  collectSkills(USER_SKILLS, ["skill"], [], shims);
+  for (const cd of projectDirs) collectSkills(join(cd, "skills"), ["skill"], [], shims);
+  for (const p of plugins) {
+    const sk = join(p.installPath, "skills");
+    if (dirIf(sk)) collectSkills(sk, ["skill", p.name], [], shims);
+  }
+
+  try {
+    rmSync(SHIM_DIR, { recursive: true, force: true });
+  } catch {
+    /* ignore */
+  }
+  mkdirSync(SHIM_DIR, { recursive: true });
+  commandIndex.clear();
+
+  const used = new Set<string>();
+  for (const { name, target, kind, baseDir } of shims) {
+    if (nativeStems.has(name)) continue; // pi serves this prompt natively — a shim would just collide
+    let linkName = name;
+    let n = 1;
+    while (used.has(linkName)) linkName = `${name}~${n++}`;
+    used.add(linkName);
+    commandIndex.set(linkName, { file: target, kind, baseDir });
+    try {
+      writeFileSync(join(SHIM_DIR, `${linkName}.md`), sanitizeFrontmatter(readFileSync(target, "utf8")));
+    } catch {
+      /* ignore */
+    }
+  }
+  return SHIM_DIR;
+}
+
+// ---- argument substitution (mirrors pi's prompt-template engine) -----------
+
+function parseCommandArgs(s: string): string[] {
+  const args: string[] = [];
+  let cur = "";
+  let q: string | null = null;
+  for (const ch of s) {
+    if (q) {
+      if (ch === q) q = null;
+      else cur += ch;
+    } else if (ch === '"' || ch === "'") q = ch;
+    else if (ch === " " || ch === "\t") {
+      if (cur) {
+        args.push(cur);
+        cur = "";
+      }
+    } else cur += ch;
+  }
+  if (cur) args.push(cur);
+  return args;
+}
+
+function substituteArgs(content: string, args: string[]): string {
+  const all = args.join(" ");
+  return content.replace(/\$\{(\d+):-([^}]*)\}|\$\{@:(\d+)(?::(\d+))?\}|\$(ARGUMENTS|@|\d+)/g, (_, defaultNum, defaultValue, sliceStart, sliceLength, simple) => {
+    if (defaultNum) return args[parseInt(defaultNum, 10) - 1] || defaultValue;
+    if (sliceStart) {
+      const start = Math.max(0, parseInt(sliceStart, 10) - 1);
+      return sliceLength ? args.slice(start, start + parseInt(sliceLength, 10)).join(" ") : args.slice(start).join(" ");
+    }
+    if (simple === "ARGUMENTS" || simple === "@") return all;
+    return args[parseInt(simple, 10) - 1] ?? "";
+  });
+}
+
+const TOKEN_REGEX = /\$(?:\{\d+:-[^}]*\}|\{@:\d+(?::\d+)?\}|\d+|ARGUMENTS|@)/;
+
+/** Pi loads user prompts before project prompts. Resolve only those native
+ * Markdown templates here; resource-contributed templates have their own input
+ * handler (such as the command shim path above). */
+function nativePromptBody(name: string, cwd: string): string | undefined {
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) return undefined;
+  for (const dir of [PI_PROMPTS, join(cwd, PROJECT_PI_PROMPTS)]) {
+    try {
+      const raw = readFileSync(join(dir, `${name}.md`), "utf8");
+      return splitFrontmatter(raw).body;
+    } catch {
+      // A missing/unreadable prompt is Pi's normal fallthrough path.
+    }
+  }
+  return undefined;
+}
+
+// Split leading `---` frontmatter from body WITHOUT parsing YAML. Claude's
+// loose frontmatter (e.g. `argument-hint: [a] [b]`) makes pi's parseFrontmatter
+// and stripFrontmatter both throw, so we delimiter-split ourselves.
+function splitFrontmatter(content: string): { fm: string; body: string } {
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+    return { fm: "", body: content };
+  }
+  const nl = content.indexOf("\n");
+  const rest = content.slice(nl + 1);
+  const end = rest.search(/^---\s*$/m);
+  if (end === -1) return { fm: "", body: content };
+  const fm = rest.slice(0, end);
+  const afterIdx = rest.indexOf("\n", end);
+  const body = afterIdx === -1 ? "" : rest.slice(afterIdx + 1);
+  return { fm, body };
+}
+
+function shellTimeoutMs(fm: string): number {
+  const m = fm.match(/^shell-timeout:[ \t]*([0-9]+(?:\.[0-9]+)?)\s*$/m);
+  if (!m) return DEFAULT_SHELL_TIMEOUT_MS;
+  const v = parseFloat(m[1]);
+  if (!Number.isFinite(v) || v < 0) return DEFAULT_SHELL_TIMEOUT_MS;
+  return v === 0 ? 0 : v * 1000;
+}
+
+// ---- shell execution (mirrors @juicesharp/rpiv-args) -----------------------
+
+const SHELL_INLINE = /!`([^`\n]+)`/g;
+const SHELL_BLOCK = /```!\n([\s\S]*?)\n```/g;
+const DEFAULT_SHELL_TIMEOUT_MS = 120_000;
+
+function truncateForLLM(content: string): string {
+  const t = truncateTail(content, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+  let out = t.content;
+  if (t.truncated) {
+    const limit = t.truncatedBy === "lines" ? `${t.maxLines} lines` : formatSize(t.maxBytes);
+    out += `\n[truncated: hit ${limit}]`;
+  }
+  return out;
+}
+
+async function runShell(cmd: string, pi: ExtensionAPI, cwd: string, timeoutMs: number): Promise<string> {
+  const [sh, flag] = process.platform === "win32" ? ["powershell.exe", "-Command"] : ["sh", "-c"];
+  const res: any = await pi.exec(sh, [flag, cmd], { cwd, timeout: timeoutMs });
+  if (res.killed) return `[Shell error: timed out after ${Math.max(1, Math.round(timeoutMs / 1000))}s]`;
+  if (res.code !== 0) return `[Shell error: exit code ${res.code}]\n${truncateForLLM(res.stderr ?? "")}`;
+  let combined = res.stdout ?? "";
+  if (res.stderr) {
+    const sep = combined.length === 0 || combined.endsWith("\n") ? "" : "\n";
+    combined = `${combined}${sep}[stderr]\n${res.stderr}`;
+  }
+  return truncateForLLM(combined);
+}
+
+async function executeShell(body: string, pi: ExtensionAPI, cwd: string, timeoutMs: number): Promise<string> {
+  // blocks first (mask with sentinels), then inlines, then restore.
+  const blockOut: string[] = [];
+  let masked = "";
+  let last = 0;
+  for (const m of body.matchAll(SHELL_BLOCK)) {
+    const idx = m.index ?? 0;
+    masked += body.slice(last, idx) + `\x00B${blockOut.length}\x00`;
+    blockOut.push(await runShell(m[1] ?? "", pi, cwd, timeoutMs));
+    last = idx + m[0].length;
+  }
+  masked += body.slice(last);
+
+  let inlined = "";
+  last = 0;
+  for (const m of masked.matchAll(SHELL_INLINE)) {
+    const idx = m.index ?? 0;
+    inlined += masked.slice(last, idx) + (await runShell(m[1] ?? "", pi, cwd, timeoutMs));
+    last = idx + m[0].length;
+  }
+  inlined += masked.slice(last);
+
+  return inlined.replace(/\x00B(\d+)\x00/g, (_, n) => blockOut[parseInt(n, 10)] ?? "");
+}
+
+// ---------------------------------------------------------------------------
+
+export default function (pi: ExtensionAPI) {
+  pi.on("resources_discover", async (event: { cwd?: string }) => {
+    const dir = buildShims(event?.cwd ?? process.cwd());
+    return { promptPaths: [dir] };
+  });
+
+  pi.on("input", async (event: any, ctx: any) => {
+    if (event.source === "extension") return { action: "continue" };
+    const text: string = event.text ?? "";
+    if (!text.startsWith("/")) return { action: "continue" };
+
+    const sp = text.indexOf(" ");
+    const name = sp === -1 ? text.slice(1) : text.slice(1, sp);
+    const argsString = sp === -1 ? "" : text.slice(sp + 1).trim();
+
+    const rec = commandIndex.get(name);
+    if (!rec) return { action: "continue" }; // not one of ours — let pi handle it
+
+    let raw: string;
+    try {
+      raw = readFileSync(rec.file, "utf8");
+    } catch {
+      return { action: "continue" };
+    }
+
+    const { fm, body: rawBody } = splitFrontmatter(raw);
+    const body = stripMarkdownComments(rawBody).trim();
+    const hadTokens = TOKEN_REGEX.test(body);
+
+    let processed = hadTokens ? substituteArgs(body, parseCommandArgs(argsString)) : body;
+    processed = await executeShell(processed, pi, ctx.cwd ?? process.cwd(), shellTimeoutMs(fm));
+    if (!hadTokens && argsString) processed = `${processed}\n\n${argsString}`;
+
+    // Skills lean on relative paths (scripts/, references/, assets/). Pin the
+    // base dir so the model can resolve them regardless of cwd.
+    if (rec.kind === "skill") {
+      processed = `[Skill: ${name}. Base directory: ${rec.baseDir}. Resolve relative paths (scripts, references, assets) referenced below against this directory.]\n\n${processed}`;
+    }
+
+    return { action: "transform", text: processed };
+  });
+
+  // Native pi prompt templates bypass the command index above. Intercept their
+  // source Markdown before Pi expands it so author-only HTML comments never
+  // become a user message. Extension commands execute before input hooks, and
+  // resource-contributed templates are already handled by their own hooks.
+  pi.on("input", async (event: any, ctx: any) => {
+    if (event.source === "extension") return { action: "continue" };
+    const match = (event.text ?? "").match(/^\/([^\s]+)(?:\s+([\s\S]*))?$/);
+    if (match === null || commandIndex.has(match[1]!)) return { action: "continue" };
+    const body = nativePromptBody(match[1]!, ctx.cwd ?? process.cwd());
+    if (body === undefined) return { action: "continue" };
+    return {
+      action: "transform",
+      text: substituteArgs(stripMarkdownComments(body).trim(), parseCommandArgs(match[2] ?? "")),
+    };
+  });
+}

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/crouter-help.ts

@@ -0,0 +1,95 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+
+const run = promisify(execFile);
+
+// `crtr -h` is the auto-loaded tool guide. Capturing it costs a real subprocess:
+// bare `crtr -h` is the one invocation that must build the FULL command tree, so
+// it loads every subtree's module graph — ~250ms on a laptop, ~320ms in the
+// guest container. The guide's content is static per crouter version + installed
+// plugins, so that cost must never sit in front of a turn. The TTL only exists
+// to pick a tree change (an upgrade, a newly installed plugin) up eventually.
+const TTL_MS = 15_000;
+
+// The TTL cache is also persisted to disk, keyed by cwd (skills resolve by
+// scope, so the guide is cwd-specific). Every broker/node is a FRESH process, so
+// the in-memory cache alone is always cold at session_start — each boot would
+// re-spawn `crtr -h`. The disk layer lets a cluster of node boots within one TTL
+// window (daemon revives, child spawns, rapid relaunches) share a single capture.
+function helpCacheFile(cwd: string): string {
+  const h = createHash("sha1").update(cwd).digest("hex").slice(0, 16);
+  return join(homedir(), ".crouter", "cache", `crouter-help-${h}.json`);
+}
+
+export default function (pi: ExtensionAPI) {
+  let helpText = "";
+  let capturedAt = 0;
+
+  async function refresh(): Promise<void> {
+    if (Date.now() - capturedAt < TTL_MS && helpText) return; // in-memory fresh
+    const file = helpCacheFile(process.cwd());
+
+    // Cross-process disk cache: reuse a recent capture from a sibling boot.
+    try {
+      const c = JSON.parse(readFileSync(file, "utf8")) as { text?: string; at?: number };
+      if (typeof c.text === "string" && c.text && typeof c.at === "number" && Date.now() - c.at < TTL_MS) {
+        helpText = c.text;
+        capturedAt = c.at;
+        return; // fresh on disk — skip the spawn
+      }
+    } catch {
+      // miss / corrupt — fall through to re-probe
+    }
+
+    try {
+      const { stdout } = await run("crouter", ["-h"], { timeout: 10_000 });
+      helpText = stdout.trim();
+      capturedAt = Date.now();
+      try {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, JSON.stringify({ text: helpText, at: capturedAt }), "utf8");
+      } catch {
+        // best-effort: a missing cache just means the next boot re-probes
+      }
+    } catch {
+      // soft-fail: keep last-known text (or empty); never block the turn
+    }
+  }
+
+  // Boot-time capture: the one place a refresh may block, because it happens at
+  // node mint/revive, never in front of a user's turn. A warm-pool spare has
+  // therefore already paid it before it is ever claimed.
+  pi.on("session_start", refresh);
+
+  pi.on("before_agent_start", (event) => {
+    // NEVER await here. A stale-by-TTL capture used to re-spawn `crtr -h`
+    // synchronously, putting its full subprocess cost between the delivered
+    // message and agent_start — measured as the single largest term in a
+    // Northlight first-message ack. Serve the last-known text and let the
+    // refresh land for the next turn instead.
+    if (Date.now() - capturedAt >= TTL_MS) void refresh();
+    if (!helpText) return;
+
+    const block = `<crtr-tool-guide>\n${helpText}\n</crtr-tool-guide>`;
+
+    // Place the guide in the tool-selection frame, right after pi's native
+    // "Available tools" list rather than at the very bottom — the agent decides
+    // which capability to reach for while reading the tools, so the crtr
+    // commands (agent/skill/job) must be present there, not 3k tokens later.
+    // `\n\nGuidelines:` is the stable seam that closes the tools area. Fall back
+    // to appending if pi ever changes that marker.
+    const anchor = "\n\nGuidelines:";
+    const idx = event.systemPrompt.indexOf(anchor);
+    if (idx === -1) {
+      return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+    }
+    return {
+      systemPrompt: `${event.systemPrompt.slice(0, idx)}\n\n${block}${event.systemPrompt.slice(idx)}`,
+    };
+  });
+}

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/crtr-commands/filters.json

@@ -0,0 +1,7 @@
+{
+  "_help": "Controls which crtr nodes become slash commands. Edit, then /reload. Matching is by colon-joined path; an entry matches that node AND all descendants. e.g. 'node' matches node, node:new, node:list. When 'include' is non-empty, EVERYTHING is excluded by default and only matching nodes are registered. 'exclude' always wins.",
+  "include": [
+    "node:new"
+  ],
+  "exclude": []
+}