@mutagent/cli 0.1.261 → 0.1.263

package/dist/bin/cli.js

@@ -68,8 +68,8 @@ function loadConfig() {
     ...credentials,
     apiKey: process.env.MUTAGENT_API_KEY ?? credentials?.apiKey ?? rcConfig?.apiKey,
     endpoint: process.env.MUTAGENT_ENDPOINT ?? credentials?.endpoint ?? rcConfig?.endpoint,
-    defaultWorkspace: credentials?.defaultWorkspace ?? rcConfig?.defaultWorkspace,
-    defaultWorkspaceSource: credentials?.defaultWorkspace ? credentials.defaultWorkspaceSource ?? "login-inferred" : rcConfig?.defaultWorkspace ? "login-inferred" : undefined,
+    defaultWorkspace: process.env.MUTAGENT_WORKSPACE_ID ?? credentials?.defaultWorkspace ?? rcConfig?.defaultWorkspace,
+    defaultWorkspaceSource: process.env.MUTAGENT_WORKSPACE_ID ? "user" : credentials?.defaultWorkspace ? credentials.defaultWorkspaceSource ?? "login-inferred" : rcConfig?.defaultWorkspace ? "login-inferred" : undefined,
     defaultOrganization: credentials?.defaultOrganization ?? rcConfig?.defaultOrganization
   };
   return configSchema.parse(merged);
@@ -269,7 +269,7 @@ function handleError(error, isJson) {
   }
   process.exit(1);
 }
-var MutagentError, AUTH_REMEDIATION_MESSAGE, AuthenticationError, ApiError, WORKSPACE_REMEDIATION_MESSAGE, WorkspaceContextError, ValidationError;
+var MutagentError, AUTH_REMEDIATION_MESSAGE, AuthenticationError, ApiError, WORKSPACE_REMEDIATION_MESSAGE, WorkspaceContextError, ValidationError, NotFoundError;
 var init_errors = __esm(() => {
   MutagentError = class MutagentError extends Error {
     code;
@@ -335,6 +335,11 @@ var init_errors = __esm(() => {
       super("VALIDATION_ERROR", message, "Check the command syntax with: mutagent <command> --help", 1);
     }
   };
+  NotFoundError = class NotFoundError extends MutagentError {
+    constructor(resource, id) {
+      super("NOT_FOUND", `${resource} not found: ${id}`, `Check the ID and try again. List available ${resource.toLowerCase()}s with the appropriate list command.`, 1);
+    }
+  };
 });
 
 // src/lib/provider-request.ts
@@ -878,10 +883,10 @@ var init_sdk_client = __esm(() => {
 });
 
 // src/bin/cli.ts
-import { Command as Command13 } from "commander";
-import chalk19 from "chalk";
-import { readFileSync as readFileSync10 } from "fs";
-import { join as join14, dirname as dirname3 } from "path";
+import { Command as Command14 } from "commander";
+import chalk25 from "chalk";
+import { readFileSync as readFileSync12 } from "fs";
+import { join as join15, dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/auth.ts
@@ -4369,8 +4374,149 @@ Examples:
 }
 
 // src/commands/hooks/index.ts
+import { readFileSync as readFileSync8 } from "node:fs";
+import { basename } from "node:path";
 import { Command as Command9 } from "commander";
 
+// src/commands/hooks/import-transcript.ts
+var MAX_SPAN_TEXT = 4000;
+function contentToText(content) {
+  if (typeof content === "string")
+    return content.slice(0, MAX_SPAN_TEXT);
+  if (Array.isArray(content)) {
+    return content.map((part) => part !== null && typeof part === "object" && ("text" in part) ? String(part.text) : "").filter(Boolean).join(" ").slice(0, MAX_SPAN_TEXT);
+  }
+  return "";
+}
+function convertTranscript(records, opts) {
+  const maxSpans = opts.maxSpans ?? 200;
+  const session = records.find((r) => r.type === "session");
+  if (session === undefined || typeof session.id !== "string" || session.id === "") {
+    return { trace: null, skipped: opts.skipped ?? 0, ignored: records.length };
+  }
+  const spans = [];
+  let ignored = 0;
+  let lastTs = session.timestamp ?? new Date().toISOString();
+  for (const r of records) {
+    if (r.type !== "message" && r.type !== "custom_message") {
+      ignored += 1;
+      continue;
+    }
+    if (spans.length >= maxSpans) {
+      ignored += 1;
+      continue;
+    }
+    const role = r.message?.role ?? r.role ?? r.type;
+    const startTime = r.timestamp ?? lastTs;
+    lastTs = startTime;
+    const text = contentToText(r.message?.content);
+    const span = {
+      spanId: String(r.id ?? r.uuid ?? `span-${String(spans.length)}`).slice(0, 128),
+      name: `helix.${role}`,
+      kind: role === "assistant" ? "llm" : "message",
+      startTime,
+      status: "ok"
+    };
+    if (text !== "")
+      span.output = text;
+    spans.push(span);
+  }
+  return {
+    trace: {
+      traceId: `helix-${session.id}`.slice(0, 128),
+      sessionId: session.id.slice(0, 256),
+      name: "helix.session",
+      source: "helix",
+      startTime: session.timestamp ?? lastTs,
+      endTime: lastTs,
+      status: "ok",
+      spans,
+      metadata: {
+        harness: "helix",
+        transcript: opts.fileName,
+        ...session.cwd !== undefined ? { cwd: session.cwd } : {},
+        ...session.version !== undefined ? { version: session.version } : {}
+      }
+    },
+    skipped: opts.skipped ?? 0,
+    ignored
+  };
+}
+function parseTranscript(raw) {
+  const records = [];
+  let skipped = 0;
+  for (const line of raw.split(`
+`)) {
+    const t = line.trim();
+    if (t === "")
+      continue;
+    try {
+      records.push(JSON.parse(t));
+    } catch {
+      skipped += 1;
+    }
+  }
+  return { records, skipped };
+}
+
+// src/commands/hooks/api.ts
+init_config();
+var API_TIMEOUT_MS = 5000;
+function resolveTenancyHeaders(config) {
+  if (config.defaultWorkspace && !config.defaultOrganization) {
+    return {
+      ok: false,
+      warning: "[mutagent hooks] Warning: a default workspace is set but no default organization, " + "so the server will reject every trace batch. " + `Fix with: mutagent config set organization <org-id>
+`
+    };
+  }
+  const headers = {};
+  if (config.defaultWorkspace)
+    headers["x-workspace-id"] = config.defaultWorkspace;
+  if (config.defaultOrganization)
+    headers["x-organization-id"] = config.defaultOrganization;
+  return { ok: true, headers };
+}
+async function sendBatchTrace(traces) {
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    process.stderr.write(`[mutagent hooks] Warning: Not authenticated. Run: mutagent auth login
+`);
+    return;
+  }
+  const config = loadConfig();
+  const endpoint = config.endpoint ?? "http://localhost:3003";
+  const headers = {
+    "x-api-key": apiKey,
+    "Content-Type": "application/json"
+  };
+  const tenancy = resolveTenancyHeaders(config);
+  if (!tenancy.ok) {
+    process.stderr.write(tenancy.warning);
+    return;
+  }
+  Object.assign(headers, tenancy.headers);
+  const controller = new AbortController;
+  const timeout = setTimeout(() => {
+    controller.abort();
+  }, API_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${endpoint}/api/traces/batch`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ traces }),
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      process.stderr.write(`[mutagent hooks] Warning: API returned ${String(response.status)}: ${body.slice(0, 200)}
+`);
+    }
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
 // src/commands/hooks/handlers-core.ts
 import { randomUUID } from "crypto";
 
@@ -4434,49 +4580,6 @@ function peekParentKind(state) {
   return state.parentStackKinds[state.parentStackKinds.length - 1] ?? null;
 }
 
-// src/commands/hooks/api.ts
-init_config();
-var API_TIMEOUT_MS = 5000;
-async function sendBatchTrace(traces) {
-  const apiKey = getApiKey();
-  if (!apiKey) {
-    process.stderr.write(`[mutagent hooks] Warning: Not authenticated. Run: mutagent auth login
-`);
-    return;
-  }
-  const config = loadConfig();
-  const endpoint = config.endpoint ?? "http://localhost:3003";
-  const headers = {
-    "x-api-key": apiKey,
-    "Content-Type": "application/json"
-  };
-  if (config.defaultWorkspace) {
-    headers["x-workspace-id"] = config.defaultWorkspace;
-  }
-  if (config.defaultOrganization) {
-    headers["x-organization-id"] = config.defaultOrganization;
-  }
-  const controller = new AbortController;
-  const timeout = setTimeout(() => {
-    controller.abort();
-  }, API_TIMEOUT_MS);
-  try {
-    const response = await fetch(`${endpoint}/api/traces/batch`, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({ traces }),
-      signal: controller.signal
-    });
-    if (!response.ok) {
-      const body = await response.text().catch(() => "");
-      process.stderr.write(`[mutagent hooks] Warning: API returned ${String(response.status)}: ${body.slice(0, 200)}
-`);
-    }
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
 // src/commands/hooks/handlers-core.ts
 async function readStdin() {
   const chunks = [];
@@ -5200,6 +5303,69 @@ Claude Code Session Telemetry:
 
   Or run: mutagent hooks install
     `);
+  hooks.command("import").argument("<files...>", "Session transcript files (.jsonl)").description("Import harness session transcripts as traces").option("--max-spans <n>", "Cap spans per session", "200").option("--dry-run", "Convert and report, but do not send").addHelpText("after", `
+Sources traces from transcripts already on disk, rather than capturing them
+live. mutagent-pi discovers these same files for its own /trace viewer; this
+ships them to the backend instead.
+
+Where they live:
+  ~/.mutagent/sessions*                 Helix
+  ~/Library/Caches/mutagent/helix       Helix (cache)
+
+Examples:
+  mutagent hooks import ~/.mutagent/sessions-rc/*.jsonl
+  mutagent hooks import session.jsonl --dry-run
+
+AI Agent Directive: use --dry-run first; it reports span counts and any
+unparseable lines without sending anything.
+    `).action(async (files, opts) => {
+    const maxSpans = Number.parseInt(opts.maxSpans ?? "200", 10);
+    if (!Number.isFinite(maxSpans) || maxSpans < 1) {
+      process.stderr.write(`[mutagent hooks] --max-spans must be a positive integer
+`);
+      process.exitCode = 2;
+      return;
+    }
+    const batch = [];
+    for (const file of files) {
+      let raw;
+      try {
+        raw = readFileSync8(file, "utf8");
+      } catch (err) {
+        process.stderr.write(`[mutagent hooks] skipped ${file}: ${err instanceof Error ? err.message : String(err)}
+`);
+        continue;
+      }
+      const { records, skipped } = parseTranscript(raw);
+      const { trace, ignored } = convertTranscript(records, {
+        fileName: basename(file),
+        maxSpans,
+        skipped
+      });
+      if (trace === null) {
+        process.stderr.write(`[mutagent hooks] ${basename(file)}: no session record, skipped
+`);
+        continue;
+      }
+      process.stderr.write(`[mutagent hooks] ${basename(file)}: ${String(trace.spans.length)} spans` + `${skipped > 0 ? `, ${String(skipped)} unparseable lines` : ""}` + `${ignored > 0 ? `, ${String(ignored)} records ignored` : ""}
+`);
+      batch.push(trace);
+    }
+    if (batch.length === 0) {
+      process.stderr.write(`[mutagent hooks] nothing to import
+`);
+      process.exitCode = 1;
+      return;
+    }
+    if (opts.dryRun === true) {
+      process.stderr.write(`[mutagent hooks] --dry-run: ${String(batch.length)} trace(s) not sent
+`);
+      return;
+    }
+    await sendBatchTrace(batch);
+    process.stderr.write(`[mutagent hooks] imported ${String(batch.length)} session(s)
+`);
+  });
   hooks.command("install").description("Install Mutagent hooks into .claude/settings.local.json (safe merge — never overwrites existing hooks)").option("--cwd <dir>", "Target directory (defaults to cwd)", process.cwd()).addHelpText("after", `
 Reads existing .claude/settings.local.json (if present) and deep-merges
 Mutagent telemetry hooks into each event array (all 10 events). Skips any
@@ -5305,7 +5471,7 @@ times is safe.
 import { Command as Command10 } from "commander";
 import chalk17 from "chalk";
 import { type as osType, release as osRelease } from "os";
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 import { join as join13, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 init_errors();
@@ -5318,7 +5484,7 @@ import { join as join12 } from "path";
 import {
   existsSync as fsExistsSync,
   statSync as fsStatSync,
-  readFileSync as readFileSync8,
+  readFileSync as readFileSync9,
   readdirSync as readdirSync2,
   openSync,
   readSync,
@@ -5329,7 +5495,7 @@ var TAIL_BYTES = 200000;
 function defaultReadTail(path, tailBytes) {
   const { size } = fsStatSync(path);
   if (size <= tailBytes) {
-    return { content: readFileSync8(path, "utf-8"), truncated: false };
+    return { content: readFileSync9(path, "utf-8"), truncated: false };
   }
   const fd = openSync(path, "r");
   try {
@@ -5692,7 +5858,7 @@ function getCliVersion() {
   try {
     const __dirname2 = dirname2(fileURLToPath(import.meta.url));
     const pkgPath = join13(__dirname2, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync9(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync10(pkgPath, "utf-8"));
     return pkg.version ?? "0.1.1";
   } catch {
     return "0.1.1";
@@ -5986,85 +6152,1422 @@ If mutagent-cli is not installed: mutagent install diagnostics`), isJson);
   return trace;
 }
 
