@mu-crew/mu 3.2.1 → 3.3.0

package/AGENTS.md

@@ -169,7 +169,7 @@ is one atomic call. Keep the tmux workaround out of herdr.
 
 ## Orchestrating on this repo
 
-Follow the loop in [skills/mu/SKILL.md](skills/mu/SKILL.md). Repo specifics:
+Follow [skills/mu/recipes/orchestrator-loop.md](skills/mu/recipes/orchestrator-loop.md). Repo specifics:
 
 - Each workspace runs `npm install` into its own `node_modules`. Never
   symlink main's.
@@ -188,15 +188,20 @@ Follow the loop in [skills/mu/SKILL.md](skills/mu/SKILL.md). Repo specifics:
 ## Skill files are context, not documentation
 
 `skills/mu/SKILL.md` loads into every orchestrator's context, and
-`skills/mu/REMOTE_WORKERS.md` on demand. Every word competes with the
-user's work. Read the `writing-for-agents` skill before you edit
-either one.
+the recipes in `skills/mu/recipes/` on demand. Every word competes with the
+user's work. The recipes are written for an agent with no context;
+[recipes/brief.md](skills/mu/recipes/brief.md) holds the rules, and
+they apply to the skill files too.
 
 - Leave verb lists, flags, and option tables to `--help`. The skill
   carries only what `--help` cannot: the gotcha, the reason, the trap.
 - Say each thing once, next to where it applies.
 - SKILL.md holds the trigger and the rule. Detail that only some
-  branches need goes in REMOTE_WORKERS.md.
+  branches need goes in a recipe under `skills/mu/recipes/`, with a
+  row in SKILL.md's recipe index. Recipes reference only mu, never
+  skills outside this repo.
+- `docs/guide/` pages stay terse for humans and link to the recipe
+  instead of restating it.
 - Delete sentences the model obeys by default. State the target
   behaviour.
 

package/README.md

@@ -89,6 +89,52 @@ pane.
 For many tiny calls, a hidden subagent is lighter. mu bets that seeing
 and steering agent work is worth a pane.
 
+## Ultrathink, the mu way
+
+Long agent runs fail in two ways: the agent stops at 35 of 50 items and
+calls it done, and it grades its own work generously. The fix is to
+take the plan out of the agent's head, fan the work out to fresh
+agents, and have other agents try to refute each result before it
+counts. Claude Code's ultracode does this with a hidden script. mu does
+it in the open:
+
+- **The plan is the DAG.** Every unit, every review, and every round
+  is a task before an agent spawns. `mu state` shows 35 of 50 done, so
+  nobody can declare victory early.
+- **Reviews are tasks.** A `review_x` task is blocked by `x` and run by
+  a fresh agent, ideally on another model, against criteria written
+  up front. A rejection adds `fix_x` and a second review to the DAG
+  instead of rewriting history.
+- **Every agent is a pane.** Attach to any worker, reviewer, or judge
+  mid-run and steer it.
+- **Nothing lives only in a context window.** Verdicts, evidence, and
+  stop rules are task notes. The run survives compaction, crashes, and
+  a new orchestrator.
+
+Ask your orchestrator to *ultrathink* a job, and it follows
+[skills/mu/recipes/ultrathink.md](skills/mu/recipes/ultrathink.md).
+That recipe composes smaller ones you can also use on their own:
+
+| Recipe | Shape |
+| ------ | ----- |
+| [fan-out](skills/mu/recipes/fan-out.md) | one task per unit, merged as each closes |
+| [adversarial-review](skills/mu/recipes/adversarial-review.md) | a fresh agent tries to reject each unit before it ships |
+| [refute](skills/mu/recipes/refute.md) | finders, then one refuter per finding, then a report |
+| [hypothesis-panel](skills/mu/recipes/hypothesis-panel.md) | independent theories from separate evidence, each attacked |
+| [tournament](skills/mu/recipes/tournament.md) | competing attempts, judged in pairs |
+| [loop-until-done](skills/mu/recipes/loop-until-done.md) | rounds until a stop rule written up front holds |
+| [triage](skills/mu/recipes/triage.md) | quarantined readers classify, a trusted actor acts |
+| [deep-research](skills/mu/recipes/deep-research.md) | searchers by angle, one checker per claim, a cited report |
+| [review-panel](skills/mu/recipes/review-panel.md) | one reviewer per angle on a diff, refuted, then fixed or reported |
+| [rules-audit](skills/mu/recipes/rules-audit.md) | one checker per AGENTS.md rule plus a skeptic; or mine repeated corrections into new rules |
+
+In pi, `mu link pi` adds them as commands: `/ultrathink <job>`,
+`/mu-research <question>`, `/mu-review [target]`, `/mu-refute <scope>`,
+`/mu-tournament <task>`, and `/mu-rules-audit [check <target> | mine]`.
+
+All recipes, including the orchestrator loop and remote workers, are
+in [skills/mu/recipes/](skills/mu/recipes/).
+
 ## Documentation
 
 - [Getting started](docs/guide/getting-started.md): the first
