@mutagent/cli 0.1.279 → 0.1.281

package/dist/bin/cli.js

@@ -883,8 +883,8 @@ var init_sdk_client = __esm(() => {
 });
 
 // src/bin/cli.ts
-import { Command as Command14 } from "commander";
-import chalk25 from "chalk";
+import { Command as Command15 } from "commander";
+import chalk28 from "chalk";
 import { readFileSync as readFileSync12 } from "fs";
 import { join as join14, dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -1139,7 +1139,7 @@ init_errors();
 import { spawn } from "child_process";
 import { createHash } from "crypto";
 import { homedir as homedir2 } from "os";
-import { join as join5 } from "path";
+import { join as join5, posix as posixPath, win32 as win32Path, resolve as resolvePath } from "path";
 import {
   existsSync as existsSync4,
   mkdirSync as mkdirSync2,
@@ -1266,9 +1266,18 @@ async function defaultDownload(url, destPath) {
 async function defaultSha256(filePath) {
   return Promise.resolve(createHash("sha256").update(readFileSync4(filePath)).digest("hex"));
 }
+function buildTarExtractInvocation(tgzPath, destDir, platform = process.platform) {
+  const p = platform === "win32" ? win32Path : posixPath;
+  const cwd = p.dirname(tgzPath) || ".";
+  const archive = p.basename(tgzPath);
+  const dest = p.isAbsolute(destDir) ? destDir : resolvePath(destDir);
+  return { args: ["-xzf", archive, "-C", dest], cwd };
+}
 function defaultExtract(tgzPath, destDir) {
+  const invocation = buildTarExtractInvocation(tgzPath, destDir);
   return new Promise((resolve, reject) => {
-    const child = spawn("tar", ["-xzf", tgzPath, "-C", destDir], {
+    const child = spawn("tar", invocation.args, {
+      cwd: invocation.cwd,
       stdio: ["ignore", "ignore", "pipe"]
     });
     let stderr = "";
@@ -6112,11 +6121,11 @@ If mutagent-cli is not installed: mutagent install helix`), isJson);
 }
 
 // src/commands/helix/index.ts
-import { Command as Command13 } from "commander";
-import chalk24 from "chalk";
+import { Command as Command14 } from "commander";
+import chalk27 from "chalk";
 
 // src/commands/helix/spawn.ts
-import chalk20 from "chalk";
+import chalk21 from "chalk";
 init_errors();
 
 // src/lib/sandbox-api.ts
@@ -6399,6 +6408,20 @@ async function execSandbox(id, body) {
     sandboxId: id
   });
 }
+async function postInput(id, body) {
+  return requestJson(`/api/sandbox/${encodeURIComponent(id)}/input`, {
+    method: "POST",
+    body: JSON.stringify(body),
+    sandboxId: id
+  });
+}
+async function startSession(id, body) {
+  return requestJson(`/api/sandbox/${encodeURIComponent(id)}/session`, {
+    method: "POST",
+    body: JSON.stringify(body),
+    sandboxId: id
+  });
+}
 async function oneShotRun(body) {
   return requestJson("/api/sandbox/run", {
     method: "POST",
@@ -6534,7 +6557,7 @@ function canAnimate(isJson) {
 }
 
 // src/commands/helix/session.ts
-import chalk19 from "chalk";
+import chalk20 from "chalk";
 
 // src/lib/sse.ts
 var DEFAULT_EVENT_NAME = "message";
@@ -6633,6 +6656,13 @@ async function runStreamSession(options) {
   });
   const detached = () => outcome("detached");
   const isAborted = () => signal.aborted;
+  const noteSeq = (seq) => {
+    if (seq > lastSeq + 1 && lastSeq > 0) {
+      gaps += 1;
+      sink.notice(gapNotice(lastSeq, seq));
+    }
+    lastSeq = Math.max(lastSeq, seq);
+  };
   for (;; ) {
     if (isAborted())
       return detached();
@@ -6657,38 +6687,44 @@ async function runStreamSession(options) {
       for await (const event of readSseEvents(stream)) {
         attempt = 0;
         if (event.event === "stdout" || event.event === "stderr") {
-          const payload = parseOutputPayload(event.data);
-          if (!payload)
+          const payload2 = parseOutputPayload(event.data);
+          if (!payload2)
             continue;
-          if (payload.seq > lastSeq + 1 && lastSeq > 0) {
-            gaps += 1;
-            sink.notice(gapNotice(lastSeq, payload.seq));
-          }
-          lastSeq = Math.max(lastSeq, payload.seq);
+          noteSeq(payload2.seq);
           if (event.event === "stdout")
-            sink.stdout(payload.text, payload.seq);
+            sink.stdout(payload2.text, payload2.seq);
           else
-            sink.stderr(payload.text, payload.seq);
+            sink.stderr(payload2.text, payload2.seq);
           continue;
         }
         if (event.event === "sandbox") {
-          const payload = parseSandboxRunPayload(event.data);
-          if (payload) {
-            sandbox = payload;
-            options.onSandbox?.(payload);
+          const payload2 = parseSandboxRunPayload(event.data);
+          if (payload2) {
+            sandbox = payload2;
+            options.onSandbox?.(payload2);
           }
           continue;
         }
         if (event.event === "result") {
-          const payload = parseSandboxResultPayload(event.data);
-          if (payload)
-            result = payload;
+          const payload2 = parseSandboxResultPayload(event.data);
+          if (payload2)
+            result = payload2;
+          continue;
+        }
+        if (event.event === "rpc") {
+          const payload2 = parseOutputPayload(event.data);
+          if (!payload2) {
+            sink.unrecognised(event.data, 0);
+            continue;
+          }
+          noteSeq(payload2.seq);
+          sink.rpc(payload2.text, payload2.seq);
           continue;
         }
         if (event.event === "status") {
-          const payload = parseStatusPayload(event.data);
-          if (payload?.state === "exited") {
-            exitCode = payload.exitCode;
+          const payload2 = parseStatusPayload(event.data);
+          if (payload2?.state === "exited") {
+            exitCode = payload2.exitCode;
             exited = true;
             break;
           }
@@ -6704,6 +6740,15 @@ async function runStreamSession(options) {
           }
           continue;
         }
+        if (event.event === "ping")
+          continue;
+        const payload = parseOutputPayload(event.data);
+        if (payload) {
+          noteSeq(payload.seq);
+          sink.unrecognised(payload.text, payload.seq);
+        } else {
+          sink.unrecognised(event.data, 0);
+        }
       }
     } catch (error) {
       if (isAborted())
@@ -6766,8 +6811,226 @@ function delay(ms, signal) {
 
 // src/commands/helix/session.ts
 init_errors();
+
+// src/commands/helix/frames.ts
+import chalk19 from "chalk";
+var SILENT = new Set([
+  "message_start",
+  "message_update",
+  "message_delta",
+  "turn_end",
+  "agent_start",
+  "agent_end"
+]);
+var IDENTIFYING_ARG = {
+  read: ["path", "file_path", "filePath"],
+  write: ["path", "file_path", "filePath"],
+  edit: ["path", "file_path", "filePath"],
+  ls: ["path", "dir"],
+  glob: ["pattern", "path"],
+  grep: ["pattern", "query"],
+  search: ["pattern", "query"],
+  bash: ["command", "cmd", "script"],
+  shell: ["command", "cmd"],
+  exec: ["command", "cmd"],
+  fetch: ["url"],
+  webfetch: ["url"],
+  task: ["description", "prompt"],
+  agent: ["description", "prompt"]
+};
+var GENERIC_ARG = ["path", "file_path", "command", "pattern", "url", "query", "name", "id"];
+var TOOL_COL = 9;
+var DURATION_COL = 44;
+var MAX_ARG = 56;
+var MAX_TEXT = 400;
+
+class FrameFeed {
+  #plain;
+  #pending = new Map;
+  #turn = 0;
+  #now;
+  constructor(options = {}) {
+    this.#plain = options.plain ?? isPlainOutput();
+    this.#now = options.now ?? (() => Date.now());
+  }
+  render(frameText, seq) {
+    const frame = asRecord(frameText);
+    if (!frame)
+      return this.renderUnrecognised(frameText, seq);
+    const type = typeof frame.type === "string" ? frame.type : "";
+    switch (type) {
+      case "tool_execution_start":
+        this.#startCall(frame);
+        return null;
+      case "tool_execution_end":
+        return this.#endCall(frame);
+      case "turn_start":
+        this.#turn += 1;
+        return this.#rule(`turn ${String(this.#turn)}`);
+      case "message_end":
+        return this.#assistantText(frame);
+      case "agent_settled":
+        return this.#line(this.#sym("●", "*"), this.#dim("agent settled — waiting for input"));
+      case "extension_ui_request":
+        return this.#hitl(frame);
+      case "response":
+        return this.#response(frame);
+      default:
+        if (type === "" || SILENT.has(type))
+          return null;
+        return this.#line(this.#sym("·", "."), this.#dim(type));
+    }
+  }
+  renderUnrecognised(raw, seq) {
+    const where = seq > 0 ? ` (seq ${String(seq)})` : "";
+    const body = `unrecognised${where}: ${oneLine(raw, MAX_ARG * 2)}`;
+    return this.#line(this.#sym("·", "."), this.#dim(body));
+  }
+  #startCall(frame) {
+    const id = typeof frame.toolCallId === "string" ? frame.toolCallId : "";
+    if (id === "")
+      return;
+    this.#pending.set(id, {
+      toolName: typeof frame.toolName === "string" ? frame.toolName : "tool",
+      arg: identifyingArg(frame.toolName, frame.args),
+      startedAt: this.#now()
+    });
+  }
+  #endCall(frame) {
+    const id = typeof frame.toolCallId === "string" ? frame.toolCallId : "";
+    const started = id === "" ? undefined : this.#pending.get(id);
+    if (id !== "")
+      this.#pending.delete(id);
+    const toolName = started?.toolName ?? (typeof frame.toolName === "string" ? frame.toolName : "tool");
+    const arg = started?.arg ?? identifyingArg(frame.toolName, frame.args);
+    const failed = isFailure(frame.result);
+    const elapsed = started === undefined ? "" : formatDuration(this.#now() - started.startedAt);
+    const name = this.#plain ? toolName : failed ? chalk19.red(toolName) : chalk19.cyan(toolName);
+    const visible = arg === "" ? toolName.padEnd(TOOL_COL) : `${toolName.padEnd(TOOL_COL)} ${arg}`;
+    const head = arg === "" ? pad(name, toolName, TOOL_COL) : `${pad(name, toolName, TOOL_COL)} ${arg}`;
+    const gap = " ".repeat(Math.max(2, DURATION_COL - visible.length));
+    const tail = elapsed === "" ? "" : gap + this.#dim(elapsed);
+    return this.#line(failed ? this.#sym("✗", "x") : this.#sym("▸", ">"), head + tail);
+  }
+  #assistantText(frame) {
+    const text = extractText(frame);
+    if (text === "")
+      return null;
+    return this.#line(this.#sym("❯", "|"), oneLine(text, MAX_TEXT));
+  }
+  #hitl(frame) {
+    const method = typeof frame.method === "string" ? frame.method : "request";
+    const key = typeof frame.statusKey === "string" ? ` ${frame.statusKey}` : "";
+    const body = `hitl ${method}${key}`;
+    return this.#line(this.#sym("◆", "?"), this.#plain ? body : chalk19.yellow(body));
+  }
+  #response(frame) {
+    const command = typeof frame.command === "string" ? frame.command : "command";
+    const id = typeof frame.id === "string" ? ` ${frame.id}` : "";
+    const ok = frame.success !== false;
+    const body = `${command}${id} ${ok ? "accepted" : "rejected"}`;
+    if (this.#plain)
+      return this.#line(ok ? "+" : "x", body);
+    return this.#line(ok ? "✓" : "✗", ok ? chalk19.green(body) : chalk19.red(body));
+  }
+  #line(symbol, body) {
+    return `  ${symbol} ${body}`;
+  }
+  #sym(styled, plain) {
+    return this.#plain ? plain : styled;
+  }
+  #dim(text) {
+    return this.#plain ? text : chalk19.dim(text);
+  }
+  #rule(label) {
+    const dash = this.#plain ? "-" : "─";
+    const body = `${dash.repeat(2)} ${label} ${dash.repeat(Math.max(2, 40 - label.length))}`;
+    return `  ${this.#dim(body)}`;
+  }
+}
+function asRecord(text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {}
+  return null;
+}
+function pad(styled, visible, width) {
+  const missing = Math.max(0, width - visible.length);
+  return styled + " ".repeat(missing);
+}
+function identifyingArg(toolName, args) {
+  if (!args || typeof args !== "object" || Array.isArray(args))
+    return "";
+  const record = args;
+  const name = typeof toolName === "string" ? toolName.toLowerCase() : "";
+  for (const key of IDENTIFYING_ARG[name] ?? GENERIC_ARG) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim() !== "")
+      return oneLine(value, MAX_ARG);
+    if (typeof value === "number")
+      return String(value);
+  }
+  for (const value of Object.values(record)) {
+    if (typeof value === "string" && value.trim() !== "")
+      return oneLine(value, MAX_ARG);
+  }
+  return "";
+}
+function isFailure(result) {
+  if (!result || typeof result !== "object" || Array.isArray(result))
+    return false;
+  const record = result;
+  if (record.isError === true || record.error != null)
+    return true;
+  return record.success === false;
+}
+function extractText(frame) {
+  const candidates = [
+    frame.text,
+    frame.content,
+    frame.message?.content,
+    frame.message?.text,
+    frame.message
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim() !== "")
+      return candidate.trim();
+    if (Array.isArray(candidate)) {
+      const joined = candidate.map((part) => {
+        if (typeof part === "string")
+          return part;
+        if (part && typeof part === "object" && typeof part.text === "string") {
+          return part.text;
+        }
+        return "";
+      }).join("").trim();
+      if (joined !== "")
+        return joined;
+    }
+  }
+  return "";
+}
+function oneLine(text, max) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+function formatDuration(ms) {
+  const safe = Math.max(0, Math.round(ms));
+  if (safe < 1000)
+    return `${String(safe)}ms`;
+  if (safe < 60000)
+    return `${(safe / 1000).toFixed(1)}s`;
+  const minutes = Math.floor(safe / 60000);
+  const seconds = Math.round(safe % 60000 / 1000);
+  return `${String(minutes)}m ${String(seconds).padStart(2, "0")}s`;
+}
+
+// src/commands/helix/session.ts
 function dim(text) {
-  return isPlainOutput() ? text : chalk19.dim(text);
+  return isPlainOutput() ? text : chalk20.dim(text);
 }
 function reattachHint(id, lastSeq) {
   const since = lastSeq > 0 ? ` --since ${String(lastSeq)}` : "";
@@ -6782,12 +7045,23 @@ function createSessionSink(isJson) {
       stderr: (text, seq) => {
         writeEvent("stderr", { seq, text });
       },
+      rpc: (frame, seq) => {
+        const parsed = parseFrame(frame);
+        if (parsed === null)
+          writeEvent("unrecognised", { seq, raw: frame });
+        else
+          writeEvent("rpc", { seq, frame: parsed });
+      },
+      unrecognised: (raw, seq) => {
+        writeEvent("unrecognised", { seq, raw });
+      },
       notice: (message) => {
         process.stderr.write(`${JSON.stringify({ type: "notice", message })}
 `);
       }
     };
   }