-// src/bin/cli.ts
+// src/commands/helix/index.ts
+import { Command as Command13 } from "commander";
+import chalk24 from "chalk";
+
+// src/commands/helix/spawn.ts
+import chalk20 from "chalk";
+init_errors();
+
+// src/lib/sandbox-api.ts
 init_config();
+init_errors();
 
-// src/lib/brand.ts
-var BRAND = {
-  name: "MUTAGENT",
-  primary: "#7E47D7",
-  accent: "#45b8cc",
-  gradientFrom: "#45b8cc",
-  gradientTo: "#7E47D7"
-};
-var WORDMARK = [
-  " ███╗   ███╗ ██╗   ██╗ ████████╗  █████╗   ██████╗  ███████╗ ███╗   ██╗ ████████╗  ",
-  " ████╗ ████║ ██║   ██║ ╚══██╔══╝ ██╔══██╗ ██╔════╝  ██╔════╝ ████╗  ██║ ╚══██╔══╝  ",
-  " ██╔████╔██║ ██║   ██║    ██║    ███████║ ██║  ███╗ █████╗   ██╔██╗ ██║    ██║     ",
-  " ██║╚██╔╝██║ ██║   ██║    ██║    ██╔══██║ ██║   ██║ ██╔══╝   ██║╚██╗██║    ██║     ",
-  " ██║ ╚═╝ ██║ ╚██████╔╝    ██║    ██║  ██║ ╚██████╔╝ ███████╗ ██║ ╚████║    ██║     ",
-  " ╚═╝     ╚═╝  ╚═════╝     ╚═╝    ╚═╝  ╚═╝  ╚═════╝  ╚══════╝ ╚═╝  ╚═══╝    ╚═╝     "
-];
-var WORDMARK_MIN_COLUMNS = 84;
-function hexToRgb(hex) {
-  const n = parseInt(hex.slice(1), 16);
-  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+// src/lib/sandbox-token.ts
+init_secure_file();
+init_errors();
+import { existsSync as existsSync9, readFileSync as readFileSync11, mkdirSync as mkdirSync6, rmSync as rmSync2 } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join14, dirname as dirname3 } from "path";
+function sandboxTokenFile() {
+  const override = process.env.MUTAGENT_SANDBOX_TOKEN_FILE;
+  return override !== undefined && override !== "" ? override : join14(homedir4(), ".config", "mutagent", "sandbox-token.json");
 }
