@mutagent/cli 0.1.337 → 0.1.338

package/dist/bin/cli.js

@@ -1233,7 +1233,7 @@ var init_sdk_client = __esm(() => {
 
 // src/bin/cli.ts
 import { Command as Command17 } from "commander";
-import chalk35 from "chalk";
+import chalk36 from "chalk";
 import { readFileSync as readFileSync15 } from "fs";
 import { join as join16, dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -2188,21 +2188,23 @@ async function loginWithPastedKey(initialEndpoint, output, wasFirstLogin) {
 
 // src/commands/auth.ts
 function createAuthCommand() {
-  const auth = new Command("auth").description("Authenticate with Mutagent platform").addHelpText("after", `
+  const auth = new Command("auth").description("Sign in, show the sign-in state, or sign out on this machine").addHelpText("after", `
 Examples:
   ${chalk4.dim("$")} mutagent auth login
   ${chalk4.dim("$")} mutagent auth login --browser
   ${chalk4.dim("$")} mutagent auth status
   ${chalk4.dim("$")} mutagent auth logout
+
+${chalk4.dim("mutagent auth login is the same command as mutagent login.")}
     `);
-  auth.command("login").description("Authenticate and store API key").option("--browser", "Force browser-based authentication").option("--non-interactive", "Disable interactive prompts (auto-selects browser auth)").option("--endpoint <url>", "API endpoint", "https://api.mutagent.io").addHelpText("after", `
+  auth.command("login").description("Same as mutagent login: sign in and store the API key on this machine").option("--browser", "Sign in with the browser (skip the method prompt)").option("--non-interactive", "Skip the method prompt and use browser sign-in (with --json it also needs --browser)").option("--endpoint <url>", "API endpoint", "https://api.mutagent.io").addHelpText("after", `
 Examples:
-  ${chalk4.dim("$")} mutagent auth login                    ${chalk4.dim("# Interactive (choose method)")}
-  ${chalk4.dim("$")} mutagent auth login --browser          ${chalk4.dim("# Browser OAuth flow")}
-  ${chalk4.dim("$")} mutagent auth login --non-interactive  ${chalk4.dim("# Auto browser flow (AI agents)")}
+  ${chalk4.dim("$")} mutagent auth login                    ${chalk4.dim("# In a terminal, choose browser or API key")}
+  ${chalk4.dim("$")} mutagent auth login --browser          ${chalk4.dim("# Sign in with the browser")}
+  ${chalk4.dim("$")} mutagent auth login --non-interactive  ${chalk4.dim("# Browser sign-in without the method prompt (a person approves in the browser)")}
 
-${chalk4.dim("Note: this command is an alias for `mutagent login`.")}
-${chalk4.dim("See `mutagent login --help` for full documentation.")}
+This runs the same sign-in as mutagent login, with the same options and --json output.
+See mutagent login --help for the full description.
     `).action(async (options) => {
     const isJson = getJsonFlag(auth);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -2236,7 +2238,7 @@ ${chalk4.dim("See `mutagent login --help` for full documentation.")}
       throw error;
     }
   });
-  auth.command("status").description("Check authentication status").addHelpText("after", `
+  auth.command("status").description("Show the sign-in state, endpoint and active workspace").addHelpText("after", `
 Examples:
   ${chalk4.dim("$")} mutagent auth status
   ${chalk4.dim("$")} mutagent auth status --json
@@ -2322,37 +2324,29 @@ import { Command as Command2 } from "commander";
 import chalk5 from "chalk";
 init_errors();
 function createLoginCommand() {
-  const login = new Command2("login").description("Login to Mutagent (browser OAuth — signup, onboard, authorize CLI in one flow)").option("--browser", "Force browser-based authentication").option("--non-interactive", "Disable interactive prompts (auto-selects browser auth)").option("--endpoint <url>", "API endpoint", "https://api.mutagent.io").addHelpText("after", `
+  const login = new Command2("login").description("Sign in to Mutagent and store the API key on this machine").option("--browser", "Sign in with the browser (skip the method prompt)").option("--non-interactive", "Skip the method prompt and use browser sign-in (with --json it also needs --browser)").option("--endpoint <url>", "API endpoint", "https://api.mutagent.io").addHelpText("after", `
 Examples:
-  ${chalk5.dim("$")} mutagent login                          ${chalk5.dim("# Browser OAuth (recommended — handles signup + onboarding)")}
-  ${chalk5.dim("$")} mutagent login --browser                ${chalk5.dim("# Force browser flow (skip method prompt)")}
-  ${chalk5.dim("$")} mutagent login --non-interactive        ${chalk5.dim("# Auto-browser for AI agents and CI")}
-
-${chalk5.yellow("Browser OAuth flow (recommended for end users):")}
-  Opens app.mutagent.io in your browser. You will:
-    1. Sign in or sign up with your account
-    2. Complete onboarding (workspace, provider config)
-    3. Authorize this CLI session
-  The CLI polls for completion and saves credentials when you authorize.
-
-${chalk5.yellow("Automation / CI / AI Agents:")}
-  Set MUTAGENT_API_KEY environment variable before running:
-    ${chalk5.dim("$")} export MUTAGENT_API_KEY=mt_...
-    ${chalk5.dim("$")} mutagent login --json
-  When MUTAGENT_API_KEY is set, login skips the browser flow entirely and
-  validates the key directly. This is the canonical CI / agent path.
-
-Environment Variables:
-  MUTAGENT_API_KEY              Pre-existing API key (skips interactive flow)
-  MUTAGENT_ENDPOINT             Custom API endpoint
-  MUTAGENT_NON_INTERACTIVE=true Treat environment as non-interactive
-  CI=true                       Automatically enables non-interactive mode
-
-Verify after login:
-  ${chalk5.dim("$")} mutagent auth status                    ${chalk5.dim("# Show session, workspace, org")}
-  ${chalk5.dim("$")} mutagent workspaces list --json         ${chalk5.dim("# List available workspaces")}
-
-${chalk5.dim("Note: `mutagent auth login` is a back-compat alias and behaves identically.")}
+  ${chalk5.dim("$")} mutagent login                          ${chalk5.dim("# In a terminal, choose browser or API key")}
+  ${chalk5.dim("$")} mutagent login --browser                ${chalk5.dim("# Sign in with the browser")}
+  ${chalk5.dim("$")} mutagent login --non-interactive        ${chalk5.dim("# Browser sign-in without the method prompt (a person approves in the browser)")}
+  ${chalk5.dim("$")} MUTAGENT_API_KEY=mt_... mutagent login --json   ${chalk5.dim("# Sign in with a key (CI)")}
+
+Browser sign-in opens app.mutagent.io, where you sign in or sign up, finish onboarding
+and approve this CLI. The CLI waits up to 5 minutes and saves the credentials.
+
+When MUTAGENT_API_KEY is set, login skips the browser and validates the key.
+
+Environment:
+  MUTAGENT_API_KEY               Use this key; no browser
+  MUTAGENT_ENDPOINT              API endpoint (overrides --endpoint)
+  MUTAGENT_NON_INTERACTIVE=true  Same as --non-interactive
+  CI=true                        Same as --non-interactive
+
+Then:
+  ${chalk5.dim("$")} mutagent auth status
+  ${chalk5.dim("$")} mutagent workspaces list --json
+
+mutagent auth login runs the same sign-in.
     `).action(async (options) => {
     const isJson = getJsonFlag(login);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -2425,6 +2419,7 @@ Examples:
   ${chalk6.dim("$")} mutagent config get apiKey --json
 
 ${chalk6.dim("Keys: apiKey, endpoint, format, timeout, defaultWorkspace, defaultOrganization")}
+${chalk6.dim("A key with no value set is reported as unknown.")}
     `).action((key) => {
     const isJson = getJsonFlag(config);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -2453,7 +2448,7 @@ ${chalk6.dim("Keys: apiKey, endpoint, format, timeout, defaultWorkspace, default
 Examples:
   ${chalk6.dim("$")} mutagent config set workspace <workspace-id>
 
-${chalk6.dim("Persists workspace ID so you don't need to pass headers on every request.")}
+${chalk6.dim("Commands use this workspace until you change it.")}
     `).action((id) => {
     const isJson = getJsonFlag(config);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -2594,10 +2589,8 @@ Examples:
   ${chalk7.dim("$")} mutagent workspaces list
   ${chalk7.dim("$")} mutagent workspaces get <workspace-id>
 
-Subcommands:
-  list, get
-
-Note: Workspace management (create, update, delete) is available in the Admin Panel only.
+Choose the active workspace with: mutagent config set workspace <workspace-id>
+Create or change workspaces in the dashboard: https://app.mutagent.io
     `);
   workspaces.command("list").description("List all workspaces").option("-l, --limit <n>", "Limit results", "50").option("-o, --offset <n>", "Offset for pagination").addHelpText("after", `
 Examples:
@@ -3149,32 +3142,30 @@ function collectCredentialFields(options) {
   return fields;
 }
 function registerAddCommand(parent) {
-  parent.command("add").description("Add a new provider configuration").requiredOption("-p, --provider <type>", "Provider type (openai, anthropic, azure, ...)").requiredOption("-n, --name <name>", "Display name for this provider").option("-k, --api-key <key>", "API key for the provider (every entry except Google Vertex)").option("--service-account-key <json>", "Google Vertex service-account credential JSON").option("--hosted-family <family>", `Hosted model family for gateway providers: ${HOSTED_FAMILIES.join(", ")}`).option("--base-url <url>", "Custom base URL for the provider API").option("--api-format <format>", apiFormatHelpText()).option("--resource-endpoint <url>", "Azure resource endpoint").option("--deployment-name <name>", "Azure deployment name").option("--api-version <version>", "Azure API version (e.g. 2024-08-01-preview)").option("--project-id <id>", "Google Vertex project ID").option("--region <region>", "Region (Vertex location, or AWS Bedrock region)").option("--set-default", "Set as the default provider of its kind").addHelpText("after", `
+  parent.command("add").description("Add an LLM provider to the workspace").requiredOption("-p, --provider <type>", "LLM provider type (openai, anthropic, azure, ...)").requiredOption("-n, --name <name>", "Display name").option("-k, --api-key <key>", "API key (every type except vertex)").option("--service-account-key <json>", "Google Vertex service-account credential JSON").option("--hosted-family <family>", `Model family a gateway (azure, vertex, bedrock) serves: ${HOSTED_FAMILIES.join(", ")}`).option("--base-url <url>", "Base URL of the API").option("--api-format <format>", apiFormatHelpText()).option("--resource-endpoint <url>", "Azure resource endpoint").option("--deployment-name <name>", "Azure deployment name").option("--api-version <version>", "Azure API version (e.g. 2024-08-01-preview)").option("--project-id <id>", "Google Vertex project ID").option("--region <region>", "Region (Vertex location, or AWS Bedrock region)").option("--set-default", "Make it the workspace's default LLM provider of its type").addHelpText("after", `
 Examples:
   ${chalk8.dim("$")} mutagent providers add --provider openai --name "My OpenAI" --api-key $OPENAI_API_KEY
   ${chalk8.dim("$")} mutagent providers add --provider azure --name "Azure GPT" --api-key $KEY \\
       --hosted-family openai --resource-endpoint https://my.openai.azure.com --deployment-name gpt-5
-  ${chalk8.dim("$")} mutagent providers add --provider bedrock --name "Bedrock Claude" --api-key $KEY \\
-      --hosted-family anthropic --region us-east-1
-  ${chalk8.dim("$")} mutagent providers add --provider custom --name "Ollama" --api-key none --base-url https://ollama.internal --json
-  ${chalk8.dim("$")} mutagent providers add --provider custom --name "Claude-compatible" --api-key $KEY \\
-      --base-url https://llm.internal --api-format anthropic
-
-Gateway providers (${[...GATEWAY_PROVIDERS].join(", ")}) serve another vendor's models and
-require --hosted-family. Direct providers must not set it.
-
-${apiFormatHelpText()}. An endpoint speaking the Anthropic request shape needs
---api-format anthropic; left unset, the server's default applies. Passing it to a
-provider that speaks its own API is an error, not a silent no-op.
-
-Providers are configured for your workspace. Set the target with:
-  ${chalk8.dim("$")} mutagent config set workspace <workspace-id>
-
-The API key is encrypted server-side and never returned in plain text.
+  ${chalk8.dim("$")} mutagent providers add --provider bedrock --name "Bedrock Claude" --api-key $KEY --region us-east-1
+  ${chalk8.dim("$")} mutagent providers add --provider custom --name "My gateway" --api-key $KEY \\
+      --base-url https://llm.example.com/v1 --api-format anthropic
+
+azure and vertex serve another vendor's models and need --hosted-family; bedrock serves
+anthropic and needs none. Other LLM provider types must not set it.
+--api-format applies only to the LLM provider types its option line lists. Use
+anthropic for an endpoint that speaks the Anthropic API; unset, the server default applies.
+The base URL must be a public address: hosts ending in .internal, .local, .localhost or
+.home.arpa are refused.
+
+Adds the LLM provider to the configured workspace (mutagent config set workspace <id>).
+The key is encrypted and never returned.
+Workspace default model: when the workspace has none, adding a keyed LLM provider sets
+one on the server. An existing workspace default model is never changed.
 
 AI Agent Directive:
-  Run 'mutagent providers list --json' first to check whether the provider already exists.
-  This command writes a credential — confirm with the user before running it.
+  Run 'mutagent providers list --json' first to check whether the LLM provider already exists.
+  This command writes a credential: confirm with the user before running it.
     `).action(async (options) => {
     const isJson = getJsonFlag(parent);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -3285,14 +3276,14 @@ init_sdk_client();
 import chalk9 from "chalk";
 init_errors();
 function registerUpdateCommand(parent) {
-  parent.command("update").description("Update an existing provider configuration").argument("<id>", "Provider ID (from: mutagent providers list)").option("-n, --name <name>", "Updated display name").option("-k, --api-key <key>", "Updated API key (will be re-encrypted)").option("--active <bool>", "Activate or deactivate (true|false)").option("--set-default", "Set as the default provider of its kind").option("--base-url <url>", 'Updated base URL (use "" to clear)').addHelpText("after", `
+  parent.command("update").description("Update an LLM provider").argument("<id>", "LLM provider ID (from: mutagent providers list)").option("-n, --name <name>", "Updated display name").option("-k, --api-key <key>", "New API key (stored encrypted)").option("--active <bool>", "Activate or deactivate (true|false)").option("--set-default", "Make it the workspace's default LLM provider of its type").option("--base-url <url>", 'Updated base URL (use "" to clear)').addHelpText("after", `
 Examples:
-  ${chalk9.dim("$")} mutagent providers update <id> --name "New Name"
-  ${chalk9.dim("$")} mutagent providers update <id> --api-key $NEW_KEY --json
-  ${chalk9.dim("$")} mutagent providers update <id> --active false
-  ${chalk9.dim("$")} mutagent providers update <id> --set-default --json
+  ${chalk9.dim("$")} mutagent providers update <provider-id> --name "New Name"
+  ${chalk9.dim("$")} mutagent providers update <provider-id> --api-key $NEW_KEY --json
+  ${chalk9.dim("$")} mutagent providers update <provider-id> --active false
+  ${chalk9.dim("$")} mutagent providers update <provider-id> --set-default --json
 
-PATCH semantics — only provided fields are updated.
+Only the fields you pass change. An update never sets the workspace default model.
     `).action(async (id, options) => {
     const isJson = getJsonFlag(parent);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -3386,14 +3377,16 @@ init_sdk_client();
 import chalk10 from "chalk";
 init_errors();
 function registerDeleteCommand(parent) {
-  parent.command("delete").description("Delete a provider configuration").argument("<id>", "Provider ID (from: mutagent providers list)").option("-f, --force", "Skip confirmation prompt").addHelpText("after", `
+  parent.command("delete").description("Delete an LLM provider").argument("<id>", "LLM provider ID (from: mutagent providers list)").option("-f, --force", "Confirm the delete (required unless --json)").addHelpText("after", `
 Examples:
-  ${chalk10.dim("$")} mutagent providers delete <id>
-  ${chalk10.dim("$")} mutagent providers delete <id> --force
-  ${chalk10.dim("$")} mutagent providers delete <id> --force --json
+  ${chalk10.dim("$")} mutagent providers delete <provider-id> --force
+  ${chalk10.dim("$")} mutagent providers delete <provider-id> --force --json
+
+Without --force (and without --json) the command refuses; it never prompts.
+The stored key is deleted and cannot be recovered. Deleting an unknown ID succeeds.
 
-${chalk10.dim("Note: --force is required. The CLI is non-interactive — confirm with the user via your native flow, then pass --force.")}
-${chalk10.dim("Warning: API keys are AES-256-GCM encrypted and irrecoverable after deletion. Agents referencing this provider will lose their model config.")}
+AI Agent Directive:
+  Confirm with the user before running it, then pass --force (or --json). The stored key cannot be recovered.
     `).action(async (id, options) => {
     const isJson = getJsonFlag(parent);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -4115,44 +4108,42 @@ function statusGlyph(result) {
   }
 }
 function registerMirrorCommand(parent) {
-  parent.command("mirror").description("Copy the local Helix provider logins into the workspace, on request").option("-y, --yes", "Consent without prompting (required when non-interactive)").option("--no-overwrite", "Leave providers the workspace already has untouched").option("--workspace <id>", "Target workspace (default: the configured one)").option("--channel <channel>", `Helix channel whose store is read: ${HELIX_CHANNELS.join(" | ")}`, "stable").option("--provider <id>", "Only this local provider id (repeatable)", (value, prev = []) => [...prev, value]).addHelpText("after", `
+  parent.command("mirror").description("Copy the API keys from your local Helix login store into the workspace as LLM providers").option("-y, --yes", "Consent without prompting (required when non-interactive)").option("--no-overwrite", "Leave LLM providers the workspace already has untouched").option("--workspace <id>", "Target workspace for this run (default: the configured one)").option("--channel <channel>", `Helix channel whose store is read: ${HELIX_CHANNELS.join(" | ")}`, "stable").option("--provider <id>", "Only this local LLM provider id (repeatable)", (value, prev = []) => [...prev, value]).addHelpText("after", `
 Examples:
   ${chalk11.dim("$")} mutagent providers mirror
+  ${chalk11.dim("$")} mutagent providers mirror --json                 ${chalk11.dim("Show the plan without sending anything")}
   ${chalk11.dim("$")} mutagent providers mirror --yes --json
   ${chalk11.dim("$")} mutagent providers mirror --provider zai --provider openrouter
-  ${chalk11.dim("$")} mutagent providers mirror --no-overwrite --workspace <workspace-id>
+  ${chalk11.dim("$")} mutagent providers mirror --no-overwrite
   ${chalk11.dim("$")} mutagent providers mirror --channel rc
 
-Reads the durable Helix agent dir ($HELIX_CODING_AGENT_DIR, else ~/.mutagent/agent;
-~/.mutagent/agent-rc with --channel rc): api_key entries in auth.json and custom
-providers in models.json. OAuth-shaped logins are listed as unsupported, not copied.
-Exception: the pinned OpenRouter permanent-key shape is treated as a literal
-API key; other OAuth and Foundry companion credentials remain unsupported.
-Only literal keys are mirrored: a key stored as a reference (!command, $VAR,
-\${VAR}, or a bare ENV_NAME) is listed as skipped and is never evaluated.
-
-On an existing row the plan states what changes before consent: an endpoint
-moved (old → new), an endpoint override removed locally (reset to default),
-and the wire format a Custom provider is written with.
-Supported native model declarations, capabilities and compatibility fields are
-copied too. Headers, companion credentials and unsupported fields block that
-provider. Mirroring is not proof of Cloud execution; no model roster is invented.
-
-anthropic, openai, google, xai and deepseek land under their own provider id.
-zai, zai-coding-cn, moonshotai, moonshotai-cn, kimi-coding, openrouter and groq
-land as Custom providers with the harness's endpoint and harnessProvider metadata.
-
-Requires \`mutagent auth login\` first — nothing is read from disk without a
-platform identity and a workspace. Keys go only into the request body to the
-configured endpoint; they are never printed, logged or written anywhere else.
-
-Consent is asked once per run. Non-interactive callers must pass --yes;
-without it the run refuses (exit 2). Exit 3: no platform identity.
-Exit 1: at least one entry failed — see the per-entry report.
-
-In --json, each written result carries "endpoint" {from, to} (a URL or
-"default") and, for Custom providers, "apiFormat" {from, to}; the refusal
-without --yes carries the same per-entry "plan". Names and URLs only.
+Reads the API keys in your local Helix login store (~/.mutagent/agent, ~/.mutagent/agent-rc
+with --channel rc, or $HELIX_CODING_AGENT_DIR when set) and creates or updates the
+matching LLM providers in the workspace. OAuth logins and keys stored as references
+($VAR, \${VAR}, !command or a bare ENV_NAME) are listed and skipped; a reference is never
+evaluated. Exception: an openrouter login that holds a permanent key is copied as an
+API key. Before anything is sent, the plan shows every create and update, endpoint
+changes and the API format a custom LLM provider is written with.
+
+anthropic, openai, google, xai and deepseek become LLM providers of the same type.
+zai, zai-coding-cn, moonshotai, moonshotai-cn, kimi-coding, openrouter and groq become
+custom LLM providers. Declared model lists are copied. An entry with headers or other
+fields that cannot be copied is skipped.
+
+Workspace default model: when the workspace has none, the server sets one from the
+first LLM provider this run creates, and the output names it. An existing workspace
+default model is never changed. Change it with
+\`mutagent helix models default <provider/model>\`.
+
+Mirroring does not test the keys: check \`mutagent helix models\`, then run a model.
+
+Requires \`mutagent login\` and a workspace. Keys are sent only to the configured
+endpoint and are never printed. Consent is asked once per run; without a terminal,
+--yes is required. Without it the run exits 2 (with --json it returns the plan).
+Exit 3: not logged in or no workspace. Exit 1: at least one entry failed.
+
+JSON: each written result carries "endpoint" {from, to} and, for custom LLM providers,
+"apiFormat" {from, to}; workspaceDefaultModelSet names a default the run set.
 
 AI Agent Directive:
   This command sends credentials off the machine. Run it with --json first
@@ -4281,24 +4272,20 @@ function validateProviderType(type) {
 function createProvidersCommand() {
   const providers = new Command5("providers").description("Manage LLM provider configurations (BYOK)").addHelpText("after", `
 Examples:
+  ${chalk12.dim("$")} mutagent providers mirror
   ${chalk12.dim("$")} mutagent providers list
   ${chalk12.dim("$")} mutagent providers get <provider-id>
   ${chalk12.dim("$")} mutagent providers add --provider openai --name "My OpenAI" --api-key $KEY
-  ${chalk12.dim("$")} mutagent providers update <id> --name "New Name"
-  ${chalk12.dim("$")} mutagent providers delete <id> --force
   ${chalk12.dim("$")} mutagent providers test <provider-id>
-  ${chalk12.dim("$")} mutagent providers mirror --yes --json
-
-Provider Types:
-  ${VALID_PROVIDER_TYPES.join(", ")}
+  ${chalk12.dim("$")} mutagent providers update <provider-id> --name "New Name"
+  ${chalk12.dim("$")} mutagent providers delete <provider-id> --force
 
-Subcommands:
-  list, get, add, update, delete, test, mirror
+LLM providers hold the keys Helix uses to call models in the cloud. See what they
+unlock with \`mutagent helix models\`.
 
-Tip:
-  Use --models on list to see available models per provider.
+LLM provider types: ${VALID_PROVIDER_TYPES.join(", ")}
     `);
-  providers.command("list").description("List all providers").option("-l, --limit <n>", "Limit results", "50").option("-o, --offset <n>", "Offset for pagination").option("-t, --type <type>", "Filter by provider type").option("-m, --models", "Show available models per provider (calls /providers/catalog)").addHelpText("after", `
+  providers.command("list").description("List the workspace's LLM providers").option("-l, --limit <n>", "Limit results", "50").option("-o, --offset <n>", "Offset for pagination").option("-t, --type <type>", "Filter by LLM provider type").option("-m, --models", "Show catalogue models for each LLM provider type (for Helix cloud models: mutagent helix models)").addHelpText("after", `
 Examples:
   ${chalk12.dim("$")} mutagent providers list
   ${chalk12.dim("$")} mutagent providers list --type openai
@@ -4377,7 +4364,7 @@ Examples:
       handleError(error, isJson);
     }
   });
-  providers.command("get").description("Get provider details").argument("<id>", "Provider ID (from: mutagent providers list)").addHelpText("after", `
+  providers.command("get").description("Show one LLM provider").argument("<id>", "LLM provider ID (from: mutagent providers list)").addHelpText("after", `
 Examples:
   ${chalk12.dim("$")} mutagent providers get <provider-id>
   ${chalk12.dim("$")} mutagent providers get <provider-id> --json
@@ -4407,12 +4394,12 @@ Examples:
       handleError(error, isJson);
     }
   });
-  providers.command("test").description("Test provider connectivity").argument("<id>", "Provider ID (from: mutagent providers list)").addHelpText("after", `
+  providers.command("test").description("Test an LLM provider's connection").argument("<id>", "LLM provider ID (from: mutagent providers list)").addHelpText("after", `
 Examples:
   ${chalk12.dim("$")} mutagent providers test <provider-id>
   ${chalk12.dim("$")} mutagent providers test <provider-id> --json
 
-${chalk12.dim("Tests connectivity and lists available models for the provider.")}
+${chalk12.dim("Tests the connection and lists the models the LLM provider reports.")}
     `).action(async (id) => {
     const isJson = getJsonFlag(providers);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -5281,13 +5268,14 @@ that teaches coding agents how to use the Mutagent CLI effectively.
 // src/commands/init.ts
 var LOGIN_GUIDANCE = "Run: mutagent login — sign-up happens in the browser. Then re-run mutagent init.";
 function createInitCommand(deps = {}) {
-  const init = new Command7("init").description("Initialize Mutagent in your project").option("--non-interactive", "No-op kept for back-compat (init never prompts)").addHelpText("after", `
+  const init = new Command7("init").description("Initialize Mutagent in your project").option("--non-interactive", "Has no effect: init never prompts").addHelpText("after", `
 Examples:
   ${chalk14.dim("$")} mutagent init    # Write .mutagentrc.json + install the CLI skill
 
 What it does:
   1. Writes .mutagentrc.json (endpoint / workspace / org) — skipped if present
   2. Installs the Mutagent CLI skill into ${SKILL_DIR}/
+It never prompts. Without a sign-in it prints what to run and exits.
     `).action(async (options) => {
     const isJson = getJsonFlag(init);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -5405,7 +5393,7 @@ init_errors();
 init_sdk_client();
 var PROVIDERS_URL = "https://app.mutagent.io/settings/providers";
 function createUsageCommand() {
-  const usage = new Command8("usage").description("Show account resource counts (providers, workspaces) and provider status").addHelpText("after", `
+  const usage = new Command8("usage").description("Count the workspace's LLM providers and the workspaces you can see").addHelpText("after", `
 Examples:
   ${chalk15.dim("$")} mutagent usage
   ${chalk15.dim("$")} mutagent usage --json
@@ -5463,6 +5451,7 @@ Examples:
 import { readFileSync as readFileSync9 } from "node:fs";
 import { basename } from "node:path";
 import { Command as Command9 } from "commander";
+import chalk16 from "chalk";
 
 // src/commands/hooks/import-transcript.ts
 var MAX_SPAN_TEXT = 4000;
@@ -6372,32 +6361,17 @@ function installHooks(cwd) {
 // src/commands/hooks/index.ts
 function createHooksCommand() {
   const hooks = new Command9("hooks").description("Hook handlers for AI coding assistants").addHelpText("after", `
-Claude Code Session Telemetry:
-  Sends lightweight session activity to the Mutagent traces API for observability.
+Claude Code session telemetry:
+  Sends session activity (turns, tool calls, subagents, compactions) to the Mutagent
+  traces API.
 
-  Install by adding to .claude/settings.local.json:
+  ${chalk16.dim("$")} mutagent hooks install    ${chalk16.dim("Add the Mutagent hooks to .claude/settings.local.json (11 events)")}
 
-  {
-    "hooks": {
-      "SessionStart": [{"matcher": "startup", "hooks": [{"type": "command", "command": "mutagent hooks claude-code session-start"}]}],
-      "Stop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code session-end"}]}],
-      "PreToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-tool-use"}]}],
-      "PostToolUse": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use"}]}],
-      "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code user-prompt-submit"}]}],
-      "SubagentStart": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code subagent-start"}]}],
-      "SubagentStop": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code subagent-stop"}]}],
-      "PreCompact": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code pre-compact"}]}],
-      "PostCompact": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-compact"}]}],
-      "PostToolUseFailure": [{"hooks": [{"type": "command", "command": "mutagent hooks claude-code post-tool-use-failure"}]}]
-    }
-  }
-
-  Or run: mutagent hooks install
+  The claude-code subcommands are what those hooks run; Claude Code calls them.
     `);
-  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.
+  hooks.command("import").argument("<files...>", "Session transcript files (.jsonl)").description("Upload Helix 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", `
+Uploads Helix session transcripts that are already on disk, instead of capturing
+them live.
 
 Where they live:
   ~/.mutagent/sessions*                 Helix
@@ -6494,11 +6468,16 @@ unparseable lines without sending anything.
 `);
     emit(batch.length, false);
   });
-  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
-hook already present (checked by command string) so running this multiple
-times is safe.
+  hooks.command("install").description("Add the Mutagent hooks to .claude/settings.local.json (merges; existing hooks stay)").option("--cwd <dir>", "Target directory", process.cwd()).addHelpText("after", `
+Examples:
+  ${chalk16.dim("$")} mutagent hooks install
+  ${chalk16.dim("$")} mutagent hooks install --cwd ../other-project
+
+Merges the Mutagent hooks into all 11 Claude Code events of
+.claude/settings.local.json (created if missing). Hooks already present are left
+alone. An old Stop → claude-code session-end entry is removed.
+Stop runs 'claude-code stop' and SessionEnd runs 'claude-code session-end'.
+Safe to run again.
     `).action((opts) => {
     const targetDir = opts.cwd ?? process.cwd();
     const isJson = Boolean(opts.json);
@@ -6597,7 +6576,7 @@ times is safe.
 
 // src/commands/feedback.ts
 import { Command as Command10 } from "commander";
-import chalk18 from "chalk";
+import chalk19 from "chalk";
 import { type as osType, release as osRelease } from "os";
 import { readFileSync as readFileSync11 } from "fs";
 import { join as join13, dirname as dirname2 } from "path";
@@ -6618,7 +6597,7 @@ import {
   readSync,
   closeSync
 } from "fs";
-import chalk16 from "chalk";
+import chalk17 from "chalk";
 var TAIL_BYTES = 200000;
 function defaultReadTail(path, tailBytes) {
   const { size } = fsStatSync(path);
@@ -6694,7 +6673,7 @@ Or omit the path to auto-detect the newest coding-agent session.`);
     }
   }
   if (!newest) {
-    warn(chalk16.yellow("⚠ No coding-agent transcript found; sending feedback without one."));
+    warn(chalk17.yellow("⚠ No coding-agent transcript found; sending feedback without one."));
     return null;
   }
   const { content, truncated } = readTail(newest.path, TAIL_BYTES);
@@ -6708,7 +6687,7 @@ Or omit the path to auto-detect the newest coding-agent session.`);
 }
 
 // src/lib/feedback-safety.ts
-import chalk17 from "chalk";
+import chalk18 from "chalk";
 
 // src/lib/secret-scan.ts
 var PATTERNS = [
@@ -6903,9 +6882,9 @@ function buildPreview(transcript) {
 function buildTranscriptWarning(preview) {
   const kb = (preview.bytes / 1024).toFixed(1);
   return [
-    chalk17.yellow("⚠ About to upload your coding-agent session transcript."),
-    `  ${chalk17.bold("Source:")}  ${preview.sourcePath}`,
-    `  ${chalk17.bold("Sending:")} ${String(preview.fileCount)} file, ${kb} KB${preview.truncated ? " (tail only)" : ""}`,
+    chalk18.yellow("⚠ About to upload your coding-agent session transcript."),
+    `  ${chalk18.bold("Source:")}  ${preview.sourcePath}`,
+    `  ${chalk18.bold("Sending:")} ${String(preview.fileCount)} file, ${kb} KB${preview.truncated ? " (tail only)" : ""}`,
     "",
     "  A session transcript typically contains:",
     "    • source code and file contents you or the agent opened",
@@ -6914,9 +6893,9 @@ function buildTranscriptWarning(preview) {
     "    • internal hostnames, service names, and URLs",
     "    • business context from your prompts and the agent replies",
     "",
-    `  ${chalk17.dim("Credentials are scanned for and redacted automatically, but detection")}`,
-    `  ${chalk17.dim("is best-effort — review the source file if the session touched secrets.")}`,
-    `  ${chalk17.dim("Omit --attach-transcript to send feedback without it.")}`
+    `  ${chalk18.dim("Credentials are scanned for and redacted automatically, but detection")}`,
+    `  ${chalk18.dim("is best-effort — review the source file if the session touched secrets.")}`,
+    `  ${chalk18.dim("Omit --attach-transcript to send feedback without it.")}`
   ].join(`
 `);
 }
@@ -6928,12 +6907,12 @@ function buildRedactionReport(redactions) {
     byKind.set(match.label, (byKind.get(match.label) ?? 0) + 1);
   }
   const lines = [
-    chalk17.green(`✓ Redacted ${String(redactions.length)} credential${redactions.length === 1 ? "" : "s"} from the transcript before upload:`)
+    chalk18.green(`✓ Redacted ${String(redactions.length)} credential${redactions.length === 1 ? "" : "s"} from the transcript before upload:`)
   ];
   for (const [label, count] of byKind) {
     lines.push(`    • ${label} ×${String(count)}`);
   }
-  lines.push(chalk17.dim("  These were replaced with [REDACTED:…] markers and never left your machine."));
+  lines.push(chalk18.dim("  These were replaced with [REDACTED:…] markers and never left your machine."));
   return lines.join(`
 `);
 }
@@ -6941,17 +6920,17 @@ function buildByDesignNotice(entries) {
   if (entries.length === 0)
     return "";
   const lines = [
-    chalk17.cyan("ℹ Heads up — this may describe intended behaviour:"),
+    chalk18.cyan("ℹ Heads up — this may describe intended behaviour:"),
     ""
   ];
   for (const entry of entries) {
-    lines.push(`  ${chalk17.bold(entry.title)}`);
+    lines.push(`  ${chalk18.bold(entry.title)}`);
     for (const line of wrap(entry.reality, 76)) {
       lines.push(`    ${line}`);
     }
     lines.push("");
   }
-  lines.push(chalk17.dim("  Sending anyway — if this is a regression rather than the design,"), chalk17.dim("  your report is exactly what we need. Nothing was withheld."));
+  lines.push(chalk18.dim("  Sending anyway — if this is a regression rather than the design,"), chalk18.dim("  your report is exactly what we need. Nothing was withheld."));
   return lines.join(`
 `);
 }
@@ -7062,18 +7041,18 @@ function buildPayload(feedback, category, title, session, transcript) {
 }
 function createFeedbackCommand() {
   const feedback = new Command10("feedback").description("Send product feedback to Mutagent").addHelpText("after", `
-${chalk18.bold("Examples:")}
-  ${chalk18.cyan('mutagent feedback send "Optimizer results were great"')}
-  ${chalk18.cyan('mutagent feedback send "Eval gate was confusing" --category stage:evaluate')}
-  ${chalk18.cyan('mutagent feedback send "CLI crashed on export" --category cli --json')}
+${chalk19.bold("Examples:")}
+  ${chalk19.cyan('mutagent feedback send "helix session attach was easy to follow"')}
+  ${chalk19.cyan('mutagent feedback send "Eval gate was confusing" --category stage:evaluate')}
+  ${chalk19.cyan('mutagent feedback send "CLI crashed on export" --category cli --json')}
 
-${chalk18.yellow("AI Agent (MANDATORY):")}
+AI Agent Directive:
   ALWAYS use --json: mutagent feedback send "..." --category cli --json
-  ${chalk18.yellow("Do NOT attach a transcript by default.")} --attach-transcript uploads the
+  ${chalk19.yellow("Do NOT attach a transcript by default.")} --attach-transcript uploads the
   coding-agent SESSION JSONL — source code, absolute paths, branch and repository
   names, internal hostnames, and the business context of the operator's prompts.
   Use it only when the operator explicitly asks for it. See:
-  ${chalk18.dim("mutagent feedback send --help")}
+  ${chalk19.dim("mutagent feedback send --help")}
     `).action(() => {
     feedback.help();
   });
@@ -7081,42 +7060,34 @@ ${chalk18.yellow("AI Agent (MANDATORY):")}
   return feedback;
 }
 function registerFeedbackSend(feedback) {
-  feedback.command("send").description("Send product feedback about the Mutagent platform or CLI").argument("<feedback>", "The feedback body (content), max 10000 characters").option("--title <string>", "Optional 5–8 word summary of the session timeline").option("--category <value>", `Feedback category: 'cli', 'helix', or 'stage:<${VALID_STAGES.join("|")}>'`, "cli").option("--session <id>", "Link this feedback to a session id (maps to server sessionId)").option("--attach-transcript [path]", "Attach the coding-agent session JSONL. Bare = auto-detect newest; or pass an explicit path.").addHelpText("after", `
-${chalk18.bold("Arguments & flags:")}
-  ${chalk18.bold("<feedback>")}              Feedback body / content (required, ≤10000 chars)
-  ${chalk18.bold("--title <string>")}        Optional 5–8 word summary of the session timeline
-  ${chalk18.bold("--category <value>")}      ${chalk18.bold("cli")} (default) | ${chalk18.bold("helix")} | ${chalk18.bold("stage:<")}${VALID_STAGES.join("|")}${chalk18.bold(">")}
-                          ${chalk18.dim("stage = the lifecycle skill (evaluator/diagnostics live under stage:*)")}
-  ${chalk18.bold("--session <id>")}          Link feedback to a session id (server sessionId)
-  ${chalk18.bold("--attach-transcript")} ${chalk18.dim("[path]")}  Attach the coding-agent session JSONL (bare = auto-detect newest)
-  ${chalk18.bold("--json")}                  Structured output (MANDATORY for AI agents)
-
-${chalk18.bold("Examples:")}
-  ${chalk18.dim("$")} mutagent feedback send "The setup flow could show progress better"
-  ${chalk18.dim("$")} mutagent feedback send "Eval gate was confusing" --category stage:evaluate --title "eval gate unclear"
-  ${chalk18.dim("$")} mutagent feedback send "Diagnose loop stalled" --category stage:diagnose --session sess_abc123 --json
-  ${chalk18.dim("$")} mutagent feedback send "CLI crashed mid-run" --category cli --attach-transcript --json
-  ${chalk18.dim("$")} mutagent feedback send "Repro attached" --category cli --attach-transcript /tmp/session.jsonl
-
-${chalk18.bold("Category:")}
-  ${chalk18.bold("cli")}            Feedback about the CLI itself (default)
-  ${chalk18.bold("helix")}          Feedback about Helix
-  ${chalk18.bold("stage:<x>")}      Feedback about a lifecycle stage: ${VALID_STAGES.join(", ")}
-
-${chalk18.bold("Transcript (--attach-transcript):")}
-  Uploads your coding-agent SESSION JSONL as context (raw last-200KB tail) — a
-  SEPARATE artifact from the feedback body. Bare flag auto-detects the newest
-  session across claude-code, codex, and omp; explicit path overrides.
-
-  ${chalk18.yellow("A session transcript contains source code, absolute paths (including your")}
-  ${chalk18.yellow("username), branch and repository names, internal hostnames, and the business")}
-  ${chalk18.yellow("context of your prompts.")} Credentials are scanned for and redacted before
-  upload, and the exact size + source path are printed before the network call.
-  Detection is best-effort — omit the flag if the session handled secrets.
-
-${chalk18.yellow("AI Agent (MANDATORY):")}
-  ALWAYS use --json: mutagent feedback send "..." --json
-  Auto-captured context (harness, CLI version, platform, OS, node version) is included automatically.
+  feedback.command("send").description("Send product feedback about the Mutagent platform or CLI").argument("<feedback>", "The feedback body (content), max 10000 characters").option("--title <string>", "Short title").option("--category <value>", `Feedback category: 'cli', 'helix', or 'stage:<${VALID_STAGES.join("|")}>'`, "cli").option("--session <id>", "Link the feedback to a session").option("--attach-transcript [path]", "Attach the coding-agent session JSONL. Bare = auto-detect newest; or pass an explicit path.").addHelpText("after", `
+${chalk19.bold("Examples:")}
+  ${chalk19.dim("$")} mutagent feedback send "The setup flow could show progress better"
+  ${chalk19.dim("$")} mutagent feedback send "Eval gate was confusing" --category stage:evaluate --title "eval gate unclear"
+  ${chalk19.dim("$")} mutagent feedback send "Diagnose loop stalled" --category stage:diagnose --session sess_abc123 --json
+  ${chalk19.dim("$")} mutagent feedback send "CLI crashed mid-run" --category cli --attach-transcript --json
+  ${chalk19.dim("$")} mutagent feedback send "Repro attached" --category cli --attach-transcript /tmp/session.jsonl
+
+${chalk19.bold("Category:")}
+  ${chalk19.bold("cli")}            Feedback about the CLI itself (default)
+  ${chalk19.bold("helix")}          Feedback about Helix
+  ${chalk19.bold("stage:<x>")}      Feedback about a lifecycle stage: ${VALID_STAGES.join(", ")}
+
+${chalk19.bold("Transcript (--attach-transcript):")}
+  Uploads the last 200 KB of a coding-agent session transcript, separately from the
+  feedback text. Without a path it picks the newest session from Claude Code, Codex
+  or omp; a path picks that file.
+
+  ${chalk19.yellow("A session transcript contains source code, absolute paths (including your")}
+  ${chalk19.yellow("username), branch and repository names, internal hostnames, and the business")}
+  ${chalk19.yellow("context of your prompts.")} Credentials are scanned for and redacted before
+  upload, and the exact size and source path are printed before anything is sent.
+  Detection is best-effort: omit the flag if the session handled secrets.
+
+AI Agent Directive:
+  Use --json: mutagent feedback send "..." --json
+  Do not pass --attach-transcript unless the user explicitly asks for it.
+  Every report includes the CLI version, platform, OS and Node version; the coding agent's name is added when a transcript is attached.
     `).action(async (feedbackBody, options) => {
     const isJson = getJsonFlag(feedback);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -7190,34 +7161,19 @@ Or set an API key: mutagent config set apiKey <key>`);
 
 // src/commands/install/index.ts
 import { Command as Command11 } from "commander";
-import chalk19 from "chalk";
+import chalk20 from "chalk";
 init_errors();
 function createInstallCommand(deps) {
-  const install = new Command11("install").description("Install a Mutagent package (helix)").argument("<package>", `Package to install: ${VALID_PACKAGES.join(", ")}`).option("--harness <harness>", `Target harness: ${VALID_HARNESSES.join(", ")}`, "claude-code").option("--global", "(retired) Install scope is fixed per package").option("--version <version>", "Package version to install (default: latest)").addHelpText("after", `
-${chalk19.bold("Arguments & flags:")}
-  ${chalk19.bold("<package>")}            ${VALID_PACKAGES.join(" | ")}
-  ${chalk19.bold("--harness <h>")}        ${VALID_HARNESSES.join(" | ")} ${chalk19.dim("(default: claude-code)")}
-  ${chalk19.bold("--version <v>")}        Pin a package version ${chalk19.dim("(default: latest)")}
-  ${chalk19.bold("--json")}               Structured output
-
-${chalk19.bold("Install scope")} ${chalk19.dim("(fixed per package — not selectable)")}:
-  ${chalk19.bold("helix")}                    → installed into the current directory
-  ${chalk19.dim("--global")} is retired: scope is no longer a choice.
-
-${chalk19.bold("Examples:")}
-  ${chalk19.dim("$")} mutagent install helix
-  ${chalk19.dim("$")} mutagent install helix --harness codex
-  ${chalk19.dim("$")} mutagent install helix --version 1.2.3
-  ${chalk19.dim("$")} mutagent install helix --json
-
-${chalk19.bold("Packages:")}
-  ${chalk19.bold("helix")}        ${chalk19.green("(available)")} — the ADLC (Agent Development Life Cycle Orchestrator). Downloaded from a private
-                 registry via a login-brokered signed URL, sha256-verified, then
-                 initialized into your project. No static secret ships in the CLI.
-                 ${chalk19.dim("Installs every harness itself (Claude + Codex) — --harness does not apply.")}
-                 ${chalk19.dim("Carries the diagnostics and evaluator skills, plus the helix-cli binary.")}
-
-${chalk19.yellow("Note:")} install is login-gated. Run ${chalk19.cyan("mutagent login")} first (else exits with a login directive).
+  const install = new Command11("install").description("Install a Mutagent package on this machine (helix)").argument("<package>", `Package to install: ${VALID_PACKAGES.join(", ")}`).option("--harness <harness>", `Harness named in the output and the install report: ${VALID_HARNESSES.join(", ")}`, "claude-code").option("--global", "Refused: helix always installs into the current directory").option("--version <version>", "Package version to install (default: latest)").addHelpText("after", `
+${chalk20.bold("Examples:")}
+  ${chalk20.dim("$")} mutagent install helix
+  ${chalk20.dim("$")} mutagent install helix --version <version>
+  ${chalk20.dim("$")} mutagent install helix --json
+
+${chalk20.bold("helix")}: the Helix agent-development toolkit, set up in the current directory for
+Claude Code and Codex (includes the diagnostics and evaluator skills and helix-cli).
+Requires \`mutagent login\`. This installs Helix locally; \`mutagent helix\` runs it in the cloud.
+--harness does not change what is installed. --global exits with an error.
     `).action(async (pkg, options) => {
     const isJson = getJsonFlag(install);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -7242,9 +7198,9 @@ ${chalk19.yellow("Note:")} install is login-gated. Run ${chalk19.cyan("mutagent
         output.success(`Installed ${result.package}@${result.version} for ${result.harness} in ${result.projectPath ?? "this project"}`);
       } else {
         output.success(`Installed ${result.package}@${result.version}, but the skill is not in place yet`);
-        console.log(`${chalk19.yellow("⚠")} No skill was installed yet — a setup step still has to run.`);
+        console.log(`${chalk20.yellow("⚠")} No skill was installed yet — a setup step still has to run.`);
         if (result.nextStep) {
-          console.log(`${chalk19.blue("→")} Run next: ${chalk19.cyan(result.nextStep)}`);
+          console.log(`${chalk20.blue("→")} Run next: ${chalk20.cyan(result.nextStep)}`);
         }
       }
     } catch (error) {
@@ -7260,13 +7216,12 @@ init_errors();
 var TRACE_RELOCATION_HINT = "trace lives in the `helix-cli` binary, which ships inside helix (install it with: mutagent install helix)";
 function createTraceCommand() {
   const trace = new Command12("trace").description("Not in this binary — trace lives in helix-cli").allowUnknownOption(true).allowExcessArguments(true).argument("[args...]", "Arguments intended for `helix-cli trace`").addHelpText("after", `
-This binary (mutagent) does not provide trace.
-
-  ${TRACE_RELOCATION_HINT}
-
-Install one of those, then run:
+mutagent does not run trace. trace is a command of helix-cli, which
+mutagent install helix installs. Run:
 
   helix-cli trace <args>
+
+This command only prints where trace is and exits with an error.
 `).action((args) => {
     const isJson = getJsonFlag(trace);
     const forwarded = args.length > 0 ? ` ${args.join(" ")}` : " <args>";
@@ -9083,39 +9038,29 @@ async function runCloudLaunch(plan, mode) {
 var MISSING_TASK_MESSAGE = 'cloud runs are non-interactive: pass the task with -p "<task>"';
 function registerAgentCommand(parent, registration, deps = defaultPlanDeps()) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("agent").description("Run a native Helix agent in Cloud").argument("[argv...]", "Native definition, task (-p or JSON-mode positional), and harness flags").allowUnknownOption(true).allowExcessArguments(true).option("--sandbox <id>", "Run in this existing sandbox instead of a fresh preset box").option("--preset <name>", "Preset for automatic placement (not combined with --sandbox)").option("--sandbox-provider <name>", "Cloud placement: run this launch on the named configured sandbox provider").option("--env <name>", "Workspace Environment (mutagent env ls) to load for this run").option("--rpc", "Bridge native JSONL commands on stdin and responses/events on stdout").option("--cwd <path>", "Working directory inside the Cloud session").addHelpText("after", [
+  parent.command("agent").description("Run a Helix agent in the cloud").argument("[argv...]", "Agent definition, then the task and Helix flags").allowUnknownOption(true).allowExcessArguments(true).option("--sandbox <id>", "(internal) Run in an existing sandbox, by sandbox id").option("--preset <name>", "Sandbox preset (not with --sandbox)").option("--sandbox-provider <name>", "Run on this configured sandbox provider").option("--env <name>", "Workspace Environment to load for this run (see mutagent env ls)").option("--rpc", "Read JSON commands on stdin; write events on stdout").option("--cwd <path>", "Working directory in the sandbox").addHelpText("after", [
     "",
     "Examples:",
     '  mutagent helix agent "You are a test reviewer." -p "review the diff"',
-    '  mutagent helix agent --file runtime-agent.md --mode json "run the suite"',
-    "  mutagent helix agent --file runtime-agent.md --prime --mode rpc",
+    '  mutagent helix agent --file reviewer.md --mode json "run the suite"',
+    "  mutagent helix agent --file reviewer.md --prime --mode rpc",
     '  mutagent helix agent --name reviewer --env staging -p "check the deploy"',
     "",
-    "Native grammar:",
-    "  The leading positional is the DEFINITION; later positionals are native task messages.",
-    "  Text/JSON runs preserve every message and option in relative order.",
-    "  --file reads a native runtime brief locally. Its body travels to the harness.",
-    "  --name/--agent resolves local agent roots first, otherwise the image roster.",
-    "  Deployment frontmatter, tools, skills and assets are not compiled by this command.",
-    "  Deployment packages belong to the separate mutagent agent compiler surface.",
-    "  Package deployment and native brief execution complement each other on the same runtime.",
-    "  --prime preserves the agent definition and selects the native Prime scaffold.",
+    "Definition and task:",
+    "  The first argument (or --prompt, --file, --name) defines the agent; -p gives the task.",
+    "  With --mode json, a later positional is the task (JSON-mode positional).",
+    "  --file is read on this machine and its body is sent as the definition; tools, skills and assets its frontmatter names are not installed.",
+    "  --name looks in your local agents first, then the ones built into Helix.",
+    "  Flags that point at other files on this machine are refused, with the reason.",
+    "  --prime keeps the definition and runs it on the lean Prime agent.",
     "",
     "Modes:",
-    "  -p processes the complete model/tool loop; it imposes no one-turn cap.",
-    "  --mode json emits native JSONL; --mode rpc bridges JSONL stdin/stdout.",
-    "  The last valid --mode wins; RPC overrides -p and ignores positional messages.",
-    "  --mode=rpc is a Cloud convenience, normalized to native --mode rpc.",
-    "  RPC stdin EOF closes remote input; stream disconnect only detaches.",
-    "  Default native launch output stays native even with global --json.",
-    "  Native session disconnect detaches; box retention follows the server idle policy.",
-    "  Ctrl-C on a native launch sends SIGINT to that execution and reports its exit status.",
-    "",
-    "Placement:",
-    "  The server selects the configured preset/destination; --preset overrides the preset.",
-    "  --sandbox-provider <name> places a fresh-box launch on that configured provider.",
-    "  --env selects a workspace Environment, independently of LLM --provider/--model.",
-    "  --sandbox selects an existing internal test box.",
+    "  -p runs the whole model and tool loop for this run and prints the final answer.",
+    "  --mode json streams events as JSON lines; --mode rpc reads JSON commands on stdin.",
+    "  With --mode rpc, closing stdin ends the session's input; a dropped connection only detaches.",
+    "  Output is Helix's own, even with --json.",
+    "  Ctrl-C on a native launch sends SIGINT to the session, which stops it; the exit status is reported.",
+    "  A sandbox idle for 15 minutes is checkpointed and stopped.",
     "",
     "AI Agent Directive:",
     "  Preserve the definition/task distinction and select an explicit headless mode.",
@@ -9331,7 +9276,7 @@ function planLauncherArgv(argv, deps = defaultPlanDeps()) {
 
 // src/commands/helix/session-commands.ts
 import { Command as Command13 } from "commander";
-import chalk25 from "chalk";
+import chalk26 from "chalk";
 init_errors();
 
 // src/lib/sandbox-checkpoints.ts
@@ -9357,7 +9302,7 @@ async function restoreCheckpoint(id, body) {
 }
 
 // src/lib/sandbox-session.ts
-import chalk21 from "chalk";
+import chalk22 from "chalk";
 
 // src/lib/tty.ts
 function isPlainOutput() {
@@ -9378,7 +9323,7 @@ init_errors();
 init_known_secrets();
 
 // src/lib/sandbox-frames.ts
-import chalk20 from "chalk";
+import chalk21 from "chalk";
 var SILENT2 = new Set([
   "message_start",
   "message_update",
@@ -9470,7 +9415,7 @@ class FrameFeed {
     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 ? chalk20.red(toolName) : chalk20.cyan(toolName);
+    const name = this.#plain ? toolName : failed ? chalk21.red(toolName) : chalk21.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));
@@ -9487,7 +9432,7 @@ class FrameFeed {
     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 : chalk20.yellow(body));
+    return this.#line(this.#sym("◆", "?"), this.#plain ? body : chalk21.yellow(body));
   }
   #response(frame) {
     const command = typeof frame.command === "string" ? frame.command : "command";
@@ -9496,7 +9441,7 @@ class FrameFeed {
     const body = `${command}${id} ${ok ? "accepted" : "rejected"}`;
     if (this.#plain)
       return this.#line(ok ? "+" : "x", body);
-    return this.#line(ok ? "✓" : "✗", ok ? chalk20.green(body) : chalk20.red(body));
+    return this.#line(ok ? "✓" : "✗", ok ? chalk21.green(body) : chalk21.red(body));
   }
   #line(symbol, body) {
     return `  ${symbol} ${body}`;
@@ -9505,7 +9450,7 @@ class FrameFeed {
     return this.#plain ? plain : styled;
   }
   #dim(text) {
-    return this.#plain ? text : chalk20.dim(text);
+    return this.#plain ? text : chalk21.dim(text);
   }
   #rule(label) {
     const dash = this.#plain ? "-" : "─";
@@ -9595,7 +9540,7 @@ function formatDuration(ms) {
 
 // src/lib/sandbox-session.ts
 function dim(text) {
-  return isPlainOutput() ? text : chalk21.dim(text);
+  return isPlainOutput() ? text : chalk22.dim(text);
 }
 function reattachHint(id, lastSeq) {
   const since = lastSeq > 0 ? ` --since ${String(lastSeq)}` : "";
@@ -9760,66 +9705,38 @@ function parseSince(raw) {
 }
 
 // src/commands/helix/restore-command.ts
-import chalk22 from "chalk";
+import chalk23 from "chalk";
 init_errors();
 var DRIFT_MODES = ["warn", "refuse", "skip"];
 function registerRestore(session, root) {
-  session.command("restore").description("Rebuild a sandbox from a checkpoint, with its workspace and settings").argument("<id>", "Sandbox ID to rebuild. It does NOT have to still be running").option("--snapshot <id>", "Which checkpoint. Defaults to the newest one from this sandbox").option("--on-drift <mode>", `What to do when the transcript references files this box lacks: ${DRIFT_MODES.join(" | ")} (default: warn)`).option("--partial", "Also restore the incremental transcript prefix captured after the last consistency point; may end on an unanswered tool call").addHelpText("after", `
+  session.command("restore").description("(internal) Continue a session from a checkpoint in a rebuilt sandbox, by sandbox id").argument("<sandbox-id>", "Sandbox the checkpoint came from (it may be stopped)").option("--snapshot <id>", "Checkpoint to use (default: the newest complete one from this sandbox)").option("--on-drift <mode>", `If files the conversation names are missing: ${DRIFT_MODES.join(" | ")} (default: warn)`).option("--partial", "Also restore turns saved after the checkpoint (may end mid tool call)").addHelpText("after", `
 Examples:
-  ${chalk22.dim("$")} mutagent helix session restore sbx_456
-  ${chalk22.dim("$")} mutagent helix session restore sbx_456 --snapshot snap_1
-  ${chalk22.dim("$")} mutagent helix session restore sbx_456 --on-drift refuse --json
-  ${chalk22.dim("$")} mutagent helix session restore sbx_456 --partial
-
-THE BOX DOES NOT HAVE TO BE ALIVE. This is the cloud equivalent of a local
-'/resume', and a reaped or torn-down sandbox is the ORDINARY input — it is what a
-cloud session normally ends as. There is no --session flag any more: the old
-route restored into a session you had already started, which assumed a live box,
-which is exactly what a hard kill does not leave.
-
-WHAT HAPPENS, IN ORDER:
-  1. a fresh box for the SAME sandbox id at generation+1, same secret names
-  2. the seq counter is seeded from what is already stored, so your ?since=
-     cursor keeps working across the seam
-  3. the workspace and ~/.mutagent are extracted BEFORE Helix starts
-  4. a session starts in the checkpoint's cwd
-  5. the conversation is written in, its sha256 checked, and only then switched
-     onto — a mismatch is a 422 and the agent is never pointed at it
-  6. the runtime settings and pending queue are replayed
-  7. a 'restored' marker goes on the stream with a real seq
-
-READ 'notRestored'. Restoring only the conversation is a legitimate outcome — a
-deployment with no object store, or a checkpoint taken before continuous capture
-existed — and it must not look identical to a full-state restore. Every leg that
-did not come back names itself there.
-
---on-drift, for files that are STILL missing after the workspace was extracted:
-  ${chalk22.bold("warn")}    (default) restore, and report them in workspaceDrift.
-  ${chalk22.bold("refuse")}  fail with 409 BEFORE switching.
-  ${chalk22.bold("skip")}    do not probe at all; status comes back 'unchecked'.
-
---partial restores the incremental transcript prefix captured AFTER the last
-consistency point — the turns a mid-turn kill would otherwise lose — when it
-extends the checkpoint. ACCEPTED RISK: the prefix is cut at its last complete
-line and may end on a tool call whose result never landed; the harness answers
-it with a synthetic error result on the next turn, and any side effect the
-original call had is not undone. When no prefix exists, or it does not extend
-the checkpoint, the checkpoint is restored and 'notRestored' says why; 'partial'
-on the result says which happened.
-
-A DEFAULTED restore (no --snapshot) may pass over newer checkpoints whose
-manifest never landed to reach one it can restore in full. Each one skipped is
-listed in 'skippedSnapshots' with why.
+  ${chalk23.dim("$")} mutagent helix session restore sbx_456
+  ${chalk23.dim("$")} mutagent helix session restore sbx_456 --snapshot snap_1
+  ${chalk23.dim("$")} mutagent helix session restore sbx_456 --on-drift refuse --json
+
+Rebuilds the sandbox (the old one may be stopped or gone), restores the workspace
+and settings where the checkpoint has them, and starts a new session that
+continues the conversation. notRestored lists anything not carried over.
+Find the new session's reference with 'mutagent helix session ls' (STATUS restored).
+
+--on-drift, for files still missing after the workspace is restored:
+  warn    restore, and list them in workspaceDrift
+  refuse  fail before switching to the restored conversation
+  skip    do not check
+--partial may end on a tool call whose result never arrived; Helix answers it
+with an error on the next turn, and that call's side effects are not undone.
+Without --snapshot, newer checkpoints that cannot be restored in full are passed
+over and listed in skippedSnapshots.
 
 AI Agent Directive:
   --json returns { success, restored, sandboxId, generation, snapshotId,
   sessionId, harnessSessionId, cwd, bytes, sha256, seq, settingsReplayed,
   queueReplayed, workspace, workspaceDrift, notRestored, partial, partialBytes,
-  skippedSnapshots }. 'sessionId' is a NEW session in the rebuilt box — send the
-  next turn to that one, not to the id you held before. 'seq' is where the
-  stream continues; pass it as ?since=. 'partial' is true only when the
-  incremental prefix was restored; 'skippedSnapshots' names newer checkpoints a
-  defaulted restore passed over.
+  skippedSnapshots }. The restore starts a NEW session and returns no reference:
+  find it with 'mutagent helix session ls --json' (status restored) and use that
+  reference for attach, send, signal and checkpoint. Read notRestored before
+  relying on the restored state.
       `).action(async (id, options) => {
     const isJson = getJsonFlag(root);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -9847,21 +9764,21 @@ AI Agent Directive:
         return;
       }
       output.success(`Sandbox ${id} rebuilt at generation ${String(result.generation)} from snapshot ${result.snapshotId}`);
-      console.error(chalk22.dim(`  New session ${result.sessionId} · stream continues at seq ${String(result.seq)}`));
+      console.error(chalk23.dim(`  New session ${result.sessionId} · stream continues at seq ${String(result.seq)}`));
       if (result.workspace !== null) {
-        console.error(chalk22.dim(`  Workspace: ${String(result.workspace.files)} files into ${result.cwd ?? "the default cwd"}`));
+        console.error(chalk23.dim(`  Workspace: ${String(result.workspace.files)} files into ${result.cwd ?? "the default cwd"}`));
       }
       if (result.settingsReplayed.length > 0) {
-        console.error(chalk22.dim(`  Replayed: ${result.settingsReplayed.join(", ")}`));
+        console.error(chalk23.dim(`  Replayed: ${result.settingsReplayed.join(", ")}`));
       }
       if (result.partial) {
-        console.error(chalk22.dim(`  Partial: ${String(result.partialBytes)} bytes beyond the checkpoint`));
+        console.error(chalk23.dim(`  Partial: ${String(result.partialBytes)} bytes beyond the checkpoint`));
       }
       for (const skipped of result.skippedSnapshots) {
-        console.error(chalk22.dim(`  skipped ${skipped.id}: ${skipped.reason}`));
+        console.error(chalk23.dim(`  skipped ${skipped.id}: ${skipped.reason}`));
       }
       for (const gap of result.notRestored)
-        console.error(chalk22.yellow(`  ! ${gap}`));
+        console.error(chalk23.yellow(`  ! ${gap}`));
     } catch (error) {
       handleError(error, isJson);
     }
@@ -9890,54 +9807,45 @@ function planSessionStartArgs(argv, deps) {
 }
 
 // src/commands/helix/send.ts
-import chalk23 from "chalk";
+import chalk24 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, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("send").description("Send a command line into a running session").argument("<id>", "Live execution reference (or internal sandbox ID with --session)").argument("[message...]", "What to say to the agent").option("--session <id>", "Internal operation: session ID inside the named 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", `
+  parent.command("send").description("Send a prompt or command to a session").argument("<reference>", "Session reference (hs1_...); with --session, a sandbox id (internal)").argument("[message...]", "What to say to the agent").option("--session <id>", "(internal) The session id, when the first argument is a sandbox id").option("--type <type>", `${COMMAND_TYPES.join(" | ")} (default: prompt)`).option("--line <json>", "Send this exact JSON command instead of building one").option("--message-id <id>", "Use this command id instead of a generated one").addHelpText("after", `
 Examples:
-  ${chalk23.dim("$")} mutagent helix session send <reference> "also check the refresh path"
-  ${chalk23.dim("$")} mutagent helix session send <reference> --type steer "stop and re-read the spec"
-  ${chalk23.dim("$")} mutagent helix session send <reference> --type abort
-  ${chalk23.dim("$")} mutagent helix session send <reference> --line '{"type":"prompt","id":"p7","message":"go"}'
-  ${chalk23.dim("$")} mutagent helix session send <reference> "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 session attach <reference>
-
-A session that is no longer running is refused rather than silently accepted —
-'mutagent sandbox ls' shows what is still up.
-
-For internal box operations, use send <sandbox-id> --session <session-id>.
-The live reference is execution-scoped, not durable conversation identity.
+  ${chalk24.dim("$")} mutagent helix session send <reference> "also check the refresh path"
+  ${chalk24.dim("$")} mutagent helix session send <reference> --type steer "stop and re-read the spec"
+  ${chalk24.dim("$")} mutagent helix session send <reference> --type abort
+  ${chalk24.dim("$")} mutagent helix session send <reference> --line '{"type":"prompt","id":"p7","message":"go"}'
+  ${chalk24.dim("$")} mutagent helix session send <reference> "run the tests" --json
+
+Types:
+  prompt     A new instruction to an agent that has finished its turn
+  steer      Redirect the turn in progress
+  follow_up  Continue from what the agent just said
+  abort      Stop the current turn (no message)
+--line sends one JSON object as written, for a command the four types do not
+cover. It cannot be combined with --type or a message.
+
+Only rpc sessions (started with --mode rpc or --rpc) accept input, and a session
+that has ended refuses it; 'mutagent helix session ls' shows which are live.
+With a sandbox id and --session, if the sandbox is being stopped for idling, send
+waits the time the server asks and retries once. If the session's sandbox was stopped for idling,
+'mutagent helix session ls --json' shows its sandboxId; 'mutagent helix session
+restore <sandbox-id>' (internal) continues it in a new session.
+Send does not wait for the reply. The reply arrives on the session's stream as a
+'response' event carrying the command id (in --json output). Watch it with:
+  ${chalk24.dim("$")} mutagent helix session attach <reference>
 
 AI Agent Directive:
-  --json returns ONE object: { success, reference, type, id, line,
-  accepted, _links }. 'accepted' means DELIVERED, not answered — the answer is a
-  'response' frame with the same id on 'mutagent helix session attach <reference> --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.
+  --json returns ONE object: { success, reference, type, id, line, accepted,
+  _links }. 'accepted' means delivered, not answered: the answer is a 'response'
+  event with the same id on 'mutagent helix session attach <reference>'. This
+  command does not wait for it. Use --type and a message; use --line only for a
+  command the four types cannot express.
       `).action(async (id, messageParts, options) => {
     const isJson = getJsonFlag(jsonSource);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -9978,8 +9886,8 @@ AI Agent Directive:
         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 sandbox attach ${id}`));
+      console.error(chalk24.dim(`  ${built.line}`));
+      console.error(chalk24.dim(`  The reply arrives on the stream, not here: mutagent sandbox attach ${id}`));
     } catch (error) {
       handleError(error, isJson);
     }
@@ -10041,56 +9949,33 @@ function readType(raw) {
 }
 
 // src/commands/helix/signal.ts
-import chalk24 from "chalk";
+import chalk25 from "chalk";
 init_errors();
 var SIGNAL_TYPES = ["SIGINT", "SIGTERM"];
 var DEFAULT_SIGNAL = "SIGINT";
 function registerSignalCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("signal").description("Stop a running session, leaving its sandbox up").argument("<id>", "Live execution reference (or internal sandbox ID with --session)").option("--session <id>", "Internal operation: session ID inside the named sandbox").option("--type <signal>", `${SIGNAL_TYPES.join(" | ")} (default: ${DEFAULT_SIGNAL})`).addHelpText("after", `
+  parent.command("signal").description("Stop a session with SIGINT or SIGTERM; its sandbox stays up").argument("<reference>", "Session reference (hs1_...); with --session, a sandbox id (internal)").option("--session <id>", "(internal) The session id, when the argument is a sandbox id").option("--type <signal>", `${SIGNAL_TYPES.join(" | ")} (default: ${DEFAULT_SIGNAL})`).addHelpText("after", `
 Examples:
-  ${chalk24.dim("$")} mutagent helix session signal <reference>                    ${chalk24.dim("SIGINT — like Ctrl-C")}
-  ${chalk24.dim("$")} mutagent helix session signal <reference> --type SIGTERM     ${chalk24.dim("Ask it to shut down")}
-  ${chalk24.dim("$")} mutagent helix session signal <reference> --json
-
-THE SANDBOX SURVIVES. This stops the SESSION — the agent process — and leaves
-the box, its filesystem and its event log exactly where they are, so you can
-attach, exec against it, or read what the agent did before you stopped it.
-'mutagent sandbox rm <id>' is still the only thing that destroys a sandbox.
-
-THREE WAYS TO STOP AN AGENT, WEAKEST FIRST:
-  ${chalk24.bold("send --type abort")}  Asks the agent to end the turn. Needs a cooperating agent
-                     that is still reading its stdin. Try this first.
-  ${chalk24.bold("signal")}             Does not ask. Reaches a wedged or looping process.
-                     The session ends; the box stays.
-  ${chalk24.bold("rm")}                 Destroys the sandbox and everything in it.
-
-THE SIGNALS:
-  SIGINT    Interrupts the current turn, the way Ctrl-C does in a local terminal.
-  SIGTERM   Asks the process to shut down.
-SIGKILL is not accepted: it would end the session before it could flush the
-output you came back to read.
-
-A 200 here means a LIVE process was signalled — not just that the request was
-understood. A session that had already finished is reported as such rather than
-being counted as a success, so this never tells you that you stopped an agent
-that had in fact been done for a while.
-
-'mutagent sandbox ls' shows which sandboxes are up; 'mutagent helix session attach <reference>'
-shows what the session was doing.
-
-For internal box operations, use signal <sandbox-id> --session <session-id>.
-The live reference is execution-scoped, not durable conversation identity.
+  ${chalk25.dim("$")} mutagent helix session signal <reference>
+  ${chalk25.dim("$")} mutagent helix session signal <reference> --type SIGTERM
+  ${chalk25.dim("$")} mutagent helix session signal <reference> --json
+
+SIGINT (the signal Ctrl-C sends) and SIGTERM both stop the session's Helix process.
+SIGKILL is not supported.
+To end only the current turn and keep the session, use
+'mutagent helix session send <reference> --type abort' instead; signal works even
+when the agent has stopped reading its input.
+Exits non-zero if the session had already ended.
+The sandbox is not deleted: its files and event log stay, and
+'mutagent helix session attach <reference>' shows what the session did. A sandbox
+idle for 15 minutes is checkpointed and stopped.
 
 AI Agent Directive:
-  --json returns ONE object: { success, reference, signal, signalled,
-  _links }. 'signalled' is an EFFECT, not an acknowledgement — it is true only
-  when a running process was actually stopped.
-  A session that has already ended exits non-zero rather than reporting success.
-  Treat that as information, not as a failure to retry: the agent is already
-  stopped, which is what you wanted.
-  This does NOT destroy the sandbox. It stays billable until 'mutagent sandbox rm
-  <id>'. Confirm with the user before that.
+  --json returns ONE object: { success, reference, signal, signalled, _links }.
+  'signalled' is true only when a running process was stopped. A session that had
+  already ended exits non-zero; the agent is already stopped, so treat it as
+  information and do not retry.
       `).action(async (id, options) => {
     const isJson = getJsonFlag(jsonSource);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -10129,8 +10014,8 @@ AI Agent Directive:
         return;
       }
       output.success(`Sent ${signal} to session ${sessionId}`);
-      console.error(chalk24.dim(`  The sandbox is still up: mutagent sandbox attach ${id}`));
-      console.error(chalk24.dim(`  Destroy it with: mutagent sandbox rm ${id}`));
+      console.error(chalk25.dim(`  The sandbox is still up: mutagent sandbox attach ${id}`));
+      console.error(chalk25.dim(`  Destroy it with: mutagent sandbox rm ${id}`));
     } catch (error) {
       handleError(error, isJson);
     }
@@ -10148,46 +10033,26 @@ function resolveSignal(raw) {
 
 // src/commands/helix/session-commands.ts
 function registerSessionCommand(parent) {
-  const session = new Command13("session").description("Control live Helix executions; start/ls are internal existing-box operations").addHelpText("after", `
+  const session = new Command13("session").description("List, watch and control Helix sessions").addHelpText("after", `
 Examples:
-  ${chalk25.dim("$")} mutagent helix session start sbx_123 --rpc
-  ${chalk25.dim("$")} mutagent helix session ls sbx_123
-  ${chalk25.dim("$")} mutagent helix session attach <reference>
-  ${chalk25.dim("$")} mutagent helix session send <reference> "and now the tests"
-  ${chalk25.dim("$")} mutagent helix session signal <reference>
-  ${chalk25.dim("$")} mutagent helix session checkpoint <reference>
-  ${chalk25.dim("$")} mutagent helix session checkpoints sbx_123 --json
-  ${chalk25.dim("$")} mutagent helix session restore sbx_456
-
-A sandbox and a session are not the same thing:
-  ${chalk25.bold("sandbox spawn")}   gives you a BOX — a machine with nothing running in it.
-  ${chalk25.bold("session start")}   gives you an AGENT inside that box.
-  ${chalk25.bold("session attach")}  WATCHES it.
-  ${chalk25.bold("session send")}    TYPES INTO it.
-  ${chalk25.bold("session signal")}  STOPS it, and leaves the box standing.
-  ${chalk25.bold("sandbox rm")}      destroys the box. Only that.
-A box with no session is a normal state — that is what 'sandbox exec' runs against.
-
-EXPLICIT TRANSCRIPT TRANSFER (NOT A DURABLE CONVERSATION ID):
-  ${chalk25.bold("checkpoint")} copies the HARNESS's own transcript off the box. That is what a
-  new box needs to CONTINUE the conversation — it is not the same as replaying
-  the stream, which shows what you watched and restores no agent state at all.
-  ${chalk25.bold("restore")} rebuilds from the checkpoint and starts a new runtime session,
-  verifying captured data before using it. Workspace/settings capture depends
-  on deployment support and the checkpoint. Read notCaptured and notRestored;
-  a stored transcript alone is not a full-state checkpoint or durable identity.
-
-Moved here from 'mutagent helix' (BREAKING):
-  'helix send' and 'helix signal' are now 'helix session send' and
-  'helix session signal'. There is no alias; the old spellings are gone.
+  ${chalk26.dim("$")} mutagent helix session ls
+  ${chalk26.dim("$")} mutagent helix session attach <reference>
+  ${chalk26.dim("$")} mutagent helix session send <reference> "and now the tests"
+  ${chalk26.dim("$")} mutagent helix session signal <reference>
+  ${chalk26.dim("$")} mutagent helix session checkpoint <reference>
+
+A session reference (hs1_...) is printed when a run starts and listed by 'session ls'.
+attach, send, signal and checkpoint take it.
+start, 'ls <sandbox-id>', checkpoints and restore are internal and take a sandbox id.
+checkpoint saves a session's conversation; restore continues it in a rebuilt sandbox.
+A sandbox idle for 15 minutes is checkpointed and stopped; restore rebuilds it.
 
 AI Agent Directive:
-  Launch with 'mutagent helix --mode rpc'; use its live execution reference for
-  attach/send/signal/checkpoint. The reference expires with its live execution.
-  Internal box operations remain available via start/ls and --session <id> on
-  send/signal/checkpoint; these require an explicit box ID and session ID.
-  Use --rpc to send commands into a live session; a one-shot refuses input.
-  Restore addresses the checkpoint's sandbox ID and starts a NEW session.
+  Start work with 'mutagent helix --mode rpc' and keep the session reference it
+  prints; 'mutagent helix session ls --json' lists references too. Use the
+  reference for attach, send, signal and checkpoint; never guess one. Only an rpc
+  session accepts send. start, checkpoints and restore are internal and take a
+  sandbox id; restore starts a NEW session, found with 'session ls'.
       `);
   registerStart(session, parent);
   registerSessionLs(session, parent);
@@ -10210,50 +10075,25 @@ function withSessionFlags(options, own) {
   };
 }
 function registerStart(session, root) {
-  session.command("start").description("Start a Helix session inside an existing sandbox").argument("<id>", "Sandbox ID").argument("[args...]", "Arguments for the Helix binary inside the box").allowUnknownOption(true).allowExcessArguments(true).option("--rpc", "Long-lived session you can send into (default: one-shot)").option("--cwd <path>", "Working directory for the agent (default: the box's $HOME in rpc mode)").option("--env <name>", "Workspace Environment (mutagent env ls) to load into this session").addHelpText("after", `
+  session.command("start").description("(internal) Start a Helix session in an existing sandbox, by sandbox id").argument("<sandbox-id>", "Sandbox to start the session in").argument("[args...]", "Helix flags (put -- before them)").allowUnknownOption(true).allowExcessArguments(true).option("--rpc", "Keep the session open for 'session send' (default: run once and end)").option("--cwd <path>", "Working directory (default: $HOME for an rpc session)").option("--env <name>", "Workspace Environment to load (see mutagent env ls)").addHelpText("after", `
 Examples:
-  ${chalk25.dim("$")} mutagent helix session start sbx_123 --rpc
-  ${chalk25.dim("$")} mutagent helix session start sbx_123 --rpc --cwd /workspace
-  ${chalk25.dim("$")} mutagent helix session start sbx_123 --rpc --env staging
-  ${chalk25.dim("$")} mutagent helix session start sbx_123 --rpc --json
-  ${chalk25.dim("$")} mutagent helix session start sbx_123 -- --model gpt-5 --thinking high
-
-TWO MODES, AND ONLY ONE OF THEM LISTENS:
-  ${chalk25.bold("--rpc")}      A long-lived agent reading commands on its stdin. This is
-             the mode 'session send' writes into; without it there is
-             nothing to write to and every send is refused with a 409.
-  ${chalk25.dim("(default)")}  One-shot. The session completes its run and ends. Watchable
-             with 'session attach', not steerable.
-
-${chalk25.bold("--cwd")} IS NOT COSMETIC. The in-box server runs from /app, which is root-owned
-while the agent runs as 'sandbox'. An rpc child started there loses its subagent
-scheduler to EACCES — and then answers normally, because the failure goes to
-stderr and the core loop survives. A half-crippled agent that looks healthy. So
-an rpc session with no --cwd runs in $HOME, writable by construction; name a
-directory only for the real case that cannot serve, a mounted work directory.
-
-${chalk25.bold("--env <name>")} loads a WORKSPACE ENVIRONMENT — the variables and secrets the
-agent's tools need, stored with 'mutagent env set' — into this session. It is
-resolved on the server; no value passes through this machine. It is NOT a model
-key: providers come from the workspace's provider configuration, and an
-Environment variable named like one is refused at 'env set' for that reason.
-
-TRAILING ARGUMENTS are classified exactly as on 'mutagent helix agent --sandbox':
-forwarded, translated or REFUSED with a reason. A flag naming a path on THIS
-machine (--extension, --session <file>, --skill, …) is refused, because it would
-point at nothing inside the box. A leading positional, --prompt, --file or
---name is the agent DEFINITION, resolved here first. Put ${chalk25.bold("--")} before them so
-they are not read as flags for this command. A ${chalk25.bold("--")} does NOT stop the
-classification: the harness has no end-of-options marker, so neither does this.
-
-The box must already exist — 'mutagent sandbox spawn --image <ref>' makes one,
-and 'mutagent sandbox ls' shows which are running. One sandbox can host several
-sessions, so starting one never replaces another.
+  ${chalk26.dim("$")} mutagent helix session start sbx_123 --rpc
+  ${chalk26.dim("$")} mutagent helix session start sbx_123 --rpc --env staging
+  ${chalk26.dim("$")} mutagent helix session start sbx_123 --rpc --json
+  ${chalk26.dim("$")} mutagent helix session start sbx_123 -- --model <provider/model> --thinking high
+
+Prints the session id. Address the session as <sandbox-id> --session <session-id>
+for send, signal and checkpoint, and watch it with 'mutagent sandbox attach <sandbox-id>'.
+Only an --rpc session accepts 'session send'; a one-shot session runs and ends.
+Flags after -- go to Helix. A flag that names a file on this machine is refused,
+because the sandbox cannot read it. A leading positional, --prompt, --file or
+--name is the agent definition, resolved on this machine first.
+One sandbox can host several sessions; starting one never replaces another.
 
 AI Agent Directive:
   --json returns ONE object: { success, sandboxId, sessionId, status, mode,
-  _links }. Capture 'sessionId' for internal send, signal and checkpoint.
-  Restore takes the sandbox ID and returns a NEW sessionId; it needs no live session.
+  _links, _directive }. Address the session as <sandbox-id> --session <sessionId>
+  for send, signal and checkpoint.
       `).action(async (id, rawArgs, options) => {
     const isJson = getJsonFlag(root);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -10293,9 +10133,9 @@ AI Agent Directive:
         return;
       }
       output.success(`Session ${sessionId} started in ${id} (${mode})`);
-      console.error(chalk25.dim(`  Watch it:   mutagent sandbox attach ${id}`));
+      console.error(chalk26.dim(`  Watch it:   mutagent sandbox attach ${id}`));
       if (mode === "rpc") {
-        console.error(chalk25.dim(`  Talk to it: mutagent helix session send ${id} --session ${sessionId} "<message>"`));
+        console.error(chalk26.dim(`  Talk to it: mutagent helix session send ${id} --session ${sessionId} "<message>"`));
       }
     } catch (error) {
       handleError(error, isJson);
@@ -10308,24 +10148,18 @@ function requireSessionId(result, sandboxId) {
   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 sandbox attach ${sandboxId}`);
 }
 function registerSessionLs(session, root) {
-  session.command("ls").description("List Helix sessions — no argument: the whole workspace; with a box id: that one box").argument("[id]", "Sandbox ID (omit for the workspace-wide listing)").addHelpText("after", `
+  session.command("ls").description("List this workspace's Helix sessions").argument("[sandbox-id]", "(internal) List the session ids in one sandbox instead").addHelpText("after", `
 Examples:
-  ${chalk25.dim("$")} mutagent helix session ls              ${chalk25.dim("Every session in the workspace, all boxes")}
-  ${chalk25.dim("$")} mutagent helix session ls --json
-  ${chalk25.dim("$")} mutagent helix session ls sbx_123     ${chalk25.dim("One box (internal): ids only")}
-  ${chalk25.dim("$")} mutagent helix session ls sbx_123 --json
-
-NO ARGUMENT — the workspace listing. Rows across ALL of your sandboxes, live
-and ended, newest activity first: reference (the address attach/send/signal
-take), box, arm, mode, status and last activity. Status tells you what
-happened: 'live' is running now; 'ended' finished (exitCode in --json names
-how); 'stopped-for-idling' died with its box, reaped by the idle policy;
-'restored' is running on a box rebuilt from a checkpoint. Sessions older than
-the persisted arm/mode fields show those columns blank rather than a guess.
-
-WITH A BOX ID — the internal box listing, unchanged: bare session ids that one
-sandbox is hosting. An empty list is a normal result: a box with no session in
-it is what 'mutagent sandbox exec' runs against.
+  ${chalk26.dim("$")} mutagent helix session ls
+  ${chalk26.dim("$")} mutagent helix session ls --json
+
+Every session in the workspace, live and ended, newest activity first.
+STATUS is live (running now), ended (finished; exitCode in --json), stopped-for-idling
+(its sandbox was idle for 15 minutes, then checkpointed and stopped) or restored
+(running in a sandbox rebuilt from a checkpoint). ARM and MODE are blank for
+sessions older than those fields.
+Pass the REFERENCE to attach, send, signal or checkpoint.
+With a sandbox id, lists the bare session ids in that one sandbox (internal).
 
 AI Agent Directive:
   Run 'mutagent helix session ls --json' to discover live work — { workspaceId,
@@ -10342,7 +10176,7 @@ AI Agent Directive:
           return;
         }
         if (sessions2.length === 0) {
-          console.log(chalk25.gray(`No sessions running in ${id}.`));
+          console.log(chalk26.gray(`No sessions running in ${id}.`));
           console.log("");
           console.log(`  Start one: mutagent helix session start ${id} --rpc`);
           return;
@@ -10361,7 +10195,7 @@ AI Agent Directive:
         return;
       }
       if (sessions.length === 0) {
-        console.log(chalk25.gray("No Helix sessions in this workspace yet."));
+        console.log(chalk26.gray("No Helix sessions in this workspace yet."));
         console.log("");
         console.log('  Launch one: mutagent helix launch --task "..."  (or session start <box>)');
         return;
@@ -10375,7 +10209,7 @@ AI Agent Directive:
         "LAST ACTIVITY": s.lastActivityAt
       })));
       if (nextCursor !== undefined) {
-        console.log(chalk25.gray("\nMore sessions — re-run with the cursor from --json `nextCursor`."));
+        console.log(chalk26.gray("\nMore sessions — re-run with the cursor from --json `nextCursor`."));
       }
     } catch (error) {
       handleError(error, isJson);
@@ -10383,17 +10217,16 @@ AI Agent Directive:
   });
 }
 function registerSessionAttach(session) {
-  session.command("attach").description("Watch one live Helix execution").argument("<reference>", "Reference returned when the session started").option("--since <seq>", "Resume after this transport sequence number").addHelpText("after", [
+  session.command("attach").description("Watch a session").argument("<reference>", "Session reference (hs1_...) from 'mutagent helix' or 'session ls'").option("--since <n>", "Replay from after event number n").addHelpText("after", [
     "",
     "Examples:",
     "  mutagent helix session attach <reference>",
     "  mutagent helix session attach <reference> --since 412",
     "",
     "AI Agent Directive:",
-    "  Output is native harness text/JSONL. Diagnostics stay on stderr.",
-    "  Ctrl-C detaches without signalling or destroying the session.",
-    "  A live execution reference does not identify a conversation across restore.",
-    "  Use mutagent sandbox attach for the internal box-wide event stream."
+    "  Output is Helix's own text or JSON lines on stdout; CLI messages go to stderr. --json does not change it.",
+    "  Ctrl-C stops watching without signalling the session.",
+    "  A reference names one session; after a restore, take the new reference from session ls."
   ].join(`
 `)).action(async (reference, options) => {
     try {
@@ -10411,28 +10244,20 @@ function registerSessionAttach(session) {
   });
 }
 function registerCheckpoint(session, root) {
-  session.command("checkpoint").description("Capture a running session's own transcript into a snapshot").argument("<id>", "Live reference (or internal sandbox ID with --session)").option("--session <id>", "Internal operation: session ID inside the named sandbox").addHelpText("after", `
+  session.command("checkpoint").description("Save a session's conversation as a checkpoint").argument("<reference>", "Session reference (hs1_...); with --session, a sandbox id (internal)").option("--session <id>", "(internal) The session id, when the argument is a sandbox id").addHelpText("after", `
 Examples:
-  ${chalk25.dim("$")} mutagent helix session checkpoint <reference>
-  ${chalk25.dim("$")} mutagent helix session checkpoint <reference> --json
+  ${chalk26.dim("$")} mutagent helix session checkpoint <reference>
+  ${chalk26.dim("$")} mutagent helix session checkpoint <reference> --json
 
-WHAT IS CAPTURED: the HARNESS's own session file, verbatim. That is what a new
-box needs to CONTINUE the conversation. It is NOT the same as replaying the
-stream with --since, which shows what a client observed and restores no agent
-state at all.
-
-Workspace and settings may also be captured when supported. Read notCaptured
-before treating a result as full-state capture: an existing transcript snapshot
-can be reused without replacing its original manifest or capturing new state.
-
-A 409 means the session has not completed a turn yet: the harness writes its
-file lazily, so there is genuinely nothing to capture, and storing an empty
-snapshot would produce a restore that succeeds and restores nothing.
+Saves Helix's own session file, and the workspace and settings where the
+deployment supports it. notCaptured lists anything left out.
+Fails until the session has finished its first turn: before that there is no
+conversation to save.
 
 AI Agent Directive:
-  --json returns { success, snapshotId, bytes, sha256, harnessSessionId,
+  --json returns { success, reference, snapshotId, bytes, sha256, harnessSessionId,
   messageCount, sourcePath, manifestKey, workspaceBytes, workspaceFiles, notCaptured }.
-  Capture snapshotId and inspect notCaptured before relying on a restore.
+  Keep snapshotId and read notCaptured before relying on a restore.
       `).action(async (id, options) => {
     const isJson = getJsonFlag(root);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -10471,22 +10296,20 @@ AI Agent Directive:
       if (Array.isArray(result.notCaptured))
         for (const reason of result.notCaptured)
           output.warn("Not captured: " + reason);
-      console.error(chalk25.dim(`  ${String(result.messageCount)} messages, ${String(result.bytes)} bytes, from ${result.sourcePath}`));
+      console.error(chalk26.dim(`  ${String(result.messageCount)} messages, ${String(result.bytes)} bytes, from ${result.sourcePath}`));
     } catch (error) {
       handleError(error, isJson);
     }
   });
 }
 function registerCheckpoints(session, root) {
-  session.command("checkpoints").description("List the checkpoints captured from a sandbox").argument("<id>", "Sandbox ID").addHelpText("after", `
+  session.command("checkpoints").description("(internal) List a sandbox's checkpoints, by sandbox id").argument("<sandbox-id>", "Sandbox the checkpoints were captured from").addHelpText("after", `
 Examples:
-  ${chalk25.dim("$")} mutagent helix session checkpoints sbx_123
-  ${chalk25.dim("$")} mutagent helix session checkpoints sbx_123 --json
+  ${chalk26.dim("$")} mutagent helix session checkpoints sbx_123
+  ${chalk26.dim("$")} mutagent helix session checkpoints sbx_123 --json
 
-Newest first, and WITHOUT the stored bytes: a list route returning every
-transcript in full would be the most expensive query in the system and would
-spread conversations into logs and caches nobody chose. 'messageCount' is how
-much conversation each one holds.
+Newest first, without the stored bytes. MESSAGES is how much conversation each holds.
+Pass an id to 'mutagent helix session restore <sandbox-id> --snapshot <id>'.
 
 AI Agent Directive:
   --json returns { snapshots: [...], count: N, sandboxId }. Read it to find a
@@ -10501,7 +10324,7 @@ AI Agent Directive:
         return;
       }
       if (snapshots.length === 0) {
-        console.log(chalk25.gray(`No checkpoints captured from ${id}.`));
+        console.log(chalk26.gray(`No checkpoints captured from ${id}.`));
         console.log("");
         console.log(`  Capture one: mutagent helix session checkpoint ${id} --session <session-id>`);
         return;
@@ -10526,11 +10349,11 @@ function requireSession(raw, example) {
 }
 
 // src/commands/helix/models.ts
-import chalk26 from "chalk";
+import chalk27 from "chalk";
 init_errors();
 function printView(view, output) {
   if (view.models.length === 0) {
-    console.log(chalk26.gray("No Helix Cloud models: this workspace has no active LLM provider the box can use."));
+    console.log(chalk27.gray("No Helix Cloud models: this workspace has no active LLM provider the box can use."));
     console.log("");
     console.log("  Add one: mutagent providers add --provider <id> --name <name> --api-key <key>");
   } else {
@@ -10540,27 +10363,26 @@ function printView(view, output) {
       name: m.displayName
     })));
     console.log("");
-    console.log(view.default === null ? chalk26.yellow("No default set — a run without --model answers 428. Set one: mutagent helix models default <provider/model>") : `Default: ${view.default}`);
+    console.log(view.default === null ? chalk27.yellow("No default set — a run without --model answers 428. Set one: mutagent helix models default <provider/model>") : `Default: ${view.default}`);
   }
   if (view.unmapped.length > 0) {
-    console.log(chalk26.yellow(`Not usable in a box (no harness credential mapping): ${view.unmapped.join(", ")}`));
+    console.log(chalk27.yellow(`Not usable in a box (no harness credential mapping): ${view.unmapped.join(", ")}`));
   }
 }
 function registerModelsCommand(helix) {
-  const models = helix.command("models").description("List this workspace's Helix Cloud models and its default").addHelpText("after", `
+  const models = helix.command("models").description("List the models Helix can use in the cloud, and the workspace default model").addHelpText("after", `
 Examples:
-  ${chalk26.dim("$")} mutagent helix models
-  ${chalk26.dim("$")} mutagent helix models --json
-  ${chalk26.dim("$")} mutagent helix models default zai-coding-cn/glm-5.2
-  ${chalk26.dim("$")} mutagent helix models default zai-coding-cn/glm-5.2 anthropic/claude-sonnet-4-5
+  ${chalk27.dim("$")} mutagent helix models
+  ${chalk27.dim("$")} mutagent helix models --json
+  ${chalk27.dim("$")} mutagent helix models default zai-coding-cn/glm-5.2
+  ${chalk27.dim("$")} mutagent helix models default zai-coding-cn/glm-5.2 openai/gpt-5
 
-The list is the platform catalog restricted to this workspace's active LLM
-providers ('mutagent providers'). Each id is provider/model in the harness's
-spelling — pass it as --model to 'helix session start' or 'helix agent'.
+Lists the models your workspace's active LLM providers ('mutagent providers') give
+Helix in the cloud. Each id is provider/model: pass it as --model to 'mutagent helix'
+or 'mutagent helix agent'.
 
-A cloud run that names no model uses the workspace DEFAULT (★). With none set
-it answers 428 before any sandbox is spawned. Local 'helix' is unaffected: it
-keeps its own default.
+A cloud run that names no model uses the workspace default model (★). With none
+set, such runs fail until you set one. Your local Helix keeps its own default.
 
 AI Agent Directive:
   --json returns { workspaceId, models: [{ id, provider, harnessProvider, model,
@@ -10580,15 +10402,15 @@ AI Agent Directive:
       handleError(error, isJson);
     }
   });
-  models.command("default").description("Set the workspace default Helix Cloud model (then ordered fallbacks)").argument("[models...]", "provider/model ids from `mutagent helix models`, first = the default").option("--clear", "Remove every default (runs without --model then answer 428)").addHelpText("after", `
+  models.command("default").description("Set the workspace default model for Helix in the cloud, and its fallbacks").argument("[models...]", "Model ids from 'mutagent helix models'; the first is the default").option("--clear", "Remove the default model and every fallback").addHelpText("after", `
 Examples:
-  ${chalk26.dim("$")} mutagent helix models default zai-coding-cn/glm-5.2
-  ${chalk26.dim("$")} mutagent helix models default zai-coding-cn/glm-5.2 openai/gpt-5
-  ${chalk26.dim("$")} mutagent helix models default --clear
+  ${chalk27.dim("$")} mutagent helix models default zai-coding-cn/glm-5.2
+  ${chalk27.dim("$")} mutagent helix models default zai-coding-cn/glm-5.2 openai/gpt-5
+  ${chalk27.dim("$")} mutagent helix models default --clear
 
-REPLACES the list. The first id is the default; the rest are fallbacks used in
-order when an earlier one's provider has since been deactivated. Every id must
-be in 'mutagent helix models' — the server rejects the rest with the list.
+Replaces the list. The first id is the default; later ids are used in order when
+an earlier model's LLM provider has been turned off. Every id must appear in
+'mutagent helix models'; the server refuses the rest.
 
 AI Agent Directive:
   --json returns the same shape as 'mutagent helix models --json', after the
@@ -10616,7 +10438,7 @@ AI Agent Directive:
 }
 
 // src/commands/helix/doctor.ts
-import chalk27 from "chalk";
+import chalk28 from "chalk";
 init_errors();
 
 // src/lib/sandbox-catalog.ts
@@ -10651,23 +10473,14 @@ function refreshRuntimeRefusal() {
 }
 function registerDoctorCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("doctor").description("Run the Helix binary's own diagnostics inside a sandbox").option("--sandbox <id>", "Run in this existing sandbox instead of a fresh preset box").option("--preset <name>", "Preset for the fresh sandbox (ignored with --sandbox)").option("--strict", "Pass the binary's --strict").option("--welcome", "Pass the binary's --welcome").option("--refresh-runtime", "Refused: the box's harness is baked into the image").allowUnknownOption(true).addHelpText("after", `
+  parent.command("doctor").description("Check the Helix build in the cloud image").option("--sandbox <id>", "(internal) Run in an existing sandbox, by sandbox id").option("--preset <name>", "Sandbox preset (not with --sandbox)").option("--strict", "Also launch Helix's embedded harness with --version and fail if it fails").option("--welcome", "Print the Helix welcome screen instead of the report").option("--refresh-runtime", "Refused: the cloud image has no Helix runtime to refresh").allowUnknownOption(true).addHelpText("after", `
 Examples:
-  ${chalk27.dim("$")} mutagent helix doctor
-  ${chalk27.dim("$")} mutagent helix doctor --strict --json
-  ${chalk27.dim("$")} mutagent helix doctor --sandbox sbx_123
-
-This runs the BOX's Helix, not yours. It answers "is the image healthy", which
-is a different question from 'mutagent doctor' (this CLI's own environment) and
-from a local 'helix doctor' (your machine's extracted runtime).
+  ${chalk28.dim("$")} mutagent helix doctor
+  ${chalk28.dim("$")} mutagent helix doctor --strict --json
 
---refresh-runtime is REFUSED, with the reason, before any box is touched. The
-box's harness is baked into the image; there is no runtime cache to refresh,
-and the flag would report success against a layer it cannot write.
-
-Without --sandbox this spawns a fresh box from a preset, runs, and tears it
-down. That costs a box for a diagnostic, so pass --sandbox when you already have
-one up.
+Runs Helix's own diagnostics in a temporary sandbox that is removed afterwards,
+and exits with Helix's exit code. It checks the cloud image, not your machine:
+for your local Helix run 'helix doctor'.
 
 AI Agent Directive:
   --json returns { success, command, result: { sandboxId, exitCode, stdout,
@@ -10697,15 +10510,13 @@ AI Agent Directive:
 }
 function registerSmokeCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("smoke").description("Run the Helix binary's own smoke test inside a sandbox").option("--sandbox <id>", "Run in this existing sandbox instead of a fresh preset box").option("--preset <name>", "Preset for the fresh sandbox (ignored with --sandbox)").allowUnknownOption(true).addHelpText("after", `
+  parent.command("smoke").description("Run Helix's smoke test in the cloud").option("--sandbox <id>", "(internal) Run in an existing sandbox, by sandbox id").option("--preset <name>", "Sandbox preset (not with --sandbox)").allowUnknownOption(true).addHelpText("after", `
 Examples:
-  ${chalk27.dim("$")} mutagent helix smoke
-  ${chalk27.dim("$")} mutagent helix smoke --sandbox sbx_123 --json
+  ${chalk28.dim("$")} mutagent helix smoke
+  ${chalk28.dim("$")} mutagent helix smoke --json
 
-The binary's own end-to-end check, run in the box. It takes a real turn, so it
-needs a box with egress — a preset box has it; a box you spawned with the
-default deny policy does not, and the failure will present as an unreachable
-model provider.
+Runs one real model turn in a temporary sandbox that is removed afterwards, and
+exits with Helix's exit code.
 
 AI Agent Directive:
   --json returns the same shape as 'mutagent helix doctor --json'. The binary's
@@ -10729,15 +10540,9 @@ AI Agent Directive:
 }
 function registerUpdateCommand2(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("update").description("Not available in the cloud — the image pins the Helix build").allowUnknownOption(true).allowExcessArguments(true).argument("[argv...]", "The local binary's update flags, accepted so the refusal can name them").addHelpText("after", `
-Locally, 'helix update' replaces the extracted runtime. A cloud sandbox has no
-extracted runtime: the harness is BAKED into the image, and its version is a
-property of the image rather than something a session can change.
-
-To move the cloud version you change which image the preset points at, which is
-a backend/release operation, not a CLI one.
-  ${chalk27.dim("$")} mutagent sandbox presets --json     ${chalk27.dim("what is available, and which is default")}
-  ${chalk27.dim("$")} mutagent helix --version            ${chalk27.dim("this CLI, and the version the image pins")}
+  parent.command("update").description("Not available in the cloud").allowUnknownOption(true).allowExcessArguments(true).argument("[argv...]", "Ignored").addHelpText("after", `
+The cloud Helix version is set by the release. Check it with 'mutagent helix version'.
+To update the Helix on this machine, run 'helix update'.
       `).action(async () => {
     const isJson = getJsonFlag(jsonSource);
     try {
@@ -10750,21 +10555,14 @@ a backend/release operation, not a CLI one.
 }
 function registerVersionCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("version").description("This CLI’s version, and the Helix build the cloud image pins").addHelpText("after", `
+  parent.command("version").description("Show this CLI's version and the Helix version the cloud uses").addHelpText("after", `
 Examples:
-  ${chalk27.dim("$")} mutagent helix version
-  ${chalk27.dim("$")} mutagent helix version --json
-
-TWO DIFFERENT VERSIONS, AND THEY ARE NOT THE SAME THING:
-  cli     the 'mutagent' binary you are running.
-  helix   the build the cloud IMAGE pins, as the backend DECLARES it.
+  ${chalk28.dim("$")} mutagent helix version
+  ${chalk28.dim("$")} mutagent helix version --json
 
-The helix line is DECLARED, not observed: reading it for real means spawning a
-box to run one command. When the difference matters, observe it:
-  ${chalk27.dim("$")} mutagent sandbox exec -- ${IN_BOX_HELIX_BINARY} --version
-
-This says nothing about a Helix installed on THIS machine. For that, run
-'helix --version' directly.
+cli    the mutagent CLI you are running
+helix  the Helix version the cloud image is released with, as the server reports it
+For the Helix on this machine, run 'helix --version'.
 
 AI Agent Directive:
   --json returns { cli, helix, helixSource }. 'helixSource' is "presets", which
@@ -10786,7 +10584,7 @@ async function reportVersions(isJson) {
     return;
   }
   console.log(`cli    ${cli}`);
-  console.log(`helix  ${helix ?? "unknown"} ${chalk27.dim("(pinned by the image, per the backend’s presets)")}`);
+  console.log(`helix  ${helix ?? "unknown"} ${chalk28.dim("(pinned by the image, per the backend’s presets)")}`);
 }
 async function pinnedHelixVersion() {
   const { presets, default: fallback } = await listPresets();
@@ -10827,47 +10625,39 @@ function reportBoxRun(result, output, isJson, context) {
 
 // src/commands/helix/index.ts
 function createHelixCommand() {
-  const helix = new Command14("helix").description("Run Helix in Cloud using the workspace destination").allowUnknownOption(true).allowExcessArguments(true).argument("[argv...]", "Native harness arguments for the classic arm (or --prime)").helpCommand("help [command]", "Print usage for mutagent helix or one of its subcommands").addHelpText("after", [
+  const helix = new Command14("helix").description("Run Helix in the cloud").allowUnknownOption(true).allowExcessArguments(true).argument("[argv...]", 'Helix flags and the task, e.g. -p "<task>"').helpCommand("help [command]", "Print usage for mutagent helix or one of its subcommands").addHelpText("after", [
+    "",
+    "Run options:",
+    '  -p "<task>"                Run the task to completion and print the final answer',
+    '  --mode json "<task>"       Stream events as JSON lines',
+    "  --mode rpc, --rpc          Read JSON commands on stdin; write events on stdout",
+    "  --prime                    Run the lean Prime agent instead of the full orchestrator",
+    "  --model <provider/model>   Model to use (default: the workspace default model; see mutagent helix models)",
+    "  --env <name>               Workspace Environment to load (see mutagent env ls)",
+    "  --preset <name>            Sandbox preset (default: the server's Helix preset)",
+    "  --sandbox-provider <name>  Run on this configured sandbox provider",
+    "  --cwd <path>               Working directory in the sandbox",
+    "  --sandbox <id>             (internal) Run in an existing sandbox, by sandbox id",
     "",
     "Examples:",
     '  mutagent helix -p "plan the refactor"',
     '  mutagent helix --mode json "run the tests"',
     "  mutagent helix --prime --mode rpc",
-    '  mutagent helix --env staging --preset helix -p "check the deploy"',
-    "  mutagent helix agent --file runtime-agent.md --prime --mode rpc",
-    "",
-    "Modes:",
-    "  -p runs the complete model/tool loop and prints the final text.",
-    "  --mode json streams native harness JSONL events; -p is optional.",
-    "  --mode rpc reads JSONL commands on stdin and writes native responses/events.",
-    "  Text/JSON runs preserve every message and option in relative order.",
-    "  The last valid --mode wins; RPC overrides -p and ignores positional messages.",
-    "  --mode=rpc is a Cloud convenience, normalized to native --mode rpc.",
-    "  RPC stdin EOF explicitly closes remote input; stream disconnect only detaches.",
-    "  Ctrl-C sends SIGINT to the launched execution; its native exit status is reported.",
-    "  Read-only session attach Ctrl-C detaches without signalling the execution.",
-    "  --rpc also selects the Cloud RPC transport.",
-    "  A standalone terminal chat UI is not available.",
-    "  Native launch stdout contains harness output only, including with global --json.",
-    "",
-    "Placement:",
-    "  The server selects the configured Helix preset and destination.",
-    "  --preset selects a compatible preset; --env selects a workspace Environment.",
-    "  --sandbox-provider <name> places the launch on that configured sandbox provider.",
-    "  LLM --provider/--model select a model, not the execution destination.",
-    "  --sandbox <id> is available for an existing internal test box.",
-    "  mutagent sandbox and mutagent env retain their independent command groups.",
+    '  mutagent helix --env staging -p "check the deploy"',
+    "  mutagent helix agent --file reviewer.md --prime --mode rpc",
     "",
-    "Sessions:",
-    "  Live execution references support reconnect and control.",
-    "  A reference is not a durable conversation identity across restore.",
-    "  Disconnect detaches; box retention follows the server idle policy.",
+    "Each run prints its session reference (hs1_...) on stderr. Use it with",
+    "mutagent helix session attach, send, signal and checkpoint.",
+    "Ctrl-C sends SIGINT to the session, which stops it; the exit status is reported.",
+    "There is no interactive chat UI: choose -p, --mode json or --mode rpc.",
+    "With --mode rpc, closing stdin ends the session's input; a dropped connection only detaches.",
+    "A sandbox idle for 15 minutes is checkpointed and stopped; mutagent helix session restore rebuilds it.",
     "",
     "AI Agent Directive:",
     "  Choose -p, --mode json or --mode rpc explicitly.",
-    "  Classic loads full ADLC; --prime selects Prime.",
-    "  helix agent selects a native runtime brief; it does not compile deployment packages.",
-    "  mutagent install helix installs the tool locally; this command runs it remotely."
+    "  Without --prime the full Helix orchestrator runs; --prime runs the lean Prime agent.",
+    "  Keep the session reference (hs1_...) printed on stderr; attach, send, signal and checkpoint take it.",
+    "  mutagent install helix installs Helix on this machine; this command runs it in the cloud."
   ].join(`
 `)).action(async (argv, _options, command) => {
     try {
@@ -10897,75 +10687,37 @@ function createHelixCommand() {
 
 // src/commands/sandbox/index.ts
 import { Command as Command15 } from "commander";
-import chalk33 from "chalk";
+import chalk34 from "chalk";
 
 // src/commands/sandbox/spawn.ts
-import chalk28 from "chalk";
+import chalk29 from "chalk";
 init_errors();
 var ARCHES = ["x86_64", "arm64"];
 var EGRESS_POLICIES = ["deny", "allowlist", "allow"];
 var EGRESS_KINDS = ["port", "cidr", "domain"];
 function registerSpawnCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("spawn").description("Spawn a persistent sandbox from an image 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", `
+  parent.command("spawn").description("Spawn a persistent sandbox from an image 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>", "Sandbox provider (default: the server's; see sandbox providers)").option("--env <name>", "Workspace Environment to load (see mutagent env ls)").option("--egress <policy>", `Outbound network: ${EGRESS_POLICIES.join(" | ")} (default: deny)`).option("--egress-allow <rule>", "domain:, port: or cidr: rule for --egress allowlist (repeatable)", collectRule, []).option("--detach", "Print the sandbox ID and return").addHelpText("after", `
 Examples:
-  ${chalk28.dim("$")} mutagent sandbox spawn --image alpine:3.20
-  ${chalk28.dim("$")} mutagent sandbox spawn --image ghcr.io/example/helix:latest --arch x86_64
-  ${chalk28.dim("$")} mutagent sandbox spawn --image alpine:3.20 --detach --json
-  ${chalk28.dim("$")} mutagent sandbox spawn --image alpine:3.20 --provider docker --env staging
-  ${chalk28.dim("$")} mutagent sandbox spawn --image <helix-image> --egress allow   ${chalk28.dim("Required for a Helix session")}
-  ${chalk28.dim("$")} mutagent sandbox 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
-something without knowing an image reference, use 'mutagent helix agent' or
-'mutagent sandbox 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.
-
-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: ${chalk28.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.
-
-  ${chalk28.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 sandbox rm <id> --force' to destroy it.
+  ${chalk29.dim("$")} mutagent sandbox spawn --image alpine:3.20
+  ${chalk29.dim("$")} mutagent sandbox spawn --image alpine:3.20 --detach --json
+  ${chalk29.dim("$")} mutagent sandbox spawn --image <helix-image> --egress allow
+  ${chalk29.dim("$")} mutagent sandbox spawn --image <ref> --egress allowlist --egress-allow domain:api.anthropic.com
+
+--arch defaults to this machine's architecture; set it for an image built elsewhere.
+Egress defaults to deny. On Docker the sandbox then runs with --network none, so a Helix
+session in it cannot be reached and cannot call its LLM provider: use --egress allow
+for a Helix sandbox. An allowlist needs at least one --egress-allow rule
+(domain:, port: or cidr:).
+Without --detach, spawn attaches; Ctrl-C detaches and prints the re-attach command.
 
 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.
-  A spawned sandbox costs resources until 'mutagent sandbox rm <id>' — confirm
-  with the user before spawning, and tell them the ID afterwards.
+  Pass --egress allow when the sandbox is for a Helix session: under the default deny
+  policy the session cannot be reached, and the error names the sandbox, not the
+  policy. A sandbox used only for exec needs no egress.
+  Prefer --detach --json for automation: it returns one object, { success, sandbox,
+  _links }. A spawned sandbox runs until it is removed or stopped by the idle policy:
+  confirm with the user before spawning, and tell them the sandbox ID.
       `).action(async (options) => {
     const isJson = getJsonFlag(jsonSource);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -11087,10 +10839,10 @@ async function createSandbox(definition, isJson) {
   const spinner = ora2(`Spawning ${definition.image} (${definition.arch})...`).start();
   try {
     const sandbox = await spawnSandbox(definition);
-    spinner.succeed(chalk28.green(`Sandbox ${sandbox.id} spawned`));
+    spinner.succeed(chalk29.green(`Sandbox ${sandbox.id} spawned`));
     return sandbox;
   } catch (error) {
-    spinner.fail(chalk28.red("Spawn failed"));
+    spinner.fail(chalk29.red("Spawn failed"));
     throw error;
   }
 }
@@ -11125,30 +10877,24 @@ function reportDetached(sandbox, id, output, isJson) {
 }
 
 // src/commands/sandbox/exec.ts
-import chalk29 from "chalk";
+import chalk30 from "chalk";
 init_errors();
 function registerExecCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? 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", `
+  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 a fresh sandbox (not with --sandbox)").option("--keep", "Keep the fresh sandbox after the command (not with --sandbox)").option("--cwd <dir>", "Working directory inside the sandbox").option("--timeout-ms <n>", "Command timeout in milliseconds").option("--no-stream", "With --sandbox, wait for the full result instead of streaming").addHelpText("after", `
 Examples:
-  ${chalk29.dim("$")} mutagent sandbox exec -- ls -la /workspace
-  ${chalk29.dim("$")} mutagent sandbox exec --sandbox sbx_123 -- bun test
-  ${chalk29.dim("$")} mutagent sandbox exec --sandbox sbx_123 --cwd /src -- git status
-  ${chalk29.dim("$")} mutagent sandbox exec --preset default -- uname -m --json
+  ${chalk30.dim("$")} mutagent sandbox exec -- uname -m
+  ${chalk30.dim("$")} mutagent sandbox exec --json --preset <name> -- uname -m
+  ${chalk30.dim("$")} mutagent sandbox exec --sandbox sbx_123 --cwd /src -- git status
+  ${chalk30.dim("$")} mutagent sandbox exec -- sh -c 'ls | wc -l'
 
-Put ${chalk29.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.
+Put this command's flags, and --json, before the sandbox command; everything after it
+goes to the sandbox unchanged (${chalk30.bold("--")} is optional). The command is argv, not a shell
+string: name a shell for pipes.
 
-ARGV, NOT A SHELL STRING. There is no shell in the sandbox unless you name one:
-  ${chalk29.dim("$")} mutagent sandbox exec -- sh -c 'ls | wc -l'      ${chalk29.dim("a shell, explicitly")}
-  ${chalk29.dim("$")} mutagent sandbox exec -- 'ls | wc -l'            ${chalk29.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.
+Without --sandbox, a fresh sandbox starts from a preset (see sandbox presets), runs the
+command and is removed unless --keep. With --sandbox, output streams as it is produced;
+--preset and --keep are refused there. The sandbox command's exit code is this command's.
 
 AI Agent Directive:
   Use --no-stream --json (or the one-shot form, which is always blocking) for a
@@ -11273,35 +11019,30 @@ function reportResult(result, output, isJson, context) {
 }
 
 // src/commands/sandbox/attach.ts
-import chalk30 from "chalk";
+import chalk31 from "chalk";
 init_errors();
 function registerAttachCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? 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", `
+  parent.command("attach").description("Stream a running sandbox's output").argument("<id>", "Sandbox ID").option("--since <seq>", "Resume after this sequence number instead of from the start").addHelpText("after", `
 Examples:
-  ${chalk30.dim("$")} mutagent sandbox attach sbx_123
-  ${chalk30.dim("$")} mutagent sandbox attach sbx_123 --since 412
-  ${chalk30.dim("$")} mutagent sandbox attach sbx_123 --json | tail -1
-  ${chalk30.dim("$")} mutagent sandbox attach sbx_123 > session.log
+  ${chalk31.dim("$")} mutagent sandbox attach sbx_123
+  ${chalk31.dim("$")} mutagent sandbox attach sbx_123 --since 412
+  ${chalk31.dim("$")} mutagent sandbox attach sbx_123 --json | tail -1
+  ${chalk31.dim("$")} mutagent sandbox 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 sandbox rm <id> --force'
-destroys a sandbox.
+Ctrl-C detaches; the sandbox keeps running and the re-attach command, with the resume
+point filled in, is printed to stderr. The sandbox runs until it is removed or stopped
+by the idle policy (see \`mutagent sandbox --help\`).
 
-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.
+Sandbox stdout goes to stdout and sandbox stderr to stderr; CLI messages go 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.
+A dropped connection resumes from the last sequence number; output the server no
+longer holds is reported as a gap.
 
 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 sandbox ls --json' first to confirm the sandbox is running.
+  Run 'mutagent sandbox ls --json' first to confirm the sandbox is running. With
+  --json the output is one JSON object per line; the last line is the summary, so
+  read it with 'tail -1' when you only need the result.
       `).action(async (id, options) => {
     const isJson = getJsonFlag(jsonSource);
     try {
@@ -11332,27 +11073,24 @@ AI Agent Directive:
 }
 
 // src/commands/sandbox/providers.ts
-import chalk31 from "chalk";
+import chalk32 from "chalk";
 init_errors();
 function registerProvidersCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("providers").description("List the sandbox providers this backend can reach").addHelpText("after", `
+  parent.command("providers").description("List sandbox providers for mutagent helix --sandbox-provider").addHelpText("after", `
 Examples:
-  ${chalk31.dim("$")} mutagent sandbox providers
-  ${chalk31.dim("$")} mutagent sandbox providers --json
-
-A PROVIDER is where a sandbox runs (docker, agentcore, …). It is a different
-axis from --env, which names a stored bundle of secrets and variables, and from
---preset, which names a whole definition. Omitting --provider takes the default
-reported here.
+  ${chalk32.dim("$")} mutagent sandbox providers
+  ${chalk32.dim("$")} mutagent sandbox providers --json
 
-Providers are a property of the BACKEND, not of your workspace: this list is the
-same for everyone on this deployment.
+A sandbox provider is where a sandbox runs (for example docker or agentcore). It is not an
+LLM provider (\`mutagent providers\`) and not an Environment (\`mutagent env\`).
+\`mutagent helix --sandbox-provider <name>\` accepts a name here when a Helix preset runs
+on it. The list is the same for every workspace on this server.
 
 AI Agent Directive:
   --json returns { providers: [...], default: <name|null>, count: N }. Read it
-  before passing --provider to 'spawn' or 'preflight'; an unknown provider is
-  rejected by the server.
+  before passing --provider to 'spawn' or 'preflight', or --sandbox-provider to
+  'mutagent helix'; the server refuses an unknown sandbox provider.
       `).action(async () => {
     const isJson = getJsonFlag(jsonSource);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -11363,7 +11101,7 @@ AI Agent Directive:
         return;
       }
       if (list.names.length === 0) {
-        console.log(chalk31.gray("No sandbox providers configured on this backend."));
+        console.log(chalk32.gray("No sandbox providers configured on this backend."));
         return;
       }
       output.output(list.names.map((name) => ({ name, default: name === list.default ? "yes" : "" })));
@@ -11374,28 +11112,19 @@ AI Agent Directive:
 }
 function registerPreflightCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("preflight").description("Check a definition against a provider without creating anything").requiredOption("--image <ref>", "Image reference (repository:tag or @digest)").option("--arch <arch>", "Image architecture: x86_64 | arm64 (default: this host's)").option("--name <name>", "Definition name (default: derived from the image reference)").option("--provider <name>", "Provider to check against (default: the backend default)").option("--env <name>", "Environment (secrets + variables) the definition would load").option("--egress <policy>", "Outbound network policy: deny | allowlist | allow").option("--egress-allow <rule>", "Allowance for --egress allowlist, as kind:value (repeatable)", (value, previous) => [...previous, value], []).addHelpText("after", `
+  parent.command("preflight").description("Check whether a sandbox provider can run a definition, without creating anything").requiredOption("--image <ref>", "Image reference (repository:tag or @digest)").option("--arch <arch>", "Image architecture: x86_64 | arm64 (default: this host's)").option("--name <name>", "Definition name (default: derived from the image reference)").option("--provider <name>", "Sandbox provider to check against (default: the server's)").option("--env <name>", "Workspace Environment the definition would load").option("--egress <policy>", "Outbound network: deny | allowlist | allow (default: deny)").option("--egress-allow <rule>", "domain:, port: or cidr: rule for --egress allowlist (repeatable)", (value, previous) => [...previous, value], []).addHelpText("after", `
 Examples:
-  ${chalk31.dim("$")} mutagent sandbox preflight --image alpine:3.20
-  ${chalk31.dim("$")} mutagent sandbox preflight --image alpine:3.20 --provider agentcore --json
-  ${chalk31.dim("$")} mutagent sandbox preflight --image <ref> --egress allowlist --egress-allow domain:api.anthropic.com
+  ${chalk32.dim("$")} mutagent sandbox preflight --image alpine:3.20
+  ${chalk32.dim("$")} mutagent sandbox preflight --image alpine:3.20 --provider agentcore --json
+  ${chalk32.dim("$")} mutagent sandbox preflight --image <ref> --egress allowlist --egress-allow domain:api.anthropic.com
 
-FREE, AND CREATES NOTHING. This is the question 'spawn' answers by spawning:
-whether the provider you are aiming at can actually run this definition. It
-takes the same flags as 'mutagent sandbox spawn' and builds the same definition,
-so a verdict here is about the object spawn would really send — not a near-miss.
-
-EVERY violation comes back, not just the first, so one round trip is enough to
-fix a definition rather than one per problem.
-
-INCOMPATIBLE IS NOT AN ERROR. A definition the provider refuses is a successful
-answer to the question you asked; the command exits 0 and reports
-compatible: false. A non-zero exit here means the CHECK failed — a bad flag, an
-unknown provider, a network problem.
+Takes the same flags as spawn and checks the definition spawn would send. Every
+violation is listed. An incompatible definition exits 0 with compatible: false;
+a non-zero exit means the check itself failed.
 
 AI Agent Directive:
-  --json returns { success, provider, compatible, violations: [...] }. Read
-  'compatible', not the exit code — an incompatible definition still exits 0.
+  --json returns { success, provider, compatible, violations, definition }. Read
+  'compatible', not the exit code: an incompatible definition still exits 0.
       `).action(async (options) => {
     const isJson = getJsonFlag(jsonSource);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -11416,7 +11145,7 @@ AI Agent Directive:
         output.success(`${definition.name} is compatible with ${verdict.provider}`);
         return;
       }
-      console.log(chalk31.yellow(`${definition.name} is NOT compatible with ${verdict.provider}:`));
+      console.log(chalk32.yellow(`${definition.name} is NOT compatible with ${verdict.provider}:`));
       for (const violation of verdict.violations)
         console.log(`  - ${violation}`);
     } catch (error) {
@@ -11426,20 +11155,18 @@ AI Agent Directive:
 }
 
 // src/commands/sandbox/inventory.ts
-import chalk32 from "chalk";
+import chalk33 from "chalk";
 init_errors();
 function registerLsCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("ls").description("List your sandboxes").addHelpText("after", `
+  parent.command("ls").description("List the workspace's live sandboxes").addHelpText("after", `
 Examples:
-  ${chalk32.dim("$")} mutagent sandbox ls
-  ${chalk32.dim("$")} mutagent sandbox 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:
-  ${chalk32.dim("$")} mutagent config set workspace <workspace-id>
+  ${chalk33.dim("$")} mutagent sandbox ls
+  ${chalk33.dim("$")} mutagent sandbox ls --json
 
-An empty list is a normal result, not an error: it means no sandbox is running.
+Lists the sandboxes in the configured workspace
+(mutagent config set workspace <workspace-id>).
+An empty list means none are running.
 
 AI Agent Directive:
   Run this before attach, exec or rm to confirm the sandbox exists and is
@@ -11457,7 +11184,7 @@ AI Agent Directive:
         return;
       }
       if (sandboxes.length === 0) {
-        console.log(chalk32.gray("No sandboxes running."));
+        console.log(chalk33.gray("No sandboxes running."));
         console.log("");
         console.log("  Start one: mutagent sandbox spawn --image <ref>");
         return;
@@ -11480,15 +11207,14 @@ function toRow(sandbox) {
 }
 function registerPresetsCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("presets").description("List the presets a one-shot run can name").addHelpText("after", `
+  parent.command("presets").description("List presets for mutagent helix --preset").addHelpText("after", `
 Examples:
-  ${chalk32.dim("$")} mutagent sandbox presets
-  ${chalk32.dim("$")} mutagent sandbox presets --json
+  ${chalk33.dim("$")} mutagent sandbox presets
+  ${chalk33.dim("$")} mutagent sandbox presets --json
 
-A preset is a named definition on the backend. It is what lets 'mutagent helix agent' and
-'mutagent sandbox 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'.
+A preset is a named sandbox definition kept on the server. \`mutagent helix --preset <name>\`
+and \`mutagent sandbox exec --preset <name>\` use it. Image references are not shown.
+An unknown preset name is refused.
 
 AI Agent Directive:
   --json returns { presets: [...], default: <name|null>, count: N }. Read this
@@ -11504,7 +11230,7 @@ AI Agent Directive:
         return;
       }
       if (presets.length === 0) {
-        console.log(chalk32.gray("No presets configured on this backend."));
+        console.log(chalk33.gray("No presets configured on this backend."));
         console.log("");
         console.log("  Spawn with an explicit image: mutagent sandbox spawn --image <ref>");
         return;
@@ -11523,21 +11249,19 @@ AI Agent Directive:
 }
 function registerRmCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("rm").description("Destroy a sandbox").argument("<id>", "Sandbox ID").option("-f, --force", "Skip confirmation").addHelpText("after", `
+  parent.command("rm").description("Destroy a sandbox now").argument("<id>", "Sandbox ID").option("-f, --force", "Confirm (required unless --json)").addHelpText("after", `
 Examples:
-  ${chalk32.dim("$")} mutagent sandbox rm sbx_123 --force
-  ${chalk32.dim("$")} mutagent sandbox 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.
+  ${chalk33.dim("$")} mutagent sandbox rm sbx_123 --force
+  ${chalk33.dim("$")} mutagent sandbox rm sbx_123 --json
 
-${chalk32.dim("Note: --force is required. The CLI is non-interactive — confirm with the user via your native flow, then pass --force. --json auto-confirms.")}
-${chalk32.dim("Warning: any session running in the sandbox ends immediately and cannot be recovered.")}
+Ends every session in the sandbox. The server first tries to capture a checkpoint,
+so a Helix session can be rebuilt with \`mutagent helix session restore <id>\`.
+Removing a sandbox that is already gone succeeds.
+Without --force (and without --json) the command refuses; it never prompts.
 
 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).
+  Removing a sandbox ends every session in it now. Confirm with the user before
+  running it, then pass --force (or --json).
       `).action(async (id, options) => {
     const isJson = getJsonFlag(jsonSource);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -11567,17 +11291,13 @@ Use --force to confirm: mutagent sandbox rm ${id} --force`);
 }
 function registerTracesCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("traces").description("Show the spans captured for a sandbox").argument("<id>", "Sandbox ID").addHelpText("after", `
+  parent.command("traces").description("Show the spans recorded for a sandbox").argument("<id>", "Sandbox ID").addHelpText("after", `
 Examples:
-  ${chalk32.dim("$")} mutagent sandbox traces sbx_123
-  ${chalk32.dim("$")} mutagent sandbox 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.
+  ${chalk33.dim("$")} mutagent sandbox traces sbx_123
+  ${chalk33.dim("$")} mutagent sandbox traces sbx_123 --json
 
-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.
+An empty list means no spans were recorded; telemetry must be configured on the
+server for spans to exist.
 
 AI Agent Directive:
   --json returns { spans: [...], count: N, sandboxId }. Read spans before
@@ -11594,7 +11314,7 @@ AI Agent Directive:
         return;
       }
       if (spans.length === 0) {
-        console.log(chalk32.gray(`No spans captured for sandbox ${id}.`));
+        console.log(chalk33.gray(`No spans captured for sandbox ${id}.`));
         return;
       }
       output.output(spans.map((span) => {
@@ -11613,17 +11333,14 @@ AI Agent Directive:
 }
 function registerStatusCommand(parent, registration) {
   const jsonSource = registration?.jsonSource ?? parent;
-  parent.command("status").description("Report one sandbox’s lifecycle state").argument("<id>", "Sandbox ID").addHelpText("after", `
+  parent.command("status").description("Print one sandbox's state").argument("<id>", "Sandbox ID").addHelpText("after", `
 Examples:
-  ${chalk32.dim("$")} mutagent sandbox status sbx_123
-  ${chalk32.dim("$")} mutagent sandbox status sbx_123 --json
-
-ONE FIELD, DELIBERATELY. 'GET /api/sandbox/:id' answers with the lifecycle
-state and nothing else — provider, arch, definition and creation time come from
-the LIST route. Use 'mutagent sandbox ls --json' when you want the record.
+  ${chalk33.dim("$")} mutagent sandbox status sbx_123
+  ${chalk33.dim("$")} mutagent sandbox status sbx_123 --json
 
 States: pending, starting, running, paused, stopping, stopped, failed.
-A sandbox this workspace does not own is a 404, not an empty status.
+For sandbox provider, arch and creation time use \`mutagent sandbox ls --json\`.
+A sandbox outside this workspace is reported as not found.
 
 AI Agent Directive:
   --json returns { success, sandboxId, status, _links }. Prefer this over
@@ -11646,58 +11363,41 @@ AI Agent Directive:
 
 // src/commands/sandbox/index.ts
 function createSandboxCommand() {
-  const sandbox = new Command15("sandbox").description("Create, inspect and run commands in cloud sandboxes").addHelpText("after", `
+  const sandbox = new Command15("sandbox").description("Internal: sandbox management. Everyday use goes through `mutagent helix`.").addHelpText("after", `
 Examples:
-  ${chalk33.dim("$")} mutagent sandbox presets                        ${chalk33.dim("What a one-shot can run on")}
-  ${chalk33.dim("$")} mutagent sandbox providers                      ${chalk33.dim("Where a box can run")}
-  ${chalk33.dim("$")} mutagent sandbox preflight --image alpine:3.20  ${chalk33.dim("Would this definition run?")}
-  ${chalk33.dim("$")} mutagent sandbox spawn --image alpine:3.20      ${chalk33.dim("Persistent box, then attach")}
-  ${chalk33.dim("$")} mutagent sandbox ls                             ${chalk33.dim("What is running")}
-  ${chalk33.dim("$")} mutagent sandbox status sbx_1                   ${chalk33.dim("One box, one field")}
-  ${chalk33.dim("$")} mutagent sandbox exec --sandbox sbx_1 -- bun test
-  ${chalk33.dim("$")} mutagent sandbox attach sbx_1 --since 412       ${chalk33.dim("Resume after a sequence number")}
-  ${chalk33.dim("$")} mutagent sandbox traces sbx_1 --json            ${chalk33.dim("What the box actually did")}
-  ${chalk33.dim("$")} mutagent sandbox rm sbx_1 --force               ${chalk33.dim("Destroy it")}
-
-BOXES ARE NOT AGENTS. This group is the machine. To put an agent in one:
-  ${chalk33.dim("$")} mutagent helix agent --prompt "<who>" -p "<task>"   ${chalk33.dim("One turn, fresh box")}
-  ${chalk33.dim("$")} mutagent helix session start sbx_1 --rpc            ${chalk33.dim("An agent inside a box you own")}
+  ${chalk34.dim("$")} mutagent sandbox presets                        ${chalk34.dim("Presets `mutagent helix --preset` can name")}
+  ${chalk34.dim("$")} mutagent sandbox providers                      ${chalk34.dim("Sandbox providers `mutagent helix --sandbox-provider` can name")}
+  ${chalk34.dim("$")} mutagent sandbox preflight --image alpine:3.20  ${chalk34.dim("Would this definition run?")}
+  ${chalk34.dim("$")} mutagent sandbox spawn --image alpine:3.20 --detach
+  ${chalk34.dim("$")} mutagent sandbox ls
+  ${chalk34.dim("$")} mutagent sandbox status sbx_1
+  ${chalk34.dim("$")} mutagent sandbox exec --sandbox sbx_1 -- bun test
+  ${chalk34.dim("$")} mutagent sandbox attach sbx_1 --since 412
+  ${chalk34.dim("$")} mutagent sandbox traces sbx_1
+  ${chalk34.dim("$")} mutagent sandbox rm sbx_1 --force
 
 One-shot vs persistent:
-  ${chalk33.bold("exec")} without --sandbox starts from a named PRESET, does one thing and
-  tears the sandbox down. Nothing to clean up, no image to know.
-  ${chalk33.bold("spawn")} takes an explicit --image and leaves a box running for you to
-  ${chalk33.bold("attach")} and ${chalk33.bold("exec --sandbox")} against until you ${chalk33.bold("rm")} it.
+  ${chalk34.bold("exec")} without --sandbox starts a fresh sandbox from a preset, runs one command
+  and removes the sandbox. ${chalk34.bold("spawn")} starts a sandbox from an image and leaves it running
+  for ${chalk34.bold("attach")} and ${chalk34.bold("exec --sandbox")}.
 
 Lifecycle:
-  A spawned sandbox outlives your terminal. Ctrl-C, a dropped connection and a
-  closed terminal all DETACH — whatever is running keeps running and can be
-  re-attached. Only 'mutagent sandbox rm <id> --force' 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:
-  ${chalk33.dim("$")} mutagent config set workspace <workspace-id>
+  Ctrl-C, a dropped connection or a closed terminal detaches; the sandbox keeps running.
+  After 15 minutes with no input, attach, exec or agent turn, the server checkpoints
+  and stops it. A Helix session in it can be rebuilt with
+  \`mutagent helix session restore <id>\`. \`sandbox rm\` destroys a sandbox now.
 
 Output:
-  Sandbox stdout goes to stdout, sandbox stderr goes to stderr, and anything
-  this CLI says about the box 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.
-
-Moved here from 'mutagent helix' (BREAKING):
-  spawn, ls, rm, presets, exec, traces and attach used to live under
-  'mutagent helix'. Those spellings are GONE — there is no alias. Rewrite
-  'mutagent helix <verb>' as 'mutagent sandbox <verb>'.
+  Sandbox stdout goes to stdout, sandbox stderr to stderr; CLI messages go to stderr.
+  With --json, attach, spawn without --detach and exec --sandbox without --no-stream
+  print one JSON object per line, ending with a summary. Other commands print one object.
 
 AI Agent Directive:
-  Run 'mutagent sandbox ls --json' before attach, exec --sandbox, status 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.
-  Spawning consumes resources until removed — confirm with the user before
-  'spawn' and before 'rm'.
+  Run 'mutagent sandbox ls --json' before attach, exec --sandbox, status or rm. A
+  spawned sandbox runs until it is removed or stopped by the idle policy: confirm
+  with the user before 'spawn' and before 'rm', and tell them the sandbox ID.
+
+Requires a workspace: mutagent config set workspace <workspace-id>
       `);
   registerSpawnCommand(sandbox);
   registerLsCommand(sandbox);
@@ -11714,7 +11414,7 @@ AI Agent Directive:
 
 // src/commands/env/index.ts
 import { Command as Command16 } from "commander";
-import chalk34 from "chalk";
+import chalk35 from "chalk";
 import { readFileSync as readFileSync14 } from "fs";
 init_errors();
 
@@ -11814,34 +11514,26 @@ function describeWithoutValue(arg) {
 
 // src/commands/env/index.ts
 function createEnvCommand() {
-  const env = new Command16("env").description("Workspace Environments — the variables and secrets an agent’s tools need").addHelpText("after", `
+  const env = new Command16("env").description("Workspace Environments: the variables and secrets an agent’s tools need").addHelpText("after", `
 Examples:
-  ${chalk34.dim("$")} mutagent env ls
-  ${chalk34.dim("$")} mutagent env set demo GREETING=hello --secret GITHUB_TOKEN=ghp_…
-  ${chalk34.dim("$")} mutagent env set staging --from-file .env.staging --secrets-from-file .env.staging.secrets
-  ${chalk34.dim("$")} mutagent env show demo
-  ${chalk34.dim("$")} mutagent env unset demo GREETING
-  ${chalk34.dim("$")} mutagent env rm demo --force
-  ${chalk34.dim("$")} mutagent helix session start sbx_1 --rpc --env demo     ${chalk34.dim("Load it into a session")}
-  ${chalk34.dim("$")} mutagent helix agent --env demo -p "…"                  ${chalk34.dim("Load it into a one-shot turn")}
-
-ENVIRONMENTS ARE NOT PROVIDERS. 'mutagent providers' configures which LLM models
-a workspace may call and with whose key. 'mutagent env' holds what an agent's
-TOOLS need — a GitHub token, a Langfuse key, a database URL, a feature flag.
-A variable named like a provider key (ANTHROPIC_API_KEY, OPENAI_API_KEY, …) is
-refused, because it would shadow the workspace's provider injection in the box;
-pass --allow-provider-key to store it deliberately.
-
-VALUES ARE WRITE-ONLY. No verb here prints one, and no server route returns one.
-'show' prints each entry's name and a sha256[:8] fingerprint of its value, which
-is enough to tell whether the value you hold is the one stored.
-
-Names: Environment ^[A-Za-z0-9._-]{1,64}$ · variables ^[A-Z_][A-Z0-9_]*$ · 64 KiB
-per Environment.
-
-Access:
-  Environments are minted per WORKSPACE, so a workspace must be configured:
-  ${chalk34.dim("$")} mutagent config set workspace <workspace-id>
+  ${chalk35.dim("$")} mutagent env ls
+  ${chalk35.dim("$")} mutagent env set demo GREETING=hello --secret GITHUB_TOKEN=ghp_…
+  ${chalk35.dim("$")} mutagent env set staging --from-file .env.staging --secrets-from-file .env.staging.secrets
+  ${chalk35.dim("$")} mutagent env show demo
+  ${chalk35.dim("$")} mutagent env unset demo GREETING
+  ${chalk35.dim("$")} mutagent env rm demo --force
+  ${chalk35.dim("$")} mutagent helix --env demo -p "check the deploy"    ${chalk35.dim("Load it into a Helix cloud run")}
+
+An Environment holds the variables and secrets an agent's tools need: a GitHub token,
+a Langfuse key, a database URL. LLM provider keys belong in \`mutagent providers\`; a
+variable named like one (ANTHROPIC_API_KEY, …) is refused unless --allow-provider-key.
+
+Values are write-only. \`show\` prints each entry's name and a sha256[:8] fingerprint.
+
+Names: Environments use letters, digits, '.', '_' and '-' (up to 64); variables use
+A-Z, 0-9 and _, not starting with a digit. An Environment holds up to 64 KiB.
+
+Requires a workspace: mutagent config set workspace <workspace-id>
 
 AI Agent Directive:
   Use 'set' to create or update — it creates the Environment when absent and
@@ -11860,10 +11552,10 @@ AI Agent Directive:
 function registerLs(parent) {
   parent.command("ls").description("List the workspace’s Environments").addHelpText("after", `
 Examples:
-  ${chalk34.dim("$")} mutagent env ls
-  ${chalk34.dim("$")} mutagent env ls --json
+  ${chalk35.dim("$")} mutagent env ls
+  ${chalk35.dim("$")} mutagent env ls --json
 
-An empty list is a normal result: the workspace has no Environments yet.
+An empty list means the workspace has no Environments yet.
 
 AI Agent Directive:
   --json returns { success, environments: [{ name, vars, secrets, createdAt, updatedAt }], count }.
@@ -11878,7 +11570,7 @@ AI Agent Directive:
         return;
       }
       if (environments.length === 0) {
-        console.log(chalk34.gray("No Environments in this workspace. Create one: mutagent env set <name> KEY=VALUE"));
+        console.log(chalk35.gray("No Environments in this workspace. Create one: mutagent env set <name> KEY=VALUE"));
         return;
       }
       output.output(environments.map((e) => ({
@@ -11895,13 +11587,15 @@ AI Agent Directive:
 function registerShow(parent) {
   parent.command("show").description("Entry names and fingerprints of one Environment — never a value").argument("<name>", "Environment name").addHelpText("after", `
 Examples:
-  ${chalk34.dim("$")} mutagent env show demo
-  ${chalk34.dim("$")} mutagent env show demo --json
+  ${chalk35.dim("$")} mutagent env show demo
+  ${chalk35.dim("$")} mutagent env show demo --json
 
 Each line is NAME  KIND  FINGERPRINT. The fingerprint is sha256(value)[:8]; compare
 it with your own (printf %s "$VALUE" | shasum -a 256 | cut -c1-8) to check what is
 stored without the server ever sending the value.
 
+An unknown name is an error.
+
 AI Agent Directive:
   --json returns { success, environment: { name, vars: [{name, fingerprint}],
   secrets: [{name, fingerprint}], createdAt, updatedAt } }.
@@ -11917,37 +11611,29 @@ AI Agent Directive:
   });
 }
 function registerSet(parent) {
-  parent.command("set").description("Set variables (and --secret secrets) on an Environment; creates it when absent").argument("<name>", "Environment name").argument("[assignments...]", "KEY=VALUE variables (non-secret)").option("-s, --secret <KEY=VALUE...>", "Secret entries — encrypted at rest, never returned").option("--from-file <path>", "Read variables from a .env file (KEY=VALUE lines); argv wins on the same name").option("--secrets-from-file <path>", "Read secrets from a .env file").option("--replace", "Replace the whole Environment (PUT) instead of merging into it (PATCH)").option("--allow-provider-key", "Permit a variable named like an LLM provider key (it would shadow the workspace’s provider injection)").addHelpText("after", `
+  parent.command("set").description("Set variables (and --secret secrets) on an Environment; creates it when absent").argument("<name>", "Environment name").argument("[assignments...]", "KEY=VALUE variables (non-secret)").option("-s, --secret <KEY=VALUE...>", "Secret entries — encrypted at rest, never returned").option("--from-file <path>", "Read variables from a .env file (KEY=VALUE lines); argv wins on the same name").option("--secrets-from-file <path>", "Read secrets from a .env file").option("--replace", "Replace the whole Environment instead of merging into it").option("--allow-provider-key", "Permit a variable named like an LLM provider key").addHelpText("after", `
 Examples:
-  ${chalk34.dim("$")} mutagent env set demo GREETING=hello
-  ${chalk34.dim("$")} mutagent env set demo GREETING=hello --secret TOKEN=abc123
-  ${chalk34.dim("$")} mutagent env set demo --secret GITHUB_TOKEN=ghp_x --secret LANGFUSE_SECRET_KEY=sk-lf-x
-  ${chalk34.dim("$")} mutagent env set staging --from-file .env.staging
-  ${chalk34.dim("$")} mutagent env set staging --secrets-from-file .env.staging.secrets
-  ${chalk34.dim("$")} mutagent env set staging --replace --from-file .env.staging   ${chalk34.dim("Drop everything not in the file")}
-
-MERGE BY DEFAULT. Entries you name are set; entries you do not name stay. The
-Environment is created if it does not exist, so this is one step on a fresh
-workspace. --replace sends the whole Environment instead and REMOVES every entry
-you did not name — secrets included.
-
-VARIABLES vs SECRETS. Positional KEY=VALUE and --from-file are non-secret
-variables (stored readable). --secret and --secrets-from-file are secrets
-(encrypted at rest with the same key as provider credentials). Both reach the
-box as plain environment variables; the difference is how they are stored and
-that a secret's value can never be read back through the API. A name may not be
-both.
-
-A VALUE MAY CONTAIN '='. The split is at the first one: TOKEN=a=b stores "a=b".
-Quote values with spaces for your shell; this command does not re-split them.
-
-Names: variables ^[A-Z_][A-Z0-9_]*$ · Environment ^[A-Za-z0-9._-]{1,64}$ · 64 KiB
-per Environment. A variable named like an LLM provider key (ANTHROPIC_API_KEY, …)
-is a 409 unless --allow-provider-key is passed — see 'mutagent env --help'.
+  ${chalk35.dim("$")} mutagent env set demo GREETING=hello
+  ${chalk35.dim("$")} mutagent env set demo GREETING=hello --secret TOKEN=abc123
+  ${chalk35.dim("$")} mutagent env set staging --from-file .env.staging
+  ${chalk35.dim("$")} mutagent env set staging --replace --from-file .env.staging   ${chalk35.dim("Drop everything not in the file")}
+
+Entries you name are set and the rest stay; the Environment is created if missing.
+--replace removes every entry you do not name, secrets included.
+Positional KEY=VALUE and --from-file are variables; --secret and --secrets-from-file are
+secrets (encrypted at rest, never returned). Both reach the box as env vars. A name
+cannot be both.
+--secret takes every KEY=VALUE after it, so put variables first:
+  ${chalk35.dim("$")} mutagent env set demo A=1 --secret TOKEN=x
+A value may contain '=': TOKEN=a=b stores "a=b".
+Names: A-Z, 0-9 and _, not starting with a digit. An invalid name exits 2. A name that
+looks like an LLM provider key is refused by the server (exit 1) unless
+--allow-provider-key.
 
 AI Agent Directive:
   Nothing printed here contains a value. --json returns { success, environment,
-  replaced: boolean }. A refused name exits 2 and names the KEY, not the value.
+  replaced: boolean }. An invalid name exits 2 and names the KEY, not the value;
+  a name that looks like an LLM provider key exits 1 unless --allow-provider-key.
       `).action(async (name, assignments, options) => {
     const isJson = getJsonFlag(parent);
     const output = new OutputFormatter(isJson ? "json" : "table");
@@ -11977,12 +11663,11 @@ AI Agent Directive:
 function registerUnset(parent) {
   parent.command("unset").description("Remove entries from an Environment").argument("<name>", "Environment name").argument("<keys...>", "Entry names to remove").option("-s, --secret", "The names are secrets (default: try both variables and secrets)").addHelpText("after", `
 Examples:
-  ${chalk34.dim("$")} mutagent env unset demo GREETING
-  ${chalk34.dim("$")} mutagent env unset demo TOKEN OTHER_TOKEN
+  ${chalk35.dim("$")} mutagent env unset demo GREETING
+  ${chalk35.dim("$")} mutagent env unset demo TOKEN OTHER_TOKEN
 
-A name is removed wherever it is — variable or secret — because a name cannot be
-both. Unsetting a name that is not there is not an error: the Environment ends
-in the state you asked for.
+A name is removed wherever it is, variable or secret. Unsetting a name that is not
+there succeeds.
 
 AI Agent Directive:
   --json returns { success, environment, removed: [names] }.
@@ -12007,15 +11692,17 @@ AI Agent Directive:
   });
 }
 function registerRm(parent) {
-  parent.command("rm").description("Delete an Environment and its secrets").argument("<name>", "Environment name").option("-f, --force", "Skip confirmation").addHelpText("after", `
+  parent.command("rm").description("Delete an Environment and its secrets").argument("<name>", "Environment name").option("-f, --force", "Confirm (required unless --json)").addHelpText("after", `
 Examples:
-  ${chalk34.dim("$")} mutagent env rm demo --force
-  ${chalk34.dim("$")} mutagent env rm demo --json
+  ${chalk35.dim("$")} mutagent env rm demo --force
+  ${chalk35.dim("$")} mutagent env rm demo --json
 
-Deletes the Environment and its encrypted secrets. Boxes already running keep
-what they were handed; the next run naming this Environment fails with 404.
+Deletes the Environment and its encrypted secrets. Boxes already running keep what
+they were handed; the next run naming this Environment fails.
+Without --force (and without --json) the command refuses; it never prompts.
+An unknown name is an error.
 
-${chalk34.dim("Note: --force is required. The CLI is non-interactive — confirm with the user via your native flow, then pass --force. --json auto-confirms.")}
+JSON: { success, deleted, name }
 
 AI Agent Directive:
   Confirm with the user before running it, then pass --force (or --json).
@@ -12061,7 +11748,7 @@ function printEnvironment(environment, output, isJson) {
     output.output({ success: true, environment });
     return;
   }
-  console.log(`${chalk34.bold(environment.name)}  ${chalk34.dim(environment.updatedAt ?? "")}`);
+  console.log(`${chalk35.bold(environment.name)}  ${chalk35.dim(environment.updatedAt ?? "")}`);
   printEntries(environment);
 }
 function printEntries(environment) {
@@ -12070,12 +11757,12 @@ function printEntries(environment) {
     ...environment.secrets.map((s) => ({ name: s.name, kind: "secret", fingerprint: s.fingerprint }))
   ];
   if (rows.length === 0) {
-    console.log(chalk34.gray("  (no entries)"));
+    console.log(chalk35.gray("  (no entries)"));
     return;
   }
   const width = Math.max(...rows.map((r) => r.name.length));
   for (const row of rows) {
-    console.log(`  ${row.name.padEnd(width)}  ${row.kind === "secret" ? chalk34.yellow("secret") : chalk34.dim("var   ")}  ${chalk34.dim(row.fingerprint)}`);
+    console.log(`  ${row.name.padEnd(width)}  ${row.kind === "secret" ? chalk35.yellow("secret") : chalk35.dim("var   ")}  ${chalk35.dim(row.fingerprint)}`);
   }
 }
 
@@ -12647,77 +12334,56 @@ program.name("mutagent").description(`Mutagent CLI - command-line client for the
 });
 program.addHelpText("beforeAll", () => renderBanner());
 program.addHelpText("after", `
-${chalk35.bold.cyan("WORKFLOWS:")}
-  ${chalk35.bold("Setup")}                mutagent login  →  mutagent init
-  ${chalk35.bold("Lifecycle Tools")}      mutagent install helix  ${chalk35.dim("(login-gated)")}
-  ${chalk35.bold("Feedback")}             mutagent feedback send "<what happened>" --category <cli|helix|stage:<x>>  ${chalk35.dim("[--session <id>] [--attach-transcript]")}
-
-${chalk35.dim("For CLI usage guidance for AI agents, see the Skill at")}
-${chalk35.cyan(".claude/skills/mutagent-cli/SKILL.md")}
-
-${chalk35.yellow("Global flags:")}
-  -v, --version ${chalk35.dim("Print the CLI version")}   ${chalk35.dim("(before a subcommand; after one it is the subcommand's)")}
-  --json  --api-key <k>  --endpoint <url>  --non-interactive
-
-${chalk35.yellow("Non-Interactive Mode (CI/CD & Coding Agents):")}
-  export MUTAGENT_API_KEY=mt_...  ${chalk35.dim("or")}  --api-key mt_...
-  --json ${chalk35.dim("for structured output")}    --non-interactive ${chalk35.dim("to disable prompts")}
-
-${chalk35.yellow("Command Navigation:")}
-  mutagent login                        ${chalk35.dim("Login (browser OAuth — recommended)")}
-  mutagent auth status                  ${chalk35.dim("Check auth + workspace")}
-  mutagent init                         ${chalk35.dim("Initialize project (.mutagentrc.json)")}
-  mutagent workspaces list --json       ${chalk35.dim("List workspaces (verify ID)")}
-  mutagent config set workspace <id>    ${chalk35.dim("Set active workspace")}
-  mutagent usage --json                 ${chalk35.dim("Show account usage + provider status")}
-
-  mutagent providers list --json        ${chalk35.dim("List configured BYOK providers")}
-  mutagent providers list --models      ${chalk35.dim("See available models per provider")}
-
-  mutagent helix agent "<who>" -p "<task>"  ${chalk35.dim("One Helix agent turn in a cloud sandbox")}
-  mutagent sandbox ls --json            ${chalk35.dim("List running sandboxes")}
-  mutagent sandbox spawn --image <ref>  ${chalk35.dim("Persistent sandbox you attach to")}
-  mutagent sandbox rm <id> --force      ${chalk35.dim("Destroy a sandbox (the only thing that does)")}
-
-  mutagent install helix                ${chalk35.dim("Install the ADL lifecycle conductor locally (login-gated)")}
-  mutagent install helix --version 1.2.3  ${chalk35.dim("Pin a version")}
-  mutagent install --help               ${chalk35.dim("helix")}
-
-  mutagent hooks --help                 ${chalk35.dim("Hook setup for Claude Code session telemetry upload")}
-
-${chalk35.bold.red("Report Issues:")}
-  Hit a bug? Run: ${chalk35.cyan('mutagent feedback send "describe what went wrong" --category cli')}
-  Lifecycle-stage feedback: ${chalk35.cyan('mutagent feedback send "eval gate unclear" --category stage:evaluate')}
-  Link to a session: ${chalk35.cyan('mutagent feedback send "..." --session <session-id>')}
-  Attach your coding-agent session transcript: ${chalk35.cyan('mutagent feedback send "..." --attach-transcript')}
-  ${chalk35.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
-
-${chalk35.yellow("Directive System:")}
-  Every --json response may include:
-  ${chalk35.bold("_directive.display")}      Type tag — 'status_card' for card-kind directives (drives test/docs guards)
-  ${chalk35.bold("_directive.renderedCard")} Pre-formatted card ${chalk35.red("(MUST echo verbatim in chat whenever this field exists — see SKILL.md Verbatim Card Display Protocol)")}
-  ${chalk35.bold("_directive.instruction")}  Next step for the agent (self-sufficient, no Skill required)
-  ${chalk35.bold("_directive.next")}         Array of suggested follow-up commands
-  ${chalk35.bold("_links")}                  Dashboard/API URLs (format as markdown links)
-  ${chalk35.bold("_compat")}                 Compat metadata: cliVersion, skillVersion, skillMinCliVersion
-
-${chalk35.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
-       (CLI prints an auth URL — surface it to the user verbatim, then the CLI
-        polls for up to 5 minutes while the user authorizes in their browser.
-        This IS agent-compatible. --non-interactive is NOT needed with --browser.)
-  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
-     ${chalk35.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
+${chalk36.yellow("Get started:")}
+  mutagent login                          ${chalk36.dim("Sign in (browser or API key)")}
+  mutagent providers mirror               ${chalk36.dim("Copy local Helix LLM provider keys into the workspace")}
+  mutagent helix -p "<task>"              ${chalk36.dim("Run Helix in the cloud")}
+  mutagent install helix                  ${chalk36.dim("Install Helix on this machine")}
+
+${chalk36.yellow("Workspace:")}
+  mutagent auth status                    ${chalk36.dim("Sign-in state and the active workspace")}
+  mutagent workspaces list                ${chalk36.dim("Workspaces you can see")}
+  mutagent config set workspace <id>      ${chalk36.dim("Choose the active workspace")}
+  mutagent providers list                 ${chalk36.dim("LLM providers in the workspace")}
+  mutagent helix models                   ${chalk36.dim("Models Helix can use in the cloud, and the workspace default model")}
+  mutagent env ls                         ${chalk36.dim("Environments: variables and secrets for tools")}
+  mutagent usage                          ${chalk36.dim("Count the workspace's LLM providers and your workspaces")}
+
+${chalk36.yellow("Automation:")}
+  MUTAGENT_API_KEY=mt_...                 ${chalk36.dim("Sign in without a browser (or --api-key <key>)")}
+  --json                                  ${chalk36.dim("Structured output")}
+  --non-interactive                       ${chalk36.dim("No sign-in method or consent prompts (also when CI=true or stdin is not a terminal); a first sign-in in a terminal ends with a menu unless --json")}
+  -v, --version                           ${chalk36.dim("CLI version (only before a subcommand)")}
+
+${chalk36.yellow("Report a problem:")}
+  mutagent feedback send "<what happened>" --category cli
+  ${chalk36.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
+
+${chalk36.dim("For CLI usage guidance for AI agents, see the Skill at")}
+${chalk36.cyan(".claude/skills/mutagent-cli/SKILL.md")}
+
+${chalk36.yellow("Directive System:")}
+  A --json response may include:
+  ${chalk36.bold("_directive.renderedCard")}  A status card: copy it into your chat reply verbatim before running another command
+  ${chalk36.bold("_directive.instruction")}   What to do next
+  ${chalk36.bold("_directive.next")}          Suggested follow-up commands
+  ${chalk36.bold("_links")}                   Dashboard and API URLs
+  ${chalk36.bold("_compat")}                  cliVersion, skillVersion, skillMinCliVersion
+
+${chalk36.yellow("AI Agent Rules (MANDATORY for coding agents):")}
+  1. Sign in: with MUTAGENT_API_KEY set, run mutagent login --json. To help a user sign in,
+     run mutagent login --browser --json, show the printed URL to the user verbatim, and
+     wait: the CLI polls for up to 5 minutes.
+  2. Pass --json to every command except a mutagent helix launch (-p, --mode json or rpc), whose output is Helix's own.
+  3. Run <command> --help before the first use of a command.
+  4. When a response has _directive.renderedCard, copy it into your chat reply verbatim
+     before running another command.
+  5. After mutagent init, check the workspace: mutagent workspaces list --json
+  6. Ask the user through your own question tool. With --json only mutagent login can prompt, in a terminal; pass --browser or set MUTAGENT_API_KEY.
 ${!hasCredentials() ? `
-` + chalk35.yellow("  Warning: Not authenticated. Run: mutagent login") + `
+` + chalk36.yellow("  Warning: Not authenticated. Run: mutagent login") + `
 ` : ""}${!hasRcConfig() ? `
-` + chalk35.green("  Get started: mutagent init") + `
+` + chalk36.green("  Get started: mutagent init") + `
 ` : ""}`);
 var rawArgs = process.argv.slice(2);
 if (isGlobalVersionFlag(rawArgs)) {
@@ -12782,5 +12448,5 @@ var argvForCommander = execCommand === undefined ? rawArgs : protectBoxArgv(rawA
 if (!helixHelpJson)
   program.parse(argvForCommander, { from: "user" });
 
-//# debugId=383FC9FB725D595F64756E2164756E21
+//# debugId=0381115E4249D9B864756E2164756E21
 //# sourceMappingURL=cli.js.map