+  const feed = new FrameFeed;
   return {
     stdout: (text) => {
       process.stdout.write(text);
@@ -6795,12 +7069,33 @@ function createSessionSink(isJson) {
     stderr: (text) => {
       process.stderr.write(text);
     },
+    rpc: (frame, seq) => {
+      const line = feed.render(frame, seq);
+      if (line !== null)
+        process.stderr.write(`${line}
+`);
+    },
+    unrecognised: (raw, seq) => {
+      const line = feed.renderUnrecognised(raw, seq);
+      if (line !== null)
+        process.stderr.write(`${line}
+`);
+    },
     notice: (message) => {
       process.stderr.write(`${dim(`[mutagent] ${message}`)}
 `);
     }
   };
 }
+function parseFrame(text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {}
+  return null;
+}
 function writeEvent(type, fields) {
   process.stdout.write(`${JSON.stringify({ type, ...fields })}
 `);
@@ -6874,13 +7169,17 @@ function parseSince(raw) {
 
 // src/commands/helix/spawn.ts
 var ARCHES = ["x86_64", "arm64"];
+var EGRESS_POLICIES = ["deny", "allowlist", "allow"];
+var EGRESS_KINDS = ["port", "cidr", "domain"];
 function registerSpawnCommand(parent) {
-  parent.command("spawn").description("Spawn a Helix session in a cloud sandbox and attach to it").requiredOption("--image <ref>", "Image reference (repository:tag or @digest)").option("--arch <arch>", `Image architecture: ${ARCHES.join(" | ")} (default: this host's)`).option("--name <name>", "Definition name (default: derived from the image reference)").option("--provider <name>", "Provider registry key (default: the backend default)").option("--env <name>", "Environment (secrets + variables) to load at spawn").option("--detach", "Spawn without attaching — print the ID and return").addHelpText("after", `
+  parent.command("spawn").description("Spawn a Helix session in a cloud sandbox and attach to it").requiredOption("--image <ref>", "Image reference (repository:tag or @digest)").option("--arch <arch>", `Image architecture: ${ARCHES.join(" | ")} (default: this host's)`).option("--name <name>", "Definition name (default: derived from the image reference)").option("--provider <name>", "Provider registry key (default: the backend default)").option("--env <name>", "Environment (secrets + variables) to load at spawn").option("--egress <policy>", `Outbound network policy: ${EGRESS_POLICIES.join(" | ")} (default: deny)`).option("--egress-allow <rule>", "Allowance for --egress allowlist, as kind:value (repeatable)", collectRule, []).option("--detach", "Spawn without attaching — print the ID and return").addHelpText("after", `
 Examples:
-  ${chalk20.dim("$")} mutagent helix spawn --image alpine:3.20
-  ${chalk20.dim("$")} mutagent helix spawn --image ghcr.io/example/helix:latest --arch x86_64
-  ${chalk20.dim("$")} mutagent helix spawn --image alpine:3.20 --detach --json
-  ${chalk20.dim("$")} mutagent helix spawn --image alpine:3.20 --provider docker --env staging
+  ${chalk21.dim("$")} mutagent helix spawn --image alpine:3.20
+  ${chalk21.dim("$")} mutagent helix spawn --image ghcr.io/example/helix:latest --arch x86_64
+  ${chalk21.dim("$")} mutagent helix spawn --image alpine:3.20 --detach --json
+  ${chalk21.dim("$")} mutagent helix spawn --image alpine:3.20 --provider docker --env staging
+  ${chalk21.dim("$")} mutagent helix spawn --image <helix-image> --egress allow   ${chalk21.dim("Required for a Helix session")}
+  ${chalk21.dim("$")} mutagent helix spawn --image <ref> --egress allowlist --egress-allow domain:api.anthropic.com
 
 --image is required. A sandbox is spawned from a DEFINITION, and the definition
 names its own image — there is no default the CLI could invent for you. To run
@@ -6896,11 +7195,37 @@ the image was built elsewhere.
 DIFFERENT axis from --provider, which selects the backend. Secrets never travel
 on the command line.
 
+NETWORK EGRESS IS DENIED BY DEFAULT, AND THAT BREAKS HELIX SESSIONS:
+  A sandbox runs code we did not write, so the safe default is the default:
+  nothing reaches out. That is right for a plain 'exec' box, which needs no
+  network at all.
+
+  It is WRONG for a Helix session, for two independent reasons — either alone
+  is enough to sink it:
+    1. Under deny the container runs with --network none. Docker accepts -P and
+       publishes nothing, so the in-box server on :8080 is unreachable and
+       'mutagent helix session start' fails with "Helix is not reachable".
+    2. An agent turn has to reach a model provider regardless.
+
+  So: ${chalk21.bold("--egress allow")} before 'helix session start'. Without it the failure
+  presents as an unreachable box, which reads like a broken image rather than a
+  policy you chose.
+
+  ${chalk21.bold("--egress allowlist")} narrows that to named allowances, each given explicitly
+  as kind:value — 'domain:api.anthropic.com', 'port:443', 'cidr:10.0.0.0/8'. The
+  kind is never inferred from the value. An allowlist with no rules denies
+  everything, so it is refused rather than silently walling the box off; it also
+  needs a provider with egress control, which not every backend has.
+
 Without --detach this spawns and immediately attaches, so the common path is a
 single command. Ctrl-C then DETACHES — the sandbox keeps running and the
 re-attach command is printed. Use 'mutagent helix rm <id> --force' to destroy it.
 
 AI Agent Directive:
+  Pass --egress allow whenever the box is for a Helix session — 'mutagent helix
+  session start' CANNOT reach the in-box server under the default deny policy,
+  and the error it raises names the box, not the policy. A box you only 'exec'
+  in needs no egress.
   Prefer --detach --json for automation: it returns one JSON object with the
   sandbox id, so you can decide what to run before committing to a live stream.
   Without --detach, --json output is NDJSON and the final line is the summary.
@@ -6959,8 +7284,49 @@ function buildDefinition(options) {
     definition.provider = options.provider;
   if (options.env)
     definition.environment = options.env;
+  const network = resolveNetwork(options.egress, options.egressAllow ?? []);
+  if (network)
+    definition.network = network;
   return definition;
 }
+function resolveNetwork(requested, rules) {
+  if (requested === undefined) {
+    if (rules.length > 0) {
+      throw new MutagentError("INVALID_ARGUMENTS", "--egress-allow only means something with --egress allowlist.", "Add --egress allowlist, or drop the allowances and use --egress allow.");
+    }
+    return;
+  }
+  const policy = requested.trim();
+  if (!EGRESS_POLICIES.includes(policy)) {
+    throw new MutagentError("INVALID_ARGUMENTS", `--egress must be one of ${EGRESS_POLICIES.join(", ")}, got "${requested}".`, "Use --egress allow to drive a Helix session; the default, deny, leaves the box with no network at all.");
+  }
+  if (policy !== "allowlist") {
+    if (rules.length > 0) {
+      throw new MutagentError("INVALID_ARGUMENTS", `--egress-allow is only read under "allowlist", so under "${policy}" the allowances would be silently discarded.`, `Use --egress allowlist to apply them, or drop them to keep --egress ${policy}.`);
+    }
+    return { egress: policy };
+  }
+  if (rules.length === 0) {
+    throw new MutagentError("INVALID_ARGUMENTS", "An allowlist with no allowances denies everything — the same wall as --egress deny, under a name that says otherwise.", `Name what may be reached: --egress-allow domain:api.anthropic.com
+Or open it fully: --egress allow`);
+  }
+  return { egress: "allowlist", allow: rules.map(parseRule) };
+}
+function collectRule(value, previous) {
+  return [...previous, value];
+}
+function parseRule(raw) {
+  const separator = raw.indexOf(":");
+  const kind = separator === -1 ? "" : raw.slice(0, separator).trim();
+  const value = separator === -1 ? "" : raw.slice(separator + 1).trim();
+  if (!EGRESS_KINDS.includes(kind) || value === "") {
+    throw new MutagentError("INVALID_ARGUMENTS", `--egress-allow must be <kind>:<value>, got "${raw}".`, `kind is one of ${EGRESS_KINDS.join(", ")}. Examples:
+  --egress-allow domain:api.anthropic.com
+  --egress-allow port:443
+  --egress-allow cidr:10.0.0.0/8`);
+  }
+  return { kind, value };
+}
 function resolveArch(requested) {
   if (requested !== undefined) {
     const value = requested.trim();
@@ -6986,10 +7352,10 @@ async function createSandbox(definition, isJson) {
   const spinner = ora2(`Spawning ${definition.image} (${definition.arch})...`).start();
   try {
     const sandbox = await spawnSandbox(definition);
-    spinner.succeed(chalk20.green(`Sandbox ${sandbox.id} spawned`));
+    spinner.succeed(chalk21.green(`Sandbox ${sandbox.id} spawned`));
     return sandbox;
   } catch (error) {
-    spinner.fail(chalk20.red("Spawn failed"));
+    spinner.fail(chalk21.red("Spawn failed"));
     throw error;
   }
 }
@@ -7024,15 +7390,15 @@ function reportDetached(sandbox, id, output, isJson) {
 }
 
 // src/commands/helix/attach.ts
-import chalk21 from "chalk";
+import chalk22 from "chalk";
 init_errors();
 function registerAttachCommand(parent) {
   parent.command("attach").description("Attach to a running sandbox and stream its output").argument("<id>", "Sandbox ID").option("--since <seq>", "Resume after this sequence number instead of from the start").addHelpText("after", `
 Examples:
-  ${chalk21.dim("$")} mutagent helix attach sbx_123
-  ${chalk21.dim("$")} mutagent helix attach sbx_123 --since 412
-  ${chalk21.dim("$")} mutagent helix attach sbx_123 --json | tail -1
-  ${chalk21.dim("$")} mutagent helix attach sbx_123 > session.log
+  ${chalk22.dim("$")} mutagent helix attach sbx_123
+  ${chalk22.dim("$")} mutagent helix attach sbx_123 --since 412
+  ${chalk22.dim("$")} mutagent helix attach sbx_123 --json | tail -1
+  ${chalk22.dim("$")} mutagent helix attach sbx_123 > session.log
 
 Ctrl-C detaches. The sandbox keeps running and the exact re-attach command,
 with the resume point filled in, is printed to stderr. Only 'mutagent helix rm <id> --force'
@@ -7081,16 +7447,244 @@ AI Agent Directive:
   });
 }
 
+// src/commands/helix/send.ts
+import chalk23 from "chalk";
+import { randomUUID as randomUUID3 } from "crypto";
+init_errors();
+var COMMAND_TYPES = ["prompt", "steer", "follow_up", "abort"];
+var NEEDS_MESSAGE = new Set(["prompt", "steer", "follow_up"]);
+function registerSendCommand(parent) {
+  parent.command("send").description("Send a command line into a running session").argument("<id>", "Sandbox ID").argument("[message...]", "What to say to the agent").requiredOption("--session <id>", "Session ID inside the sandbox").option("--type <type>", `Command verb: ${COMMAND_TYPES.join(" | ")} (default: prompt)`).option("--line <json>", "Send this exact JSON line instead of building one").option("--message-id <id>", "Correlation id to use instead of a generated one").addHelpText("after", `
+Examples:
+  ${chalk23.dim("$")} mutagent helix send sbx_123 --session s1 "also check the refresh path"
+  ${chalk23.dim("$")} mutagent helix send sbx_123 --session s1 --type steer "stop and re-read the spec"
+  ${chalk23.dim("$")} mutagent helix send sbx_123 --session s1 --type abort
+  ${chalk23.dim("$")} mutagent helix send sbx_123 --session s1 --line '{"type":"prompt","id":"p7","message":"go"}'
+  ${chalk23.dim("$")} mutagent helix send sbx_123 --session s1 "run the tests" --json
+
+TWO FORMS:
+  ${chalk23.bold("The friendly form")} — a --type and a message. This command builds the JSON:
+  {"type":"prompt","id":"<generated>","message":"<your message>"}. Use it for
+  everything the four verbs cover.
+  ${chalk23.bold("--line")} — one raw JSON object, passed through byte for byte. It exists for
+  a command shape this CLI does not know about yet. It is validated as a single
+  JSON object before anything is sent, but its CONTENTS are the harness's
+  business, not this CLI's. Do not combine it with --type or a message.
+
+THE VERBS:
+  prompt      A new instruction to a settled agent.
+  steer       Redirect the turn already running.
+  follow_up   Continue from what the agent just said.
+  abort       Stop the current turn. Takes no message.
+
+Sending is not watching. A 200 means the line was written to the session; the
+agent's reply arrives on the event stream as a 'response' frame carrying the id
+printed here. Attach in another terminal to see it:
+  ${chalk23.dim("$")} mutagent helix attach sbx_123
+
+A session that is no longer running is refused rather than silently accepted —
+'mutagent helix ls' shows what is still up.
+
+AI Agent Directive:
+  --json returns ONE object: { success, sandboxId, sessionId, type, id, line,
+  accepted, _links }. 'accepted' means DELIVERED, not answered — the answer is a
+  'response' frame with the same id on 'mutagent helix attach <id> --json'.
+  Attach BEFORE sending if you need the reply; this call does not wait for one.
+  Use the friendly form (--type + message). Reserve --line for a command shape
+  the four verbs cannot express.
+      `).action(async (id, messageParts, 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 send ${id} --session <session-id> "<message>"`);
+      }
+      const built = buildLine(messageParts.join(" ").trim(), options);
+      const result = await postInput(id, { sessionId, line: built.line });
+      if (isJson) {
+        output.output({
+          success: true,
+          sandboxId: id,
+          sessionId,
+          type: built.type,
+          id: built.id,
+          line: built.line,
+          accepted: result.accepted,
+          _links: sandboxLinks(id),
+          _directive: {
+            instruction: "The line was delivered, not answered. The reply is a `response` frame with this id on the event stream.",
+            next: [`mutagent helix attach ${id} --json`]
+          }
+        });
+        return;
+      }
+      output.success(`Sent ${built.type} to session ${sessionId}`);
+      console.error(chalk23.dim(`  ${built.line}`));
+      console.error(chalk23.dim(`  The reply arrives on the stream, not here: mutagent helix attach ${id}`));
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+function buildLine(message, options) {
+  const raw = options.line;
+  if (raw !== undefined) {
+    if (message !== "" || options.type !== undefined) {
+      throw new MutagentError("INVALID_ARGUMENTS", "--line is the whole command already — it cannot be combined with --type or a message.", `Send the raw line on its own, or drop --line and use the friendly form:
+  --type prompt "<message>"`);
+    }
+    return { line: requireOneJsonObject(raw), type: readType(raw), id: null };
+  }
+  const type = options.type ?? "prompt";
+  if (!COMMAND_TYPES.includes(type)) {
+    throw new MutagentError("INVALID_ARGUMENTS", `Unknown command type "${options.type ?? ""}".`, `Use one of: ${COMMAND_TYPES.join(", ")}. For anything else, pass the raw JSON with --line.`);
+  }
+  if (message === "" && NEEDS_MESSAGE.has(type)) {
+    throw new MutagentError("MISSING_ARGUMENTS", `A "${type}" carries a message — there is nothing to send without one.`, `Run: mutagent helix send <id> --session <session-id> --type ${type} "<message>"`);
+  }
+  if (message !== "" && !NEEDS_MESSAGE.has(type)) {
+    throw new MutagentError("INVALID_ARGUMENTS", `A "${type}" takes no message, so the text would be silently discarded.`, `Drop the message, or send it separately as a prompt.`);
+  }
+  const id = options.messageId?.trim() ?? "";
+  const correlationId = id === "" ? `cli_${randomUUID3().slice(0, 8)}` : id;
+  const body = { type, id: correlationId };
+  if (message !== "")
+    body.message = message;
+  return { line: JSON.stringify(body), type, id: correlationId };
+}
+function requireOneJsonObject(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.includes(`
+`)) {
+    throw new MutagentError("INVALID_ARGUMENTS", "--line must be ONE line — a newline inside it would be read as two commands.", "Send one command per call.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new MutagentError("INVALID_ARGUMENTS", "--line is not valid JSON.", `The harness reads one JSON object per line. Example:
+  --line '{"type":"prompt","id":"p1","message":"go"}'`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new MutagentError("INVALID_ARGUMENTS", "--line must be a JSON object, not an array or a bare value.", `Example:
+  --line '{"type":"prompt","id":"p1","message":"go"}'`);
+  }
+  return trimmed;
+}
+function readType(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && typeof parsed.type === "string") {
+      return parsed.type;
+    }
+  } catch {}
+  return "raw";
+}
+
+// src/commands/helix/session-start.ts
+import { Command as Command13 } from "commander";
+import chalk24 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
+
+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.
+A box with no session is a normal state — that is what 'exec' runs against.
+
+AI Agent Directive:
+  Run 'mutagent helix session start <sandbox-id> --rpc --json' before 'send':
+  a session id is required and there is no default one to guess.
+      `);
+  registerStart(session, parent);
+  parent.addCommand(session);
+}
+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
+
+TWO MODES, AND ONLY ONE OF THEM LISTENS:
+  ${chalk24.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
+             with 'attach', not steerable.
+
+The box must already exist — 'mutagent helix spawn --image <ref>' makes one, and
+'mutagent helix ls' shows which are running. One sandbox can host several
+sessions, so starting one never replaces another.
+
+The session id printed here is the handle for everything after it. Nothing else
+can produce it, so a session started and then forgotten can only be found again
+by attaching to the box and reading the stream.
+
+AI Agent Directive:
+  --json returns ONE object: { success, sandboxId, sessionId, status, mode,
+  _links }. Capture 'sessionId' — 'mutagent helix send' requires it and there is
+  no default. Use --rpc whenever you intend to send into the session; a one-shot
+  session refuses input with a 409.
+      `).action(async (id, options) => {
+    const isJson = getJsonFlag(root);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const mode = options.rpc === true ? "rpc" : "oneshot";
+      const result = await startSession(id, { mode });
+      const sessionId = requireSessionId(result, id);
+      if (isJson) {
+        output.output({
+          success: true,
+          sandboxId: id,
+          sessionId,
+          status: result.status,
+          mode,
+          _links: sandboxLinks(id),
+          _directive: {
+            instruction: mode === "rpc" ? "The session is live and reading its stdin. Attach to watch it; send to steer it." : "The session takes one turn and ends. Attach to watch it; it does not accept input.",
+            next: mode === "rpc" ? [
+              `mutagent helix attach ${id} --json`,
+              `mutagent helix send ${id} --session ${sessionId} "<message>" --json`
+            ] : [`mutagent helix attach ${id} --json`]
+          }
+        });
+        return;
+      }
+      output.success(`Session ${sessionId} started in ${id} (${mode})`);
+      console.error(chalk24.dim(`  Watch it:   mutagent helix attach ${id}`));
+      if (mode === "rpc") {
+        console.error(chalk24.dim(`  Talk to it: mutagent helix send ${id} --session ${sessionId} "<message>"`));
+      }
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+function requireSessionId(result, sandboxId) {
+  if (typeof result.sessionId === "string" && result.sessionId !== "")
+    return result.sessionId;
+  throw new MutagentError("INVALID_RESPONSE", "The server started a session but did not return a session id.", `The session may be running — watch it with: mutagent helix attach ${sandboxId}`);
+}
+
 // src/commands/helix/run.ts
-import chalk22 from "chalk";
+import chalk25 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", `
 Examples:
-  ${chalk22.dim("$")} mutagent helix run "summarise the failing tests" --prompt "You are a test triage agent."
-  ${chalk22.dim("$")} mutagent helix run fix the flaky login spec --prompt "$(cat agent.md)"
-  ${chalk22.dim("$")} mutagent helix run "list open PRs" --prompt "You are a release assistant." --json
-  ${chalk22.dim("$")} mutagent helix run "explore the repo" --prompt "$(cat agent.md)" --keep
+  ${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
 
 TWO PROMPTS, AND THEY ARE NOT THE SAME THING:
   --prompt   WHO the agent is — its definition, its standing instructions.
@@ -7197,17 +7791,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:
-  ${chalk22.dim("$")} mutagent helix exec -- ls -la /workspace
-  ${chalk22.dim("$")} mutagent helix exec --sandbox sbx_123 -- bun test
-  ${chalk22.dim("$")} mutagent helix exec --sandbox sbx_123 --cwd /src -- git status
-  ${chalk22.dim("$")} mutagent helix exec --preset default -- uname -m --json
+  ${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
 
-Put ${chalk22.bold("--")} before the command. Everything after it is argv and is passed through
+Put ${chalk25.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:
-  ${chalk22.dim("$")} mutagent helix exec -- sh -c 'ls | wc -l'      ${chalk22.dim("a shell, explicitly")}
-  ${chalk22.dim("$")} mutagent helix exec -- 'ls | wc -l'            ${chalk22.dim("looks for a file called 'ls | wc -l'")}
+  ${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'")}
 
 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
@@ -7339,17 +7933,17 @@ function reportResult(result, output, isJson, context) {
 }
 
 // src/commands/helix/inventory.ts
-import chalk23 from "chalk";
+import chalk26 from "chalk";
 init_errors();
 function registerLsCommand(parent) {
   parent.command("ls").description("List your sandboxes").addHelpText("after", `
 Examples:
-  ${chalk23.dim("$")} mutagent helix ls
-  ${chalk23.dim("$")} mutagent helix ls --json
+  ${chalk26.dim("$")} mutagent helix ls
+  ${chalk26.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:
-  ${chalk23.dim("$")} mutagent config set workspace <workspace-id>
+  ${chalk26.dim("$")} mutagent config set workspace <workspace-id>
 
 An empty list is a normal result, not an error: it means no sandbox is running.
 
@@ -7369,7 +7963,7 @@ AI Agent Directive:
         return;
       }
       if (sandboxes.length === 0) {
-        console.log(chalk23.gray("No sandboxes running."));
+        console.log(chalk26.gray("No sandboxes running."));
         console.log("");
         console.log("  Start one: mutagent helix spawn --image <ref>");
         return;
@@ -7393,8 +7987,8 @@ function toRow(sandbox) {
 function registerPresetsCommand(parent) {
   parent.command("presets").description("List the presets a one-shot run can name").addHelpText("after", `
 Examples:
-  ${chalk23.dim("$")} mutagent helix presets
-  ${chalk23.dim("$")} mutagent helix presets --json
+  ${chalk26.dim("$")} mutagent helix presets
+  ${chalk26.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
@@ -7415,7 +8009,7 @@ AI Agent Directive:
         return;
       }
       if (presets.length === 0) {
-        console.log(chalk23.gray("No presets configured on this backend."));
+        console.log(chalk26.gray("No presets configured on this backend."));
         console.log("");
         console.log("  Spawn with an explicit image: mutagent helix spawn --image <ref>");
         return;
@@ -7435,15 +8029,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:
-  ${chalk23.dim("$")} mutagent helix rm sbx_123 --force
-  ${chalk23.dim("$")} mutagent helix rm sbx_123 --json
+  ${chalk26.dim("$")} mutagent helix rm sbx_123 --force
+  ${chalk26.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.
 
-${chalk23.dim("Note: --force is required. The CLI is non-interactive — confirm with the user via your native flow, then pass --force. --json auto-confirms.")}
-${chalk23.dim("Warning: any session running in the sandbox ends immediately and cannot be recovered.")}
+${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.")}
 
 AI Agent Directive:
   Destroying a sandbox ends any session running in it and cannot be undone.
@@ -7478,8 +8072,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:
-  ${chalk23.dim("$")} mutagent helix traces sbx_123
-  ${chalk23.dim("$")} mutagent helix traces sbx_123 --json
+  ${chalk26.dim("$")} mutagent helix traces sbx_123
+  ${chalk26.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
@@ -7503,7 +8097,7 @@ AI Agent Directive:
         return;
       }
       if (spans.length === 0) {
-        console.log(chalk23.gray(`No spans captured for sandbox ${id}.`));
+        console.log(chalk26.gray(`No spans captured for sandbox ${id}.`));
         return;
       }
       output.output(spans.map((span) => {
@@ -7523,26 +8117,35 @@ AI Agent Directive:
 
 // src/commands/helix/index.ts
 function createHelixCommand() {
-  const helix = new Command13("helix").description("Run Helix sessions in a cloud sandbox").addHelpText("after", `
+  const helix = new Command14("helix").description("Run Helix sessions in a cloud sandbox").addHelpText("after", `
 Examples:
-  ${chalk24.dim("$")} mutagent helix run "fix the failing test" --prompt "$(cat agent.md)"
-  ${chalk24.dim("$")} mutagent helix exec -- uname -m                 ${chalk24.dim("One command, fresh box")}
-  ${chalk24.dim("$")} mutagent helix presets                          ${chalk24.dim("What a one-shot can run on")}
-  ${chalk24.dim("$")} mutagent helix spawn --image alpine:3.20        ${chalk24.dim("Persistent box, then attach")}
-  ${chalk24.dim("$")} mutagent helix ls                               ${chalk24.dim("What is running")}
-  ${chalk24.dim("$")} mutagent helix exec --sandbox sbx_1 -- bun test ${chalk24.dim("Command in that box")}
-  ${chalk24.dim("$")} mutagent helix attach sbx_1 --since 412         ${chalk24.dim("Resume after a sequence number")}
-  ${chalk24.dim("$")} mutagent helix traces sbx_1 --json              ${chalk24.dim("What the session actually did")}
-  ${chalk24.dim("$")} mutagent helix rm sbx_1 --force                 ${chalk24.dim("Destroy it")}
+  ${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")}
 
 Subcommands:
-  run, exec, spawn, ls, presets, attach, traces, rm
+  run, exec, spawn, session, ls, presets, attach, send, traces, rm
 
 One-shot vs persistent:
-  ${chalk24.bold("run")} and ${chalk24.bold("exec")} (without --sandbox) start from a named PRESET, do one
+  ${chalk27.bold("run")} and ${chalk27.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.
-  ${chalk24.bold("spawn")} takes an explicit --image and leaves a box running for you to
-  ${chalk24.bold("attach")} and ${chalk24.bold("exec --sandbox")} against until you ${chalk24.bold("rm")} it.
+  ${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.
+
+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,
+  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.
 
 Lifecycle:
   A spawned sandbox outlives your terminal. Ctrl-C, a dropped connection and a
@@ -7552,7 +8155,7 @@ Lifecycle:
 
 Access:
   Sandbox access is minted per WORKSPACE, so a workspace must be configured:
-  ${chalk24.dim("$")} mutagent config set workspace <workspace-id>
+  ${chalk27.dim("$")} mutagent config set workspace <workspace-id>
 
 Output:
   Sandbox stdout goes to stdout, sandbox stderr goes to stderr, and anything
@@ -7581,6 +8184,8 @@ AI Agent Directive:
   registerLsCommand(helix);
   registerPresetsCommand(helix);
   registerAttachCommand(helix);
+  registerSendCommand(helix);
+  registerSessionCommand(helix);
   registerTracesCommand(helix);
   registerRmCommand(helix);
   return helix;
@@ -7694,7 +8299,7 @@ if (process.env.CLI_VERSION) {
   } catch {}
 }
 setCliVersion(cliVersion);
-var program = new Command14;
+var program = new Command15;
 program.name("mutagent").description(`Mutagent CLI - command-line client for the Mutagent platform
 
   Documentation: https://docs.mutagent.io/cli
@@ -7704,61 +8309,61 @@ program.name("mutagent").description(`Mutagent CLI - command-line client for the
 });
 program.addHelpText("beforeAll", () => renderBanner());
 program.addHelpText("after", `
-${chalk25.bold.cyan("WORKFLOWS:")}
-  ${chalk25.bold("Setup")}                mutagent login  →  mutagent init
-  ${chalk25.bold("Lifecycle Tools")}      mutagent install helix  ${chalk25.dim("(login-gated)")}
-  ${chalk25.bold("Feedback")}             mutagent feedback send "<what happened>" --category <cli|helix|stage:<x>>  ${chalk25.dim("[--session <id>] [--attach-transcript]")}
+${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]")}
 
-${chalk25.dim("For CLI usage guidance for AI agents, see the Skill at")}
-${chalk25.cyan(".claude/skills/mutagent-cli/SKILL.md")}
+${chalk28.dim("For CLI usage guidance for AI agents, see the Skill at")}
+${chalk28.cyan(".claude/skills/mutagent-cli/SKILL.md")}
 
-${chalk25.yellow("Global flags:")}
-  -v, --version ${chalk25.dim("Print the CLI version")}   ${chalk25.dim("(before a subcommand; after one it is the subcommand's)")}
+${chalk28.yellow("Global flags:")}
+  -v, --version ${chalk28.dim("Print the CLI version")}   ${chalk28.dim("(before a subcommand; after one it is the subcommand's)")}
   --json  --api-key <k>  --endpoint <url>  --non-interactive
 
-${chalk25.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
-  export MUTAGENT_API_KEY=mt_...  ${chalk25.dim("or")}  --api-key mt_...
-  --json ${chalk25.dim("for structured output")}    --non-interactive ${chalk25.dim("to disable prompts")}
+${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")}
 
-${chalk25.yellow("Command Navigation:")}
-  mutagent login                        ${chalk25.dim("Login (browser OAuth — recommended)")}
-  mutagent auth status                  ${chalk25.dim("Check auth + workspace")}
-  mutagent init                         ${chalk25.dim("Initialize project (.mutagentrc.json)")}
-  mutagent workspaces list --json       ${chalk25.dim("List workspaces (verify ID)")}
-  mutagent config set workspace <id>    ${chalk25.dim("Set active workspace")}
-  mutagent usage --json                 ${chalk25.dim("Show account usage + provider status")}
+${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")}
 
-  mutagent providers list --json        ${chalk25.dim("List configured BYOK providers")}
-  mutagent providers list --models      ${chalk25.dim("See available models per provider")}
+  mutagent providers list --json        ${chalk28.dim("List configured BYOK providers")}
+  mutagent providers list --models      ${chalk28.dim("See available models per provider")}
 
-  mutagent helix run "<task>" --prompt "<who>"  ${chalk25.dim("One Helix agent turn in a cloud sandbox")}
-  mutagent helix ls --json              ${chalk25.dim("List running sandboxes")}
-  mutagent helix spawn --image <ref>    ${chalk25.dim("Persistent sandbox you attach to")}
-  mutagent helix rm <id> --force        ${chalk25.dim("Destroy a sandbox (the only thing that does)")}
+  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 install helix                ${chalk25.dim("Install the ADL lifecycle conductor locally (login-gated)")}
-  mutagent install helix --version 1.2.3  ${chalk25.dim("Pin a version")}
-  mutagent install --help               ${chalk25.dim("helix")}
+  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 hooks --help                 ${chalk25.dim("Hook setup for Claude Code session telemetry upload")}
+  mutagent hooks --help                 ${chalk28.dim("Hook setup for Claude Code session telemetry upload")}
 
-${chalk25.bold.red("Report Issues:")}
-  Hit a bug? Run: ${chalk25.cyan('mutagent feedback send "describe what went wrong" --category cli')}
-  Lifecycle-stage feedback: ${chalk25.cyan('mutagent feedback send "eval gate unclear" --category stage:evaluate')}
-  Link to a session: ${chalk25.cyan('mutagent feedback send "..." --session <session-id>')}
-  Attach your coding-agent session transcript: ${chalk25.cyan('mutagent feedback send "..." --attach-transcript')}
-  ${chalk25.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
+${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>")}
 
-${chalk25.yellow("Directive System:")}
+${chalk28.yellow("Directive System:")}
   Every --json response may include:
-  ${chalk25.bold("_directive.display")}      Type tag — 'status_card' for card-kind directives (drives test/docs guards)
-  ${chalk25.bold("_directive.renderedCard")} Pre-formatted card ${chalk25.red("(MUST echo verbatim in chat whenever this field exists — see SKILL.md Verbatim Card Display Protocol)")}
-  ${chalk25.bold("_directive.instruction")}  Next step for the agent (self-sufficient, no Skill required)
-  ${chalk25.bold("_directive.next")}         Array of suggested follow-up commands
-  ${chalk25.bold("_links")}                  Dashboard/API URLs (format as markdown links)
-  ${chalk25.bold("_compat")}                 Compat metadata: cliVersion, skillVersion, skillMinCliVersion
-
-${chalk25.yellow("AI Agent Rules (MANDATORY for coding agents):")}
+  ${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):")}
   1. Login (two paths):
      - CI / fully automated: export MUTAGENT_API_KEY=mt_... then mutagent login --json
      - Helping a user onboard: mutagent login --browser --json
@@ -7768,13 +8373,13 @@ ${chalk25.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
-     ${chalk25.red("HARD STOP")}: do NOT run further commands until the card is rendered in chat
+     ${chalk28.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() ? `
-` + chalk25.yellow("  Warning: Not authenticated. Run: mutagent login") + `
+` + chalk28.yellow("  Warning: Not authenticated. Run: mutagent login") + `
 ` : ""}${!hasRcConfig() ? `
-` + chalk25.green("  Get started: mutagent init") + `
+` + chalk28.green("  Get started: mutagent init") + `
 ` : ""}`);
 var rawArgs = process.argv.slice(2);
 if (isGlobalVersionFlag(rawArgs)) {
@@ -7815,5 +8420,5 @@ program.addCommand(createFeedbackCommand());
 program.addCommand(createTraceCommand());
 program.parse();
 
-//# debugId=0D5785F3AE94E3BA64756E2164756E21
+//# debugId=9CA63CD3787CB08B64756E2164756E21
 //# sourceMappingURL=cli.js.map