-var lerp = (a, b, t) => Math.round(a + (b - a) * t);
-function mix(from, to, t) {
-  return [lerp(from[0], to[0], t), lerp(from[1], to[1], t), lerp(from[2], to[2], t)];
+var EXPIRY_SKEW_MS = 60000;
+function isCacheShape(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const r = value;
+  return typeof r.token === "string" && typeof r.expiresAt === "number" && Number.isFinite(r.expiresAt) && typeof r.endpoint === "string" && typeof r.workspaceId === "string";
 }
-var ansi = (r, g, b) => `\x1B[38;2;${r};${g};${b}m`;
-var RESET = "\x1B[0m";
-function gradientLine(line, from, to) {
-  const chars = Array.from(line);
-  const n = chars.length;
-  let out = "";
-  chars.forEach((ch, i) => {
-    if (ch === " ") {
-      out += ch;
-      return;
+function createFileTokenStore(path) {
+  return {
+    read() {
+      if (!existsSync9(path))
+        return null;
+      try {
+        const parsed = JSON.parse(readFileSync11(path, "utf-8"));
+        return isCacheShape(parsed) ? parsed : null;
+      } catch {
+        return null;
+      }
+    },
+    write(entry) {
+      const dir = dirname3(path);
+      if (!existsSync9(dir))
+        mkdirSync6(dir, { recursive: true });
+      writeSecureFile(path, JSON.stringify(entry, null, 2));
+    },
+    clear() {
+      try {
+        rmSync2(path, { force: true });
+      } catch {}
     }
-    const [r, g, b] = mix(from, to, n > 1 ? i / (n - 1) : 0);
-    out += ansi(r, g, b) + ch;
-  });
-  return out + RESET;
+  };
 }
-function hasTruecolor(env = process.env) {
-  return /truecolor|24bit/i.test(env.COLORTERM ?? "");
+var fileTokenStore = {
+  read: () => createFileTokenStore(sandboxTokenFile()).read(),
+  write: (entry) => {
+    createFileTokenStore(sandboxTokenFile()).write(entry);
+  },
+  clear: () => {
+    createFileTokenStore(sandboxTokenFile()).clear();
+  }
+};
+function isUsable(entry, endpoint, workspaceId, now) {
+  return entry !== null && entry.endpoint === endpoint && entry.workspaceId === workspaceId && entry.expiresAt - EXPIRY_SKEW_MS > now;
 }
-function detectBannerEnv(stream = process.stdout, env = process.env) {
+function messageFrom(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === "object") {
+      const { message: value } = parsed;
+      if (typeof value === "string" && value !== "")
+        return value;
+    }
+  } catch {}
+  return "";
+}
+async function exchangeToken(input, deps = {}) {
+  const doFetch = deps.fetchImpl ?? fetch;
+  const now = (deps.now ?? Date.now)();
+  let response;
+  try {
+    response = await doFetch(`${input.endpoint}/api/sandbox/token`, {
+      method: "POST",
+      headers: {
+        "x-api-key": input.apiKey,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ workspaceId: input.workspaceId })
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new MutagentError("SANDBOX_UNREACHABLE", `Could not reach the MutagenT API at ${input.endpoint}: ${detail}`, "Check your connection, then verify the endpoint with: mutagent config list", 5);
+  }
+  if (response.status === 401) {
+    throw new AuthenticationError("Your MutagenT API key was rejected. It may have been revoked or expired.", { suggestions: ["mutagent auth login --browser", "mutagent auth status"] });
+  }
+  if (response.status === 403) {
+    const detail = messageFrom(await response.text().catch(() => ""));
+    throw new MutagentError("SANDBOX_WORKSPACE_FORBIDDEN", detail !== "" ? detail : `Your API key is valid, but this account cannot use workspace "${input.workspaceId}".`, `Pick a workspace you belong to: mutagent workspaces list, then mutagent config set workspace <id>`, 3);
+  }
+  if (!response.ok) {
+    const detail = messageFrom(await response.text().catch(() => ""));
+    throw new MutagentError("SANDBOX_TOKEN_EXCHANGE_FAILED", detail !== "" ? detail : `The MutagenT API returned ${String(response.status)} when issuing a sandbox token.`, 'Retry, and if it persists report it with: mutagent feedback send "<what happened>" --category cli');
+  }
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new MutagentError("INVALID_RESPONSE", "The server returned a non-JSON response when issuing a sandbox token.", 'Retry, and if it persists report it with: mutagent feedback send "<what happened>" --category cli');
+  }
+  if (typeof payload.token !== "string" || payload.token === "") {
+    throw new MutagentError("INVALID_RESPONSE", "The server issued a sandbox token response with no token in it.", 'Retry, and if it persists report it with: mutagent feedback send "<what happened>" --category cli');
+  }
+  const lifetimeMs = typeof payload.expiresIn === "number" && Number.isFinite(payload.expiresIn) && payload.expiresIn > 0 ? payload.expiresIn * 1000 : 0;
   return {
-    isTTY: stream.isTTY === true,
-    columns: stream.columns ?? 80,
-    truecolor: hasTruecolor(env),
-    disabled: env.MUTAGENT_NO_BANNER === "1"
+    token: payload.token,
+    expiresAt: now + lifetimeMs,
+    endpoint: input.endpoint,
+    workspaceId: input.workspaceId
   };
 }
-function renderBanner(env = detectBannerEnv()) {
-  if (env.disabled || !env.isTTY)
-    return "";
-  const from = hexToRgb(BRAND.gradientFrom);
-  const to = hexToRgb(BRAND.gradientTo);
-  const wide = env.columns >= WORDMARK_MIN_COLUMNS;
-  const art = wide ? WORDMARK : [`  ${BRAND.name}`];
-  const lines = env.truecolor ? art.map((l) => gradientLine(l, from, to)) : art.map((l) => `${ansi(...from)}${l}${RESET}`);
-  return `
-${lines.join(`
-`)}
-`;
+async function getOperatorToken(input, options = {}, deps = {}) {
+  const store = deps.store ?? fileTokenStore;
+  const now = (deps.now ?? Date.now)();
+  if (options.forceRefresh !== true) {
+    const cached = store.read();
+    if (isUsable(cached, input.endpoint, input.workspaceId, now))
+      return cached.token;
+  }
+  const fresh = await exchangeToken(input, deps);
+  store.write(fresh);
+  return fresh.token;
+}
+function clearCachedToken(deps = {}) {
+  (deps.store ?? fileTokenStore).clear();
 }
 
-// src/lib/global-version-flag.ts
-var GLOBAL_VALUE_OPTIONS = new Set(["--api-key", "--endpoint"]);
-function findSubcommandIndex(rawArgs) {
-  for (let i = 0;i < rawArgs.length; i++) {
-    const arg = rawArgs[i];
-    if (arg === undefined)
-      continue;
-    if (arg === "--")
-      return i + 1 < rawArgs.length ? i + 1 : -1;
-    if (arg.startsWith("-")) {
+// src/lib/sandbox-api.ts
+function resolveConnection() {
+  const apiKey = getApiKey();
+  if (!apiKey)
+    throw new AuthenticationError;
+  const config = loadConfig();
+  const configured = config.endpoint?.trim();
+  const endpoint = (configured === undefined || configured === "" ? "https://api.mutagent.io" : configured).replace(/\/+$/, "");
+  const workspaceId = requireWorkspace(config.defaultWorkspace);
+  const headers = { "x-workspace-id": workspaceId };
+  if (config.defaultOrganization)
+    headers["x-organization-id"] = config.defaultOrganization;
+  return { endpoint, apiKey, workspaceId, headers };
+}
+function requireWorkspace(workspaceId) {
+  if (workspaceId === undefined || workspaceId.trim() === "") {
+    throw new WorkspaceContextError("A workspace is required: sandbox access is minted per workspace, not per account.");
+  }
+  return workspaceId.trim();
+}
+async function fetchWithTokenRetry(url, init, baseHeaders, transport) {
+  const attempt = async (forceRefresh) => transport.doFetch(url, {
+    ...init,
+    headers: { ...baseHeaders, Authorization: await transport.authorization(forceRefresh) }
+  });
+  const first = await attempt(false);
+  if (first.status !== 401)
+    return first;
+  transport.onTokenRejected();
+  return attempt(true);
+}
+async function sandboxFetch(path, init, deps = {}) {
+  const connection = resolveConnection();
+  const { endpoint } = connection;
+  try {
+    const response = await fetchWithTokenRetry(`${endpoint}${path}`, init, { ...connection.headers, ...toHeaderRecord(init.headers) }, {
+      doFetch: fetch,
+      authorization: async (forceRefresh) => `Bearer ${await getOperatorToken({ endpoint, apiKey: connection.apiKey, workspaceId: connection.workspaceId }, { forceRefresh }, deps)}`,
+      onTokenRejected: () => {
+        clearCachedToken(deps);
+      }
+    });
+    return { response, endpoint };
+  } catch (error) {
+    if (error instanceof MutagentError)
+      throw error;
+    throw toNetworkError(error, endpoint);
+  }
+}
+async function toCliError(response, sandboxId) {
+  const body = await response.text().catch(() => "");
+  const message = extractMessage(body) || response.statusText || "Request failed";
+  if (response.status === 401)
+    return new AuthenticationError;
+  if (response.status === 404 && sandboxId)
+    return new NotFoundError("Sandbox", sandboxId);
+  return new ApiError(response.status, message);
+}
+function extractMessage(body) {
+  const outer = parseRecord(body);
+  if (!outer)
+    return body.slice(0, 300);
+  const code = typeof outer.error === "string" ? outer.error : "";
+  const detail = typeof outer.message === "string" ? outer.message : "";
+  const nested = parseRecord(detail);
+  const summary = nested && typeof nested.summary === "string" ? nested.summary : "";
+  if (summary !== "") {
+    const property = nested && typeof nested.property === "string" ? nested.property : "";
+    const where = property === "" ? "" : ` (at ${property})`;
+    return code === "" ? `${summary}${where}` : `${code}: ${summary}${where}`;
+  }
+  if (detail !== "" && detail.length <= 400)
+    return detail;
+  if (code !== "")
+    return code;
+  return body.slice(0, 300);
+}
+function toHeaderRecord(init) {
+  if (!init)
+    return {};
+  if (init instanceof Headers) {
+    const record = {};
+    init.forEach((value, key) => {
+      record[key] = value;
+    });
+    return record;
+  }
+  if (Array.isArray(init))
+    return Object.fromEntries(init);
+  return init;
+}
+function toNetworkError(error, endpoint) {
+  const detail = error instanceof Error ? error.message : String(error);
+  return new MutagentError("SANDBOX_UNREACHABLE", `Could not reach the MutagenT API at ${endpoint}: ${detail}`, "Check your connection, then verify the endpoint with: mutagent config list", 5);
+}
+async function requestJson(path, init = {}) {
+  const { sandboxId, ...requestInit } = init;
+  const { response } = await sandboxFetch(path, {
+    ...requestInit,
+    headers: { "Content-Type": "application/json", ...toHeaderRecord(requestInit.headers) }
+  });
+  if (!response.ok)
+    throw await toCliError(response, sandboxId);
+  const text = await response.text();
+  if (text.trim() === "")
+    return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new MutagentError("INVALID_RESPONSE", `The server returned a non-JSON response for ${path}.`, 'Retry, and if it persists report it with: mutagent feedback send "<what happened>" --category cli');
+  }
+}
+async function spawnSandbox(definition) {
+  return requestJson("/api/sandbox", {
+    method: "POST",
+    body: JSON.stringify({ definition })
+  });
+}
+async function listSandboxes() {
+  const body = await requestJson("/api/sandbox");
+  return unwrapList(body);
+}
+function unwrapList(body) {
+  if (Array.isArray(body))
+    return body;
+  if (body && typeof body === "object") {
+    for (const key of ["sandboxes", "spans", "traces", "presets", "data", "items"]) {
+      const value = body[key];
+      if (Array.isArray(value))
+        return value;
+    }
+  }
+  return [];
+}
+async function destroySandbox(id) {
+  const { response } = await sandboxFetch(`/api/sandbox/${encodeURIComponent(id)}`, {
+    method: "DELETE"
+  });
+  if (response.status === 404)
+    return;
+  if (!response.ok)
+    throw await toCliError(response, id);
+}
+async function execSandbox(id, body) {
+  return requestJson(`/api/sandbox/${encodeURIComponent(id)}/exec`, {
+    method: "POST",
+    body: JSON.stringify(body),
+    sandboxId: id
+  });
+}
+async function oneShotRun(body) {
+  return requestJson("/api/sandbox/run", {
+    method: "POST",
+    body: JSON.stringify(body)
+  });
+}
+async function agentRun(body) {
+  return requestJson("/api/sandbox/agent/run", {
+    method: "POST",
+    body: JSON.stringify(body)
+  });
+}
+async function listPresets() {
+  return requestJson("/api/sandbox/presets");
+}
+async function fetchSandboxTraces(id) {
+  return requestJson(`/api/sandbox/${encodeURIComponent(id)}/traces`, { sandboxId: id });
+}
+async function openAttachStream(id, options = {}) {
+  const query = options.since === undefined ? "" : `?since=${String(options.since)}`;
+  return openStream(`/api/sandbox/${encodeURIComponent(id)}/stream${query}`, id, options);
+}
+async function openExecStream(id, body, options = {}) {
+  return openStream(`/api/sandbox/${encodeURIComponent(id)}/exec?stream=1`, id, options, {
+    method: "POST",
+    body: JSON.stringify(body),
+    headers: { "Content-Type": "application/json" }
+  });
+}
+async function openStream(path, sandboxId, options, init = {}) {
+  const { response } = await sandboxFetch(path, {
+    ...init,
+    headers: { Accept: "text/event-stream", ...toHeaderRecord(init.headers) },
+    signal: options.signal
+  });
+  if (!response.ok)
+    throw await toCliError(response, sandboxId);
+  if (!response.body) {
+    throw new MutagentError("EMPTY_STREAM", "The server accepted the stream request but sent no body.", `Retry with: mutagent helix attach ${sandboxId}`);
+  }
+  return response.body;
+}
+function sandboxLinks(id) {
+  const base = `/api/sandbox/${encodeURIComponent(id)}`;
+  return { api: base, stream: `${base}/stream`, traces: `${base}/traces` };
+}
+function parseOutputPayload(data) {
+  const record = parseRecord(data);
+  if (!record)
+    return null;
+  const { seq, ts, text } = record;
+  if (typeof seq !== "number" || typeof text !== "string")
+    return null;
+  return { seq, ts: typeof ts === "string" ? ts : "", text };
+}
+function parseStatusPayload(data) {
+  const record = parseRecord(data);
+  if (!record)
+    return null;
+  if (typeof record.state !== "string")
+    return null;
+  return {
+    state: record.state,
+    exitCode: typeof record.exitCode === "number" ? record.exitCode : null
+  };
+}
+function parseErrorPayload(data) {
+  const record = parseRecord(data);
+  const message = record && typeof record.message === "string" ? record.message : data.trim();
+  return { message: message === "" ? "The server reported an unspecified stream error." : message };
+}
+function parseRecord(data) {
+  try {
+    const parsed = JSON.parse(data);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {}
+  return null;
+}
+function hostArch() {
+  if (process.arch === "arm64")
+    return "arm64";
+  if (process.arch === "x64")
+    return "x86_64";
+  return null;
+}
+
+// src/lib/tty.ts
+function isPlainOutput() {
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "")
+    return true;
+  if (process.env.MUTAGENT_NON_INTERACTIVE === "true")
+    return true;
+  if (process.env.CI === "true")
+    return true;
+  return !process.stdout.isTTY;
+}
+function canAnimate(isJson) {
+  return !isJson && !isPlainOutput();
+}
+
+// src/commands/helix/session.ts
+import chalk19 from "chalk";
+
+// src/lib/sse.ts
+var DEFAULT_EVENT_NAME = "message";
+
+class SseDecoder {
+  buffer = "";
+  eventName = null;
+  dataLines = [];
+  push(chunk) {
+    this.buffer += chunk;
+    const dispatched = [];
+    let newlineAt = this.buffer.indexOf(`
+`);
+    while (newlineAt !== -1) {
+      let line = this.buffer.slice(0, newlineAt);
+      this.buffer = this.buffer.slice(newlineAt + 1);
+      if (line.endsWith("\r"))
+        line = line.slice(0, -1);
+      const event = this.consumeLine(line);
+      if (event)
+        dispatched.push(event);
+      newlineAt = this.buffer.indexOf(`
+`);
+    }
+    return dispatched;
+  }
+  consumeLine(line) {
+    if (line === "")
+      return this.dispatch();
+    if (line.startsWith(":"))
+      return null;
+    const colonAt = line.indexOf(":");
+    const field = colonAt === -1 ? line : line.slice(0, colonAt);
+    let value = colonAt === -1 ? "" : line.slice(colonAt + 1);
+    if (value.startsWith(" "))
+      value = value.slice(1);
+    if (field === "event") {
+      this.eventName = value;
+    } else if (field === "data") {
+      this.dataLines.push(value);
+    }
+    return null;
+  }
+  dispatch() {
+    const name = this.eventName;
+    const data = this.dataLines;
+    this.eventName = null;
+    this.dataLines = [];
+    if (data.length === 0)
+      return null;
+    return { event: name ?? DEFAULT_EVENT_NAME, data: data.join(`
+`) };
+  }
+}
+async function* readSseEvents(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder;
+  const framer = new SseDecoder;
+  try {
+    for (;; ) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      for (const event of framer.push(decoder.decode(value, { stream: true }))) {
+        yield event;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/lib/sandbox-stream.ts
+init_errors();
+var DEFAULT_RETRY = { attempts: 3, baseDelayMs: 500 };
+async function runStreamSession(options) {
+  const retry = options.retry ?? DEFAULT_RETRY;
+  const sleep2 = options.sleep ?? delay;
+  const { sink, signal } = options;
+  let lastSeq = options.since ?? 0;
+  let exitCode = null;
+  let reconnects = 0;
+  let gaps = 0;
+  let attempt = 0;
+  const detached = () => ({ end: "detached", lastSeq, exitCode, reconnects, gaps });
+  const isAborted = () => signal.aborted;
+  for (;; ) {
+    if (isAborted())
+      return detached();
+    let stream;
+    try {
+      stream = await options.open({ since: lastSeq > 0 ? lastSeq : undefined, signal });
+    } catch (error) {
+      if (isAborted())
+        return detached();
+      if (reconnects === 0 && attempt === 0)
+        throw error;
+      attempt += 1;
+      if (attempt > retry.attempts)
+        throw exhausted(lastSeq, error);
+      reconnects += 1;
+      sink.notice(reconnectNotice(attempt, retry.attempts, lastSeq));
+      await sleep2(backoffMs(retry.baseDelayMs, attempt), signal);
+      continue;
+    }
+    let exited = false;
+    try {
+      for await (const event of readSseEvents(stream)) {
+        attempt = 0;
+        if (event.event === "stdout" || event.event === "stderr") {
+          const payload = parseOutputPayload(event.data);
+          if (!payload)
+            continue;
+          if (payload.seq > lastSeq + 1 && lastSeq > 0) {
+            gaps += 1;
+            sink.notice(gapNotice(lastSeq, payload.seq));
+          }
+          lastSeq = Math.max(lastSeq, payload.seq);
+          if (event.event === "stdout")
+            sink.stdout(payload.text, payload.seq);
+          else
+            sink.stderr(payload.text, payload.seq);
+          continue;
+        }
+        if (event.event === "status") {
+          const payload = parseStatusPayload(event.data);
+          if (payload?.state === "exited") {
+            exitCode = payload.exitCode;
+            exited = true;
+            break;
+          }
+          continue;
+        }
+        if (event.event === "error") {
+          const { message } = parseErrorPayload(event.data);
+          if (mentionsLostBuffer(message)) {
+            gaps += 1;
+            sink.notice(`Output before this point is unavailable: ${message}. ` + "What follows is not continuous with what came before.");
+          } else {
+            sink.notice(`Stream error: ${message}`);
+          }
+          continue;
+        }
+      }
+    } catch (error) {
+      if (isAborted())
+        return detached();
+      attempt += 1;
+      if (attempt > retry.attempts)
+        throw exhausted(lastSeq, error);
+      reconnects += 1;
+      sink.notice(reconnectNotice(attempt, retry.attempts, lastSeq));
+      await sleep2(backoffMs(retry.baseDelayMs, attempt), signal);
+      continue;
+    }
+    if (exited)
+      return { end: "exited", lastSeq, exitCode, reconnects, gaps };
+    if (isAborted())
+      return detached();
+    attempt += 1;
+    if (attempt > retry.attempts)
+      throw exhausted(lastSeq, null);
+    reconnects += 1;
+    sink.notice(reconnectNotice(attempt, retry.attempts, lastSeq));
+    await sleep2(backoffMs(retry.baseDelayMs, attempt), signal);
+  }
+}
+function backoffMs(base, attempt) {
+  return base * 2 ** (attempt - 1);
+}
+function reconnectNotice(attempt, max, lastSeq) {
+  return `Connection lost. Reconnecting (${String(attempt)}/${String(max)}) from seq ${String(lastSeq)}...`;
+}
+function gapNotice(lastSeq, nextSeq) {
+  const missing = nextSeq - lastSeq - 1;
+  return `Output gap: ${String(missing)} event(s) between seq ${String(lastSeq)} and ` + `${String(nextSeq)} are unavailable — the server buffer rolled past the resume point. ` + "What follows is not continuous with what came before.";
+}
+function exhausted(lastSeq, cause) {
+  const detail = cause instanceof Error ? ` (${cause.message})` : "";
+  return new MutagentError("STREAM_DISCONNECTED", `Lost the sandbox stream and could not reconnect${detail}.`, `The sandbox is still running — nothing was destroyed. Resume with: mutagent helix attach <id> --since ${String(lastSeq)}`, 5);
+}
+function mentionsLostBuffer(message) {
+  return /buffer|rolled|expired|evicted|no longer available|too old/i.test(message);
+}
+function delay(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      resolve();
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/commands/helix/session.ts
+init_errors();
+function dim(text) {
+  return isPlainOutput() ? text : chalk19.dim(text);
+}
+function reattachHint(id, lastSeq) {
+  const since = lastSeq > 0 ? ` --since ${String(lastSeq)}` : "";
+  return `mutagent helix attach ${id}${since}`;
+}
+function createSessionSink(isJson) {
+  if (isJson) {
+    return {
+      stdout: (text, seq) => writeEvent("stdout", { seq, text }),
+      stderr: (text, seq) => writeEvent("stderr", { seq, text }),
+      notice: (message) => {
+        process.stderr.write(`${JSON.stringify({ type: "notice", message })}
+`);
+      }
+    };
+  }
+  return {
+    stdout: (text) => {
+      process.stdout.write(text);
+    },
+    stderr: (text) => {
+      process.stderr.write(text);
+    },
+    notice: (message) => {
+      process.stderr.write(`${dim(`[mutagent] ${message}`)}
+`);
+    }
+  };
+}
+function writeEvent(type, fields) {
+  process.stdout.write(`${JSON.stringify({ type, ...fields })}
+`);
+}
+async function attachToSandbox(options) {
+  const sink = createSessionSink(options.isJson);
+  const controller = new AbortController;
+  const onSigint = () => {
+    controller.abort();
+  };
+  process.on("SIGINT", onSigint);
+  try {
+    if (options.announce)
+      sink.notice(options.announce);
+    const result = await runStreamSession({
+      open: options.open,
+      sink,
+      since: options.since,
+      signal: controller.signal
+    });
+    reportOutcome(options.id, result, sink);
+    return result;
+  } finally {
+    process.removeListener("SIGINT", onSigint);
+  }
+}
+function reportOutcome(id, result, sink) {
+  if (result.end === "detached") {
+    sink.notice(`Detached. Sandbox ${id} is still running — nothing was destroyed.`);
+    sink.notice(`Re-attach with: ${reattachHint(id, result.lastSeq)}`);
+    sink.notice(`Destroy it with: mutagent helix rm ${id} --force`);
+    return;
+  }
+  if (result.gaps > 0) {
+    sink.notice(`Session ended, but ${String(result.gaps)} gap(s) occurred — the output above is not complete.`);
+  }
+  if (result.exitCode === null) {
+    sink.notice(`Sandbox ${id} exited (no exit code reported).`);
+    return;
+  }
+  sink.notice(`Sandbox ${id} exited with code ${String(result.exitCode)}.`);
+  if (result.exitCode !== 0) {
+    process.exitCode = result.exitCode;
+  }
+}
+function parseSince(raw) {
+  if (raw === undefined)
+    return;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new MutagentError("INVALID_ARGUMENTS", `--since must be a non-negative sequence number, got "${raw}".`, "Sequence numbers start at 1 and are printed when a session detaches.");
+  }
+  return value;
+}
+
+// src/commands/helix/spawn.ts
+var ARCHES = ["x86_64", "arm64"];
+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", `
+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
+
+--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
+something without knowing an image reference, use 'mutagent helix run' or
+'mutagent helix exec', which spawn from a named preset instead.
+
+--arch defaults to this host's architecture, on the assumption that you are
+running an image you just built. A definition whose arch does not match its
+image is rejected at preflight rather than emulated, so set it explicitly when
+the image was built elsewhere.
+
+--env names an Environment (a stored bundle of secrets and variables). It is a
+DIFFERENT axis from --provider, which selects the backend. Secrets never travel
+on the command line.
+
+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:
+  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.
+  A spawned sandbox costs resources until 'mutagent helix rm <id>' — confirm
+  with the user before spawning, and tell them the ID afterwards.
+      `).action(async (options) => {
+    const isJson = getJsonFlag(parent);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const definition = buildDefinition(options);
+      const sandbox = await createSandbox(definition, isJson);
+      const id = requireId(sandbox);
+      if (options.detach) {
+        reportDetached(sandbox, id, output, isJson);
+        return;
+      }
+      if (isJson) {
+        process.stdout.write(`${JSON.stringify({ type: "spawned", sandbox })}
+`);
+      }
+      const result = await attachToSandbox({
+        id,
+        isJson,
+        announce: `Spawned sandbox ${id}. Ctrl-C detaches without destroying it.`,
+        open: ({ since, signal }) => openAttachStream(id, { since, signal })
+      });
+      if (isJson) {
+        console.log(JSON.stringify({
+          success: true,
+          sandbox,
+          end: result.end,
+          exitCode: result.exitCode,
+          lastSeq: result.lastSeq,
+          reconnects: result.reconnects,
+          gaps: result.gaps,
+          _links: sandboxLinks(id)
+        }));
+      }
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+function buildDefinition(options) {
+  const image = options.image?.trim() ?? "";
+  if (image === "") {
+    throw new MutagentError("MISSING_ARGUMENTS", "--image is required and cannot be empty.", "Example: mutagent helix spawn --image alpine:3.20");
+  }
+  const arch = resolveArch(options.arch);
+  const definition = {
+    name: options.name?.trim() || deriveName(image),
+    image,
+    arch
+  };
+  if (options.provider)
+    definition.provider = options.provider;
+  if (options.env)
+    definition.environment = options.env;
+  return definition;
+}
+function resolveArch(requested) {
+  if (requested !== undefined) {
+    const value = requested.trim();
+    if (!ARCHES.includes(value)) {
+      throw new MutagentError("INVALID_ARGUMENTS", `--arch must be one of ${ARCHES.join(", ")}, got "${requested}".`, "Use --arch arm64 for Apple Silicon images, --arch x86_64 for Intel/AMD.");
+    }
+    return value;
+  }
+  const detected = hostArch();
+  if (detected === null) {
+    throw new MutagentError("MISSING_ARGUMENTS", `This host reports architecture "${process.arch}", which has no sandbox equivalent.`, `Name it explicitly: --arch ${ARCHES.join(" | --arch ")}`);
+  }
+  return detected;
+}
+function deriveName(image) {
+  const slug = image.replace(/^.*\//, "").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120);
+  return slug === "" ? "mutagent-cli" : slug;
+}
+async function createSandbox(definition, isJson) {
+  if (!canAnimate(isJson))
+    return spawnSandbox(definition);
+  const { default: ora2 } = await import("ora");
+  const spinner = ora2(`Spawning ${definition.image} (${definition.arch})...`).start();
+  try {
+    const sandbox = await spawnSandbox(definition);
+    spinner.succeed(chalk20.green(`Sandbox ${String(sandbox.id)} spawned`));
+    return sandbox;
+  } catch (error) {
+    spinner.fail(chalk20.red("Spawn failed"));
+    throw error;
+  }
+}
+function requireId(sandbox) {
+  if (typeof sandbox.id === "string" && sandbox.id !== "")
+    return sandbox.id;
+  throw new MutagentError("INVALID_RESPONSE", "The server created a sandbox but did not return an id.", "The sandbox may still be running — check with: mutagent helix ls");
+}
+function reportDetached(sandbox, id, output, isJson) {
+  if (isJson) {
+    output.output({
+      success: true,
+      sandbox,
+      _links: sandboxLinks(id),
+      _directive: {
+        instruction: "The sandbox is running and detached. Attach to stream its output, or destroy it when finished — a detached sandbox consumes resources until removed.",
+        next: [`mutagent helix attach ${id} --json`, `mutagent helix rm ${id} --json`]
+      }
+    });
+    return;
+  }
+  output.output({
+    id,
+    status: sandbox.status ?? "unknown",
+    provider: sandbox.provider ?? "unknown",
+    arch: sandbox.arch ?? "unknown",
+    definition: sandbox.definitionName ?? "unknown"
+  });
+  console.log("");
+  console.log(`  Attach:  ${reattachHint(id, 0)}`);
+  console.log(`  Destroy: mutagent helix rm ${id} --force`);
+}
+
+// src/commands/helix/attach.ts
+import chalk21 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
+
+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'
+destroys a sandbox.
+
+Sandbox stdout goes to stdout and sandbox stderr goes to stderr, so redirects
+and pipes behave as they would for a local process. Everything this CLI says
+about the session goes to stderr.
+
+If the connection drops, attach reconnects from the last sequence number seen.
+If the server's buffer has rolled past that point, the missing range is stated
+plainly rather than being papered over.
+
+AI Agent Directive:
+  Use --json. Output is NDJSON — one object per line, {"type":"stdout"|"stderr"|
+  "notice", ...} — because a live stream cannot be one JSON document until it is
+  over. The final line is a complete summary object; read it with 'tail -1' if
+  you only need the result.
+  Run 'mutagent helix ls --json' first to confirm the sandbox is running.
+      `).action(async (id, options) => {
+    const isJson = getJsonFlag(parent);
+    try {
+      const since = parseSince(options.since);
+      const result = await attachToSandbox({
+        id,
+        isJson,
+        since,
+        announce: `Attaching to sandbox ${id}. Ctrl-C detaches without destroying it.`,
+        open: ({ since: resumeFrom, signal }) => openAttachStream(id, { since: resumeFrom, signal })
+      });
+      if (isJson) {
+        console.log(JSON.stringify({
+          success: true,
+          sandboxId: id,
+          end: result.end,
+          exitCode: result.exitCode,
+          lastSeq: result.lastSeq,
+          reconnects: result.reconnects,
+          gaps: result.gaps,
+          _links: sandboxLinks(id)
+        }));
+      }
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+
+// src/commands/helix/run.ts
+import chalk22 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").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
+
+TWO PROMPTS, AND THEY ARE NOT THE SAME THING:
+  --prompt   WHO the agent is — its definition, its standing instructions.
+  <task...>  WHAT to do this turn.
+They are never concatenated. Passing the task as --prompt produces a run that
+starts, looks plausible, and answers a different question.
+
+This is a ONE-SHOT call: it spawns a fresh sandbox from a preset, takes the turn
+and tears the sandbox down. There is no sandbox id argument because there is no
+endpoint that runs an agent turn inside an existing box. Pass --keep to hold the
+sandbox open; the id is reported so you can attach or exec against it.
+
+The turn is blocking and does not stream — the server returns the whole result.
+Its exit code becomes this command's exit code. See 'mutagent helix presets' for
+what --preset accepts.
+
+AI Agent Directive:
+  --json returns ONE object: { success, result: { sandboxId, exitCode, stdout,
+  stderr, timedOut, tornDown }, _links }. No NDJSON here — the call is blocking.
+  Both --prompt and the task are required; do not fold one into the other.
+      `).action(async (taskParts, options) => {
+    const isJson = getJsonFlag(parent);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const task = taskParts.join(" ").trim();
+      if (task === "") {
+        throw new MutagentError("MISSING_ARGUMENTS", "The task is required — it is WHAT the agent should do this turn.", 'Run: mutagent helix run "<what to do>" --prompt "<who the agent is>"');
+      }
+      const prompt = options.prompt?.trim() ?? "";
+      if (prompt === "") {
+        throw new MutagentError("MISSING_ARGUMENTS", "--prompt is required — it is WHO the agent is, not what it should do.", `The task you already passed is the WHAT. Add the agent definition:
+  --prompt "You are a ..." (or --prompt "$(cat agent.md)")`);
+      }
+      const result = await agentRun({
+        prompt,
+        task,
+        ...oneShotFields(options.preset, options.keep, options.timeoutMs)
+      });
+      reportResult(result, output, isJson, { prompt, task });
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+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
+
+Put ${chalk22.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'")}
+
+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
+                  path is blocking, so --no-stream is redundant there and
+                  --preset / --keep apply only there.
+
+The command's exit code becomes this command's exit code.
+
+AI Agent Directive:
+  Use --no-stream --json (or the one-shot form, which is always blocking) for a
+  result you intend to parse: one object, no NDJSON to reassemble.
+  Run 'mutagent helix ls --json' first to confirm a --sandbox id is running.
+      `).action(async (argv, options) => {
+    const isJson = getJsonFlag(parent);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const command = argv.filter((part) => part !== "");
+      if (command.length === 0) {
+        throw new MutagentError("MISSING_ARGUMENTS", "A command is required.", "Run: mutagent helix exec -- <command> [args...]");
+      }
+      const timeoutMs = parseTimeout(options.timeoutMs);
+      const id = options.sandbox?.trim();
+      if (id === undefined || id === "") {
+        const result = await oneShotRun({
+          command,
+          ...options.cwd === undefined ? {} : { cwd: options.cwd },
+          ...oneShotFields(options.preset, options.keep, options.timeoutMs)
+        });
+        reportResult(result, output, isJson, { command });
+        return;
+      }
+      rejectOneShotOnlyFlags(options);
+      const body = {
+        command,
+        ...options.cwd === undefined ? {} : { cwd: options.cwd },
+        ...timeoutMs === undefined ? {} : { timeoutMs }
+      };
+      if (options.stream === false) {
+        const result = await execSandbox(id, body);
+        reportResult(result, output, isJson, { command, sandboxId: id });
+        return;
+      }
+      const session = await attachToSandbox({
+        id,
+        isJson,
+        announce: `Running in sandbox ${id}. Ctrl-C detaches without stopping it.`,
+        open: createExecOpener(id, body)
+      });
+      if (isJson) {
+        console.log(JSON.stringify({
+          success: true,
+          sandboxId: id,
+          command,
+          end: session.end,
+          exitCode: session.exitCode,
+          lastSeq: session.lastSeq,
+          reconnects: session.reconnects,
+          gaps: session.gaps,
+          _links: sandboxLinks(id)
+        }));
+      }
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+function rejectOneShotOnlyFlags(options) {
+  const offenders = [];
+  if (options.preset !== undefined)
+    offenders.push("--preset");
+  if (options.keep === true)
+    offenders.push("--keep");
+  if (offenders.length === 0)
+    return;
+  throw new MutagentError("INVALID_ARGUMENTS", `${offenders.join(" and ")} ${offenders.length === 1 ? "applies" : "apply"} only to a fresh sandbox, but --sandbox names an existing one.`, "Drop --sandbox to run one-shot in a fresh box, or drop these flags to run in the existing one.");
+}
+function createExecOpener(id, body) {
+  let submitted = false;
+  return ({ since, signal }) => {
+    if (!submitted) {
+      submitted = true;
+      return openExecStream(id, body, { signal });
+    }
+    return openAttachStream(id, { since, signal });
+  };
+}
+function oneShotFields(preset, keep, timeoutMs) {
+  const parsed = parseTimeout(timeoutMs);
+  return {
+    ...preset === undefined ? {} : { preset },
+    ...keep === true ? { keep: true } : {},
+    ...parsed === undefined ? {} : { timeoutMs: parsed }
+  };
+}
+function parseTimeout(raw) {
+  if (raw === undefined)
+    return;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new MutagentError("INVALID_ARGUMENTS", `--timeout-ms must be a positive whole number of milliseconds, got "${raw}".`, "Example: --timeout-ms 30000 for thirty seconds.");
+  }
+  return value;
+}
+function reportResult(result, output, isJson, context) {
+  if (isJson) {
+    const links = typeof result.sandboxId === "string" ? sandboxLinks(result.sandboxId) : undefined;
+    output.output({
+      success: true,
+      ...context,
+      result,
+      ...links === undefined ? {} : { _links: links }
+    });
+  } else {
+    if (result.stdout)
+      process.stdout.write(result.stdout);
+    if (result.stderr)
+      process.stderr.write(result.stderr);
+    if (result.timedOut)
+      process.stderr.write(`[mutagent] The command timed out.
+`);
+    if (typeof result.sandboxId === "string" && result.tornDown === false) {
+      process.stderr.write(`[mutagent] Sandbox ${result.sandboxId} is still running. Destroy it with: mutagent helix rm ${result.sandboxId} --force
+`);
+    }
+  }
+  if (typeof result.exitCode === "number" && result.exitCode !== 0) {
+    process.exitCode = result.exitCode;
+  }
+}
+
+// src/commands/helix/inventory.ts
+import chalk23 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
+
+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>
+
+An empty list is a normal result, not an error: it means no sandbox is running.
+
+AI Agent Directive:
+  Run this before attach, exec or rm to confirm the sandbox exists and is
+  running. --json returns { sandboxes: [...], count: N }.
+      `).action(async () => {
+    const isJson = getJsonFlag(parent);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const sandboxes = await listSandboxes();
+      if (isJson) {
+        output.output({
+          sandboxes: sandboxes.map((s) => ({ ...s, _links: sandboxLinks(String(s.id)) })),
+          count: sandboxes.length
+        });
+        return;
+      }
+      if (sandboxes.length === 0) {
+        console.log(chalk23.gray("No sandboxes running."));
+        console.log("");
+        console.log("  Start one: mutagent helix spawn --image <ref>");
+        return;
+      }
+      output.output(sandboxes.map(toRow));
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+function toRow(sandbox) {
+  return {
+    id: sandbox.id,
+    status: sandbox.status ?? "unknown",
+    provider: sandbox.provider ?? "",
+    arch: sandbox.arch ?? "",
+    definition: sandbox.definitionName ?? "",
+    created: typeof sandbox.createdAt === "string" ? new Date(sandbox.createdAt).toLocaleString() : ""
+  };
+}
+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
+
+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
+or a region. Image references are deliberately not returned — if you need
+image-level detail you are looking for 'helix spawn --image'.
+
+AI Agent Directive:
+  --json returns { presets: [...], default: <name|null>, count: N }. Read this
+  before passing --preset; an unknown preset is rejected by the server.
+      `).action(async () => {
+    const isJson = getJsonFlag(parent);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const list = await listPresets();
+      const presets = list.presets;
+      if (isJson) {
+        output.output({ presets, default: list.default, count: presets.length });
+        return;
+      }
+      if (presets.length === 0) {
+        console.log(chalk23.gray("No presets configured on this backend."));
+        console.log("");
+        console.log("  Spawn with an explicit image: mutagent helix spawn --image <ref>");
+        return;
+      }
+      output.output(presets.map((p) => ({
+        name: p.name,
+        default: p.name === list.default ? "yes" : "",
+        arch: p.arch ?? "",
+        provider: p.provider ?? "",
+        description: p.description ?? ""
+      })));
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+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
+
+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.")}
+
+AI Agent Directive:
+  Destroying a sandbox ends any session running in it and cannot be undone.
+  Confirm with the user before running it, then pass --force (or --json).
+      `).action(async (id, options) => {
+    const isJson = getJsonFlag(parent);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      if (!options.force && !isJson) {
+        throw new MutagentError("CONFIRMATION_REQUIRED", `Destroying sandbox ${id} requires confirmation. Any session running in it ends immediately.`, `[Agent: confirm with the user first]
+Use --force to confirm: mutagent helix rm ${id} --force`);
+      }
+      await destroySandbox(id);
+      if (isJson) {
+        output.output({
+          success: true,
+          deletedId: id,
+          _links: sandboxLinks(id),
+          _directive: {
+            instruction: "The sandbox is destroyed. Any session it was running has ended. Spawn a new one to continue.",
+            next: ["mutagent helix ls --json", "mutagent helix spawn --image <ref> --detach --json"]
+          }
+        });
+        return;
+      }
+      output.success(`Sandbox ${id} destroyed`);
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+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
+
+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
+that is what the server returns; the command keeps the familiar name.
+
+An empty result means no spans were captured. That is not the same as the box
+having done nothing: telemetry ingest has to be configured for spans to exist.
+
+AI Agent Directive:
+  --json returns { spans: [...], count: N, sandboxId }. Read spans before
+  concluding why a session behaved the way it did; the streamed output is only
+  what was printed, not what was attempted.
+      `).action(async (id) => {
+    const isJson = getJsonFlag(parent);
+    const output = new OutputFormatter(isJson ? "json" : "table");
+    try {
+      const body = await fetchSandboxTraces(id);
+      const spans = unwrapList(body);
+      if (isJson) {
+        output.output({ spans, count: spans.length, sandboxId: id, _links: sandboxLinks(id) });
+        return;
+      }
+      if (spans.length === 0) {
+        console.log(chalk23.gray(`No spans captured for sandbox ${id}.`));
+        return;
+      }
+      output.output(spans.map((span) => {
+        const {
+          workspaceId: _workspaceId,
+          sandboxId: _sandboxId,
+          receivedAt: _receivedAt,
+          ...rest
+        } = span;
+        return rest;
+      }));
+    } catch (error) {
+      handleError(error, isJson);
+    }
+  });
+}
+
+// src/commands/helix/index.ts
+function createHelixCommand() {
+  const helix = new Command13("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")}
+
+Subcommands:
+  run, exec, spawn, ls, presets, attach, traces, rm
+
+One-shot vs persistent:
+  ${chalk24.bold("run")} and ${chalk24.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.
+
+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.
+  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:
+  ${chalk24.dim("$")} mutagent config set workspace <workspace-id>
+
+Output:
+  Sandbox stdout goes to stdout, sandbox stderr goes to stderr, and anything
+  this CLI says about the session goes to stderr. Redirects and pipes therefore
+  behave as they would for a locally running process. Spinners and colour are
+  suppressed when the output is not a terminal or NO_COLOR is set.
+
+Not to be confused with:
+  'mutagent install helix' — that installs the Helix tool on THIS machine.
+  This group runs a session on a REMOTE sandbox.
+
+AI Agent Directive:
+  Run 'mutagent helix ls --json' before attach, exec --sandbox, or rm.
+  ONLY the streaming paths ('attach', 'spawn' without --detach, 'exec --sandbox'
+  without --no-stream) emit NDJSON in --json mode — one object per line, with a
+  complete summary object as the final line — because a live stream is not a
+  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.
+  Spawning consumes resources until removed — confirm with the user before
+  'spawn' and before 'rm'.
+      `);
+  registerRunCommand(helix);
+  registerExecCommand(helix);
+  registerSpawnCommand(helix);
+  registerLsCommand(helix);
+  registerPresetsCommand(helix);
+  registerAttachCommand(helix);
+  registerTracesCommand(helix);
+  registerRmCommand(helix);
+  return helix;
+}
+
+// src/bin/cli.ts
+init_config();
+
+// src/lib/brand.ts
+var BRAND = {
+  name: "MUTAGENT",
+  primary: "#7E47D7",
+  accent: "#45b8cc",
+  gradientFrom: "#45b8cc",
+  gradientTo: "#7E47D7"
+};
+var WORDMARK = [
+  " ███╗   ███╗ ██╗   ██╗ ████████╗  █████╗   ██████╗  ███████╗ ███╗   ██╗ ████████╗  ",
+  " ████╗ ████║ ██║   ██║ ╚══██╔══╝ ██╔══██╗ ██╔════╝  ██╔════╝ ████╗  ██║ ╚══██╔══╝  ",
+  " ██╔████╔██║ ██║   ██║    ██║    ███████║ ██║  ███╗ █████╗   ██╔██╗ ██║    ██║     ",
+  " ██║╚██╔╝██║ ██║   ██║    ██║    ██╔══██║ ██║   ██║ ██╔══╝   ██║╚██╗██║    ██║     ",
+  " ██║ ╚═╝ ██║ ╚██████╔╝    ██║    ██║  ██║ ╚██████╔╝ ███████╗ ██║ ╚████║    ██║     ",
+  " ╚═╝     ╚═╝  ╚═════╝     ╚═╝    ╚═╝  ╚═╝  ╚═════╝  ╚══════╝ ╚═╝  ╚═══╝    ╚═╝     "
+];
+var WORDMARK_MIN_COLUMNS = 84;
+function hexToRgb(hex) {
+  const n = parseInt(hex.slice(1), 16);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+var lerp = (a, b, t) => Math.round(a + (b - a) * t);
+function mix(from, to, t) {
+  return [lerp(from[0], to[0], t), lerp(from[1], to[1], t), lerp(from[2], to[2], t)];
+}
+var ansi = (r, g, b) => `\x1B[38;2;${r};${g};${b}m`;
+var RESET = "\x1B[0m";
+function gradientLine(line, from, to) {
+  const chars = Array.from(line);
+  const n = chars.length;
+  let out = "";
+  chars.forEach((ch, i) => {
+    if (ch === " ") {
+      out += ch;
+      return;
+    }
+    const [r, g, b] = mix(from, to, n > 1 ? i / (n - 1) : 0);
+    out += ansi(r, g, b) + ch;
+  });
+  return out + RESET;
+}
+function hasTruecolor(env = process.env) {
+  return /truecolor|24bit/i.test(env.COLORTERM ?? "");
+}
+function detectBannerEnv(stream = process.stdout, env = process.env) {
+  return {
+    isTTY: stream.isTTY === true,
+    columns: stream.columns ?? 80,
+    truecolor: hasTruecolor(env),
+    disabled: env.MUTAGENT_NO_BANNER === "1"
+  };
+}
+function renderBanner(env = detectBannerEnv()) {
+  if (env.disabled || !env.isTTY)
+    return "";
+  const from = hexToRgb(BRAND.gradientFrom);
+  const to = hexToRgb(BRAND.gradientTo);
+  const wide = env.columns >= WORDMARK_MIN_COLUMNS;
+  const art = wide ? WORDMARK : [`  ${BRAND.name}`];
+  const lines = env.truecolor ? art.map((l) => gradientLine(l, from, to)) : art.map((l) => `${ansi(...from)}${l}${RESET}`);
+  return `
+${lines.join(`
+`)}
+`;
+}
+
+// src/lib/global-version-flag.ts
+var GLOBAL_VALUE_OPTIONS = new Set(["--api-key", "--endpoint"]);
+function findSubcommandIndex(rawArgs) {
+  for (let i = 0;i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === undefined)
+      continue;
+    if (arg === "--")
+      return i + 1 < rawArgs.length ? i + 1 : -1;
+    if (arg.startsWith("-")) {
       if (GLOBAL_VALUE_OPTIONS.has(arg))
         i++;
       continue;
@@ -6087,14 +7590,14 @@ if (process.env.CLI_VERSION) {
   cliVersion = process.env.CLI_VERSION;
 } else {
   try {
-    const __dirname2 = dirname3(fileURLToPath2(import.meta.url));
-    const pkgPath = join14(__dirname2, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync10(pkgPath, "utf-8"));
+    const __dirname2 = dirname4(fileURLToPath2(import.meta.url));
+    const pkgPath = join15(__dirname2, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync12(pkgPath, "utf-8"));
     cliVersion = pkg.version ?? cliVersion;
   } catch {}
 }
 setCliVersion(cliVersion);
-var program = new Command13;
+var program = new Command14;
 program.name("mutagent").description(`Mutagent CLI - command-line client for the Mutagent platform
 
   Documentation: https://docs.mutagent.io/cli
@@ -6104,56 +7607,61 @@ program.name("mutagent").description(`Mutagent CLI - command-line client for the
 });
 program.addHelpText("beforeAll", () => renderBanner());
 program.addHelpText("after", `
-${chalk19.bold.cyan("WORKFLOWS:")}
-  ${chalk19.bold("Setup")}                mutagent login  →  mutagent init
-  ${chalk19.bold("Lifecycle Tools")}      mutagent install <helix|diagnostics|evaluator>  ${chalk19.dim("(login-gated)")}
-  ${chalk19.bold("Feedback")}             mutagent feedback send "<what happened>" --category <cli|helix|stage:<x>>  ${chalk19.dim("[--session <id>] [--attach-transcript]")}
+${chalk25.bold.cyan("WORKFLOWS:")}
+  ${chalk25.bold("Setup")}                mutagent login  →  mutagent init
+  ${chalk25.bold("Lifecycle Tools")}      mutagent install <helix|diagnostics|evaluator>  ${chalk25.dim("(login-gated)")}
+  ${chalk25.bold("Feedback")}             mutagent feedback send "<what happened>" --category <cli|helix|stage:<x>>  ${chalk25.dim("[--session <id>] [--attach-transcript]")}
 
-${chalk19.dim("For CLI usage guidance for AI agents, see the Skill at")}
-${chalk19.cyan(".claude/skills/mutagent-cli/SKILL.md")}
+${chalk25.dim("For CLI usage guidance for AI agents, see the Skill at")}
+${chalk25.cyan(".claude/skills/mutagent-cli/SKILL.md")}
 
-${chalk19.yellow("Global flags:")}
-  -v, --version ${chalk19.dim("Print the CLI version")}   ${chalk19.dim("(before a subcommand; after one it is the subcommand's)")}
+${chalk25.yellow("Global flags:")}
+  -v, --version ${chalk25.dim("Print the CLI version")}   ${chalk25.dim("(before a subcommand; after one it is the subcommand's)")}
   --json  --api-key <k>  --endpoint <url>  --non-interactive
 
-${chalk19.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
-  export MUTAGENT_API_KEY=mt_...  ${chalk19.dim("or")}  --api-key mt_...
-  --json ${chalk19.dim("for structured output")}    --non-interactive ${chalk19.dim("to disable prompts")}
+${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")}
+
+${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")}
 
-${chalk19.yellow("Command Navigation:")}
-  mutagent login                        ${chalk19.dim("Login (browser OAuth — recommended)")}
-  mutagent auth status                  ${chalk19.dim("Check auth + workspace")}
-  mutagent init                         ${chalk19.dim("Initialize project (.mutagentrc.json)")}
-  mutagent workspaces list --json       ${chalk19.dim("List workspaces (verify ID)")}
-  mutagent config set workspace <id>    ${chalk19.dim("Set active workspace")}
-  mutagent usage --json                 ${chalk19.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        ${chalk19.dim("List configured BYOK providers")}
-  mutagent providers list --models      ${chalk19.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 install helix                ${chalk19.dim("Install the ADL lifecycle conductor (login-gated)")}
-  mutagent install evaluator --version 1.2.3  ${chalk19.dim("Pin a version")}
-  mutagent install --help               ${chalk19.dim("helix | diagnostics | evaluator")}
+  mutagent install helix                ${chalk25.dim("Install the ADL lifecycle conductor locally (login-gated)")}
+  mutagent install evaluator --version 1.2.3  ${chalk25.dim("Pin a version")}
+  mutagent install --help               ${chalk25.dim("helix | diagnostics | evaluator")}
 
-  mutagent hooks --help                 ${chalk19.dim("Hook setup for Claude Code session telemetry upload")}
+  mutagent hooks --help                 ${chalk25.dim("Hook setup for Claude Code session telemetry upload")}
 
-${chalk19.bold.red("Report Issues:")}
-  Hit a bug? Run: ${chalk19.cyan('mutagent feedback send "describe what went wrong" --category cli')}
-  Lifecycle-stage feedback: ${chalk19.cyan('mutagent feedback send "eval gate unclear" --category stage:evaluate')}
-  Link to a session: ${chalk19.cyan('mutagent feedback send "..." --session <session-id>')}
-  Attach your coding-agent session transcript: ${chalk19.cyan('mutagent feedback send "..." --attach-transcript')}
-  ${chalk19.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
+${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>")}
 
-${chalk19.yellow("Directive System:")}
+${chalk25.yellow("Directive System:")}
   Every --json response may include:
-  ${chalk19.bold("_directive.display")}      Type tag — 'status_card' for card-kind directives (drives test/docs guards)
-  ${chalk19.bold("_directive.renderedCard")} Pre-formatted card ${chalk19.red("(MUST echo verbatim in chat whenever this field exists — see SKILL.md Verbatim Card Display Protocol)")}
-  ${chalk19.bold("_directive.instruction")}  Next step for the agent (self-sufficient, no Skill required)
-  ${chalk19.bold("_directive.next")}         Array of suggested follow-up commands
-  ${chalk19.bold("_links")}                  Dashboard/API URLs (format as markdown links)
-  ${chalk19.bold("_compat")}                 Compat metadata: cliVersion, skillVersion, skillMinCliVersion
-
-${chalk19.yellow("AI Agent Rules (MANDATORY for coding agents):")}
+  ${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):")}
   1. Login (two paths):
      - CI / fully automated: export MUTAGENT_API_KEY=mt_... then mutagent login --json
      - Helping a user onboard: mutagent login --browser --json
@@ -6163,13 +7671,13 @@ ${chalk19.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
-     ${chalk19.red("HARD STOP")}: do NOT run further commands until the card is rendered in chat
+     ${chalk25.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() ? `
-` + chalk19.yellow("  Warning: Not authenticated. Run: mutagent login") + `
+` + chalk25.yellow("  Warning: Not authenticated. Run: mutagent login") + `
 ` : ""}${!hasRcConfig() ? `
-` + chalk19.green("  Get started: mutagent init") + `
+` + chalk25.green("  Get started: mutagent init") + `
 ` : ""}`);
 var rawArgs = process.argv.slice(2);
 if (isGlobalVersionFlag(rawArgs)) {
@@ -6205,9 +7713,10 @@ program.addCommand(createSkillsCommand());
 program.addCommand(createUsageCommand());
 program.addCommand(createHooksCommand());
 program.addCommand(createInstallCommand());
+program.addCommand(createHelixCommand());
 program.addCommand(createFeedbackCommand());
 program.addCommand(createTraceCommand());
 program.parse();
 
-//# debugId=B0E8F30FEF98BABD64756E2164756E21
+//# debugId=4276BD959C14332264756E2164756E21
 //# sourceMappingURL=cli.js.map