@mutagent/cli 0.1.282 → 0.1.284

package/dist/bin/cli.js

@@ -884,7 +884,7 @@ var init_sdk_client = __esm(() => {
 
 // src/bin/cli.ts
 import { Command as Command15 } from "commander";
-import chalk28 from "chalk";
+import chalk29 from "chalk";
 import { readFileSync as readFileSync12 } from "fs";
 import { join as join14, dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -6122,7 +6122,7 @@ If mutagent-cli is not installed: mutagent install helix`), isJson);
 
 // src/commands/helix/index.ts
 import { Command as Command14 } from "commander";
-import chalk27 from "chalk";
+import chalk28 from "chalk";
 
 // src/commands/helix/spawn.ts
 import chalk21 from "chalk";
@@ -6415,6 +6415,13 @@ async function postInput(id, body) {
     sandboxId: id
   });
 }
+async function postSignal(id, body) {
+  return requestJson(`/api/sandbox/${encodeURIComponent(id)}/signal`, {
+    method: "POST",
+    body: JSON.stringify(body),
+    sandboxId: id
+  });
+}
 async function startSession(id, body) {
   return requestJson(`/api/sandbox/${encodeURIComponent(id)}/session`, {
     method: "POST",
@@ -7582,22 +7589,112 @@ function readType(raw) {
   return "raw";
 }
 
+// src/commands/helix/signal.ts
+import chalk24 from "chalk";
+init_errors();
+var SIGNAL_TYPES = ["SIGINT", "SIGTERM"];
+var DEFAULT_SIGNAL = "SIGINT";
+function registerSignalCommand(parent) {
+  parent.command("signal").description("Stop a running session, leaving its sandbox up").argument("<id>", "Sandbox ID").requiredOption("--session <id>", "Session ID inside the sandbox").option("--type <signal>", `${SIGNAL_TYPES.join(" | ")} (default: ${DEFAULT_SIGNAL})`).addHelpText("after", `
+Examples:
+  ${chalk24.dim("$")} mutagent helix signal sbx_123 --session s1                    ${chalk24.dim("SIGINT — like Ctrl-C")}
+  ${chalk24.dim("$")} mutagent helix signal sbx_123 --session s1 --type SIGTERM     ${chalk24.dim("Ask it to shut down")}
+  ${chalk24.dim("$")} mutagent helix signal sbx_123 --session s1 --json
+
+THE SANDBOX SURVIVES. This stops the SESSION — the agent process — and leaves
+the box, its filesystem and its event log exactly where they are, so you can
+attach, exec against it, or read what the agent did before you stopped it.
+'mutagent helix rm <id>' is still the only thing that destroys a sandbox.
+
+THREE WAYS TO STOP AN AGENT, WEAKEST FIRST:
+  ${chalk24.bold("send --type abort")}  Asks the agent to end the turn. Needs a cooperating agent
+                     that is still reading its stdin. Try this first.
+  ${chalk24.bold("signal")}             Does not ask. Reaches a wedged or looping process.
+                     The session ends; the box stays.
+  ${chalk24.bold("rm")}                 Destroys the sandbox and everything in it.
+
+THE SIGNALS:
+  SIGINT    Interrupts the current turn, the way Ctrl-C does in a local terminal.
+  SIGTERM   Asks the process to shut down.
+SIGKILL is not accepted: it would end the session before it could flush the
+output you came back to read.
+
+A 200 here means a LIVE process was signalled — not just that the request was
+understood. A session that had already finished is reported as such rather than
+being counted as a success, so this never tells you that you stopped an agent
+that had in fact been done for a while.
+
+'mutagent helix ls' shows which sandboxes are up; 'mutagent helix attach <id>'
+shows what the session was doing.
+
+AI Agent Directive:
+  --json returns ONE object: { success, sandboxId, sessionId, signal, signalled,
+  _links }. 'signalled' is an EFFECT, not an acknowledgement — it is true only
+  when a running process was actually stopped.
+  A session that has already ended exits non-zero rather than reporting success.
+  Treat that as information, not as a failure to retry: the agent is already
+  stopped, which is what you wanted.
+  This does NOT destroy the sandbox. It stays billable until 'mutagent helix rm
+  <id>'. Confirm with the user before that.
+      `).action(async (id, options) => {
+    const isJson = getJsonFlag(parent);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const sessionId = options.session?.trim() ?? "";
+      if (sessionId === "") {
+        throw new MutagentError("MISSING_ARGUMENTS", "--session is required — a sandbox can hold more than one session.", `Run: mutagent helix signal ${id} --session <session-id>`);
+      }
+      const signal = resolveSignal(options.type);
+      const result = await postSignal(id, { sessionId, signal });
+      if (isJson) {
+        output.output({
+          success: true,
+          sandboxId: id,
+          sessionId,
+          signal,
+          signalled: result.signalled,
+          _links: sandboxLinks(id),
+          _directive: {
+            instruction: "The session was stopped. The SANDBOX is still running and still billable — remove it explicitly when you are done with it.",
+            next: [`mutagent helix attach ${id} --json`, `mutagent helix rm ${id}`]
+          }
+        });
+        return;
+      }
+      output.success(`Sent ${signal} to session ${sessionId}`);
+      console.error(chalk24.dim(`  The sandbox is still up: mutagent helix attach ${id}`));
+      console.error(chalk24.dim(`  Destroy it with: mutagent helix rm ${id}`));
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+function resolveSignal(raw) {
+  if (raw === undefined)
+    return DEFAULT_SIGNAL;
+  const normalised = raw.trim().toUpperCase();
+  if (!SIGNAL_TYPES.includes(normalised)) {
+    throw new MutagentError("INVALID_ARGUMENTS", `Unknown signal "${raw}".`, `Use one of: ${SIGNAL_TYPES.join(", ")}. SIGKILL is not accepted — it would end the session before it could flush its output.`);
+  }
+  return normalised;
+}
+
 // src/commands/helix/session-start.ts
 import { Command as Command13 } from "commander";
-import chalk24 from "chalk";
+import chalk25 from "chalk";
 init_errors();
 function registerSessionCommand(parent) {
   const session = new Command13("session").description("Start and inspect Helix sessions inside a sandbox").addHelpText("after", `
 Examples:
-  ${chalk24.dim("$")} mutagent helix session start sbx_123 --rpc
-  ${chalk24.dim("$")} mutagent helix session start sbx_123
-  ${chalk24.dim("$")} mutagent helix session start sbx_123 --rpc --json
+  ${chalk25.dim("$")} mutagent helix session start sbx_123 --rpc
+  ${chalk25.dim("$")} mutagent helix session start sbx_123
+  ${chalk25.dim("$")} mutagent helix session start sbx_123 --rpc --json
 
 A sandbox and a session are not the same thing:
-  ${chalk24.bold("spawn")}          gives you a BOX — a machine with nothing running in it.
-  ${chalk24.bold("session start")}  gives you an AGENT inside that box.
-  ${chalk24.bold("attach")}         WATCHES that agent.
-  ${chalk24.bold("send")}           TYPES INTO it.
+  ${chalk25.bold("spawn")}          gives you a BOX — a machine with nothing running in it.
+  ${chalk25.bold("session start")}  gives you an AGENT inside that box.
+  ${chalk25.bold("attach")}         WATCHES that agent.
+  ${chalk25.bold("send")}           TYPES INTO it.
 A box with no session is a normal state — that is what 'exec' runs against.
 
 AI Agent Directive:
@@ -7610,15 +7707,15 @@ AI Agent Directive:
 function registerStart(session, root) {
   session.command("start").description("Start a Helix session inside an existing sandbox").argument("<id>", "Sandbox ID").option("--rpc", "Long-lived session you can send into (default: one-shot)").addHelpText("after", `
 Examples:
-  ${chalk24.dim("$")} mutagent helix session start sbx_123 --rpc
-  ${chalk24.dim("$")} mutagent helix session start sbx_123
-  ${chalk24.dim("$")} mutagent helix session start sbx_123 --rpc --json
+  ${chalk25.dim("$")} mutagent helix session start sbx_123 --rpc
+  ${chalk25.dim("$")} mutagent helix session start sbx_123
+  ${chalk25.dim("$")} mutagent helix session start sbx_123 --rpc --json
 
 TWO MODES, AND ONLY ONE OF THEM LISTENS:
-  ${chalk24.bold("--rpc")}      A long-lived agent reading commands on its stdin. This is
+  ${chalk25.bold("--rpc")}      A long-lived agent reading commands on its stdin. This is
              the mode 'mutagent helix send' writes into; without it there
              is nothing to write to and every send is refused.
-  ${chalk24.dim("(default)")}  One-shot. The session takes its turn and ends. Watchable
+  ${chalk25.dim("(default)")}  One-shot. The session takes its turn and ends. Watchable
              with 'attach', not steerable.
 
 The box must already exist — 'mutagent helix spawn --image <ref>' makes one, and
@@ -7660,9 +7757,9 @@ AI Agent Directive:
         return;
       }
       output.success(`Session ${sessionId} started in ${id} (${mode})`);
-      console.error(chalk24.dim(`  Watch it:   mutagent helix attach ${id}`));
+      console.error(chalk25.dim(`  Watch it:   mutagent helix attach ${id}`));
       if (mode === "rpc") {
-        console.error(chalk24.dim(`  Talk to it: mutagent helix send ${id} --session ${sessionId} "<message>"`));
+        console.error(chalk25.dim(`  Talk to it: mutagent helix send ${id} --session ${sessionId} "<message>"`));
       }
     } catch (error) {
       handleError(error, isJson);
@@ -7676,15 +7773,32 @@ function requireSessionId(result, sandboxId) {
 }
 
 // src/commands/helix/run.ts
-import chalk25 from "chalk";
+import chalk26 from "chalk";
 init_errors();
 function registerRunCommand(parent) {
-  parent.command("run").description("Run one Helix agent turn in a fresh sandbox").argument("<task...>", "WHAT to do this turn").requiredOption("--prompt <definition>", "WHO the agent is — the agent definition").option("--preset <name>", "Preset to run on (default: the backend default)").option("--keep", "Keep the sandbox afterwards instead of tearing it down").option("--timeout-ms <n>", "Per-command timeout in milliseconds").option("--no-stream", "Wait for the whole turn instead of watching it happen").addHelpText("after", `
+  parent.command("run").alias("agent").description("Run one Helix agent turn in a fresh sandbox (alias: agent)").argument("<task...>", "WHAT to do this turn").requiredOption("--prompt <definition>", "WHO the agent is — the agent definition").option("--preset <name>", "Preset to run on (default: the backend default)").option("--keep", "Keep the sandbox afterwards instead of tearing it down").option("--timeout-ms <n>", "Per-command timeout in milliseconds").option("--no-stream", "Wait for the whole turn instead of watching it happen").option("--prime", "Run on the leaner ASPS-Prime scaffold (the binary's --prime)").addHelpText("after", `
 Examples:
-  ${chalk25.dim("$")} mutagent helix run "summarise the failing tests" --prompt "You are a test triage agent."
-  ${chalk25.dim("$")} mutagent helix run fix the flaky login spec --prompt "$(cat agent.md)"
-  ${chalk25.dim("$")} mutagent helix run "list open PRs" --prompt "You are a release assistant." --json
-  ${chalk25.dim("$")} mutagent helix run "explore the repo" --prompt "$(cat agent.md)" --keep
+  ${chalk26.dim("$")} mutagent helix run "summarise the failing tests" --prompt "You are a test triage agent."
+  ${chalk26.dim("$")} mutagent helix run fix the flaky login spec --prompt "$(cat agent.md)"
+  ${chalk26.dim("$")} mutagent helix run "list open PRs" --prompt "You are a release assistant." --json
+  ${chalk26.dim("$")} mutagent helix run "explore the repo" --prompt "$(cat agent.md)" --keep
+
+--prime — THE SAME FLAG THE LOCAL BINARY TAKES:
+  'helix agent --prime' locally and 'mutagent helix run --prime' in the cloud
+  select the same thing: the ASPS-Prime scaffold, a leaner code-first arm with
+  no orchestrator persona, no skills and no sub-agent crew. It is forwarded to
+  the binary as argv rather than interpreted by the server, so it means exactly
+  what the binary's own --help says it means. This is NOT a speed setting — it
+  changes which agent takes the turn.
+
+SAME COMMAND, TWO NAMES:
+  'mutagent helix agent' is an ALIAS of 'mutagent helix run'. Not a variant, not
+  a shorthand with different defaults — the same command, the same flags, the
+  same behaviour. It exists so the verb that works against the local binary
+  ('helix agent --prompt "..." "task"') also works against the cloud.
+  RUN is the canonical name: it is what the docs, the JSON output and the error
+  messages use. 'agent' is there so a caller who learned the local CLI does not
+  have to learn a second word for the same operation.
 
 TWO PROMPTS, AND THEY ARE NOT THE SAME THING:
   --prompt   WHO the agent is — its definition, its standing instructions.
@@ -7719,6 +7833,11 @@ AI Agent Directive:
   is a complete summary object, so '| tail -1' still yields one object. Same
   convention as 'mutagent helix exec'.
   Both --prompt and the task are required; do not fold one into the other.
+  'mutagent helix agent' and 'mutagent helix run' are THE SAME COMMAND. Prefer
+  'run' in anything you write down; 'agent' exists for parity with the local
+  'helix agent' verb.
+  --prime selects the binary's leaner scaffold. Omit it unless the user asked
+  for it; it is not a performance flag, it changes which agent runs.
       `).action(async (taskParts, options) => {
     const isJson = getJsonFlag(parent);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -7735,6 +7854,7 @@ AI Agent Directive:
       const body = {
         prompt,
         task,
+        ...options.prime === true ? { prime: true } : {},
         ...oneShotFields(options.preset, options.keep, options.timeoutMs)
       };
       if (options.stream === false) {
@@ -7791,17 +7911,17 @@ async function streamAgentTurn(body, isJson, keep) {
 function registerExecCommand(parent) {
   parent.command("exec").description("Run a command in a sandbox — an existing one, or a fresh one").argument("<argv...>", "Command and arguments (argv, not a shell string)").option("--sandbox <id>", "Run in this existing sandbox instead of a fresh one").option("--preset <name>", "Preset for the fresh sandbox (ignored with --sandbox)").option("--keep", "Keep the fresh sandbox afterwards (ignored with --sandbox)").option("--cwd <dir>", "Working directory inside the sandbox").option("--timeout-ms <n>", "Command timeout in milliseconds").option("--no-stream", "Wait for the full result instead of streaming it").addHelpText("after", `
 Examples:
-  ${chalk25.dim("$")} mutagent helix exec -- ls -la /workspace
-  ${chalk25.dim("$")} mutagent helix exec --sandbox sbx_123 -- bun test
-  ${chalk25.dim("$")} mutagent helix exec --sandbox sbx_123 --cwd /src -- git status
-  ${chalk25.dim("$")} mutagent helix exec --preset default -- uname -m --json
+  ${chalk26.dim("$")} mutagent helix exec -- ls -la /workspace
+  ${chalk26.dim("$")} mutagent helix exec --sandbox sbx_123 -- bun test
+  ${chalk26.dim("$")} mutagent helix exec --sandbox sbx_123 --cwd /src -- git status
+  ${chalk26.dim("$")} mutagent helix exec --preset default -- uname -m --json
 
-Put ${chalk25.bold("--")} before the command. Everything after it is argv and is passed through
+Put ${chalk26.bold("--")} before the command. Everything after it is argv and is passed through
 untouched, so flags meant for your command are not read as flags for this one.
 
 ARGV, NOT A SHELL STRING. There is no shell in the sandbox unless you name one:
-  ${chalk25.dim("$")} mutagent helix exec -- sh -c 'ls | wc -l'      ${chalk25.dim("a shell, explicitly")}
-  ${chalk25.dim("$")} mutagent helix exec -- 'ls | wc -l'            ${chalk25.dim("looks for a file called 'ls | wc -l'")}
+  ${chalk26.dim("$")} mutagent helix exec -- sh -c 'ls | wc -l'      ${chalk26.dim("a shell, explicitly")}
+  ${chalk26.dim("$")} mutagent helix exec -- 'ls | wc -l'            ${chalk26.dim("looks for a file called 'ls | wc -l'")}
 
 WITH --sandbox    runs in that box and streams as output is produced.
 WITHOUT --sandbox spawns a fresh box from a preset, runs, tears it down. That
@@ -7933,17 +8053,17 @@ function reportResult(result, output, isJson, context) {
 }
 
 // src/commands/helix/inventory.ts
-import chalk26 from "chalk";
+import chalk27 from "chalk";
 init_errors();
 function registerLsCommand(parent) {
   parent.command("ls").description("List your sandboxes").addHelpText("after", `
 Examples:
-  ${chalk26.dim("$")} mutagent helix ls
-  ${chalk26.dim("$")} mutagent helix ls --json
+  ${chalk27.dim("$")} mutagent helix ls
+  ${chalk27.dim("$")} mutagent helix ls --json
 
 Listing is always workspace-scoped — these are the sandboxes in the workspace
 you are configured for, not every sandbox on the account. Change it with:
-  ${chalk26.dim("$")} mutagent config set workspace <workspace-id>
+  ${chalk27.dim("$")} mutagent config set workspace <workspace-id>
 
 An empty list is a normal result, not an error: it means no sandbox is running.
 
@@ -7963,7 +8083,7 @@ AI Agent Directive:
         return;
       }
       if (sandboxes.length === 0) {
-        console.log(chalk26.gray("No sandboxes running."));
+        console.log(chalk27.gray("No sandboxes running."));
         console.log("");
         console.log("  Start one: mutagent helix spawn --image <ref>");
         return;
@@ -7987,8 +8107,8 @@ function toRow(sandbox) {
 function registerPresetsCommand(parent) {
   parent.command("presets").description("List the presets a one-shot run can name").addHelpText("after", `
 Examples:
-  ${chalk26.dim("$")} mutagent helix presets
-  ${chalk26.dim("$")} mutagent helix presets --json
+  ${chalk27.dim("$")} mutagent helix presets
+  ${chalk27.dim("$")} mutagent helix presets --json
 
 A preset is a named definition on the backend. It is what lets 'helix run' and
 'helix exec' start something without you knowing an image reference, a registry
@@ -8009,7 +8129,7 @@ AI Agent Directive:
         return;
       }
       if (presets.length === 0) {
-        console.log(chalk26.gray("No presets configured on this backend."));
+        console.log(chalk27.gray("No presets configured on this backend."));
         console.log("");
         console.log("  Spawn with an explicit image: mutagent helix spawn --image <ref>");
         return;
@@ -8029,15 +8149,15 @@ AI Agent Directive:
 function registerRmCommand(parent) {
   parent.command("rm").description("Destroy a sandbox").argument("<id>", "Sandbox ID").option("-f, --force", "Skip confirmation").addHelpText("after", `
 Examples:
-  ${chalk26.dim("$")} mutagent helix rm sbx_123 --force
-  ${chalk26.dim("$")} mutagent helix rm sbx_123 --json
+  ${chalk27.dim("$")} mutagent helix rm sbx_123 --force
+  ${chalk27.dim("$")} mutagent helix rm sbx_123 --json
 
 This is the ONLY command that destroys a sandbox — detaching, Ctrl-C and a
 closed terminal all leave it running. Removing a sandbox that is already gone
 succeeds, so a retried teardown is safe.
 
-${chalk26.dim("Note: --force is required. The CLI is non-interactive — confirm with the user via your native flow, then pass --force. --json auto-confirms.")}
-${chalk26.dim("Warning: any session running in the sandbox ends immediately and cannot be recovered.")}
+${chalk27.dim("Note: --force is required. The CLI is non-interactive — confirm with the user via your native flow, then pass --force. --json auto-confirms.")}
+${chalk27.dim("Warning: any session running in the sandbox ends immediately and cannot be recovered.")}
 
 AI Agent Directive:
   Destroying a sandbox ends any session running in it and cannot be undone.
@@ -8072,8 +8192,8 @@ Use --force to confirm: mutagent helix rm ${id} --force`);
 function registerTracesCommand(parent) {
   parent.command("traces").description("Show the spans captured for a sandbox").argument("<id>", "Sandbox ID").addHelpText("after", `
 Examples:
-  ${chalk26.dim("$")} mutagent helix traces sbx_123
-  ${chalk26.dim("$")} mutagent helix traces sbx_123 --json
+  ${chalk27.dim("$")} mutagent helix traces sbx_123
+  ${chalk27.dim("$")} mutagent helix traces sbx_123 --json
 
 Spans are what the session actually did — the record to read when the output
 alone does not explain the result. They are called spans, not traces, because
@@ -8097,7 +8217,7 @@ AI Agent Directive:
         return;
       }
       if (spans.length === 0) {
-        console.log(chalk26.gray(`No spans captured for sandbox ${id}.`));
+        console.log(chalk27.gray(`No spans captured for sandbox ${id}.`));
         return;
       }
       output.output(spans.map((span) => {
@@ -8119,43 +8239,49 @@ AI Agent Directive:
 function createHelixCommand() {
   const helix = new Command14("helix").description("Run Helix sessions in a cloud sandbox").addHelpText("after", `
 Examples:
-  ${chalk27.dim("$")} mutagent helix run "fix the failing test" --prompt "$(cat agent.md)"
-  ${chalk27.dim("$")} mutagent helix exec -- uname -m                 ${chalk27.dim("One command, fresh box")}
-  ${chalk27.dim("$")} mutagent helix presets                          ${chalk27.dim("What a one-shot can run on")}
-  ${chalk27.dim("$")} mutagent helix spawn --image alpine:3.20        ${chalk27.dim("Persistent box, then attach")}
-  ${chalk27.dim("$")} mutagent helix session start sbx_1 --rpc        ${chalk27.dim("Start an agent inside that box")}
-  ${chalk27.dim("$")} mutagent helix ls                               ${chalk27.dim("What is running")}
-  ${chalk27.dim("$")} mutagent helix exec --sandbox sbx_1 -- bun test ${chalk27.dim("Command in that box")}
-  ${chalk27.dim("$")} mutagent helix attach sbx_1 --since 412         ${chalk27.dim("Resume after a sequence number")}
-  ${chalk27.dim("$")} mutagent helix send sbx_1 --session s1 "and now"  ${chalk27.dim("Talk to a running session")}
-  ${chalk27.dim("$")} mutagent helix traces sbx_1 --json              ${chalk27.dim("What the session actually did")}
-  ${chalk27.dim("$")} mutagent helix rm sbx_1 --force                 ${chalk27.dim("Destroy it")}
+  ${chalk28.dim("$")} mutagent helix run "fix the failing test" --prompt "$(cat agent.md)"
+  ${chalk28.dim("$")} mutagent helix exec -- uname -m                 ${chalk28.dim("One command, fresh box")}
+  ${chalk28.dim("$")} mutagent helix presets                          ${chalk28.dim("What a one-shot can run on")}
+  ${chalk28.dim("$")} mutagent helix spawn --image alpine:3.20        ${chalk28.dim("Persistent box, then attach")}
+  ${chalk28.dim("$")} mutagent helix session start sbx_1 --rpc        ${chalk28.dim("Start an agent inside that box")}
+  ${chalk28.dim("$")} mutagent helix ls                               ${chalk28.dim("What is running")}
+  ${chalk28.dim("$")} mutagent helix exec --sandbox sbx_1 -- bun test ${chalk28.dim("Command in that box")}
+  ${chalk28.dim("$")} mutagent helix attach sbx_1 --since 412         ${chalk28.dim("Resume after a sequence number")}
+  ${chalk28.dim("$")} mutagent helix send sbx_1 --session s1 "and now"  ${chalk28.dim("Talk to a running session")}
+  ${chalk28.dim("$")} mutagent helix signal sbx_1 --session s1        ${chalk28.dim("Stop the agent, keep the box")}
+  ${chalk28.dim("$")} mutagent helix traces sbx_1 --json              ${chalk28.dim("What the session actually did")}
+  ${chalk28.dim("$")} mutagent helix rm sbx_1 --force                 ${chalk28.dim("Destroy it")}
 
 Subcommands:
-  run, exec, spawn, session, ls, presets, attach, send, traces, rm
+  run (alias: agent), exec, spawn, session, ls, presets, attach, send, signal,
+  traces, rm
 
 One-shot vs persistent:
-  ${chalk27.bold("run")} and ${chalk27.bold("exec")} (without --sandbox) start from a named PRESET, do one
+  ${chalk28.bold("run")} and ${chalk28.bold("exec")} (without --sandbox) start from a named PRESET, do one
   thing and tear the sandbox down. Nothing to clean up, no image to know.
-  ${chalk27.bold("spawn")} takes an explicit --image and leaves a box running for you to
-  ${chalk27.bold("attach")} and ${chalk27.bold("exec --sandbox")} against until you ${chalk27.bold("rm")} it.
+  ${chalk28.bold("spawn")} takes an explicit --image and leaves a box running for you to
+  ${chalk28.bold("attach")} and ${chalk28.bold("exec --sandbox")} against until you ${chalk28.bold("rm")} it.
 
 Boxes vs sessions vs watching vs steering:
-  ${chalk27.bold("spawn")} gives you a BOX. ${chalk27.bold("session start")} gives you an AGENT inside that box.
-  ${chalk27.bold("attach")} WATCHES that agent; it does not type into one. ${chalk27.bold("send")} TYPES INTO it,
+  ${chalk28.bold("spawn")} gives you a BOX. ${chalk28.bold("session start")} gives you an AGENT inside that box.
+  ${chalk28.bold("attach")} WATCHES that agent; it does not type into one. ${chalk28.bold("send")} TYPES INTO it,
   from any terminal holding the id — so a session can be redirected without the
   terminal that started it. A box with no session is normal: that is what
-  ${chalk27.bold("exec")} runs against.
+  ${chalk28.bold("exec")} runs against.
+  ${chalk28.bold("signal")} STOPS that agent and leaves the box standing — the remote Ctrl-C.
+  Only ${chalk28.bold("rm")} destroys a sandbox.
 
 Lifecycle:
   A spawned sandbox outlives your terminal. Ctrl-C, a dropped connection and a
   closed terminal all DETACH — the session keeps running and can be re-attached.
+  Stopping the AGENT is a different thing from destroying the BOX: 'signal' does
+  the first, 'rm' does the second.
   Only 'mutagent helix rm <id>' destroys a sandbox, so remember to run it when
   you are finished.
 
 Access:
   Sandbox access is minted per WORKSPACE, so a workspace must be configured:
-  ${chalk27.dim("$")} mutagent config set workspace <workspace-id>
+  ${chalk28.dim("$")} mutagent config set workspace <workspace-id>
 
 Output:
   Sandbox stdout goes to stdout, sandbox stderr goes to stderr, and anything
@@ -8175,6 +8301,9 @@ AI Agent Directive:
   single JSON document until it ends. Everything else returns one JSON object.
   'run' is always blocking: it takes TWO strings, --prompt (WHO the agent is)
   and the task (WHAT to do). Never fold one into the other.
+  'run' and 'agent' are the same command; 'run' is the canonical name.
+  To stop a running agent, prefer 'send --type abort' (asks it to stop), then
+  'signal' (does not ask). Neither destroys the sandbox — only 'rm' does.
   Spawning consumes resources until removed — confirm with the user before
   'spawn' and before 'rm'.
       `);
@@ -8185,6 +8314,7 @@ AI Agent Directive:
   registerPresetsCommand(helix);
   registerAttachCommand(helix);
   registerSendCommand(helix);
+  registerSignalCommand(helix);
   registerSessionCommand(helix);
   registerTracesCommand(helix);
   registerRmCommand(helix);
@@ -8309,61 +8439,61 @@ program.name("mutagent").description(`Mutagent CLI - command-line client for the
 });
 program.addHelpText("beforeAll", () => renderBanner());
 program.addHelpText("after", `
-${chalk28.bold.cyan("WORKFLOWS:")}
-  ${chalk28.bold("Setup")}                mutagent login  →  mutagent init
-  ${chalk28.bold("Lifecycle Tools")}      mutagent install helix  ${chalk28.dim("(login-gated)")}
-  ${chalk28.bold("Feedback")}             mutagent feedback send "<what happened>" --category <cli|helix|stage:<x>>  ${chalk28.dim("[--session <id>] [--attach-transcript]")}
+${chalk29.bold.cyan("WORKFLOWS:")}
+  ${chalk29.bold("Setup")}                mutagent login  →  mutagent init
+  ${chalk29.bold("Lifecycle Tools")}      mutagent install helix  ${chalk29.dim("(login-gated)")}
+  ${chalk29.bold("Feedback")}             mutagent feedback send "<what happened>" --category <cli|helix|stage:<x>>  ${chalk29.dim("[--session <id>] [--attach-transcript]")}
 
-${chalk28.dim("For CLI usage guidance for AI agents, see the Skill at")}
-${chalk28.cyan(".claude/skills/mutagent-cli/SKILL.md")}
+${chalk29.dim("For CLI usage guidance for AI agents, see the Skill at")}
+${chalk29.cyan(".claude/skills/mutagent-cli/SKILL.md")}
 
-${chalk28.yellow("Global flags:")}
-  -v, --version ${chalk28.dim("Print the CLI version")}   ${chalk28.dim("(before a subcommand; after one it is the subcommand's)")}
+${chalk29.yellow("Global flags:")}
+  -v, --version ${chalk29.dim("Print the CLI version")}   ${chalk29.dim("(before a subcommand; after one it is the subcommand's)")}
   --json  --api-key <k>  --endpoint <url>  --non-interactive
 
-${chalk28.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
-  export MUTAGENT_API_KEY=mt_...  ${chalk28.dim("or")}  --api-key mt_...
-  --json ${chalk28.dim("for structured output")}    --non-interactive ${chalk28.dim("to disable prompts")}
+${chalk29.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
+  export MUTAGENT_API_KEY=mt_...  ${chalk29.dim("or")}  --api-key mt_...
+  --json ${chalk29.dim("for structured output")}    --non-interactive ${chalk29.dim("to disable prompts")}
 
-${chalk28.yellow("Command Navigation:")}
-  mutagent login                        ${chalk28.dim("Login (browser OAuth — recommended)")}
-  mutagent auth status                  ${chalk28.dim("Check auth + workspace")}
-  mutagent init                         ${chalk28.dim("Initialize project (.mutagentrc.json)")}
-  mutagent workspaces list --json       ${chalk28.dim("List workspaces (verify ID)")}
-  mutagent config set workspace <id>    ${chalk28.dim("Set active workspace")}
-  mutagent usage --json                 ${chalk28.dim("Show account usage + provider status")}
+${chalk29.yellow("Command Navigation:")}
+  mutagent login                        ${chalk29.dim("Login (browser OAuth — recommended)")}
+  mutagent auth status                  ${chalk29.dim("Check auth + workspace")}
+  mutagent init                         ${chalk29.dim("Initialize project (.mutagentrc.json)")}
+  mutagent workspaces list --json       ${chalk29.dim("List workspaces (verify ID)")}
+  mutagent config set workspace <id>    ${chalk29.dim("Set active workspace")}
+  mutagent usage --json                 ${chalk29.dim("Show account usage + provider status")}
 
-  mutagent providers list --json        ${chalk28.dim("List configured BYOK providers")}
-  mutagent providers list --models      ${chalk28.dim("See available models per provider")}
+  mutagent providers list --json        ${chalk29.dim("List configured BYOK providers")}
+  mutagent providers list --models      ${chalk29.dim("See available models per provider")}
 
-  mutagent helix run "<task>" --prompt "<who>"  ${chalk28.dim("One Helix agent turn in a cloud sandbox")}
-  mutagent helix ls --json              ${chalk28.dim("List running sandboxes")}
-  mutagent helix spawn --image <ref>    ${chalk28.dim("Persistent sandbox you attach to")}
-  mutagent helix rm <id> --force        ${chalk28.dim("Destroy a sandbox (the only thing that does)")}
+  mutagent helix run "<task>" --prompt "<who>"  ${chalk29.dim("One Helix agent turn in a cloud sandbox")}
+  mutagent helix ls --json              ${chalk29.dim("List running sandboxes")}
+  mutagent helix spawn --image <ref>    ${chalk29.dim("Persistent sandbox you attach to")}
+  mutagent helix rm <id> --force        ${chalk29.dim("Destroy a sandbox (the only thing that does)")}
 
-  mutagent install helix                ${chalk28.dim("Install the ADL lifecycle conductor locally (login-gated)")}
-  mutagent install helix --version 1.2.3  ${chalk28.dim("Pin a version")}
-  mutagent install --help               ${chalk28.dim("helix")}
+  mutagent install helix                ${chalk29.dim("Install the ADL lifecycle conductor locally (login-gated)")}
+  mutagent install helix --version 1.2.3  ${chalk29.dim("Pin a version")}
+  mutagent install --help               ${chalk29.dim("helix")}
 
-  mutagent hooks --help                 ${chalk28.dim("Hook setup for Claude Code session telemetry upload")}
+  mutagent hooks --help                 ${chalk29.dim("Hook setup for Claude Code session telemetry upload")}
 
-${chalk28.bold.red("Report Issues:")}
-  Hit a bug? Run: ${chalk28.cyan('mutagent feedback send "describe what went wrong" --category cli')}
-  Lifecycle-stage feedback: ${chalk28.cyan('mutagent feedback send "eval gate unclear" --category stage:evaluate')}
-  Link to a session: ${chalk28.cyan('mutagent feedback send "..." --session <session-id>')}
-  Attach your coding-agent session transcript: ${chalk28.cyan('mutagent feedback send "..." --attach-transcript')}
-  ${chalk28.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
+${chalk29.bold.red("Report Issues:")}
+  Hit a bug? Run: ${chalk29.cyan('mutagent feedback send "describe what went wrong" --category cli')}
+  Lifecycle-stage feedback: ${chalk29.cyan('mutagent feedback send "eval gate unclear" --category stage:evaluate')}
+  Link to a session: ${chalk29.cyan('mutagent feedback send "..." --session <session-id>')}
+  Attach your coding-agent session transcript: ${chalk29.cyan('mutagent feedback send "..." --attach-transcript')}
+  ${chalk29.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
 
-${chalk28.yellow("Directive System:")}
+${chalk29.yellow("Directive System:")}
   Every --json response may include:
-  ${chalk28.bold("_directive.display")}      Type tag — 'status_card' for card-kind directives (drives test/docs guards)
-  ${chalk28.bold("_directive.renderedCard")} Pre-formatted card ${chalk28.red("(MUST echo verbatim in chat whenever this field exists — see SKILL.md Verbatim Card Display Protocol)")}
-  ${chalk28.bold("_directive.instruction")}  Next step for the agent (self-sufficient, no Skill required)
-  ${chalk28.bold("_directive.next")}         Array of suggested follow-up commands
-  ${chalk28.bold("_links")}                  Dashboard/API URLs (format as markdown links)
-  ${chalk28.bold("_compat")}                 Compat metadata: cliVersion, skillVersion, skillMinCliVersion
-
-${chalk28.yellow("AI Agent Rules (MANDATORY for coding agents):")}
+  ${chalk29.bold("_directive.display")}      Type tag — 'status_card' for card-kind directives (drives test/docs guards)
+  ${chalk29.bold("_directive.renderedCard")} Pre-formatted card ${chalk29.red("(MUST echo verbatim in chat whenever this field exists — see SKILL.md Verbatim Card Display Protocol)")}
+  ${chalk29.bold("_directive.instruction")}  Next step for the agent (self-sufficient, no Skill required)
+  ${chalk29.bold("_directive.next")}         Array of suggested follow-up commands
+  ${chalk29.bold("_links")}                  Dashboard/API URLs (format as markdown links)
+  ${chalk29.bold("_compat")}                 Compat metadata: cliVersion, skillVersion, skillMinCliVersion
+
+${chalk29.yellow("AI Agent Rules (MANDATORY for coding agents):")}
   1. Login (two paths):
      - CI / fully automated: export MUTAGENT_API_KEY=mt_... then mutagent login --json
      - Helping a user onboard: mutagent login --browser --json
@@ -8373,13 +8503,13 @@ ${chalk28.yellow("AI Agent Rules (MANDATORY for coding agents):")}
   2. EVERY command MUST include --json (no exceptions)
   3. Run <command> --help BEFORE first use of any command
   4. Parse _directive.renderedCard and copy it into your CHAT RESPONSE verbatim
-     ${chalk28.red("HARD STOP")}: do NOT run further commands until the card is rendered in chat
+     ${chalk29.red("HARD STOP")}: do NOT run further commands until the card is rendered in chat
   5. After mutagent init, verify workspace: mutagent workspaces list --json
   6. ALL user interaction via AskUserQuestion — CLI is non-interactive
 ${!hasCredentials() ? `
-` + chalk28.yellow("  Warning: Not authenticated. Run: mutagent login") + `
+` + chalk29.yellow("  Warning: Not authenticated. Run: mutagent login") + `
 ` : ""}${!hasRcConfig() ? `
-` + chalk28.green("  Get started: mutagent init") + `
+` + chalk29.green("  Get started: mutagent init") + `
 ` : ""}`);
 var rawArgs = process.argv.slice(2);
 if (isGlobalVersionFlag(rawArgs)) {
@@ -8420,5 +8550,5 @@ program.addCommand(createFeedbackCommand());
 program.addCommand(createTraceCommand());
 program.parse();
 
-//# debugId=9CA63CD3787CB08B64756E2164756E21
+//# debugId=B28A5231DE264E0C64756E2164756E21
 //# sourceMappingURL=cli.js.map