@@ -96,8 +142,9 @@ and steering agent work is worth a pane.
 - [User guide](docs/guide/README.md): how-tos for dispatch, remote
   workers, sync, recovery, and the dashboard.
 - [skills/mu/SKILL.md](skills/mu/SKILL.md): what an orchestrating
-  agent reads. [REMOTE_WORKERS.md](skills/mu/REMOTE_WORKERS.md) covers
-  agents on other machines.
+  agent reads. [skills/mu/recipes/](skills/mu/recipes/) holds the
+  recipes it points to, such as
+  [remote workers](skills/mu/recipes/remote-workers.md).
 - [ARCHITECTURE.md](docs/ARCHITECTURE.md) and
   [docs/architecture/](docs/architecture/): the module map and deep
   dives.

package/dist/cli.js

@@ -14,18 +14,20 @@ function encode(msg) {
   return `${JSON.stringify(msg)}
 `;
 }
-var CTL_PROTOCOL_VERSION, CTL_OPS, UNKNOWN_OP_PREFIX, LineDecoder;
+var CTL_PROTOCOL_VERSION, CTL_COMMANDS, CTL_OPS, UNKNOWN_OP_PREFIX, LineDecoder;
 var init_protocol = __esm({
   "src/ctl/protocol.ts"() {
     "use strict";
     CTL_PROTOCOL_VERSION = 1;
+    CTL_COMMANDS = ["new", "reload", "compact"];
     CTL_OPS = [
       "hello",
       "status",
       "send",
       "wait",
       "abort",
-      "fresh"
+      "fresh",
+      "command"
     ];
     UNKNOWN_OP_PREFIX = "unknown op: ";
     LineDecoder = class {
@@ -44,7 +46,7 @@ var init_protocol = __esm({
 import { createConnection } from "net";
 function clientTimeout(req, override) {
   if (override !== void 0) return override;
-  if (req.op === "fresh") return CTL_FRESH_TIMEOUT_MS;
+  if (req.op === "fresh" || req.op === "command") return CTL_FRESH_TIMEOUT_MS;
   if (req.op !== "wait") return CTL_DEFAULT_TIMEOUT_MS;
   return req.timeoutMs === void 0 ? void 0 : req.timeoutMs + CTL_WAIT_SLACK_MS;
 }
@@ -1289,27 +1291,6 @@ async function awaitPaneQuiescence(paneId, budgetMs) {
     await currentSleep(Math.min(SEND_READINESS_POLL_MS, remaining));
   }
 }
-async function awaitNewSession(paneId, baseline, budgetMs) {
-  if (budgetMs <= 0) return true;
-  const deadline = Date.now() + budgetMs;
-  let previous = baseline;
-  let stable = 0;
-  for (; ; ) {
-    const scrollback = await capturePane(paneId, { lines: 50 }).catch(() => void 0);
-    if (scrollback !== void 0 && scrollback !== baseline) {
-      if (scrollback === previous) {
-        stable++;
-        if (stable >= QUIESCENCE_CONFIRMATIONS) return true;
-      } else {
-        stable = 0;
-      }
-      previous = scrollback;
-    }
-    const remaining = deadline - Date.now();
-    if (remaining <= 0) return false;
-    await currentSleep(Math.min(SEND_READINESS_POLL_MS, remaining));
-  }
-}
 function pasteProbe(text2) {
   const firstLine = (text2.split("\n")[0] ?? "").trim();
   return firstLine.slice(0, 24);
@@ -1337,7 +1318,6 @@ async function sendToPane(paneId, text2, opts = {}) {
   assertValidPaneId(paneId);
   const readinessMs = opts.readinessMs ?? defaultSendReadinessMs();
   const quiesced = await awaitPaneQuiescence(paneId, readinessMs);
-  const newSessionBaseline = readinessMs > 0 && text2.trim() === "/new" ? await capturePane(paneId, { lines: 50 }).catch(() => void 0) : void 0;
   const copyResult = await currentExecutor(["copy-mode", "-q", "-t", paneId]);
   if (copyResult.exitCode !== 0 && /can't find pane|no current target/i.test(copyResult.stderr)) {
     throw new TmuxError(
@@ -1360,15 +1340,6 @@ async function sendToPane(paneId, text2, opts = {}) {
   if (delay2 > 0) await currentSleep(delay2);
   await tmux(["send-keys", "-t", paneId, "Enter"]);
   if (readinessMs <= 0) return;
-  if (newSessionBaseline !== void 0 && !await awaitNewSession(paneId, newSessionBaseline, readinessMs)) {
-    const warn3 = opts.onUndelivered ?? defaultUndeliveredWarning;
-    warn3({
-      paneId,
-      reason: "transition-unconfirmed",
-      message: `send to ${paneId} submitted /new, but the new session did not become ready within ${readinessMs}ms. Wait for the pane to settle before sending more work.`
-    });
-    return;
-  }
   const probe = pasteProbe(text2);
   if (probe.length === 0) return;
   for (let attempt = 0; attempt <= SUBMIT_RETRIES; attempt++) {
@@ -4401,7 +4372,7 @@ async function spawnAgent(db, opts) {
     agent = created.row;
     const startAgent = (await activeMux()).startAgentInPane;
     if (startAgent === void 0) {
-      await awaitSpawnLiveness(paneId, opts.name, opts.workstream, command);
+      await awaitSpawnLiveness(paneId, opts.name, command);
     } else {
       await startAgent({ paneId, name: opts.name, cli, command, commandSource });
     }
@@ -4510,7 +4481,7 @@ function detectSpawnStartupError(scrollback) {
   }
   return void 0;
 }
-async function awaitSpawnLiveness(paneId, agentName, workstreamName, command) {
+async function awaitSpawnLiveness(paneId, agentName, command) {
   const ms = defaultSpawnLivenessMs();
   if (ms === 0) return;
   await sleep(ms);
@@ -4525,30 +4496,6 @@ async function awaitSpawnLiveness(paneId, agentName, workstreamName, command) {
       throw new AgentSpawnStartupError(agentName, paneId, matchedLine, scrollback);
     }
   }
-  await awaitSpawnReadiness(paneId, agentName, workstreamName, command);
-}
-function defaultSpawnReadinessMs() {
-  const raw = process.env.MU_SPAWN_READINESS_MS;
-  if (raw === void 0) return 1e4;
-  const parsed = Number.parseInt(raw, 10);
-  if (Number.isNaN(parsed) || parsed < 0) return 1e4;
-  return parsed;
-}
-async function awaitSpawnReadiness(paneId, agentName, workstreamName, command) {
-  const budgetMs = defaultSpawnReadinessMs();
-  if (budgetMs === 0 || !murmurAvailable()) return;
-  const mux = await activeMux();
-  const deadline = Date.now() + budgetMs;
-  const agent = { name: agentName, workstreamName, paneId };
-  while (Date.now() < deadline) {
-    if (!await mux.paneExists(paneId)) {
-      const scrollback = await mux.capturePane(paneId, { lines: 50 }).catch(() => void 0);
-      throw new AgentDiedOnSpawnError(agentName, paneId, scrollback, command);
-    }
-    const reading = (await readAgentStates([agent])).get(agentKey(agent));
-    if (reading?.source === "murmur") return;
-    await sleep(Math.min(READINESS_POLL_INTERVAL_MS, Math.max(0, deadline - Date.now())));
-  }
 }
 async function createOrReusePane(opts) {
   const mux = await activeMux();
@@ -4594,11 +4541,10 @@ async function firstPaneInWindow(mux, session, windowId) {
   }
   return pane.paneId;
 }
-var AGENT_NAME_CONVENTION_RE, execFileP, activeCommandResolver, CTL_POLL_INTERVAL_MS, STARTUP_ERROR_PATTERNS, STARTUP_ERROR_TAIL_LINES, READINESS_POLL_INTERVAL_MS;
+var AGENT_NAME_CONVENTION_RE, execFileP, activeCommandResolver, CTL_POLL_INTERVAL_MS, STARTUP_ERROR_PATTERNS, STARTUP_ERROR_TAIL_LINES;
 var init_spawn = __esm({
   "src/agents/spawn.ts"() {
     "use strict";
-    init_agent_state();
     init_agents();
     init_client();
     init_path();
@@ -4644,12 +4590,11 @@ var init_spawn = __esm({
       /^(?:.*: )?(?:command not found|No such file or directory)(?::\s*\S+)?$/i
     ];
     STARTUP_ERROR_TAIL_LINES = 30;
-    READINESS_POLL_INTERVAL_MS = 250;
   }
 });
 
 // src/agents/errors.ts
-var AgentSpawnCliNotFoundError, AgentExistsError, AgentNotFoundError, AgentNotInWorkstreamError, AgentDiedOnSpawnError, AgentSpawnStartupError, WorkspacePreservedError, AgentCtlUnreachableError, AgentAbortNeedsCtlError, AgentAbortTimeoutError, AgentFreshNeedsCtlError, AgentExtensionOutdatedError, AgentBusyError;
+var AgentSpawnCliNotFoundError, AgentExistsError, AgentNotFoundError, AgentNotInWorkstreamError, AgentDiedOnSpawnError, AgentSpawnStartupError, WorkspacePreservedError, AgentCtlUnreachableError, AgentAbortNeedsCtlError, AgentAbortTimeoutError, AgentFreshNeedsCtlError, AgentExtensionOutdatedError, AgentBusyError, AgentSlashCommandUnsupportedError;
 var init_errors = __esm({
   "src/agents/errors.ts"() {
     "use strict";
@@ -5029,23 +4974,47 @@ ${scrollback.trim()}
       }
     };
     AgentBusyError = class extends Error {
-      constructor(agentName, workstream) {
-        super(`agent ${agentName} is busy: --fresh would abandon its running turn`);
+      constructor(agentName, workstream, command) {
+        super(`agent ${agentName} is busy: ${command ?? "--fresh"} would abandon its running turn`);
         this.agentName = agentName;
         this.workstream = workstream;
+        this.command = command;
       }
       agentName;
       workstream;
+      command;
       name = "AgentBusyError";
       errorNextSteps() {
+        const retry = this.command === void 0 ? `mu agent send ${this.agentName} --fresh --force '...' -w ${this.workstream}` : `mu agent send ${this.agentName} '${this.command}' --force -w ${this.workstream}`;
         return [
           {
             intent: "Stop the turn first, then retry",
             command: `mu agent abort ${this.agentName} -w ${this.workstream}`
           },
+          { intent: "Or abandon the turn in one step", command: retry }
+        ];
+      }
+    };
+    AgentSlashCommandUnsupportedError = class extends Error {
+      constructor(agentName, workstream, text2, supported) {
+        super(
+          `agent ${agentName} runs pi: over the control socket mu runs only ${supported.join(", ")}; ${JSON.stringify(text2.split("\n")[0])} is not one of them. Pass --via mux to type it into the pane`
+        );
+        this.agentName = agentName;
+        this.workstream = workstream;
+        this.text = text2;
+        this.supported = supported;
+      }
+      agentName;
+      workstream;
+      text;
+      supported;
+      name = "AgentSlashCommandUnsupportedError";
+      errorNextSteps() {
+        return [
           {
-            intent: "Or abandon the turn in one step",
-            command: `mu agent send ${this.agentName} --fresh --force '...' -w ${this.workstream}`
+            intent: "Type it into the pane on purpose (tmux paste; unconfirmed)",
+            command: `mu agent send ${this.agentName} '${this.text.split("\n")[0]}' --via mux -w ${this.workstream}`
           }
         ];
       }
@@ -5062,10 +5031,21 @@ function agentCtlSocket(db, agent) {
 function expectsCtl(agent, sock = ctlSocketPath(agent.workstreamName, agent.name)) {
   return speaksMuCtl(agent.cli, resolveCliCommand(agent.cli)) || existsSync7(sock);
 }
-function chooseTransport(agent, text2, sock) {
-  if (text2.startsWith("/")) return "mux";
+function chooseTransport(agent, sock) {
   return expectsCtl(agent, sock) ? "ctl" : "mux";
 }
+function parseSessionCommand(text2) {
+  const t = text2.trim();
+  if (t === "/new") return { name: "new" };
+  if (t === "/reload") return { name: "reload" };
+  const m = /^\/compact(?:\s+([\s\S]*))?$/.exec(t);
+  if (!m) return void 0;
+  const instructions = m[1]?.trim();
+  return instructions ? { name: "compact", instructions } : { name: "compact" };
+}
+function isSlashCommand(text2) {
+  return /^\/[A-Za-z][\w:-]*(?:\s|$)/.test(text2.trimStart());
+}
 async function extensionOutdated(agent, sock, e) {
   let extVersion;
   try {
@@ -5094,11 +5074,23 @@ async function sendViaTransport(agent, text2, opts) {
   if (opts.fresh && (opts.via === "mux" || !expectsCtl(agent, sock))) {
     throw new AgentFreshNeedsCtlError(agent.name, agent.workstreamName, agent.cli);
   }
-  const transport = opts.fresh ? "ctl" : opts.via ?? chooseTransport(agent, text2, sock);
+  const transport = opts.fresh ? "ctl" : opts.via ?? chooseTransport(agent, sock);
   if (transport === "mux") {
     await (await activeMux()).sendToPane(agent.paneId, text2, opts);
     return { transport };
   }
+  if (!opts.fresh) {
+    const cmd = parseSessionCommand(text2);
+    if (cmd) return runSessionCommand(agent, sock, cmd, opts.force === true);
+    if (isSlashCommand(text2)) {
+      throw new AgentSlashCommandUnsupportedError(
+        agent.name,
+        agent.workstreamName,
+        text2,
+        CTL_SLASH_COMMANDS
+      );
+    }
+  }
   const reply = await ctlRequestFor(
     agent,
     sock,
@@ -5112,14 +5104,36 @@ async function sendViaTransport(agent, text2, opts) {
   }
   return reply.state === void 0 ? { transport } : { transport, state: reply.state };
 }
+async function runSessionCommand(agent, sock, cmd, force) {
+  const reply = await ctlRequestFor(agent, sock, {
+    op: "command",
+    name: cmd.name,
+    ...cmd.instructions !== void 0 ? { instructions: cmd.instructions } : {},
+    ...force ? { force: true } : {}
+  });
+  if (!reply.ok) {
+    if (reply.error === "busy") {
+      throw new AgentBusyError(agent.name, agent.workstreamName, `/${cmd.name}`);
+    }
+    throw new Error(`pi refused /${cmd.name}: ${reply.error}`);
+  }
+  return {
+    transport: "ctl",
+    command: cmd.name,
+    ...reply.state !== void 0 ? { state: reply.state } : {}
+  };
+}
+var CTL_SLASH_COMMANDS;
 var init_transport = __esm({
   "src/agents/transport.ts"() {
     "use strict";
     init_client();
     init_path();
+    init_protocol();
     init_mux2();
     init_errors();
     init_spawn();
+    CTL_SLASH_COMMANDS = CTL_COMMANDS.map((n) => `/${n}`);
   }
 });
 
@@ -9597,6 +9611,15 @@ function murmurDoctorCheck(agentStateSource, opts = {}) {
     detail: version === null ? "agent state from murmur" : `agent state from murmur ${version}`
   };
 }
+function extFeatures(env) {
+  const features = [
+    ["mu_delegate", "MU_DELEGATE"],
+    ["nudge", "MU_NUDGE"]
+  ];
+  const on = ["ctl", ...features.filter(([, v]) => env[v] !== "0").map(([f]) => f)];
+  const off = features.filter(([, v]) => env[v] === "0").map(([f, v]) => `${f} disabled by ${v}=0`);
+  return `(${on.join(", ")}${off.length ? `; ${off.join("; ")}` : ""})`;
+}
 function ctlExtensionDoctorCheck(opts) {
   const { extension } = inspectLinks(opts);
   switch (extension.state) {
@@ -9604,7 +9627,7 @@ function ctlExtensionDoctorCheck(opts) {
       return {
         name: "mu ext",
         status: "ok",
-        detail: process.env.MU_DELEGATE === "0" ? "(ctl; mu_delegate disabled by MU_DELEGATE=0)" : "(ctl, mu_delegate)"
+        detail: extFeatures(process.env)
       };
     case "stale-copy":
       return { name: "mu ext", status: "warn", detail: `stale copy: ${RELINK}` };
@@ -20117,7 +20140,9 @@ function parseVia(raw) {
 }
 async function cmdSend(db, rawName, text2, opts = {}) {
   const via = parseVia(opts.via);
-  if (opts.force && !opts.fresh) throw new UsageError("--force only applies with --fresh");
+  if (opts.force && !opts.fresh && parseSessionCommand(text2) === void 0) {
+    throw new UsageError("--force only applies with --fresh or a /new, /reload, /compact");
+  }
   if (opts.fresh && opts.steer) throw new UsageError("--fresh and --steer are mutually exclusive");
   const { name } = await resolveEntityRef(db, rawName, opts, "agent");
   assertAgentInWorkstream(db, name, opts.workstream);
@@ -20127,7 +20152,7 @@ async function cmdSend(db, rawName, text2, opts = {}) {
   });
   let undelivered;
   const agentRow = getAgent(db, name, ws);
-  const plainCtl = agentRow !== void 0 && !opts.fresh && !opts.steer && (via ?? chooseTransport(agentRow, text2, agentCtlSocket(db, agentRow))) === "ctl";
+  const plainCtl = agentRow !== void 0 && !opts.fresh && !opts.steer && parseSessionCommand(text2) === void 0 && (via ?? chooseTransport(agentRow, agentCtlSocket(db, agentRow))) === "ctl";
   const before = plainCtl && agentRow !== void 0 ? await ctlProbe(agentCtlSocket(db, agentRow)) : void 0;
   const sent = await sendToAgent(db, name, text2, {
     workstream: ws,
@@ -20161,6 +20186,7 @@ async function cmdSend(db, rawName, text2, opts = {}) {
       sentBytes: text2.length,
       transport: sent.transport,
       fresh: opts.fresh === true,
+      ...sent.command !== void 0 ? { command: sent.command } : {},
       ...sent.state !== void 0 ? { state: sent.state } : {},
       delivered: undelivered === void 0,
       ...undelivered !== void 0 ? { undelivered: { reason: undelivered.reason, message: undelivered.message } } : {},
@@ -20172,7 +20198,7 @@ async function cmdSend(db, rawName, text2, opts = {}) {
   if (undelivered !== void 0) {
     console.error(pc.yellow(`warning: ${undelivered.message}`));
   } else {
-    const how = sent.transport === "mux" ? "via mux paste" : opts.fresh ? "via ctl, fresh session" : `via ctl, pi ${sent.state ?? "?"}`;
+    const how = sent.transport === "mux" ? "via mux paste" : opts.fresh ? "via ctl, fresh session" : sent.command !== void 0 ? `via ctl, pi ran /${sent.command}` : `via ctl, pi ${sent.state ?? "?"}`;
     console.log(pc.dim(`sent ${text2.length} bytes to ${name} (${how})`));
   }
   printNextSteps(nextSteps3);
@@ -20613,14 +20639,17 @@ function wireAgentCommands(program) {
     return handle((db) => cmdSpawn(db, name, opts), this)();
   });
   agent.command("send <name> <text>").description(
-    "Send text to an agent. pi agents: through the control socket (fails loud if it does not answer; no paste fallback). Non-pi CLIs and text starting with '/' (slash commands such as /new): pasted into the pane (atomic on herdr; bracketed-paste on tmux). --fresh (pi only): start a new session and send the text into it as one operation; returns once the prompt's run has started, so an immediate next send cannot be lost. Use it instead of sending '/new' then the prompt"
+    "Send text to an agent. pi agents: through the control socket (fails loud if it does not answer; no paste fallback); '/new', '/reload' and '/compact [instructions]' run inside pi over the socket (refused while busy unless --force), any other slash command is refused (--via mux types it into the pane). Non-pi CLIs: pasted into the pane (atomic on herdr; bracketed-paste on tmux). --fresh (pi only): start a new session and send the text into it as one operation; returns once the prompt's run has started, so an immediate next send cannot be lost. Use it instead of sending '/new' then the prompt"
   ).option(
     "--strict-staleness",
     "refuse send when the target agent's workspace is stale (default: warn and proceed)"
   ).option("--steer", "if pi is busy, interrupt the current run (default: queue as a follow-up)").option("--via <transport>", "force the transport: ctl or mux (mux = paste into the pane)").option(
     "--fresh",
     "pi only: new session + this prompt, one operation (refused with exit 4 while pi is busy)"
-  ).option("--force", "with --fresh: abandon a running turn instead of refusing").option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(name, text2) {
+  ).option(
+    "--force",
+    "with --fresh or a pi /new, /reload, /compact: abandon a running turn instead of refusing"
+  ).option(...WORKSTREAM_OPT).option(...JSON_OPT).action(function(name, text2) {
     const opts = this.opts();
     return handle((db) => cmdSend(db, name, text2, opts), this)();
   });
@@ -21348,7 +21377,8 @@ var NameAmbiguousError = class extends Error {
 function classifyError(err) {
   if (err instanceof UsageError || // abort on a non-pi agent: the operator picked the wrong verb (kick).
   err instanceof AgentAbortNeedsCtlError || // send --fresh on an agent with no control socket: wrong recipe.
-  err instanceof AgentFreshNeedsCtlError || err instanceof WorkstreamNameInvalidError || err instanceof WorkstreamNameReservedError || // The operator asked the ACTIVE backend for something it cannot do:
+  err instanceof AgentFreshNeedsCtlError || // an unsupported slash command to a pi agent: --via mux is the recipe.
+  err instanceof AgentSlashCommandUnsupportedError || err instanceof WorkstreamNameInvalidError || err instanceof WorkstreamNameReservedError || // The operator asked the ACTIVE backend for something it cannot do:
   // a `--cli` the mux does not recognise as an agent kind, or a
   // `--command` / `MU_<CLI>_COMMAND` override it cannot honour. The
   // substrate is healthy and answered precisely, so this is the usage