@mutagent/cli 0.1.385 → 0.1.387

package/dist/bin/cli.js

@@ -16520,6 +16520,18 @@ var SECURE_FILE_MODE = 384;
 var init_secure_file = () => {};
 
 // src/lib/config.ts
+var exports_config = {};
+__export(exports_config, {
+  setWorkspaceSelection: () => setWorkspaceSelection,
+  saveFullCredentials: () => saveFullCredentials,
+  saveCredentials: () => saveCredentials,
+  recordKeyScope: () => recordKeyScope,
+  loadConfig: () => loadConfig,
+  hasCredentials: () => hasCredentials,
+  getApiKey: () => getApiKey,
+  envKeyReplacesFile: () => envKeyReplacesFile,
+  clearCredentials: () => clearCredentials
+});
 import { cosmiconfigSync } from "cosmiconfig";
 import { z } from "zod";
 import { homedir as homedir2 } from "os";
@@ -16686,6 +16698,7 @@ __export(exports_organization_scope, {
   setWorkspaceFlag: () => setWorkspaceFlag,
   setOrgAssertion: () => setOrgAssertion,
   resolveKeyTenancy: () => resolveKeyTenancy,
+  resetKeyScopeCache: () => resetKeyScopeCache,
   otherOrganizationHint: () => otherOrganizationHint,
   orgMismatch: () => orgMismatch,
   noWorkspaceSelected: () => noWorkspaceSelected,
@@ -16848,6 +16861,20 @@ async function probeKeyScope(apiKey, endpoint, workspaceNamed) {
   const fromFile = !envKeyReplacesFile();
   if (!fromFile && workspaceNamed && orgAssertion === undefined)
     return;
+  const cacheKey = `${endpoint}
+${apiKey}`;
+  const cached = keySelfProbes.get(cacheKey);
+  if (cached)
+    return cached;
+  const probe = readKeyScope(apiKey, endpoint, fromFile);
+  keySelfProbes.set(cacheKey, probe);
+  probe.catch(() => keySelfProbes.delete(cacheKey));
+  return probe;
+}
+function resetKeyScopeCache() {
+  keySelfProbes.clear();
+}
+async function readKeyScope(apiKey, endpoint, fromFile) {
   try {
     const self = await fetchKeySelf(apiKey, endpoint);
     if (fromFile)
@@ -16931,7 +16958,7 @@ async function findWorkspace(wanted, t) {
   const orgs = await fetchOrganizations(t.apiKey, t.endpoint);
   throw otherOrganizationHint(wanted, t.organization, orgs);
 }
-var TENANCY_DENIED = "TENANCY_DENIED", UUID_PATTERN, TenancyError, ENV_KEY_WORKSPACE_FIX = "Pass --workspace <name|id> or set MUTAGENT_WORKSPACE_ID", orgAssertion, workspaceFlag;
+var TENANCY_DENIED = "TENANCY_DENIED", UUID_PATTERN, TenancyError, ENV_KEY_WORKSPACE_FIX = "Pass --workspace <name|id> or set MUTAGENT_WORKSPACE_ID", orgAssertion, workspaceFlag, keySelfProbes;
 var init_organization_scope = __esm(() => {
   init_errors();
   init_config();
@@ -16942,6 +16969,7 @@ var init_organization_scope = __esm(() => {
       this.name = "TenancyError";
     }
   };
+  keySelfProbes = new Map;
 });
 
 // src/lib/provider-request.ts
@@ -17728,7 +17756,7 @@ var init_service = __esm(() => {
 });
 
 // src/bin/cli.ts
-import { Command as Command18 } from "commander";
+import { Command as Command23 } from "commander";
 
 // src/commands/agent/index.ts
 import { existsSync as existsSync3 } from "node:fs";
@@ -18332,9 +18360,9 @@ function handleAgentParseError(error3, json) {
 }
 
 // src/bin/cli.ts
-import chalk38 from "chalk";
-import { readFileSync as readFileSync14 } from "fs";
-import { join as join21, dirname as dirname7 } from "path";
+import chalk47 from "chalk";
+import { readFileSync as readFileSync18 } from "fs";
+import { join as join22, dirname as dirname8 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 
 // src/commands/auth.ts
@@ -18812,6 +18840,8 @@ async function performBrowserAuth(options, onStatusUpdate) {
         throw error3;
       }
     }
+  } else if (process.env.MUTAGENT_TEST_MODE === "true") {
+    console.log(`AUTH_URL:${authUrl}`);
   }
   console.log("");
   console.log("  Open this URL to authenticate:");
@@ -18917,10 +18947,13 @@ async function performLoginAction(opts) {
     useBrowserAuth = method === "browser";
   }
   if (useBrowserAuth) {
-    return loginWithBrowser(endpoint, output, wasFirstLogin, opts.org);
+    return loginWithBrowser(endpoint, output, wasFirstLogin, shouldSkipBrowserOpen(isJson), opts.org);
   }
   return loginWithPastedKey(endpoint, output, wasFirstLogin);
 }
+function shouldSkipBrowserOpen(isJson) {
+  return isJson || !process.stdout.isTTY;
+}
 function buildLoginJsonResponse(result) {
   return {
     success: true,
@@ -18984,11 +19017,14 @@ async function loginWithExistingKey(apiKey, endpoint, output, wasFirstLogin) {
   saveFullCredentials({ apiKey, endpoint, ...described });
   return loginResult(apiKey, endpoint, described, wasFirstLogin);
 }
-async function loginWithBrowser(endpoint, output, wasFirstLogin, org) {
-  const spinner = ora2({ text: "Opening browser for authentication...", spinner: "dots" });
+async function loginWithBrowser(endpoint, output, wasFirstLogin, skipBrowserOpen, org) {
+  const spinner = ora2({
+    text: skipBrowserOpen ? "Waiting for the URL to be opened..." : "Opening browser for authentication...",
+    spinner: "dots"
+  });
   try {
     spinner.start();
-    const result = await performBrowserAuth({ endpoint, timeout: 300000, pollInterval: 2000, org }, (message) => {
+    const result = await performBrowserAuth({ endpoint, timeout: 300000, pollInterval: 2000, skipBrowserOpen, org }, (message) => {
       spinner.text = message;
     });
     spinner.succeed("Authenticated successfully!");
@@ -19191,16 +19227,24 @@ function createLoginCommand() {
   const login = new Command3("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("# In a terminal, choose browser or API key")}
-  ${chalk5.dim("$")} mutagent login --browser                ${chalk5.dim("# Sign in with the browser")}
+  ${chalk5.dim("$")} mutagent login --browser                ${chalk5.dim("# Opens a real browser here; sign in or sign up")}
   ${chalk5.dim("$")} mutagent login --non-interactive        ${chalk5.dim("# Browser sign-in without the method prompt (a person approves in the browser)")}
+  ${chalk5.dim("$")} mutagent login --browser --non-interactive --json  ${chalk5.dim("# Agent path: no browser opens here — see below")}
   ${chalk5.dim("$")} mutagent login --org <slug>              ${chalk5.dim("# Sign in for another organization (preselected on the approval page)")}
   ${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
+Browser sign-in: app.mutagent.io is where you sign in or sign up, finish onboarding
 and approve this CLI. The CLI waits up to 5 minutes and saves the credentials.
 The key works in every workspace you are a member of in the approved organization, for
 30 days. The approved workspace is selected; switch with mutagent workspaces use <name>.
 
+At a real terminal (no --json, stdout is a TTY), --browser opens that page for you
+automatically. Under --json, or whenever stdout is not a TTY (a coding agent's
+captured output, a pipe, CI), this CLI never opens a browser on this machine — it
+only PRINTS the URL and keeps waiting. An agent must open that URL in ITS OWN
+browser (Playwright, browser-use, or handing it to the person) for the sign-in to
+complete.
+
 When MUTAGENT_API_KEY is set, login skips the browser and validates the key.
 
 Environment:
@@ -28950,163 +28994,2412 @@ function printEntries(environment) {
   }
 }
 
-// src/bin/cli.ts
+// src/commands/gateway/index.ts
+init_config();
+import { Command as Command22 } from "commander";
+import chalk46 from "chalk";
+
+// src/commands/gateway/status.ts
+import chalk39 from "chalk";
+
+// src/lib/gateway-api.ts
 init_config();
+init_known_secrets();
 init_organization_scope();
+class GatewayApiError extends Error {
+  status;
+  code;
+  reason;
+  fix;
+  constructor(status, code, reason, fix) {
+    super(reason);
+    this.status = status;
+    this.code = code;
+    this.reason = reason;
+    this.fix = fix;
+    this.name = "GatewayApiError";
+  }
+}
 
-// src/lib/brand.ts
-var BRAND = {
-  name: "MUTAGENT",
-  primary: "#7E47D7",
-  accent: "#45b8cc",
-  gradientFrom: "#45b8cc",
-  gradientTo: "#7E47D7"
-};
-var WORDMARK = [
-  " ███╗   ███╗ ██╗   ██╗ ████████╗  █████╗   ██████╗  ███████╗ ███╗   ██╗ ████████╗  ",
-  " ████╗ ████║ ██║   ██║ ╚══██╔══╝ ██╔══██╗ ██╔════╝  ██╔════╝ ████╗  ██║ ╚══██╔══╝  ",
-  " ██╔████╔██║ ██║   ██║    ██║    ███████║ ██║  ███╗ █████╗   ██╔██╗ ██║    ██║     ",
-  " ██║╚██╔╝██║ ██║   ██║    ██║    ██╔══██║ ██║   ██║ ██╔══╝   ██║╚██╗██║    ██║     ",
-  " ██║ ╚═╝ ██║ ╚██████╔╝    ██║    ██║  ██║ ╚██████╔╝ ███████╗ ██║ ╚████║    ██║     ",
-  " ╚═╝     ╚═╝  ╚═════╝     ╚═╝    ╚═╝  ╚═╝  ╚═════╝  ╚══════╝ ╚═╝  ╚═══╝    ╚═╝     "
-];
-var WORDMARK_MIN_COLUMNS = 84;
-function hexToRgb(hex) {
-  const n = parseInt(hex.slice(1), 16);
-  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+class GatewayNetworkError extends Error {
+  endpoint;
+  constructor(endpoint, cause) {
+    super(`Could not reach the MutagenT API at ${endpoint}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.endpoint = endpoint;
+    this.name = "GatewayNetworkError";
+  }
 }
-var lerp = (a, b, t) => Math.round(a + (b - a) * t);
-function mix(from, to, t) {
-  return [lerp(from[0], to[0], t), lerp(from[1], to[1], t), lerp(from[2], to[2], t)];
+
+class GatewayConfigError extends Error {
+  code;
+  constructor(code) {
+    super("No MutagenT API key configured.");
+    this.code = code;
+    this.name = "GatewayConfigError";
+  }
 }
-var ansi = (r, g, b) => `\x1B[38;2;${String(r)};${String(g)};${String(b)}m`;
-var RESET = "\x1B[0m";
-function gradientLine(line, from, to) {
-  const chars = Array.from(line);
-  const n = chars.length;
-  let out = "";
-  chars.forEach((ch, i) => {
-    if (ch === " ") {
-      out += ch;
-      return;
+function parseGatewayErrorBody(status, bodyText, statusText) {
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyText);
+  } catch {
+    parsed = undefined;
+  }
+  if (parsed && typeof parsed === "object") {
+    const record3 = parsed;
+    if (typeof record3.code === "string" && typeof record3.reason === "string") {
+      if ("fix" in record3) {
+        const rawFix = record3.fix;
+        const fix = rawFix && typeof rawFix === "object" && typeof rawFix.action === "string" ? rawFix : null;
+        return { code: record3.code, reason: record3.reason, fix };
+      }
+      return { code: record3.code, reason: record3.reason };
     }
-    const [r, g, b] = mix(from, to, n > 1 ? i / (n - 1) : 0);
-    out += ansi(r, g, b) + ch;
-  });
-  return out + RESET;
-}
-function hasTruecolor(env = process.env) {
-  return /truecolor|24bit/i.test(env.COLORTERM ?? "");
+    if (typeof record3.error === "string" && typeof record3.message === "string") {
+      return { code: record3.error.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "") || "server_fault", reason: record3.message };
+    }
+  }
+  return { code: "server_fault", reason: bodyText.slice(0, 300) || statusText || `Request failed with status ${String(status)}` };
 }
-function detectBannerEnv(stream = process.stdout, env = process.env) {
+async function resolveGatewayConnection() {
+  const apiKey = getApiKey();
+  if (apiKey === undefined || apiKey === "")
+    throw new GatewayConfigError("not_signed_in");
+  const tenancy = await resolveKeyTenancy(apiKey);
+  const workspaceId = tenancy.workspaceId?.trim();
+  if (workspaceId === undefined || workspaceId === "")
+    throw noWorkspaceSelected();
+  const headers = { "x-api-key": apiKey, "Content-Type": "application/json" };
+  if (tenancy.keyScope !== "workspace")
+    headers["x-workspace-id"] = workspaceId;
   return {
-    isTTY: stream.isTTY === true,
-    columns: stream.columns ?? 80,
-    truecolor: hasTruecolor(env),
-    disabled: env.MUTAGENT_NO_BANNER === "1"
+    endpoint: tenancy.endpoint,
+    apiKey,
+    workspaceId,
+    headers,
+    tenancy: {
+      keyScope: tenancy.keyScope,
+      workspaceId,
+      workspaceName: tenancy.workspaceName,
+      workspaceOrigin: tenancy.workspaceOrigin,
+      organizationName: tenancy.organization?.name
+    }
   };
 }
-function renderBanner(env = detectBannerEnv()) {
-  if (env.disabled || !env.isTTY)
-    return "";
-  const from = hexToRgb(BRAND.gradientFrom);
-  const to = hexToRgb(BRAND.gradientTo);
-  const wide = env.columns >= WORDMARK_MIN_COLUMNS;
-  const art = wide ? WORDMARK : [`  ${BRAND.name}`];
-  const lines = env.truecolor ? art.map((l) => gradientLine(l, from, to)) : art.map((l) => `${ansi(...from)}${l}${RESET}`);
-  return `
-${lines.join(`
-`)}
-`;
-}
-
-// src/lib/global-version-flag.ts
-var GLOBAL_VALUE_OPTIONS = new Set(["--api-key", "--endpoint", "--workspace", "--org"]);
-function findSubcommandIndex(rawArgs) {
-  for (let i = 0;i < rawArgs.length; i++) {
-    const arg = rawArgs[i];
-    if (arg === undefined)
-      continue;
-    if (arg === "--")
-      return i + 1 < rawArgs.length ? i + 1 : -1;
-    if (arg.startsWith("-")) {
-      if (GLOBAL_VALUE_OPTIONS.has(arg))
-        i++;
-      continue;
+async function gatewayRequest(path, init = {}) {
+  const connection = await resolveGatewayConnection();
+  let response;
+  try {
+    response = await fetch(`${connection.endpoint}${path}`, {
+      ...init,
+      headers: { ...connection.headers, ...init.headers }
+    });
+  } catch (error3) {
+    throw new GatewayNetworkError(connection.endpoint, error3);
+  }
+  if (response.status === 401)
+    throw deadKeyError();
+  if (!response.ok) {
+    const bodyText = await response.text().catch(() => "");
+    if (response.status === 403 && tenancyCodeOf(bodyText) === TENANCY_DENIED) {
+      const denied = tenancyFailure(response.status, bodyText, connection.tenancy);
+      if (denied)
+        throw denied;
     }
-    return i;
+    const { code, reason, fix } = parseGatewayErrorBody(response.status, bodyText, response.statusText);
+    throw new GatewayApiError(response.status, code, reason, fix);
+  }
+  const text = await response.text();
+  if (text.trim() === "")
+    return {};
+  try {
+    return scrubKnownSuccessDeep(JSON.parse(text));
+  } catch {
+    throw new GatewayApiError(response.status, "server_fault", `The server returned a non-JSON response for ${path}.`);
   }
-  return -1;
 }
-function isGlobalVersionFlag(rawArgs) {
-  const versionAt = rawArgs.findIndex((a) => a === "-v" || a === "--version");
-  if (versionAt === -1)
-    return false;
-  const subcommandAt = findSubcommandIndex(rawArgs);
-  return subcommandAt === -1 || versionAt < subcommandAt;
+function tenancyCodeOf(bodyText) {
+  try {
+    const parsed = JSON.parse(bodyText);
+    if (parsed && typeof parsed === "object") {
+      const code = parsed.code;
+      return typeof code === "string" ? code : undefined;
+    }
+  } catch {}
+  return;
 }
-var ROOT_BOOLEAN_OPTIONS = new Set(["--json", "--non-interactive"]);
-function commandPathIndexes(rawArgs, depth) {
-  const indexes = [];
-  let from = 0;
-  while (indexes.length < depth) {
-    const at = findSubcommandIndex(rawArgs.slice(from));
-    if (at === -1)
+function qs(params) {
+  const entries = Object.entries(params).filter((entry) => entry[1] !== undefined && entry[1] !== "");
+  if (entries.length === 0)
+    return "";
+  return `?${new URLSearchParams(entries).toString()}`;
+}
+async function listIntegrations() {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/integrations${qs({ workspaceId })}`);
+}
+async function startIntegration(provider, mode) {
+  const { workspaceId } = await resolveGatewayConnection();
+  const body = { workspaceId, returnTo: "close" };
+  return gatewayRequest(`/api/gateway/integrations/${provider}/${mode}`, {
+    method: "POST",
+    body: JSON.stringify(body)
+  });
+}
+async function getIntegrationAttempt(state) {
+  return gatewayRequest(`/api/gateway/integrations/attempts/${encodeURIComponent(state)}`);
+}
+async function disconnectIntegration(provider) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/integrations/${provider}${qs({ workspaceId })}`, { method: "DELETE" });
+}
+async function listRepositories(cursor) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/integrations/github/repositories${qs({ workspaceId, cursor })}`);
+}
+async function listAllRepositories(maxPages = 20) {
+  const items = [];
+  let cursor;
+  for (let page = 0;page < maxPages; page += 1) {
+    const response = await listRepositories(cursor);
+    items.push(...response.items);
+    if (response.nextCursor === null)
       break;
-    indexes.push(from + at);
-    from += at + 1;
+    cursor = response.nextCursor;
   }
-  return indexes;
+  return items;
+}
+async function getDefaultRepository() {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/integrations/github/default-repository${qs({ workspaceId })}`);
+}
+async function setDefaultRepository(repositoryId) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest("/api/gateway/integrations/github/default-repository", {
+    method: "PUT",
+    body: JSON.stringify({ workspaceId, repositoryId })
+  });
+}
+async function startTestRun(key, repositoryId) {
+  return gatewayRequest("/api/gateway/test-run", {
+    method: "POST",
+    body: JSON.stringify({ key, repositoryId })
+  });
+}
+async function getEventRun(eventId) {
+  return gatewayRequest(`/api/gateway/events/${encodeURIComponent(eventId)}/run`);
+}
+async function emitEvent(key, kind, payload) {
+  return gatewayRequest("/api/gateway/emit", {
+    method: "POST",
+    body: JSON.stringify({ key, kind, ...payload === undefined ? {} : { payload } })
+  });
+}
+async function findRepositoryByName(name) {
+  const items = await listAllRepositories();
+  return items.find((item) => item.name === name);
 }
 
-// src/bin/cli.ts
+// src/lib/gateway-envelope.ts
+import chalk38 from "chalk";
+init_known_secrets();
 init_errors();
 
-// src/commands/helix/api-key-guard.ts
-init_errors();
-var FORWARDING_VERBS = [
-  { path: ["helix"], label: "mutagent helix" },
-  { path: ["sandbox", "exec"], label: "mutagent sandbox exec" }
-];
-function rootValueOption(arg) {
-  const eq = arg.indexOf("=");
-  const name = eq === -1 ? arg : arg.slice(0, eq);
-  return GLOBAL_VALUE_OPTIONS.has(name) ? name : undefined;
-}
-function commanderBindable(tokens) {
-  const bindable = [];
-  for (let i = 0;i < tokens.length; i++) {
-    const token = tokens[i] ?? "";
-    if (token === "--")
-      break;
-    bindable.push(token);
-    if (GLOBAL_VALUE_OPTIONS.has(token) && i + 1 < tokens.length) {
-      bindable.push(tokens[i + 1] ?? "");
-      i++;
+class GatewayCliError extends Error {
+  code;
+  fix;
+  exitCode;
+  notes;
+  constructor(code, reason, fix, exitCode = 1, notes = []) {
+    super(reason);
+    this.code = code;
+    this.fix = fix;
+    this.exitCode = exitCode;
+    this.notes = notes;
+    this.name = "GatewayCliError";
+  }
+}
+var OPERATOR_HANDOFF_COMMAND = 'mutagent feedback send "<what happened>" --category cli';
+var OPERATOR_HANDOFF_NOTE = 'The gateway is not configured on the server. Only a Mutagent operator can fix that (it needs "mutagent gateway admin preflight" from a server checkout), so report it rather than retrying.';
+var RECOVERY = {
+  not_signed_in: { exitCode: 2, fix: () => ["mutagent login --browser"] },
+  github_not_connected: { exitCode: 2, fix: () => ["mutagent gateway connect github --wait"] },
+  state_user_mismatch: {
+    exitCode: 2,
+    fix: (provider) => [`mutagent gateway connect ${provider ?? "github"}`],
+    notes: () => ["Open the printed signInUrl in a browser already signed in to Mutagent as you, then open the printed url in that SAME browser."]
+  },
+  installation_not_authorized: {
+    exitCode: 2,
+    fix: (provider) => [`mutagent gateway connect ${provider ?? "github"}`],
+    notes: () => ["Reinstall the GitHub App while signed in to GitHub as its owner."]
+  },
+  user_authorization_failed: {
+    exitCode: 2,
+    fix: (provider) => [`mutagent gateway connect ${provider ?? "github"}`]
+  },
+  installation_not_found: {
+    exitCode: 2,
+    fix: (provider) => [`mutagent gateway connect ${provider ?? "github"}`]
+  },
+  installation_not_recent: {
+    exitCode: 2,
+    fix: (provider) => [`mutagent gateway connect ${provider ?? "github"}`],
+    notes: () => ["Finish the install on GitHub during the NEW attempt — an install that predates it is not accepted."]
+  },
+  installation_suspended: {
+    exitCode: 2,
+    fix: (provider) => [`mutagent gateway reconnect ${provider ?? "github"}`],
+    notes: () => ["First unsuspend the MutagenT app for this account in GitHub settings: github.com -> Settings -> Applications."]
+  },
+  installation_owned_elsewhere: {
+    exitCode: 4,
+    fix: (provider) => [`mutagent gateway disconnect ${provider ?? "<provider>"} --yes`],
+    notes: () => ["Run that from the OTHER workspace — the one this account is already connected to."]
+  },
+  installation_inactive: {
+    exitCode: 3,
+    fix: (provider) => [`mutagent gateway reconnect ${provider ?? "github"}`]
+  },
+  provider_denied: {
+    exitCode: 2,
+    fix: (provider) => [`mutagent gateway connect ${provider ?? "slack"}`]
+  },
+  slack_oauth_refused: {
+    exitCode: 2,
+    fix: () => ["mutagent gateway connect slack"]
+  },
+  enterprise_install_unsupported: {
+    exitCode: 2,
+    fix: () => ["mutagent gateway connect slack"],
+    notes: () => ["Install the Slack app to a SINGLE workspace, not organization-wide — Enterprise Grid org installs are not supported yet."]
+  },
+  provider_unavailable: {
+    exitCode: 3,
+    fix: (provider) => [`mutagent gateway connect ${provider ?? "<provider>"}`],
+    notes: () => ["The provider did not answer. Nothing is misconfigured — start the attempt over."]
+  },
+  test_run_repository_inaccessible: {
+    exitCode: 3,
+    fix: () => ["mutagent gateway repos grant-more", "mutagent gateway repos link owner/name"]
+  },
+  repository_inaccessible: {
+    exitCode: 3,
+    fix: () => ["mutagent gateway repos grant-more", "mutagent gateway repos link owner/name"]
+  },
+  repository_not_found: {
+    exitCode: 3,
+    fix: () => ["mutagent gateway repos --json", "mutagent gateway repos grant-more"],
+    notes: () => ["The first command lists every repository this installation can reach."]
+  },
+  no_default_repository: { exitCode: 3, fix: () => ["mutagent gateway repos default owner/name"] },
+  connected_to_multiple_workspaces: {
+    exitCode: 4,
+    fix: (provider) => [`mutagent gateway disconnect ${provider ?? "<provider>"} --yes`],
+    notes: () => ["Run that from the OTHER workspace — the one this account is already connected to."]
+  },
+  run_principal_unavailable: { exitCode: 3, fix: (provider) => [`mutagent gateway reconnect ${provider ?? "github"}`] },
+  builtin_run_unconfigured: { exitCode: 2, fix: () => [OPERATOR_HANDOFF_COMMAND], notes: () => [OPERATOR_HANDOFF_NOTE] },
+  integration_unconfigured: { exitCode: 2, fix: () => [OPERATOR_HANDOFF_COMMAND], notes: () => [OPERATOR_HANDOFF_NOTE] },
+  test_run_unconfigured: { exitCode: 2, fix: () => [OPERATOR_HANDOFF_COMMAND], notes: () => [OPERATOR_HANDOFF_NOTE] },
+  test_run_key_conflict: {
+    exitCode: 4,
+    fix: () => ["mutagent gateway test-run --key <a-different-key>"],
+    notes: () => ["Or omit --key entirely and a fresh one is generated."]
+  },
+  test_run_target_unavailable: { exitCode: 1, fix: () => ["mutagent gateway test-run --wait"], notes: () => ["Transient — retry shortly."] },
+  key_invalid: { exitCode: 3, fix: () => [], notes: () => ["--key must be 1 to 256 characters. Re-run the same command with a valid --key."] },
+  cursor_invalid: { exitCode: 1, fix: () => ["mutagent gateway repos --json"], notes: () => ["That starts the listing over from the first page."] },
+  not_found: { exitCode: 1, fix: () => [], notes: () => ["Check the id and retry."] },
+  state_unknown: { exitCode: 3, fix: (provider) => [`mutagent gateway connect ${provider ?? "github"}`] },
+  state_replayed: { exitCode: 3, fix: (provider) => [`mutagent gateway connect ${provider ?? "github"}`] },
+  state_expired: { exitCode: 3, fix: (provider) => [`mutagent gateway connect ${provider ?? "github"}`] },
+  callback_invalid: { exitCode: 1, fix: (provider) => [`mutagent gateway connect ${provider ?? "github"}`] },
+  server_fault: {
+    exitCode: 1,
+    fix: () => [OPERATOR_HANDOFF_COMMAND],
+    notes: () => ["Retry shortly first — this may be transient. Report it if it persists."]
+  }
+};
+var GATEWAY_RECOVERY_CODES = Object.keys(RECOVERY);
+function recoveryEntry(code) {
+  return RECOVERY[code];
+}
+var GATEWAY_FIX_ACTION_EXIT_CODES = {
+  sign_in: 2,
+  connect_github: 2,
+  reconnect_github: 2,
+  ask_workspace_admin: 2,
+  contact_operator: 2,
+  wait_for_event_source: 4,
+  retry: 1,
+  read_run_logs: 3,
+  grant_more_repositories: 3,
+  link_repository: 3,
+  set_default_repository: 3,
+  pass_timezone: 3,
+  fix_schedule: 3,
+  choose_other_name: 3,
+  use_other_key: 3,
+  recreate_as_member: 3,
+  fix_limit: 3,
+  use_own_emit_kind: 3,
+  create_own_trigger: 3,
+  edit_existing_trigger: 3,
+  use_other_trigger_kind: 3
+};
+var UNKNOWN_FIX_ACTION_EXIT_CODE = 1;
+function exitCodeForFixAction(action) {
+  const known2 = GATEWAY_FIX_ACTION_EXIT_CODES;
+  return known2[action] ?? UNKNOWN_FIX_ACTION_EXIT_CODE;
+}
+function unknownFixActionNote(action) {
+  return `This CLI does not know the remedy the server sent ('${action}'), so it cannot name a command for it. Update the CLI to a newer version; until then, act on the reason above.`;
+}
+function renderWorkspaceConfigFix(fix, ctx = {}) {
+  const p = fix.params;
+  const resource = ctx.resource ?? "triggers";
+  switch (fix.action) {
+    case "sign_in":
+      return { commands: ["mutagent login --browser"], notes: [] };
+    case "connect_github":
+      return { commands: ["mutagent gateway connect github --wait"], notes: [] };
+    case "reconnect_github":
+      return { commands: ["mutagent gateway reconnect github"], notes: [] };
+    case "grant_more_repositories": {
+      const commands = ["mutagent gateway repos grant-more"];
+      if (p.repository)
+        commands.push(`mutagent gateway repos link ${p.repository}`);
+      return { commands, notes: p.url ? [`Or grant access directly at: ${p.url}`] : [] };
+    }
+    case "link_repository":
+      return { commands: [`mutagent gateway repos link ${p.repository ?? "owner/name"}`], notes: [] };
+    case "set_default_repository":
+      return { commands: [`mutagent gateway repos default ${p.repository ?? "owner/name"}`], notes: [] };
+    case "pass_timezone":
+      return { commands: [], notes: [`Re-run the same command with --tz ${p.example ?? "<IANA zone>"}.`] };
+    case "fix_schedule":
+      return {
+        commands: [],
+        notes: [
+          p.grammar ? `Re-run with a schedule matching: ${p.grammar}` : "Re-run with a corrected --cron or --every.",
+          ...p.example ? [`For example: --every "${p.example}"`] : []
+        ]
+      };
+    case "choose_other_name":
+      return { commands: [], notes: ["Re-run the same command with a different --name."] };
+    case "use_other_key":
+      return { commands: [], notes: ["Re-run the same command with a different --key."] };
+    case "recreate_as_member":
+      return {
+        commands: [`mutagent gateway ${resource} delete <id> --yes`],
+        notes: [`Then create it again as a current workspace member: mutagent gateway ${resource} create --help lists the flags.`]
+      };
+    case "wait_for_event_source":
+      return { commands: [], notes: [`The '${p.kind ?? "this"}' event source is not live yet — retry once it ships.`] };
+    case "contact_operator":
+      return { commands: [OPERATOR_HANDOFF_COMMAND], notes: [OPERATOR_HANDOFF_NOTE] };
+    case "retry":
+      return { commands: [], notes: ["Retry the same command — this was transient."] };
+    case "edit_existing_trigger":
+      return {
+        commands: [`mutagent gateway triggers show ${p.triggerId ?? "<id>"}`, `mutagent gateway triggers delete ${p.triggerId ?? "<id>"} --yes`],
+        notes: ["Delete it only if you would rather replace the existing trigger than keep it."]
+      };
+    case "ask_workspace_admin":
+      return { commands: [], notes: ["Ask a workspace admin to run this, or to grant you admin in the dashboard."] };
+    case "fix_limit":
+      return {
+        commands: [`mutagent gateway admin limits set --${p.field ?? "concurrent"} <n>`],
+        notes: [`--${p.field ?? "concurrent|daily"} must be between ${p.min ?? "?"} and ${p.max ?? "?"}.`]
+      };
+    case "use_own_emit_kind":
+      return {
+        commands: ["mutagent gateway routines run-now <routine-id>"],
+        notes: [`'${p.kind ?? "this"}' is reserved for the platform — emit your own kind instead, or run the routine directly.`]
+      };
+    case "create_own_trigger":
+      return { commands: ["mutagent gateway triggers create --help", "mutagent gateway routines create --help"], notes: [] };
+    case "read_run_logs":
+      return { commands: [`mutagent gateway runs logs ${p.runId ?? "<runId>"}`], notes: [] };
+    case "use_other_trigger_kind":
+      return {
+        commands: [
+          `mutagent gateway triggers create --on ${p.github ?? "github.issue.opened"} --repo owner/name --instruction "<what the agent should do>"`,
+          `mutagent gateway triggers create --on ${p.slack ?? "slack.mention"} --channel <channel-id> --instruction "<what the agent should do>"`
+        ],
+        notes: [`'${p.kind ?? "github.mention"}' is answered by the built-in @mention behaviour on every repository GitHub can reach, so it cannot be a trigger of your own.`]
+      };
+    default: {
+      const unknownAction = fix.action;
+      return { commands: [], notes: [unknownFixActionNote(unknownAction)] };
     }
   }
-  return bindable;
 }
-function forwardedRootOptionRefusal(rawArgs) {
-  for (const verb of FORWARDING_VERBS) {
-    const at = commandPathIndexes(rawArgs, verb.path.length);
-    if (at.length !== verb.path.length || at.some((index, k) => rawArgs[index] !== verb.path[k]))
-      continue;
-    const after = rawArgs.slice((at[at.length - 1] ?? -1) + 1);
-    const bindable = commanderBindable(after);
-    const isHelix = verb.path[0] === "helix";
-    const keyScope = isHelix ? after : bindable;
-    if (keyScope.some((arg) => rootValueOption(arg) === "--api-key")) {
-      return isHelix ? helixKeyRefusal() : sandboxExecKeyRefusal();
+function exitCodeForStatus(status) {
+  if (status === undefined)
+    return 1;
+  if (status === 409)
+    return 4;
+  if (status === 400 || status === 422)
+    return 3;
+  if (status === 503)
+    return 3;
+  return 1;
+}
+function gatewayErrorFromCode(code, reason, provider, status) {
+  const entry = recoveryEntry(code);
+  if (entry)
+    return new GatewayCliError(code, reason, entry.fix(provider), entry.exitCode, entry.notes?.(provider) ?? []);
+  return new GatewayCliError(code, reason, [], exitCodeForStatus(status));
+}
+function gatewayErrorFromRunError(error3, ctx = {}) {
+  if (error3.fix) {
+    const rendered = renderWorkspaceConfigFix(error3.fix, ctx);
+    return new GatewayCliError(error3.code, error3.reason, rendered.commands, exitCodeForFixAction(error3.fix.action), rendered.notes);
+  }
+  if (error3.fix === null) {
+    return new GatewayCliError(error3.code, error3.reason, [], 4, ["The server has already determined that nothing resolves this."]);
+  }
+  return gatewayErrorFromCode(error3.code, error3.reason, ctx.provider);
+}
+function renderRunErrorForDisplay(error3, ctx = {}) {
+  if (error3 === null)
+    return null;
+  const withNotes = (fix, notes) => notes.length > 0 ? { code: error3.code, reason: error3.reason, fix, notes } : { code: error3.code, reason: error3.reason, fix };
+  if (error3.fix) {
+    const rendered = renderWorkspaceConfigFix(error3.fix, ctx);
+    return withNotes(rendered.commands, rendered.notes);
+  }
+  if (error3.fix === null)
+    return withNotes([], []);
+  const fallback = gatewayErrorFromCode(error3.code, error3.reason, ctx.provider);
+  return withNotes(fallback.fix, fallback.notes);
+}
+function toGatewayCliError(error3, provider, resource) {
+  if (error3 instanceof GatewayCliError)
+    return error3;
+  if (error3 instanceof GatewayConfigError) {
+    return gatewayErrorFromCode(error3.code, error3.message, provider);
+  }
+  if (error3 instanceof GatewayApiError) {
+    if (error3.fix) {
+      const rendered = renderWorkspaceConfigFix(error3.fix, { provider, resource });
+      return new GatewayCliError(error3.code, error3.reason, rendered.commands, exitCodeForFixAction(error3.fix.action), rendered.notes);
     }
-    const other = bindable.map(rootValueOption).find((option) => option !== undefined);
-    if (other !== undefined)
-      return rootValueOptionRefusal(other, verb.label);
-    return;
+    return gatewayErrorFromCode(error3.code, error3.reason, provider, error3.status);
   }
-  return;
+  if (error3 instanceof GatewayNetworkError) {
+    return new GatewayCliError("network_error", error3.message, ["mutagent gateway doctor"], 1, ["Check your network connection first — the request never reached the server."]);
+  }
+  if (error3 instanceof MutagentError) {
+    const exitCode = error3.exitCode >= 1 && error3.exitCode <= 4 ? error3.exitCode : 1;
+    return new GatewayCliError(error3.code, error3.message, error3.suggestion ? [error3.suggestion] : [], exitCode);
+  }
+  const message = error3 instanceof Error ? error3.message : String(error3);
+  return new GatewayCliError("unexpected_error", message, [], 1);
 }
-function keyAlternative() {
+function gatewayIsJson(command) {
+  return getJsonFlag(command);
+}
+function printGatewayOk(isJson, data, opts) {
+  if (isJson) {
+    const envelope = { ok: true, data: scrubKnownSuccessDeep(data) };
+    if (opts.next && opts.next.length > 0)
+      envelope.next = opts.next;
+    console.log(JSON.stringify(envelope, null, 2));
+    return;
+  }
+  opts.human();
+  if (opts.next && opts.next.length > 0) {
+    console.log("");
+    console.log(chalk38.dim("Next:"));
+    for (const step of opts.next)
+      console.log(chalk38.dim(`  ${step}`));
+  }
+}
+function handleGatewayError(error3, isJson, provider, resource) {
+  const gwError = toGatewayCliError(error3, provider, resource);
+  if (isJson) {
+    const envelope = {
+      ok: false,
+      error: { code: gwError.code, reason: scrubKnownSuccess(gwError.message), fix: gwError.fix }
+    };
+    if (gwError.notes.length > 0 && envelope.error)
+      envelope.error.notes = gwError.notes.map(scrubKnownSuccess);
+    console.log(JSON.stringify(envelope, null, 2));
+  } else {
+    console.error(chalk38.red(`✗ ${scrubKnownSuccess(gwError.message)}`) + chalk38.dim(`  [${gwError.code}]`));
+    if (gwError.fix.length > 0) {
+      console.error("");
+      console.error(chalk38.yellow("Fix:"));
+      for (const step of gwError.fix)
+        console.error(chalk38.yellow(`  ${step}`));
+    }
+    if (gwError.notes.length > 0) {
+      console.error("");
+      for (const note of gwError.notes)
+        console.error(chalk38.dim(`  ${scrubKnownSuccess(note)}`));
+    }
+  }
+  process.exit(gwError.exitCode);
+}
+async function runGatewayAction(isJson, provider, fn, resource) {
+  let exitCode = undefined;
+  let caught;
+  try {
+    exitCode = await fn();
+  } catch (error3) {
+    caught = { error: error3 };
+  }
+  if (caught) {
+    handleGatewayError(caught.error, isJson, provider, resource);
+  }
+  if (typeof exitCode === "number" && exitCode !== 0)
+    process.exit(exitCode);
+}
+
+// src/commands/gateway/status.ts
+async function computeGatewayStatus() {
+  const [integrations, defaultRepo] = await Promise.all([listIntegrations(), getDefaultRepository()]);
+  const github = integrations.integrations.find((i) => i.provider === "github") ?? null;
+  const slack = integrations.integrations.find((i) => i.provider === "slack") ?? null;
+  return {
+    workspaceId: integrations.workspaceId,
+    connections: { github, slack },
+    defaultRepository: defaultRepo.defaultRepository
+  };
+}
+function nextStepFor(status) {
+  if (status.connections.github?.state !== "connected")
+    return ["mutagent gateway connect github --wait"];
+  if (status.defaultRepository === null)
+    return ["mutagent gateway repos default owner/name"];
+  if (status.connections.slack?.state !== "connected")
+    return ["mutagent gateway connect slack --wait   (optional)"];
+  return ["mutagent gateway test-run --wait"];
+}
+function printStatusHuman(status) {
+  console.log(chalk39.bold("Gateway status") + chalk39.dim(`  workspace ${status.workspaceId}`));
+  for (const provider of ["github", "slack"]) {
+    const conn = status.connections[provider];
+    const connected = conn?.state === "connected";
+    const mark = connected ? chalk39.green("✓") : chalk39.yellow("·");
+    const detail = conn === null ? "unknown" : connected ? conn.accountName ?? conn.accountId ?? "connected" : conn.state;
+    console.log(`  ${mark} ${provider.padEnd(6)} ${detail}`);
+  }
+  console.log(`  ${status.defaultRepository ? chalk39.green("✓") : chalk39.yellow("·")} default repo  ${status.defaultRepository?.name ?? "(none)"}`);
+}
+function registerGatewayStatusCommands(gateway) {
+  gateway.action(async () => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const status = await computeGatewayStatus();
+      printGatewayOk(isJson, status, { next: nextStepFor(status), human: () => {
+        printStatusHuman(status);
+      } });
+      return;
+    });
+  });
+  gateway.command("status").description("What's connected, what's missing, and the next command to run").addHelpText("after", `
+Examples:
+  ${chalk39.dim("$")} mutagent gateway status
+  ${chalk39.dim("$")} mutagent gateway status --json
+
+Same as bare 'mutagent gateway' — the one command that always tells you what's next.
+
+AI Agent Directive:
+  --json returns { ok, data: { workspaceId, connections: { github, slack }, defaultRepository },
+  next: ["<the one command to run next>"] }. Always run this first; follow 'next' verbatim.
+      `).action(async () => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const status = await computeGatewayStatus();
+      printGatewayOk(isJson, status, { next: nextStepFor(status), human: () => {
+        printStatusHuman(status);
+      } });
+      return;
+    });
+  });
+  gateway.command("doctor").description("End-to-end check of the gateway setup, with fixes for anything broken").addHelpText("after", `
+Examples:
+  ${chalk39.dim("$")} mutagent gateway doctor
+  ${chalk39.dim("$")} mutagent gateway doctor --json
+
+Checks: GitHub/Slack connection state, a default repository is set, and — the one thing
+'status' does not check — that the default repository is still reachable through the
+GitHub installation (access can be revoked after it was chosen).
+
+AI Agent Directive:
+  --json returns { ok, data: { ...status, checks: [{ name, pass, detail }] } }.
+  ok is false when any check fails; each failing check's 'detail' names the fix.
+      `).action(async () => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const status = await computeGatewayStatus();
+      const checks = [
+        {
+          name: "github_connected",
+          pass: status.connections.github?.state === "connected",
+          detail: status.connections.github?.state === "connected" ? "connected" : "mutagent gateway connect github --wait"
+        },
+        {
+          name: "default_repository_set",
+          pass: status.defaultRepository !== null,
+          detail: status.defaultRepository ? status.defaultRepository.name : "mutagent gateway repos default owner/name"
+        }
+      ];
+      if (status.defaultRepository !== null && status.connections.github?.state === "connected") {
+        const reachable = await listAllRepositories();
+        const stillReachable = reachable.some((repo) => repo.id === status.defaultRepository?.repositoryId);
+        checks.push({
+          name: "default_repository_reachable",
+          pass: stillReachable,
+          detail: stillReachable ? "reachable" : "mutagent gateway repos grant-more"
+        });
+      }
+      const allPass = checks.every((c) => c.pass);
+      const data = { ...status, checks };
+      if (isJson) {
+        console.log(JSON.stringify({ ok: allPass, data }, null, 2));
+      } else {
+        printStatusHuman(status);
+        console.log("");
+        console.log(chalk39.bold("Checks:"));
+        for (const check3 of checks) {
+          console.log(`  ${check3.pass ? chalk39.green("✓") : chalk39.red("✗")} ${check3.name}  ${chalk39.dim(check3.detail)}`);
+        }
+      }
+      return allPass ? undefined : 3;
+    });
+  });
+}
+
+// src/commands/gateway/connect.ts
+import chalk40 from "chalk";
+
+// src/lib/gateway-poll.ts
+function sleep2(ms) {
+  return new Promise((resolve9) => setTimeout(resolve9, ms));
+}
+function defaultIntervalMs() {
+  return envMsOverride("MUTAGENT_TEST_POLL_INTERVAL_MS") ?? 2000;
+}
+function defaultTimeoutMs() {
+  return envMsOverride("MUTAGENT_TEST_POLL_TIMEOUT_MS") ?? 300000;
+}
+function envMsOverride(name) {
+  const override2 = process.env[name];
+  if (override2 === undefined)
+    return;
+  const parsed = Number(override2);
+  if (Number.isFinite(parsed) && parsed >= 0)
+    return parsed;
+  return;
+}
+async function pollUntil(fetchOnce, isDone, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? defaultTimeoutMs();
+  const intervalMs = opts.intervalMs ?? defaultIntervalMs();
+  const start = Date.now();
+  let value2 = await fetchOnce();
+  if (isDone(value2))
+    return { value: value2, settled: true };
+  while (Date.now() - start < timeoutMs) {
+    await sleep2(intervalMs);
+    value2 = await fetchOnce();
+    if (isDone(value2))
+      return { value: value2, settled: true };
+  }
+  return { value: value2, settled: false };
+}
+
+// src/commands/gateway/connect.ts
+var PROVIDERS = ["github", "slack"];
+function parseProvider(raw) {
+  if (raw === "github" || raw === "slack")
+    return raw;
+  throw new GatewayCliError("validation_error", `Unknown provider: ${raw}`, [], 3, [`Re-run with one of: ${PROVIDERS.join(", ")}.`]);
+}
+function parseProviderOrExit(raw, isJson) {
+  try {
+    return parseProvider(raw);
+  } catch (error3) {
+    handleGatewayError(error3, isJson);
+  }
+}
+async function openInBrowser(url) {
+  try {
+    const { default: open2 } = await import("open");
+    await open2(url);
+  } catch {}
+}
+async function waitForAttempt(state) {
+  const { value: value2 } = await pollUntil(() => getIntegrationAttempt(state), (attempt) => attempt.phase !== "pending");
+  return value2;
+}
+function reportAttempt(provider, attempt, isJson) {
+  if (attempt.phase === "completed") {
+    printGatewayOk(isJson, { provider, status: attempt.status }, {
+      next: provider === "github" ? ["mutagent gateway repos default owner/name"] : [],
+      human: () => {
+        console.log(chalk40.green(`✓ ${provider} connected`) + chalk40.dim(`  ${attempt.status?.accountName ?? attempt.status?.accountId ?? ""}`));
+      }
+    });
+    return;
+  }
+  if (attempt.phase === "pending") {
+    throw new GatewayCliError("connect_pending", "Still waiting for the browser step to complete.", [`mutagent gateway connect ${provider} --wait --attempt <id>`], 2);
+  }
+  const errorCode = attempt.status?.error?.code ?? (attempt.phase === "expired" ? "state_expired" : "callback_invalid");
+  const reason = attempt.status?.error?.reason ?? `The connection attempt ${attempt.phase}.`;
+  throw gatewayErrorFromCode(errorCode, reason, provider);
+}
+function registerConnect(gateway) {
+  gateway.command("connect").description("Connect GitHub or Slack (prints a URL to open, or resumes an attempt)").argument("<gateway-provider>", "github | slack").option("--wait", "Poll until the attempt settles instead of returning immediately").option("--open", "Also open the URL in a local browser (for a human at a desktop)").option("--attempt <id>", "Resume an existing attempt instead of starting a new one").addHelpText("after", `
+Examples:
+  ${chalk40.dim("$")} mutagent gateway connect github --json
+  ${chalk40.dim("$")} mutagent gateway connect github --wait --attempt att_abc123
+  ${chalk40.dim("$")} mutagent gateway connect slack --open
+
+Already connected is success, not an error: re-running this once github or slack is
+already connected exits 0 and does nothing — safe to retry.
+
+Without --wait: prints { signInUrl, url, attempt } and exits 2 (a person or browser
+is needed). Open signInUrl and sign in FIRST, then open url in that SAME browser —
+the authorization only completes in a browser signed in to Mutagent as you.
+With --wait: polls until the attempt completes, fails or expires.
+
+AI Agent Directive:
+  1. mutagent gateway connect <provider> --json  ->  { ok:true, data:{signInUrl,url,attempt}, ... } exit 2
+  2. Open 'data.signInUrl' and sign in (Playwright/browser-use).
+  3. In that SAME browser, open 'data.url' and authorize.
+  4. mutagent gateway connect <provider> --wait --attempt <data.attempt> --json
+      `).action(async (providerArg, options) => {
+    const isJson = gatewayIsJson(gateway);
+    const provider = parseProviderOrExit(providerArg, isJson);
+    await runGatewayAction(isJson, provider, async () => {
+      if (options.attempt) {
+        const attempt2 = options.wait ? await waitForAttempt(options.attempt) : await getIntegrationAttempt(options.attempt);
+        return reportAttempt(provider, attempt2, isJson);
+      }
+      const existing = (await listIntegrations()).integrations.find((i) => i.provider === provider);
+      if (existing?.state === "connected") {
+        printGatewayOk(isJson, { provider, status: existing, alreadyConnected: true }, {
+          human: () => {
+            console.log(chalk40.green(`✓ ${provider} already connected`) + chalk40.dim(`  ${existing.accountName ?? existing.accountId ?? ""}`));
+          }
+        });
+        return;
+      }
+      const start = await startIntegration(provider, "connect");
+      if (options.open === true)
+        await openInBrowser(start.url);
+      const signInUrl = getAppBaseUrl();
+      if (options.wait !== true) {
+        printGatewayOk(isJson, { provider, signInUrl, url: start.url, attempt: start.state }, {
+          next: [
+            `Sign in at ${signInUrl}`,
+            `Then, in that SAME browser, open ${start.url}`,
+            `mutagent gateway connect ${provider} --wait --attempt ${start.state}`
+          ],
+          human: () => {
+            console.log(`1. Sign in (in a browser): ${chalk40.cyan(signInUrl)}`);
+            console.log(`2. Then, in that SAME browser, authorize: ${chalk40.cyan(start.url)}`);
+            console.log(chalk40.dim(`attempt: ${start.state}`));
+          }
+        });
+        return 2;
+      }
+      const attempt = await waitForAttempt(start.state);
+      return reportAttempt(provider, attempt, isJson);
+    });
+  });
+}
+function registerReconnect(gateway) {
+  gateway.command("reconnect").description("Re-authorize GitHub or Slack — also recovers run_principal_unavailable").argument("<gateway-provider>", "github | slack").addHelpText("after", `
+Examples:
+  ${chalk40.dim("$")} mutagent gateway reconnect github --json
+
+Starts a re-auth attempt. Sign in at signInUrl first, then open url in that SAME
+browser, then finish it the same way as 'connect':
+  mutagent gateway connect <provider> --wait --attempt <id>
+
+AI Agent Directive:
+  --json returns { ok:true, data:{ signInUrl, url, attempt },
+  next:["Sign in at ...", "Then, in that SAME browser, open ...", "mutagent gateway connect <provider> --wait --attempt <id>"] }, exit 2.
+      `).action(async (providerArg) => {
+    const isJson = gatewayIsJson(gateway);
+    const provider = parseProviderOrExit(providerArg, isJson);
+    await runGatewayAction(isJson, provider, async () => {
+      const start = await startIntegration(provider, "reauth");
+      const signInUrl = getAppBaseUrl();
+      printGatewayOk(isJson, { provider, signInUrl, url: start.url, attempt: start.state }, {
+        next: [
+          `Sign in at ${signInUrl}`,
+          `Then, in that SAME browser, open ${start.url}`,
+          `mutagent gateway connect ${provider} --wait --attempt ${start.state}`
+        ],
+        human: () => {
+          console.log(`1. Sign in (in a browser): ${chalk40.cyan(signInUrl)}`);
+          console.log(`2. Then, in that SAME browser, authorize: ${chalk40.cyan(start.url)}`);
+          console.log(chalk40.dim(`attempt: ${start.state}`));
+        }
+      });
+      return 2;
+    });
+  });
+}
+function registerDisconnect(gateway) {
+  gateway.command("disconnect").description("Disconnect GitHub or Slack from this workspace").argument("<gateway-provider>", "github | slack").option("--yes", "Confirm — required, never prompted for").addHelpText("after", `
+Examples:
+  ${chalk40.dim("$")} mutagent gateway disconnect slack --yes
+
+Idempotent: disconnecting when github or slack is already disconnected is success, not an error.
+Never prompts — pass --yes or the command refuses (exit 4).
+
+AI Agent Directive:
+  Confirm with the user before running this. --json returns { ok:true, data:{ provider, status } }.
+      `).action(async (providerArg, options) => {
+    const isJson = gatewayIsJson(gateway);
+    const provider = parseProviderOrExit(providerArg, isJson);
+    await runGatewayAction(isJson, provider, async () => {
+      if (options.yes !== true) {
+        throw new GatewayCliError("confirmation_required", `Disconnecting ${provider} requires confirmation.`, [`mutagent gateway disconnect ${provider} --yes`], 4);
+      }
+      const status = await disconnectIntegration(provider);
+      printGatewayOk(isJson, { provider, status }, {
+        human: () => {
+          console.log(chalk40.green(`✓ ${provider} disconnected`));
+        }
+      });
+      return;
+    });
+  });
+}
+function registerGatewayConnectCommands(gateway) {
+  registerConnect(gateway);
+  registerReconnect(gateway);
+  registerDisconnect(gateway);
+}
+
+// src/commands/gateway/repos.ts
+import chalk41 from "chalk";
+
+// src/lib/gateway-api-repos.ts
+async function listLinkedRepositories() {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/repositories${qs({ workspaceId })}`);
+}
+async function linkRepositories(repositories) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest("/api/gateway/repositories/link", {
+    method: "POST",
+    body: JSON.stringify({ workspaceId, repositories })
+  });
+}
+async function unlinkRepository(repository) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest("/api/gateway/repositories/unlink", {
+    method: "POST",
+    body: JSON.stringify({ workspaceId, repository })
+  });
+}
+async function getGrantMoreRepositoriesUrl() {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/repositories/grant-more${qs({ workspaceId })}`);
+}
+
+// src/commands/gateway/repos.ts
+function printLinkedRepo(repo) {
+  const mark = repo.state === "linked" ? chalk41.green("✓") : chalk41.yellow("·");
+  const def = repo.isDefault ? chalk41.dim(" (default)") : "";
+  const dependents = repo.dependents.triggers + repo.dependents.routines > 0 ? chalk41.dim(`  ${String(repo.dependents.triggers)} trigger(s), ${String(repo.dependents.routines)} routine(s)`) : "";
+  console.log(`  ${mark} ${repo.name}${def}${dependents}`);
+}
+function registerList(gateway) {
+  gateway.command("repos").description("Repositories the workspace's GitHub installation can reach, or has linked").option("--available", "Every reachable repository (same as no flag)").option("--linked", "Only repositories explicitly linked to this workspace").addHelpText("after", `
+Examples:
+  ${chalk41.dim("$")} mutagent gateway repos --json
+  ${chalk41.dim("$")} mutagent gateway repos --linked --json
+
+No flag or --available: every repository the GitHub App installation can reach
+(repos still bind lazily on first use for those not explicitly linked).
+--linked: only repositories 'repos link' has explicitly linked — shows dependents
+(triggers/routines) so an unlink's blast radius is visible before you run it.
+
+AI Agent Directive:
+  --available (default) --json: { ok, data: { items: [{ id, name, defaultBranch }], count } }.
+  --linked --json: { ok, data: { items: [{ repositoryId, name, state, isDefault, isPrivate,
+  dependents: { triggers, routines } }], count } }.
+  An empty --available list with GitHub connected means no repository access —
+  fix: mutagent gateway repos grant-more.
+      `).action(async (options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      if (options.linked === true) {
+        const { items: items2 } = await listLinkedRepositories();
+        printGatewayOk(isJson, { items: items2, count: items2.length }, {
+          human: () => {
+            if (items2.length === 0) {
+              console.log(chalk41.gray("No repositories linked. Fix: mutagent gateway repos link owner/name"));
+              return;
+            }
+            for (const repo of items2)
+              printLinkedRepo(repo);
+          }
+        });
+        return;
+      }
+      const items = await listAllRepositories();
+      printGatewayOk(isJson, { items, count: items.length }, {
+        human: () => {
+          if (items.length === 0) {
+            console.log(chalk41.gray("No repositories reachable. Fix: mutagent gateway repos grant-more"));
+            return;
+          }
+          for (const repo of items)
+            console.log(`  ${repo.name}  ${chalk41.dim(repo.defaultBranch)}`);
+        }
+      });
+      return;
+    });
+  });
+}
+function registerLink(repos, gateway) {
+  repos.command("link").description("Link repositories to this workspace so triggers/routines can target them").argument("<repositories...>", "owner/name (or GitHub repository id), 1–25").addHelpText("after", `
+Examples:
+  ${chalk41.dim("$")} mutagent gateway repos link owner/name
+  ${chalk41.dim("$")} mutagent gateway repos link owner/one owner/two
+
+Idempotent: an already-linked repository is returned unchanged. All-or-nothing —
+if one of several repositories can't be linked, none are.
+
+AI Agent Directive:
+  --json returns { ok, data: { items: LinkedRepository[] } }. An unreachable repository
+  fails with 'repository_inaccessible', fix: mutagent gateway repos grant-more.
+      `).action(async (repositories) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const { items } = await linkRepositories(repositories);
+      printGatewayOk(isJson, { items }, {
+        human: () => {
+          for (const repo of items)
+            printLinkedRepo(repo);
+        }
+      });
+      return;
+    });
+  });
+}
+function registerUnlink(repos, gateway) {
+  repos.command("unlink").description("Unlink a repository — its triggers and routines pause, they are not deleted").argument("<owner/name>", "The repository to unlink").option("--yes", "Confirm — required, never prompted for").addHelpText("after", `
+Examples:
+  ${chalk41.dim("$")} mutagent gateway repos unlink owner/name --yes
+
+Dependent triggers and routines PAUSE (visibly — 'repository_unlinked'), never delete.
+Refused for the workspace default repository — set another default first.
+Never prompts — pass --yes or the command refuses (exit 4).
+
+AI Agent Directive:
+  --json returns { ok, data: { repository, paused: { triggers: id[], routines: id[] } } }.
+      `).action(async (repository, options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      if (options.yes !== true) {
+        throw new GatewayCliError("confirmation_required", `Unlinking ${repository} requires confirmation.`, [`mutagent gateway repos unlink ${repository} --yes`], 4);
+      }
+      const result = await unlinkRepository(repository);
+      printGatewayOk(isJson, result, {
+        human: () => {
+          console.log(chalk41.green(`✓ Unlinked ${result.repository.name}`));
+          if (result.paused.triggers.length > 0)
+            console.log(chalk41.yellow(`  paused triggers: ${result.paused.triggers.join(", ")}`));
+          if (result.paused.routines.length > 0)
+            console.log(chalk41.yellow(`  paused routines: ${result.paused.routines.join(", ")}`));
+        }
+      });
+      return;
+    });
+  });
+}
+function registerGrantMore(repos, gateway) {
+  repos.command("grant-more").description("Print the GitHub page for granting the app access to more repositories").addHelpText("after", `
+Examples:
+  ${chalk41.dim("$")} mutagent gateway repos grant-more --json
+
+Opens no browser itself — prints the URL. Open it in the SAME browser you signed
+in to Mutagent with, then 'repos link owner/name'.
+
+AI Agent Directive:
+  --json returns { ok, data: { url } }, next: ["mutagent gateway repos link owner/name"].
+      `).action(async () => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const result = await getGrantMoreRepositoriesUrl();
+      printGatewayOk(isJson, result, {
+        next: ["mutagent gateway repos link owner/name"],
+        human: () => {
+          console.log(`Open this URL (in the browser you signed in with): ${chalk41.cyan(result.url)}`);
+        }
+      });
+      return;
+    });
+  });
+}
+function registerDefault(repos, gateway) {
+  repos.command("default").description("Show or set the workspace default repository").argument("[owner/name]", "Set the default to this repository (must be reachable)").addHelpText("after", `
+Examples:
+  ${chalk41.dim("$")} mutagent gateway repos default
+  ${chalk41.dim("$")} mutagent gateway repos default owner/name
+
+No argument: shows the current default (or null). With an argument: sets it — the
+repository must already be reachable through the GitHub installation (see 'repos').
+
+AI Agent Directive:
+  --json returns { ok, data: { defaultRepository: { repositoryId, name, setAt } | null } }.
+  Setting an unreachable repository fails with 'repository_not_found', fix:
+  mutagent gateway repos --json (to see what IS reachable), then repos grant-more.
+      `).action(async (ownerName) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      if (ownerName === undefined) {
+        const current = await getDefaultRepository();
+        printGatewayOk(isJson, { defaultRepository: current.defaultRepository }, {
+          human: () => {
+            console.log(current.defaultRepository ? current.defaultRepository.name : chalk41.gray("(no default repository set)"));
+          }
+        });
+        return;
+      }
+      const repo = await findRepositoryByName(ownerName);
+      if (repo === undefined) {
+        throw gatewayErrorFromCode("repository_not_found", `${ownerName} is not reachable through this workspace's GitHub installation.`);
+      }
+      const result = await setDefaultRepository(repo.id);
+      printGatewayOk(isJson, { defaultRepository: result.defaultRepository }, {
+        next: ["mutagent gateway test-run --wait"],
+        human: () => {
+          console.log(chalk41.green(`✓ Default repository set to ${result.defaultRepository?.name ?? ownerName}`));
+        }
+      });
+      return;
+    });
+  });
+}
+function registerGatewayReposCommands(gateway) {
+  registerList(gateway);
+  const reposCommand = gateway.commands.find((c) => c.name() === "repos");
+  if (reposCommand) {
+    registerDefault(reposCommand, gateway);
+    registerLink(reposCommand, gateway);
+    registerUnlink(reposCommand, gateway);
+    registerGrantMore(reposCommand, gateway);
+  }
+}
+
+// src/commands/gateway/triggers.ts
+import { readFileSync as readFileSync14 } from "node:fs";
+import { Command as Command18 } from "commander";
+import chalk42 from "chalk";
+
+// src/lib/gateway-api-triggers.ts
+var TRIGGER_KINDS = ["github.issue.opened", "slack.mention", "webhook", "github.ci-failed", "trace.threshold"];
+var BUILTIN_ONLY_TRIGGER_KINDS = ["github.mention"];
+async function listTriggers() {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/triggers?workspaceId=${encodeURIComponent(workspaceId)}`);
+}
+async function createTrigger(body) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest("/api/gateway/triggers", { method: "POST", body: JSON.stringify({ workspaceId, ...body }) });
+}
+async function getTrigger(id) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/triggers/${encodeURIComponent(id)}?workspaceId=${encodeURIComponent(workspaceId)}`);
+}
+async function setTriggerEnabled(id, enabled) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/triggers/${encodeURIComponent(id)}/${enabled ? "enable" : "disable"}`, {
+    method: "POST",
+    body: JSON.stringify({ workspaceId })
+  });
+}
+var enableTrigger = (id) => setTriggerEnabled(id, true);
+var disableTrigger = (id) => setTriggerEnabled(id, false);
+async function deleteTrigger(id) {
+  const { workspaceId } = await resolveGatewayConnection();
+  await gatewayRequest(`/api/gateway/triggers/${encodeURIComponent(id)}?workspaceId=${encodeURIComponent(workspaceId)}`, {
+    method: "DELETE"
+  });
+}
+async function testTrigger(id, event) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/triggers/${encodeURIComponent(id)}/test`, {
+    method: "POST",
+    body: JSON.stringify({ workspaceId, event })
+  });
+}
+
+// src/commands/gateway/triggers.ts
+var RESOURCE = "triggers";
+function printTrigger(t) {
+  const mark = t.status === "enabled" ? chalk42.green("✓") : t.status === "paused" ? chalk42.yellow("⏸") : chalk42.dim("○");
+  const builtin = t.builtin ? chalk42.dim(" [built-in]") : "";
+  console.log(`  ${mark} ${t.id}  ${t.name}${builtin}  ${chalk42.dim(t.kind)}  ${t.repository?.name ?? chalk42.dim("(default repo)")}`);
+  if (t.pausedReason)
+    console.log(chalk42.yellow(`      paused: ${t.pausedReason.reason}`));
+}
+function assertCreatableKind(kind) {
+  if (!BUILTIN_ONLY_TRIGGER_KINDS.includes(kind))
+    return;
+  throw gatewayErrorFromRunError({
+    code: "trigger_kind_builtin_only",
+    reason: `${kind} is answered by the built-in @mention behaviour on every repository GitHub can reach, so it cannot be a trigger of your own. Use github.issue.opened for repository events, or slack.mention with a dedicated Slack channel.`,
+    fix: { action: "use_other_trigger_kind", params: { kind, github: "github.issue.opened", slack: "slack.mention" } }
+  }, { resource: RESOURCE });
+}
+function registerList2(gateway) {
+  const triggers = new Command18("triggers").description("Event → agent run: create, list, show, enable, disable, delete, test");
+  gateway.addCommand(triggers);
+  triggers.description("List triggers — user-created first, then built-ins").addHelpText("after", `
+Examples:
+  ${chalk42.dim("$")} mutagent gateway triggers --json
+
+Built-in triggers (the default @mention behaviour) are listed, marked 'builtin: true',
+and are read-only — 'update'/'enable'/'disable'/'delete' on one refuse (409). A built-in
+always lists as enabled: no user trigger displaces it.
+
+AI Agent Directive:
+  --json returns { ok, data: { items: Trigger[] } }. status is enabled | disabled | paused
+  (paused = the SYSTEM paused it — see pausedReason; disabled = a user did). The
+  built-ins (builtin: true) are always enabled.
+      `).action(async () => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const { items } = await listTriggers();
+      printGatewayOk(isJson, { items }, {
+        human: () => {
+          if (items.length === 0) {
+            console.log(chalk42.gray("No triggers."));
+            return;
+          }
+          for (const t of items)
+            printTrigger(t);
+        }
+      });
+      return;
+    }, RESOURCE);
+  });
+  return triggers;
+}
+function normalizeInstructionText(text) {
+  return text.replace(/\r\n/g, `
+`).replace(/\r/g, `
+`);
+}
+function readInstruction(options) {
+  if (options.instructionFile) {
+    let text;
+    try {
+      text = readFileSync14(options.instructionFile, "utf8");
+    } catch {
+      throw new GatewayCliError("validation_error", `Could not read --instruction-file: ${options.instructionFile}`, [], 3, ["Check the path — --instruction-file takes a readable file."]);
+    }
+    return normalizeInstructionText(text);
+  }
+  if (options.instruction)
+    return normalizeInstructionText(options.instruction);
+  throw new GatewayCliError("validation_error", 'Pass --instruction "…" or --instruction-file f.md', ['mutagent gateway triggers create --on github.issue.opened --repo owner/name --instruction "<what the agent should do>"'], 3, ["Or read it from a file: --instruction-file <path>."]);
+}
+var WINDOW_UNIT_MINUTES = { m: 1, h: 60, d: 1440 };
+function parseWindowMinutes(raw) {
+  const match = /^(\d+)(m|h|d)$/.exec(raw.trim());
+  if (!match) {
+    throw new GatewayCliError("validation_error", `--window must look like 60m, 24h or 7d, got: ${raw}`, [], 3, ["Re-run with --window 60m, --window 24h or --window 7d."]);
+  }
+  const amount = match[1];
+  const unit = match[2];
+  if (amount === undefined || unit === undefined) {
+    throw new GatewayCliError("validation_error", `--window must look like 60m, 24h or 7d, got: ${raw}`, [], 3, ["Re-run with --window 60m, --window 24h or --window 7d."]);
+  }
+  return Number(amount) * (WINDOW_UNIT_MINUTES[unit] ?? 0);
+}
+function buildFilter(options) {
+  if (options.on === "trace.threshold") {
+    if (options.threshold === undefined || options.window === undefined) {
+      throw new GatewayCliError("trigger_filter_invalid", "trace.threshold needs --threshold and --window.", ['mutagent gateway triggers create --on trace.threshold --threshold 100 --window 60m --repo owner/name --instruction "<what the agent should do>"'], 3);
+    }
+    return {
+      traceThreshold: {
+        threshold: Number(options.threshold),
+        windowMinutes: parseWindowMinutes(options.window),
+        ...options.service ? { serviceName: options.service } : {},
+        ...options.session ? { sessionId: options.session } : {}
+      }
+    };
+  }
+  return options.channel ? { channelIds: options.channel } : undefined;
+}
+function registerCreate(triggers, gateway) {
+  triggers.command("create").description("Create a trigger").option("--on <kind>", `REQUIRED — trigger kind: ${TRIGGER_KINDS.join(" | ")} | emit:<kind>`).option("--repo <owner/name>", "Repository (default: the workspace default repository)").option("--instruction <text>", "The instruction Helix runs").option("--instruction-file <path>", "Read the instruction from a file").option("--name <name>", "Name (default: derived from kind + repository)").option("--key <key>", "Idempotency key — a retry with the same key returns the same trigger").option("--channel <id...>", "slack.mention only: limit to these Slack channel ids").option("--threshold <n>", "trace.threshold only: fire at or above this many traces (1–1,000,000)").option("--window <duration>", "trace.threshold only: the counting window, e.g. 60m, 24h, 7d").option("--service <name>", "trace.threshold only: limit to this service name").option("--session <id>", "trace.threshold only: limit to this session id").addHelpText("after", `
+Examples:
+  ${chalk42.dim("$")} mutagent gateway triggers create --on github.issue.opened --repo owner/name --instruction "Triage: label, estimate, ask one clarifying question if needed"
+  ${chalk42.dim("$")} mutagent gateway triggers create --on slack.mention --channel C0123 --instruction "…"
+  ${chalk42.dim("$")} mutagent gateway triggers create --on trace.threshold --threshold 100 --window 60m --repo owner/name --instruction "Investigate the volume spike"
+
+The built-in @mention behaviour already answers every @mention, and no trigger displaces it:
+- github.mention is built-in only: the built-in answers every GitHub @mention on every
+  repository the installation can reach, so --on github.mention is refused
+  (trigger_kind_builtin_only). Use github.issue.opened for repository events, or a
+  slack.mention trigger on a dedicated channel.
+- slack.mention needs --channel: the built-in answers in every channel the bot was invited
+  to, and a trigger takes dedicated channels of its own. A channel another ENABLED trigger
+  already holds is refused (trigger_conflict) — edit or delete that one first. Two
+  triggers on different channels may run on the same repository.
+
+A webhook trigger fires once per distinct delivery: two deliveries carrying identical
+bytes and no 'x-gateway-delivery-id' header are ONE event, however far apart they
+arrive. A trigger starts a real agent run, and with nothing to tell a retry from a new
+occurrence apart, the safe reading is a retry. To have a second delivery run again,
+send a fresh 'x-gateway-delivery-id' header, or put something distinguishing in the
+body such as a timestamp or a sequence number.
+
+The 'x-gateway-delivery-id' header is COVERED BY THE SIGNATURE: sign
+'v1:<delivery-id>:' followed by the raw body (empty id when you send no such
+header). An id the signature was not computed over is refused 401, so a captured
+body cannot be replayed under a fresh id by anyone who does not hold the secret.
+
+Idempotent: the same --key (or the same --name) retried with the SAME request
+returns the same trigger; a DIFFERENT request under it is refused (key_conflict /
+name_taken) — pick a new --key/--name rather than silently overwriting.
+
+AI Agent Directive:
+  --json returns { ok, data: Trigger }, next: ["mutagent gateway triggers test <id> --event @sample.json"].
+  Never pass --on github.mention: it is refused with code trigger_kind_builtin_only, and
+  error.fix lists the runnable alternatives. For slack.mention always pass --channel.
+      `).action(async (options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      if (options.on === undefined || options.on.trim() === "") {
+        throw new GatewayCliError("validation_error", "A trigger needs a kind.", [], 3, [`Re-run with --on <kind>, one of: ${TRIGGER_KINDS.join(" | ")} | emit:<kind>.`]);
+      }
+      assertCreatableKind(options.on);
+      const instruction = readInstruction(options);
+      const trigger = await createTrigger({
+        kind: options.on,
+        repository: options.repo,
+        instruction,
+        name: options.name,
+        key: options.key,
+        filter: buildFilter(options)
+      });
+      printGatewayOk(isJson, trigger, {
+        next: [`mutagent gateway triggers test ${trigger.id} --event @sample.json`],
+        human: () => {
+          console.log(chalk42.green(`✓ Created trigger ${trigger.id}`));
+          printTrigger(trigger);
+        }
+      });
+      return;
+    }, RESOURCE);
+  });
+}
+function registerShow2(triggers, gateway) {
+  triggers.command("show").description("Show one trigger").argument("<id>", "Trigger id").action(async (id) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const trigger = await getTrigger(id);
+      printGatewayOk(isJson, trigger, { human: () => {
+        printTrigger(trigger);
+      } });
+      return;
+    }, RESOURCE);
+  });
+}
+function registerEnableDisable(triggers, gateway) {
+  for (const verb of ["enable", "disable"]) {
+    triggers.command(verb).description(`${verb === "enable" ? "Enable" : "Disable"} a trigger`).argument("<id>", "Trigger id").addHelpText("after", `
+Built-in triggers refuse this (409 builtin_trigger_read_only).
+`).action(async (id) => {
+      const isJson = gatewayIsJson(gateway);
+      await runGatewayAction(isJson, undefined, async () => {
+        const trigger = await (verb === "enable" ? enableTrigger(id) : disableTrigger(id));
+        printGatewayOk(isJson, trigger, { human: () => {
+          printTrigger(trigger);
+        } });
+        return;
+      }, RESOURCE);
+    });
+  }
+}
+function registerDelete(triggers, gateway) {
+  triggers.command("delete").description("Delete a trigger").argument("<id>", "Trigger id").option("--yes", "Confirm — required, never prompted for").addHelpText("after", `
+Built-in triggers refuse this. Never prompts — pass --yes or exit 4.
+`).action(async (id, options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      if (options.yes !== true) {
+        throw new GatewayCliError("confirmation_required", `Deleting trigger ${id} requires confirmation.`, [`mutagent gateway triggers delete ${id} --yes`], 4);
+      }
+      await deleteTrigger(id);
+      printGatewayOk(isJson, { id, deleted: true }, { human: () => {
+        console.log(chalk42.green(`✓ Deleted trigger ${id}`));
+      } });
+      return;
+    }, RESOURCE);
+  });
+}
+function registerTest(triggers, gateway) {
+  triggers.command("test").description("Dry run: would a sample event match this trigger?").argument("<id>", "Trigger id").option("--event <file>", "REQUIRED — JSON sample event, as @file.json").addHelpText("after", `
+Examples:
+  ${chalk42.dim("$")} mutagent gateway triggers test trg_abc --event @sample.json
+
+sample.json: { "source": "github", "kind": "github.issues.opened", "repositoryId": "123" }
+Zero side effects — this never fires the trigger.
+
+AI Agent Directive:
+  --json returns { ok, data: { matches, wouldRun, checks: [{ check, passed, detail }] } }.
+      `).action(async (id, options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      if (!options.event?.startsWith("@")) {
+        throw new GatewayCliError("validation_error", "--event must be an @file.json reference", [], 3, ["Re-run with --event @sample.json — an @ reference to a JSON file."]);
+      }
+      let event;
+      try {
+        event = JSON.parse(readFileSync14(options.event.slice(1), "utf8"));
+      } catch {
+        throw new GatewayCliError("validation_error", `Could not read/parse ${options.event}`, [], 3);
+      }
+      const result = await testTrigger(id, event);
+      printGatewayOk(isJson, result, {
+        human: () => {
+          console.log(`matches: ${String(result.matches)}  wouldRun: ${String(result.wouldRun)}`);
+          for (const c of result.checks)
+            console.log(`  ${c.passed ? chalk42.green("✓") : chalk42.red("✗")} ${c.check}: ${c.detail}`);
+        }
+      });
+      return;
+    }, RESOURCE);
+  });
+}
+function registerGatewayTriggersCommands(gateway) {
+  const triggers = registerList2(gateway);
+  registerCreate(triggers, gateway);
+  registerShow2(triggers, gateway);
+  registerEnableDisable(triggers, gateway);
+  registerDelete(triggers, gateway);
+  registerTest(triggers, gateway);
+}
+
+// src/commands/gateway/routines.ts
+import { readFileSync as readFileSync15 } from "node:fs";
+import { Command as Command19 } from "commander";
+import chalk43 from "chalk";
+
+// src/lib/gateway-api-routines.ts
+var ROUTINE_EVERY_GRAMMAR = [
+  "every N minutes (N: 1,2,3,4,5,6,10,12,15,20,30)",
+  "every N hours (N: 1,2,3,4,6,8,12)",
+  "hourly",
+  "daily HH:MM",
+  "weekdays HH:MM",
+  "weekends HH:MM",
+  "mon,wed,fri HH:MM"
+];
+async function listRoutines() {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/routines${qs({ workspaceId })}`);
+}
+async function createRoutine(body) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest("/api/gateway/routines", { method: "POST", body: JSON.stringify({ workspaceId, ...body }) });
+}
+async function getRoutine(id) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/routines/${encodeURIComponent(id)}${qs({ workspaceId })}`);
+}
+async function setRoutinePaused(id, paused) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/routines/${encodeURIComponent(id)}/${paused ? "pause" : "resume"}`, {
+    method: "POST",
+    body: JSON.stringify({ workspaceId })
+  });
+}
+var pauseRoutine = (id) => setRoutinePaused(id, true);
+var resumeRoutine = (id) => setRoutinePaused(id, false);
+async function deleteRoutine(id) {
+  const { workspaceId } = await resolveGatewayConnection();
+  await gatewayRequest(`/api/gateway/routines/${encodeURIComponent(id)}${qs({ workspaceId })}`, { method: "DELETE" });
+}
+async function runRoutineNow(id, key) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/routines/${encodeURIComponent(id)}/run-now`, {
+    method: "POST",
+    body: JSON.stringify({ workspaceId, key })
+  });
+}
+
+// src/lib/gateway-run-wait.ts
+var TERMINAL_RUN_PHASES = new Set(["succeeded", "failed", "no-match"]);
+function withDisplayError(run) {
+  return { ...run, error: renderRunErrorForDisplay(run.error) };
+}
+function runWaitTimeout(eventId, phase) {
+  return new GatewayCliError("run_wait_timeout", `--wait stopped before the run settled: it is still ${phase}.`, [`mutagent gateway runs show ${eventId} --json`], 2, ["The run itself was not cancelled — it is still going. Nothing failed and nothing succeeded yet."]);
+}
+async function waitForRun(eventId) {
+  const { value: value2, settled } = await pollUntil(() => getEventRun(eventId), (r) => TERMINAL_RUN_PHASES.has(r.phase));
+  if (!settled)
+    throw runWaitTimeout(eventId, value2.phase);
+  return value2;
+}
+
+// src/commands/gateway/routines.ts
+var RESOURCE2 = "routines";
+function printRoutine(r) {
+  const mark = r.status === "active" ? chalk43.green("✓") : chalk43.yellow("⏸");
+  console.log(`  ${mark} ${r.id}  ${r.name}  ${chalk43.dim(`${r.schedule.cron} ${r.schedule.timezone}`)}  ${r.repository.name}`);
+  if (r.schedule.next.length > 0)
+    console.log(chalk43.dim(`      next: ${r.schedule.next.join(", ")}`));
+  if (r.pausedReason)
+    console.log(chalk43.yellow(`      paused: ${r.pausedReason.reason}`));
+}
+function registerList3(gateway) {
+  const routines = new Command19("routines").description("Schedule → agent run: create, list, show, pause, resume, run-now, delete");
+  gateway.addCommand(routines);
+  routines.description("List routines, with their next three fire times").addHelpText("after", `
+Examples:
+  ${chalk43.dim("$")} mutagent gateway routines --json
+
+AI Agent Directive:
+  --json returns { ok, data: { items: Routine[] } }. schedule.next is 3 ISO-8601 UTC
+  fire times — always present, computed from schedule.cron + schedule.timezone.
+      `).action(async () => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const { items } = await listRoutines();
+      printGatewayOk(isJson, { items }, {
+        human: () => {
+          if (items.length === 0) {
+            console.log(chalk43.gray("No routines."));
+            return;
+          }
+          for (const r of items)
+            printRoutine(r);
+        }
+      });
+      return;
+    }, RESOURCE2);
+  });
+  return routines;
+}
+function normalizeInstructionText2(text) {
+  return text.replace(/\r\n/g, `
+`).replace(/\r/g, `
+`);
+}
+function readInstruction2(options) {
+  if (options.instructionFile) {
+    let text;
+    try {
+      text = readFileSync15(options.instructionFile, "utf8");
+    } catch {
+      throw new GatewayCliError("validation_error", `Could not read --instruction-file: ${options.instructionFile}`, [], 3, ["Check the path — --instruction-file takes a readable file."]);
+    }
+    return normalizeInstructionText2(text);
+  }
+  if (options.instruction)
+    return normalizeInstructionText2(options.instruction);
+  throw new GatewayCliError("validation_error", 'Pass --instruction "…" or --instruction-file f.md', [], 3);
+}
+function registerCreate2(routines, gateway) {
+  routines.command("create").description("Create a routine").option("--every <schedule>", "Plain-language schedule — see --help for the grammar").option("--cron <expr>", "5-field cron expression (minute hour day-of-month month day-of-week)").option("--tz <IANA timezone>", "REQUIRED — e.g. Europe/Berlin").option("--repo <owner/name>", "REQUIRED — the repository the routine runs on").option("--instruction <text>", "The instruction Helix runs").option("--instruction-file <path>", "Read the instruction from a file").option("--name <name>", "Name (default: derived)").option("--key <key>", "Idempotency key").addHelpText("after", `
+Examples:
+  ${chalk43.dim("$")} mutagent gateway routines create --every "weekdays 09:00" --tz Europe/Berlin --repo owner/name --instruction "Check main's failing CI and open an issue for each new failure"
+  ${chalk43.dim("$")} mutagent gateway routines create --cron "0 9 * * 1-5" --tz America/New_York --repo owner/name --instruction "…"
+
+Exactly one of --every / --cron. --tz is REQUIRED — omitting it is refused locally,
+before any request:
+  mutagent gateway routines create --every "..." --repo owner/name --instruction "..."
+  ✗ timezone_required  [exit 3]  Fix: pass --tz <IANA zone>, e.g. --tz Europe/Berlin
+
+--every grammar:
+${ROUTINE_EVERY_GRAMMAR.map((g) => `  ${g}`).join(`
+`)}
+
+AI Agent Directive:
+  --json returns { ok, data: Routine }. Output always shows the normalized cron,
+  timezone and next three fire times — read data.schedule.
+      `).action(async (options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      if (options.tz === undefined || options.tz.trim() === "") {
+        throw new GatewayCliError("timezone_required", "A routine needs a timezone.", [], 3, ["Re-run the same command with --tz <IANA zone>, e.g. --tz Europe/Berlin."]);
+      }
+      if (options.repo === undefined || options.repo.trim() === "") {
+        throw new GatewayCliError("validation_error", "A routine needs a repository.", [], 3, ["Re-run the same command with --repo owner/name."]);
+      }
+      if (options.every === undefined === (options.cron === undefined)) {
+        throw new GatewayCliError("schedule_required", "Pass exactly one of --every or --cron.", [], 3, ['Re-run with exactly one of --every "weekdays 09:00" or --cron "0 9 * * 1-5".']);
+      }
+      const instruction = readInstruction2(options);
+      const routine = await createRoutine({
+        every: options.every,
+        cron: options.cron,
+        timezone: options.tz,
+        repository: options.repo,
+        instruction,
+        name: options.name,
+        key: options.key
+      });
+      printGatewayOk(isJson, routine, {
+        next: [`mutagent gateway routines run-now ${routine.id} --wait`],
+        human: () => {
+          console.log(chalk43.green(`✓ Created routine ${routine.id}`));
+          printRoutine(routine);
+        }
+      });
+      return;
+    }, RESOURCE2);
+  });
+}
+function registerShow3(routines, gateway) {
+  routines.command("show").argument("<id>", "Routine id").description("Show one routine").action(async (id) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const routine = await getRoutine(id);
+      printGatewayOk(isJson, routine, { human: () => {
+        printRoutine(routine);
+      } });
+      return;
+    }, RESOURCE2);
+  });
+}
+function registerPauseResume(routines, gateway) {
+  for (const verb of ["pause", "resume"]) {
+    routines.command(verb).argument("<id>", "Routine id").description(`${verb === "pause" ? "Pause" : "Resume"} a routine`).action(async (id) => {
+      const isJson = gatewayIsJson(gateway);
+      await runGatewayAction(isJson, undefined, async () => {
+        const routine = await (verb === "pause" ? pauseRoutine(id) : resumeRoutine(id));
+        printGatewayOk(isJson, routine, { human: () => {
+          printRoutine(routine);
+        } });
+        return;
+      }, RESOURCE2);
+    });
+  }
+}
+function registerDelete2(routines, gateway) {
+  routines.command("delete").argument("<id>", "Routine id").option("--yes", "Confirm — required, never prompted for").description("Delete a routine").action(async (id, options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      if (options.yes !== true) {
+        throw new GatewayCliError("confirmation_required", `Deleting routine ${id} requires confirmation.`, [`mutagent gateway routines delete ${id} --yes`], 4);
+      }
+      await deleteRoutine(id);
+      printGatewayOk(isJson, { id, deleted: true }, { human: () => {
+        console.log(chalk43.green(`✓ Deleted routine ${id}`));
+      } });
+      return;
+    }, RESOURCE2);
+  });
+}
+function registerRunNow(routines, gateway) {
+  routines.command("run-now").argument("<id>", "Routine id").option("--wait", "Poll until the run settles instead of returning the event id immediately").option("--key <key>", "Idempotency key (default: a fresh key each call — same key is the same run)").description("Run a routine once, right now").addHelpText("after", `
+Examples:
+  ${chalk43.dim("$")} mutagent gateway routines run-now rtn_abc --wait
+
+Idempotent per key: the same --key returns the SAME run, not a new one.
+
+AI Agent Directive:
+  --json without --wait: { ok, data: { eventId, created } }. created:false means this
+  key already ran — data.eventId is that run's event, not a new one.
+      `).action(async (id, options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const key = options.key ?? `cli-run-now-${id}-${String(Date.now())}`;
+      const result = await runRoutineNow(id, key);
+      if (options.wait !== true) {
+        printGatewayOk(isJson, result, {
+          next: [`mutagent gateway runs show ${result.eventId} --json`],
+          human: () => {
+            console.log(chalk43.dim(`event: ${result.eventId}${result.created ? "" : "  (existing run for this key)"}`));
+          }
+        });
+        return;
+      }
+      const run = await waitForRun(result.eventId);
+      if (run.phase === "failed") {
+        throw gatewayErrorFromRunError({ code: run.error?.code ?? "server_fault", reason: run.error?.reason ?? "The run failed.", fix: run.error?.fix }, { resource: RESOURCE2 });
+      }
+      const display = withDisplayError(run);
+      printGatewayOk(isJson, display, { human: () => {
+        console.log(`${display.eventId}  ${display.phase}`);
+      } });
+      return;
+    }, RESOURCE2);
+  });
+}
+function registerGatewayRoutinesCommands(gateway) {
+  const routines = registerList3(gateway);
+  registerCreate2(routines, gateway);
+  registerShow3(routines, gateway);
+  registerPauseResume(routines, gateway);
+  registerDelete2(routines, gateway);
+  registerRunNow(routines, gateway);
+}
+
+// src/commands/gateway/runs.ts
+import { randomUUID as randomUUID5 } from "node:crypto";
+import { readFileSync as readFileSync16 } from "node:fs";
+import { Command as Command20 } from "commander";
+import chalk44 from "chalk";
+
+// src/lib/gateway-api-runs.ts
+async function listRuns(opts) {
+  const { workspaceId, status, since, triggerId, routineId, cursor, limit } = opts;
+  return gatewayRequest(`/api/gateway/runs${qs({ workspaceId, status, since, triggerId, routineId, cursor, limit: limit === undefined ? undefined : String(limit) })}`);
+}
+async function getRun(runId, workspaceId) {
+  return gatewayRequest(`/api/gateway/runs/${encodeURIComponent(runId)}${qs({ workspaceId })}`);
+}
+async function getRunLogs(runId, workspaceId, after, limit) {
+  return gatewayRequest(`/api/gateway/runs/${encodeURIComponent(runId)}/logs${qs({
+    workspaceId,
+    after: after === undefined ? undefined : String(after),
+    limit: limit === undefined ? undefined : String(limit)
+  })}`);
+}
+
+// src/commands/gateway/runs.ts
+async function resolveRepositoryId(repoArg) {
+  if (repoArg !== undefined) {
+    const repo = await findRepositoryByName(repoArg);
+    if (repo === undefined) {
+      throw gatewayErrorFromCode("repository_not_found", `${repoArg} is not reachable through this workspace's GitHub installation.`);
+    }
+    return repo.id;
+  }
+  const current = await getDefaultRepository();
+  if (current.defaultRepository === null) {
+    throw gatewayErrorFromCode("no_default_repository", "No repository given and no workspace default repository set.");
+  }
+  return current.defaultRepository.repositoryId;
+}
+function printRunStatus(run) {
+  console.log(`${chalk44.bold(run.eventId)}  ${run.phase}`);
+  if (run.sandbox)
+    console.log(chalk44.dim(`  sandbox: ${run.sandbox.kind} (${run.sandbox.environment})`));
+  if (run.startedAt)
+    console.log(chalk44.dim(`  started: ${run.startedAt}`));
+  if (run.finishedAt)
+    console.log(chalk44.dim(`  finished: ${run.finishedAt}`));
+  if (run.error) {
+    console.log(chalk44.red(`  ${run.error.code}: ${run.error.reason}`));
+    for (const step of run.error.fix)
+      console.log(chalk44.yellow(`  Fix: ${step}`));
+  }
+}
+function registerTestRun(gateway) {
+  gateway.command("test-run").description("Run the built-in onboarding test agent on a repository").option("--repo <owner/name>", "Repository to run on (default: the workspace default repository)").option("--wait", "Poll until the run settles instead of returning the event id immediately").option("--key <key>", "Idempotency key — the same key is one run (default: a fresh key each call)").addHelpText("after", `
+Examples:
+  ${chalk44.dim("$")} mutagent gateway test-run --wait
+  ${chalk44.dim("$")} mutagent gateway test-run --repo owner/name --key onboarding-check-1
+
+Proves the whole pipeline runs: GitHub/Slack connection, repository access, and a
+Helix agent turn in a sandbox, latest default-branch commit.
+
+AI Agent Directive:
+  --json without --wait returns { ok, data: { eventId } } immediately — follow with
+  'mutagent gateway runs show <eventId> --json' or pass --wait to block until it settles.
+  With --wait: { ok, data: RunStatus }. ok is false and exit is non-zero when the run's
+  terminal phase is 'failed' — read data.error for the code and reason.
+      `).action(async (options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const repositoryId = await resolveRepositoryId(options.repo);
+      const key = options.key ?? `cli-test-run-${randomUUID5()}`;
+      const { eventId } = await startTestRun(key, repositoryId);
+      if (options.wait !== true) {
+        printGatewayOk(isJson, { eventId }, {
+          next: [`mutagent gateway runs show ${eventId} --json`],
+          human: () => {
+            console.log(chalk44.dim(`event: ${eventId}`));
+          }
+        });
+        return;
+      }
+      const run = await waitForRun(eventId);
+      if (run.phase === "failed") {
+        throw gatewayErrorFromRunError(run.error ?? { code: "server_fault", reason: "The test run failed.", fix: null });
+      }
+      const display = withDisplayError(run);
+      printGatewayOk(isJson, display, { human: () => {
+        printRunStatus(display);
+      } });
+      return;
+    });
+  });
+}
+function printRunSummary(r) {
+  console.log(`  ${r.id}  ${chalk44.dim(r.state)}  ${r.origin.kind}${r.origin.id ? `:${r.origin.id}` : ""}  ${r.repository?.name ?? ""}`);
+  if (r.error) {
+    console.log(chalk44.red(`    ${r.error.code}: ${r.error.reason}`));
+    for (const step of r.error.fix)
+      console.log(chalk44.yellow(`    Fix: ${step}`));
+  }
+}
+function registerRunsList(runs, gateway) {
+  runs.description("Runs from triggers, routines, the test run and emit — newest first").option("--status <s>", "Comma-separated states to filter to").option("--since <duration>", "ISO-8601 timestamp, or a duration like 30m / 24h / 7d").option("--trigger <id>", "Only runs launched by this trigger").option("--routine <id>", "Only runs launched by this routine").addHelpText("after", `
+Examples:
+  ${chalk44.dim("$")} mutagent gateway runs --since 24h --json
+  ${chalk44.dim("$")} mutagent gateway runs --status failed --json
+
+AI Agent Directive:
+  --json returns { ok, data: { items: RunSummary[] } }. state is one of queued |
+  allocating | checkout_ready | grant_ready | running | succeeded | failed |
+  cancelled | unknown.
+      `).action(async (options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const { workspaceId } = await resolveGatewayConnection();
+      const { items } = await listRuns({
+        workspaceId,
+        status: options.status,
+        since: options.since,
+        triggerId: options.trigger,
+        routineId: options.routine
+      });
+      const display = items.map(withDisplayError);
+      printGatewayOk(isJson, { items: display }, {
+        human: () => {
+          if (display.length === 0) {
+            console.log(chalk44.gray("No runs."));
+            return;
+          }
+          for (const r of display)
+            printRunSummary(r);
+        }
+      });
+      return;
+    });
+  });
+}
+function registerRunsShow(runs, gateway) {
+  runs.command("show").description("Run status — by event id or run id").argument("<id>", "The event id (from test-run/emit) or the run id (from runs list)").addHelpText("after", `
+Examples:
+  ${chalk44.dim("$")} mutagent gateway runs show evt_abc123 --json
+  ${chalk44.dim("$")} mutagent gateway runs show run_abc123 --json
+
+Tries the event-id route first ('GET events/:eventId/run', unchanged since test-run
+and emit have always used it); an id that route doesn't recognise (not_found) is
+retried as a run id ('GET runs/:runId'). An id neither route recognises reports the
+run-id lookup's not_found, since that is the more specific check.
+
+AI Agent Directive:
+  --json returns { ok, data }. An event-id hit has 'phase'; a run-id hit has 'state'
+  — branch on whichever key is present.
+      `).action(async (id) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      try {
+        const run2 = await getEventRun(id);
+        const display2 = withDisplayError(run2);
+        printGatewayOk(isJson, display2, { human: () => {
+          printRunStatus(display2);
+        } });
+        return;
+      } catch (error3) {
+        if (!(error3 instanceof GatewayApiError) || error3.code !== "not_found")
+          throw error3;
+      }
+      const { workspaceId } = await resolveGatewayConnection();
+      const run = await getRun(id, workspaceId);
+      const display = withDisplayError(run);
+      printGatewayOk(isJson, display, { human: () => {
+        printRunSummary(display);
+      } });
+      return;
+    });
+  });
+}
+function registerRunsLogs(runs, gateway) {
+  runs.command("logs").description("A run's logs, from its Helix session").argument("<runId>", "The run id (from runs list / runs show)").option("--follow", "Poll and print new entries until the run is done").addHelpText("after", `
+Examples:
+  ${chalk44.dim("$")} mutagent gateway runs logs run_abc123 --json
+  ${chalk44.dim("$")} mutagent gateway runs logs run_abc123 --follow
+
+--follow polls with 'after = nextAfter' until 'done'. archivedBefore, when non-null,
+names the seq below which entries were sealed into archived segments and are not
+served here — a stated gap, not a silent skip.
+
+AI Agent Directive:
+  --json (no --follow) returns ONE page: { ok, data: { items, nextAfter, done,
+  archivedBefore } }. --follow --json prints one such envelope per page until done.
+      `).action(async (runId, options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const { workspaceId } = await resolveGatewayConnection();
+      let after;
+      for (;; ) {
+        const page = await getRunLogs(runId, workspaceId, after);
+        printGatewayOk(isJson, page, {
+          human: () => {
+            for (const entry of page.items)
+              console.log(`${chalk44.dim(entry.at)}  ${entry.text}`);
+          }
+        });
+        if (options.follow !== true || page.done)
+          return;
+        after = page.nextAfter;
+        await new Promise((resolve9) => {
+          setTimeout(resolve9, Number(process.env.MUTAGENT_TEST_POLL_INTERVAL_MS ?? 2000));
+        });
+      }
+    });
+  });
+}
+function readPayloadFile(path) {
+  let text;
+  try {
+    text = readFileSync16(path, "utf8");
+  } catch {
+    throw new GatewayCliError("validation_error", `Could not read payload file: ${path}`, [], 3, ["--payload takes an @file.json reference to a readable file — check the path."]);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new GatewayCliError("validation_error", `Payload file is not valid JSON: ${path}`, [], 3);
+  }
+}
+function registerEmit(gateway) {
+  gateway.command("emit").description("Emit a user-defined event into the gateway").argument("<kind>", "Event kind — matched against emit:<kind> triggers").option("--key <key>", "Idempotency key (default: a fresh key each call)").option("--payload <file>", "JSON payload, as @file.json").option("--wait", "Poll every resulting run to a terminal phase before returning").addHelpText("after", `
+Examples:
+  ${chalk44.dim("$")} mutagent gateway emit deploy.finished --payload @payload.json --wait
+  ${chalk44.dim("$")} mutagent gateway emit heartbeat --key daily-2026-09-22
+
+--payload takes an '@' file reference, e.g. --payload @payload.json — never inline JSON
+(shells mangle quoting on long payloads).
+
+Some kinds are reserved for the platform's own use (routine.*, onboarding.*,
+trace.threshold, github.ci-failed) and are refused — use your own kind, or for a
+routine: mutagent gateway routines run-now <id>.
+
+AI Agent Directive:
+  --json returns { ok, data: { kind, eventIds } } (or the awaited RunStatus array with
+  --wait). No matching 'emit:<kind>' trigger is not an error: eventIds may be empty.
+      `).action(async (kind, options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const key = options.key ?? `cli-emit-${randomUUID5()}`;
+      const payload = options.payload?.startsWith("@") ? readPayloadFile(options.payload.slice(1)) : undefined;
+      const result = await emitEvent(key, kind, payload);
+      if (options.wait !== true || result.eventIds.length === 0) {
+        printGatewayOk(isJson, result, {
+          human: () => {
+            console.log(`${result.kind}  ${chalk44.dim(`${String(result.eventIds.length)} event(s)`)}`);
+            for (const id of result.eventIds)
+              console.log(`  ${id}`);
+          }
+        });
+        return;
+      }
+      const runs = [];
+      for (const eventId of result.eventIds) {
+        runs.push(await waitForRun(eventId));
+      }
+      const failed = runs.find((r) => r.phase === "failed");
+      if (failed) {
+        const failedIds = runs.filter((r) => r.phase === "failed").map((r) => r.eventId);
+        throw gatewayErrorFromRunError({
+          code: failed.error?.code ?? "server_fault",
+          reason: `${failed.error?.reason ?? "A run failed."} (${String(failedIds.length)}/${String(runs.length)} failed: ${failedIds.join(", ")})`,
+          fix: failed.error?.fix
+        });
+      }
+      const displayRuns = runs.map(withDisplayError);
+      printGatewayOk(isJson, { ...result, runs: displayRuns }, { human: () => {
+        for (const run of displayRuns)
+          printRunStatus(run);
+      } });
+      return;
+    });
+  });
+}
+function registerGatewayRunCommands(gateway) {
+  registerTestRun(gateway);
+  const runs = new Command20("runs");
+  gateway.addCommand(runs);
+  registerRunsList(runs, gateway);
+  registerRunsShow(runs, gateway);
+  registerRunsLogs(runs, gateway);
+  registerEmit(gateway);
+}
+
+// src/commands/gateway/admin.ts
+import { Command as Command21 } from "commander";
+import chalk45 from "chalk";
+
+// src/lib/gateway-admin.ts
+import { execFile } from "node:child_process";
+import { existsSync as existsSync13, readFileSync as readFileSync17 } from "node:fs";
+import { dirname as dirname7, join as join21 } from "node:path";
+var SERVER_PACKAGE_NAME = "@mutagent/server";
+function isServerDir(dir) {
+  const pkgPath = join21(dir, "package.json");
+  if (!existsSync13(pkgPath))
+    return false;
+  try {
+    const pkg = JSON.parse(readFileSync17(pkgPath, "utf8"));
+    return pkg.name === SERVER_PACKAGE_NAME;
+  } catch {
+    return false;
+  }
+}
+function resolveMutagentServerDir() {
+  const envDir = process.env.MUTAGENT_SERVER_DIR;
+  if (envDir !== undefined && envDir !== "" && isServerDir(envDir))
+    return envDir;
+  let dir = process.cwd();
+  for (let depth = 0;depth < 8; depth += 1) {
+    const candidate = join21(dir, "mutagent");
+    if (isServerDir(candidate))
+      return candidate;
+    const parent = dirname7(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return;
+}
+function requireMutagentServerDir() {
+  const dir = resolveMutagentServerDir();
+  if (dir === undefined) {
+    throw new GatewayCliError("server_checkout_not_found", "This command needs the mutagent/ server checkout (it wraps an operator script, not an HTTP route).", [], 3, [
+      "Run this from inside the mutagent-monorepo checkout — a directory with a mutagent/ sibling.",
+      "Or set MUTAGENT_SERVER_DIR=/path/to/mutagent and re-run."
+    ]);
+  }
+  return dir;
+}
+function runServerScript(script, args = []) {
+  const serverDir = requireMutagentServerDir();
+  return new Promise((resolve9) => {
+    execFile("bun", ["run", script, ...args], { cwd: serverDir, env: process.env, maxBuffer: 10 * 1024 * 1024 }, (error3, stdout, stderr) => {
+      const exitCode = error3 === null ? 0 : typeof error3.code === "number" ? error3.code : 1;
+      resolve9({ exitCode, stdout, stderr });
+    });
+  });
+}
+
+// src/lib/gateway-api-limits.ts
+var WORKSPACE_LIMIT_BOUNDS = {
+  concurrent: { min: 1, max: 1000 },
+  daily: { min: 1, max: 1e5 }
+};
+async function getWorkspaceLimits() {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest(`/api/gateway/limits${qs({ workspaceId })}`);
+}
+async function setWorkspaceLimits(body) {
+  const { workspaceId } = await resolveGatewayConnection();
+  return gatewayRequest("/api/gateway/limits", {
+    method: "PUT",
+    body: JSON.stringify({ workspaceId, ...body })
+  });
+}
+
+// src/commands/gateway/admin.ts
+init_known_secrets();
+function registerPreflight(admin, gateway) {
+  admin.command("preflight").description("End-to-end check: could this deployment serve a gateway delivery right now?").option("--workspace <id>", "Scope repository/channel/target checks to one workspace (default: the configured workspace)").addHelpText("after", `
+Examples:
+  ${chalk45.dim("$")} mutagent gateway admin preflight --json
+
+Wraps 'bun run gateway:preflight' in the mutagent/ server checkout. Operator-only —
+see 'mutagent gateway admin --help' for what that requires (checkout + DATABASE_URL).
+
+AI Agent Directive:
+  --json returns { ok, data: { verdict, checked, findings } }. ok is (verdict === 'PASS').
+  Each finding names the broken item and the fix in its own 'detail'.
+      `).action(async (options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const { loadConfig: loadConfig2 } = await Promise.resolve().then(() => (init_config(), exports_config));
+      const workspace = options.workspace ?? loadConfig2().defaultWorkspace;
+      const args = ["--json", ...workspace ? ["--workspace", workspace] : []];
+      const result = await runServerScript("gateway:preflight", args);
+      let report;
+      try {
+        report = JSON.parse(result.stdout);
+      } catch {
+        throw new GatewayCliError("server_fault", `gateway:preflight did not print JSON (exit ${String(result.exitCode)}): ${scrubKnownSuccess(result.stderr || result.stdout).slice(0, 500)}`, [], 1);
+      }
+      const ok = report.verdict === "PASS";
+      if (isJson) {
+        console.log(JSON.stringify({ ok, data: report }, null, 2));
+      } else {
+        console.log(`${ok ? chalk45.green("PASS") : chalk45.red("BLOCKED")}  ${chalk45.dim(`${String(report.checked.length)} checked`)}`);
+        for (const finding of report.findings)
+          console.log(`  ${chalk45.red("✗")} ${finding.item}: ${finding.detail}`);
+      }
+      return ok ? undefined : 3;
+    });
+  });
+}
+function registerSeedApps(admin, gateway) {
+  admin.command("seed-apps").description("Load a GitHub App's / Slack app's credentials from the environment").addHelpText("after", `
+Examples:
+  ${chalk45.dim("$")} mutagent gateway admin seed-apps --json
+
+Wraps 'bun run gateway:seed-apps' in the mutagent/ server checkout. Operator-only —
+see 'mutagent gateway admin --help'. Credentials come from the environment ONLY
+(GATEWAY_GITHUB_APP_*, GATEWAY_SLACK_APP_*, or mutagent/.env) and go straight to the
+database — never over the API, and never from a CLI argument, so nothing here can
+land a secret in shell history. Idempotent: a second run with the same input reports
+'unchanged'.
+
+AI Agent Directive:
+  --json returns { ok, data: { exitCode, output } }. ok is (exitCode === 0). The script
+  never prints a secret; 'output' is safe to show the user verbatim.
+      `).action(async () => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const result = await runServerScript("gateway:seed-apps");
+      const output = scrubKnownSuccess(`${result.stdout}${result.stderr}`.trim());
+      if (result.exitCode !== 0) {
+        throw new GatewayCliError("seed_apps_failed", output || `gateway:seed-apps exited ${String(result.exitCode)}`, [], result.exitCode === 2 ? 3 : 1, result.exitCode === 2 ? ["Set the missing GATEWAY_GITHUB_APP_* / GATEWAY_SLACK_APP_* environment variables, then re-run this command."] : []);
+      }
+      printGatewayOk(isJson, { exitCode: result.exitCode, output }, {
+        human: () => {
+          console.log(output);
+        }
+      });
+      return;
+    });
+  });
+}
+function registerLimits(admin, gateway) {
+  const limits = new Command21("limits").description("Show or set the workspace's run-concurrency and daily-run caps").addHelpText("after", `
+Examples:
+  ${chalk45.dim("$")} mutagent gateway admin limits --json
+  ${chalk45.dim("$")} mutagent gateway admin limits set --concurrent 5 --daily 100 --json
+
+Bare (or 'admin limits'): shows the current caps. 'set': changes them — admins only.
+
+AI Agent Directive:
+  --json returns { ok, data: { workspaceId, concurrent, daily, source, usedToday, day } }.
+  source is 'workspace' (an explicit override) or 'default' (the server-wide default,
+  not yet overridden for this workspace). day/usedToday reset at UTC midnight.
+      `);
+  admin.addCommand(limits);
+  limits.action(async () => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      const current = await getWorkspaceLimits();
+      printGatewayOk(isJson, current, {
+        human: () => {
+          console.log(`concurrent: ${String(current.concurrent)}   daily: ${String(current.daily)}   ${chalk45.dim(`(${current.source})`)}`);
+          console.log(chalk45.dim(`used today (${current.day}): ${String(current.usedToday)} / ${String(current.daily)}`));
+        }
+      });
+      return;
+    });
+  });
+  limits.command("set").description("Set the workspace's run-concurrency and/or daily-run caps").option("--concurrent <n>", `Runs in flight at once (${String(WORKSPACE_LIMIT_BOUNDS.concurrent.min)}–${String(WORKSPACE_LIMIT_BOUNDS.concurrent.max)})`).option("--daily <n>", `Runs started per UTC day (${String(WORKSPACE_LIMIT_BOUNDS.daily.min)}–${String(WORKSPACE_LIMIT_BOUNDS.daily.max)})`).addHelpText("after", `
+Examples:
+  ${chalk45.dim("$")} mutagent gateway admin limits set --concurrent 5 --daily 100
+
+Admins only (workspace admin, or org owner/admin) — anyone else is refused.
+Pass one or both of --concurrent / --daily; the other stays unchanged.
+
+AI Agent Directive:
+  --json returns { ok, data: WorkspaceLimits } — the shape 'admin limits' shows.
+  An out-of-range value fails locally (exit 3) before any request.
+      `).action(async (options) => {
+    const isJson = gatewayIsJson(gateway);
+    await runGatewayAction(isJson, undefined, async () => {
+      if (options.concurrent === undefined && options.daily === undefined) {
+        throw new GatewayCliError("validation_error", "Pass --concurrent and/or --daily.", ["mutagent gateway admin limits set --concurrent 5 --daily 100"], 3);
+      }
+      const body = {};
+      for (const [key, bounds] of Object.entries(WORKSPACE_LIMIT_BOUNDS)) {
+        const raw = key === "concurrent" ? options.concurrent : options.daily;
+        if (raw === undefined)
+          continue;
+        const value2 = Number(raw);
+        if (!Number.isInteger(value2) || value2 < bounds.min || value2 > bounds.max) {
+          throw new GatewayCliError("limit_out_of_range", `--${key} must be an integer between ${String(bounds.min)} and ${String(bounds.max)}, got: ${raw}`, [`mutagent gateway admin limits set --${key} <n>`], 3, [`--${key} must be between ${String(bounds.min)} and ${String(bounds.max)}.`]);
+        }
+        body[key] = value2;
+      }
+      const updated = await setWorkspaceLimits(body);
+      printGatewayOk(isJson, updated, {
+        human: () => {
+          console.log(chalk45.green(`✓ concurrent: ${String(updated.concurrent)}   daily: ${String(updated.daily)}`));
+        }
+      });
+      return;
+    });
+  });
+}
+function registerGatewayAdminCommands(gateway) {
+  const admin = new Command21("admin").description("Operator setup, and the workspace run-caps").addHelpText("after", `
+'preflight' and 'seed-apps' are OPERATOR commands: run them from a Mutagent server
+checkout (mutagent-monorepo's mutagent/) with DATABASE_URL set. Neither wraps an
+HTTP route; both shell out to the server's own scripts (bun run gateway:preflight /
+gateway:seed-apps). Environment variables pass through untouched and are never
+echoed.
+
+'limits' and 'limits set' are ordinary API calls — any workspace admin can run
+them from anywhere, no checkout needed.
+      `);
+  gateway.addCommand(admin);
+  registerPreflight(admin, gateway);
+  registerSeedApps(admin, gateway);
+  registerLimits(admin, gateway);
+}
+
+// src/commands/gateway/index.ts
+function createGatewayCommand() {
+  const gateway = new Command22("gateway").description("Connect GitHub/Slack, run and inspect the Helix gateway");
+  registerGatewayStatusCommands(gateway);
+  registerGatewayConnectCommands(gateway);
+  registerGatewayReposCommands(gateway);
+  registerGatewayTriggersCommands(gateway);
+  registerGatewayRoutinesCommands(gateway);
+  registerGatewayRunCommands(gateway);
+  registerGatewayAdminCommands(gateway);
+  gateway.addHelpText("after", `
+${chalk46.yellow("Start here:")}
+  mutagent gateway                        ${chalk46.dim("= status: connected, missing, next command")}
+  mutagent gateway status [--json]
+  mutagent gateway doctor                 ${chalk46.dim("End-to-end check, with fixes")}
+
+${chalk46.yellow("Configure:")}
+  mutagent gateway connect github|slack [--wait] [--open] [--attempt <id>]
+  mutagent gateway reconnect github|slack
+  mutagent gateway disconnect github|slack --yes
+  mutagent gateway repos [--available|--linked]
+  mutagent gateway repos default [owner/name]
+  mutagent gateway repos link owner/name…
+  mutagent gateway repos unlink owner/name --yes
+  mutagent gateway repos grant-more
+
+${chalk46.yellow("Configure — triggers (event → agent run):")}
+  mutagent gateway triggers
+  mutagent gateway triggers create --on <kind> [--repo owner/name] (--instruction "…" | --instruction-file f.md) [--name n]
+  mutagent gateway triggers show|enable|disable <id>
+  mutagent gateway triggers delete <id> --yes
+  mutagent gateway triggers test <id> --event @sample.json
+
+${chalk46.yellow("Configure — routines (schedule → agent run):")}
+  mutagent gateway routines
+  mutagent gateway routines create (--every "weekdays 09:00" | --cron "0 9 * * 1-5") --tz Europe/Berlin --repo owner/name (--instruction "…" | --instruction-file f.md) [--name n]
+  mutagent gateway routines show|pause|resume <id>
+  mutagent gateway routines run-now <id> [--wait]
+  mutagent gateway routines delete <id> --yes
+
+${chalk46.yellow("Operate:")}
+  mutagent gateway test-run [--repo owner/name] [--wait] [--key k]
+  mutagent gateway runs [--status s] [--since 24h] [--trigger id|--routine id]
+  mutagent gateway runs show <eventId|runId>
+  mutagent gateway runs logs <runId> [--follow]
+  mutagent gateway emit <kind> [--key k] [--payload @file] [--wait]
+
+${chalk46.yellow("Admin:")}
+  mutagent gateway admin preflight [--workspace id]
+  mutagent gateway admin seed-apps
+  mutagent gateway admin limits
+  mutagent gateway admin limits set --concurrent N --daily N
+
+${chalk46.yellow("The --json envelope (every command):")}
+  ${chalk46.bold("{ ok, data, next, error: { code, reason, fix, notes } }")}
+  Exit codes: 0 ok · 1 unexpected · 2 needs a person or browser · 3 fixable configuration · 4 refused.
+  'next' names the next command to run; 'error.fix' names the command(s) that resolve a failure.
+  Every 'fix' entry is a command line, never prose — but a command line may carry a
+     <placeholder> you must replace with a real value first, such as the <workspace-id>
+     in 'mutagent config set workspace <workspace-id>'. Replace every <...> before
+     running; a line with none runs as it stands. The same holds for 'next'.
+  'error.notes' is prose — what you need to know, never something to execute — and is
+     absent when there is none. A failure no command can resolve has 'fix: []' and
+     explains itself in 'notes'.
+
+${chalk46.yellow("AI Agent Directive:")}
+  1. Run 'mutagent gateway --json' first, every time, and run what 'next' says.
+  2. Exit 2 means a person or browser is needed. On 'connect', open 'data.signInUrl'
+     first and sign in, then open 'data.url' in that SAME browser — the callback only
+     completes in a browser signed in to Mutagent as you.
+  3. Never retry a failed command blind — read 'error.fix', replace any <placeholder>
+     in it with the real value, and run that. If 'error.fix' is empty, read
+     'error.notes': no command resolves it, so act on what it says instead of retrying.
+  4. Destructive commands (disconnect, repos unlink, triggers/routines delete) need
+     --yes; this CLI never prompts.
+  5. Routines REQUIRE --tz — a missing one is refused locally before any request.
+${!hasCredentials() ? `
+` + chalk46.yellow("  Warning: Not authenticated. Run: mutagent login --browser") + `
+` : ""}`);
+  return gateway;
+}
+
+// src/bin/cli.ts
+init_config();
+init_organization_scope();
+
+// src/lib/brand.ts
+var BRAND = {
+  name: "MUTAGENT",
+  primary: "#7E47D7",
+  accent: "#45b8cc",
+  gradientFrom: "#45b8cc",
+  gradientTo: "#7E47D7"
+};
+var WORDMARK = [
+  " ███╗   ███╗ ██╗   ██╗ ████████╗  █████╗   ██████╗  ███████╗ ███╗   ██╗ ████████╗  ",
+  " ████╗ ████║ ██║   ██║ ╚══██╔══╝ ██╔══██╗ ██╔════╝  ██╔════╝ ████╗  ██║ ╚══██╔══╝  ",
+  " ██╔████╔██║ ██║   ██║    ██║    ███████║ ██║  ███╗ █████╗   ██╔██╗ ██║    ██║     ",
+  " ██║╚██╔╝██║ ██║   ██║    ██║    ██╔══██║ ██║   ██║ ██╔══╝   ██║╚██╗██║    ██║     ",
+  " ██║ ╚═╝ ██║ ╚██████╔╝    ██║    ██║  ██║ ╚██████╔╝ ███████╗ ██║ ╚████║    ██║     ",
+  " ╚═╝     ╚═╝  ╚═════╝     ╚═╝    ╚═╝  ╚═╝  ╚═════╝  ╚══════╝ ╚═╝  ╚═══╝    ╚═╝     "
+];
+var WORDMARK_MIN_COLUMNS = 84;
+function hexToRgb(hex) {
+  const n = parseInt(hex.slice(1), 16);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+var lerp = (a, b, t) => Math.round(a + (b - a) * t);
+function mix(from, to, t) {
+  return [lerp(from[0], to[0], t), lerp(from[1], to[1], t), lerp(from[2], to[2], t)];
+}
+var ansi = (r, g, b) => `\x1B[38;2;${String(r)};${String(g)};${String(b)}m`;
+var RESET = "\x1B[0m";
+function gradientLine(line, from, to) {
+  const chars = Array.from(line);
+  const n = chars.length;
+  let out = "";
+  chars.forEach((ch, i) => {
+    if (ch === " ") {
+      out += ch;
+      return;
+    }
+    const [r, g, b] = mix(from, to, n > 1 ? i / (n - 1) : 0);
+    out += ansi(r, g, b) + ch;
+  });
+  return out + RESET;
+}
+function hasTruecolor(env = process.env) {
+  return /truecolor|24bit/i.test(env.COLORTERM ?? "");
+}
+function detectBannerEnv(stream = process.stdout, env = process.env) {
+  return {
+    isTTY: stream.isTTY === true,
+    columns: stream.columns ?? 80,
+    truecolor: hasTruecolor(env),
+    disabled: env.MUTAGENT_NO_BANNER === "1"
+  };
+}
+function renderBanner(env = detectBannerEnv()) {
+  if (env.disabled || !env.isTTY)
+    return "";
+  const from = hexToRgb(BRAND.gradientFrom);
+  const to = hexToRgb(BRAND.gradientTo);
+  const wide = env.columns >= WORDMARK_MIN_COLUMNS;
+  const art = wide ? WORDMARK : [`  ${BRAND.name}`];
+  const lines = env.truecolor ? art.map((l) => gradientLine(l, from, to)) : art.map((l) => `${ansi(...from)}${l}${RESET}`);
+  return `
+${lines.join(`
+`)}
+`;
+}
+
+// src/lib/global-version-flag.ts
+var GLOBAL_VALUE_OPTIONS = new Set(["--api-key", "--endpoint", "--workspace", "--org"]);
+function findSubcommandIndex(rawArgs) {
+  for (let i = 0;i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === undefined)
+      continue;
+    if (arg === "--")
+      return i + 1 < rawArgs.length ? i + 1 : -1;
+    if (arg.startsWith("-")) {
+      if (GLOBAL_VALUE_OPTIONS.has(arg))
+        i++;
+      continue;
+    }
+    return i;
+  }
+  return -1;
+}
+function isGlobalVersionFlag(rawArgs) {
+  const versionAt = rawArgs.findIndex((a) => a === "-v" || a === "--version");
+  if (versionAt === -1)
+    return false;
+  const subcommandAt = findSubcommandIndex(rawArgs);
+  return subcommandAt === -1 || versionAt < subcommandAt;
+}
+var ROOT_BOOLEAN_OPTIONS = new Set(["--json", "--non-interactive"]);
+function commandPathIndexes(rawArgs, depth) {
+  const indexes = [];
+  let from = 0;
+  while (indexes.length < depth) {
+    const at = findSubcommandIndex(rawArgs.slice(from));
+    if (at === -1)
+      break;
+    indexes.push(from + at);
+    from += at + 1;
+  }
+  return indexes;
+}
+
+// src/bin/cli.ts
+init_errors();
+
+// src/commands/helix/api-key-guard.ts
+init_errors();
+var FORWARDING_VERBS = [
+  { path: ["helix"], label: "mutagent helix" },
+  { path: ["sandbox", "exec"], label: "mutagent sandbox exec" }
+];
+function rootValueOption(arg) {
+  const eq = arg.indexOf("=");
+  const name = eq === -1 ? arg : arg.slice(0, eq);
+  return GLOBAL_VALUE_OPTIONS.has(name) ? name : undefined;
+}
+function commanderBindable(tokens) {
+  const bindable = [];
+  for (let i = 0;i < tokens.length; i++) {
+    const token = tokens[i] ?? "";
+    if (token === "--")
+      break;
+    bindable.push(token);
+    if (GLOBAL_VALUE_OPTIONS.has(token) && i + 1 < tokens.length) {
+      bindable.push(tokens[i + 1] ?? "");
+      i++;
+    }
+  }
+  return bindable;
+}
+function forwardedRootOptionRefusal(rawArgs) {
+  for (const verb of FORWARDING_VERBS) {
+    const at = commandPathIndexes(rawArgs, verb.path.length);
+    if (at.length !== verb.path.length || at.some((index, k) => rawArgs[index] !== verb.path[k]))
+      continue;
+    const after = rawArgs.slice((at[at.length - 1] ?? -1) + 1);
+    const bindable = commanderBindable(after);
+    const isHelix = verb.path[0] === "helix";
+    const keyScope = isHelix ? after : bindable;
+    if (keyScope.some((arg) => rootValueOption(arg) === "--api-key")) {
+      return isHelix ? helixKeyRefusal() : sandboxExecKeyRefusal();
+    }
+    const other = bindable.map(rootValueOption).find((option) => option !== undefined);
+    if (other !== undefined)
+      return rootValueOptionRefusal(other, verb.label);
+    return;
+  }
+  return;
+}
+function keyAlternative() {
   return transportFor("--api-key")?.alternative ?? "";
 }
 function helixKeyRefusal() {
@@ -29125,6 +31418,34 @@ function rootValueOptionRefusal(option, label) {
   return new MutagentError("NOT_SUPPORTED", `${option} after '${label}' and before a -- is refused: the mutagent CLI would read it as ${what}, and the command it forwards would never see it.`, `For the mutagent CLI, put it before the command (mutagent ${option} <value> ${command} …)${env}.
 For the forwarded command, put it after --: ${label} … -- … ${option} <value>.`, 2);
 }
+
+// src/commands/providers/api-key-scope.ts
+var API_KEY_FLAG = "--api-key";
+var API_KEY_FLAG_EQUALS = `${API_KEY_FLAG}=`;
+var RESCOPED_COMMAND_PATHS = [
+  ["providers", "add"],
+  ["providers", "update"]
+];
+function rescopeProviderApiKeyFlag(rawArgs) {
+  for (const path of RESCOPED_COMMAND_PATHS) {
+    const at = commandPathIndexes(rawArgs, path.length);
+    if (at.length !== path.length)
+      continue;
+    if (at.some((index, i) => rawArgs[index] !== path[i]))
+      continue;
+    const spanStart = (at[at.length - 1] ?? -1) + 1;
+    const before = rawArgs.slice(0, spanStart);
+    const span = rawArgs.slice(spanStart).map((token) => {
+      if (token === API_KEY_FLAG)
+        return "-k";
+      if (token.startsWith(API_KEY_FLAG_EQUALS))
+        return `-k${token.slice(API_KEY_FLAG_EQUALS.length)}`;
+      return token;
+    });
+    return [...before, ...span];
+  }
+  return [...rawArgs];
+}
 // src/commands/helix/helix-surface.json
 var helix_surface_default = {
   helixVersion: "0.0.33-m0",
@@ -29502,14 +31823,14 @@ if (process.env.CLI_VERSION) {
   cliVersion = process.env.CLI_VERSION;
 } else {
   try {
-    const __dirname2 = dirname7(fileURLToPath4(import.meta.url));
-    const pkgPath = join21(__dirname2, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync14(pkgPath, "utf-8"));
+    const __dirname2 = dirname8(fileURLToPath4(import.meta.url));
+    const pkgPath = join22(__dirname2, "..", "..", "package.json");
+    const pkg = JSON.parse(readFileSync18(pkgPath, "utf-8"));
     cliVersion = pkg.version ?? cliVersion;
   } catch {}
 }
 setCliVersion(cliVersion);
-var program = new Command18;
+var program = new Command23;
 program.name("mutagent").description(`Mutagent CLI - command-line client for the Mutagent platform
 
   Documentation: https://docs.mutagent.io/cli
@@ -29519,50 +31840,50 @@ program.name("mutagent").description(`Mutagent CLI - command-line client for the
 });
 program.addHelpText("beforeAll", () => renderBanner());
 program.addHelpText("after", `
-${chalk38.yellow("Get started:")}
-  mutagent login                          ${chalk38.dim("Sign in (browser or API key)")}
-  mutagent providers mirror               ${chalk38.dim("Copy local Helix LLM provider keys into the workspace")}
-  mutagent helix -p "<task>"              ${chalk38.dim("Run Helix in the cloud")}
-  mutagent install helix                  ${chalk38.dim("Install the standalone Helix binary on this machine")}
-
-${chalk38.yellow("Managed agents:")}
-  mutagent agent deploy <agent.md>        ${chalk38.dim("Check, upload and activate an agent.md folder (--env names the slot)")}
-  mutagent helix agent @<slug> -p "<task>" ${chalk38.dim("Run a managed agent in the cloud")}
-  mutagent agent --help                   ${chalk38.dim("check, pack, run, deploy, activate, list, inspect, retire")}
-
-${chalk38.yellow("Workspace:")}
-  mutagent workspaces use <name>          ${chalk38.dim("Choose the workspace every later command works in")}
-  mutagent workspaces current             ${chalk38.dim("The key's scope, organization and the verified workspace")}
-  mutagent workspaces list                ${chalk38.dim("Your workspaces in the key's organization")}
-  --workspace <name|id>                   ${chalk38.dim("One command in another workspace (then MUTAGENT_WORKSPACE_ID, then the selection)")}
-  mutagent login --org <slug>             ${chalk38.dim("Sign in for another organization")}
-  mutagent providers list                 ${chalk38.dim("LLM providers in the workspace")}
-  mutagent helix models                   ${chalk38.dim("Models Helix can use in the cloud, and the workspace default model")}
-  mutagent env ls                         ${chalk38.dim("Environments: variables and secrets for tools")}
-  mutagent usage                          ${chalk38.dim("Count the workspace's LLM providers and your workspaces")}
-
-${chalk38.yellow("Automation:")}
-  MUTAGENT_API_KEY=mt_...                 ${chalk38.dim("Sign in without a browser (or --api-key <key>)")}
-  --json                                  ${chalk38.dim("Structured output")}
-  --non-interactive                       ${chalk38.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                           ${chalk38.dim("CLI version (only before a subcommand)")}
-
-${chalk38.yellow("Report a problem:")}
+${chalk47.yellow("Get started:")}
+  mutagent login                          ${chalk47.dim("Sign in (browser or API key)")}
+  mutagent providers mirror               ${chalk47.dim("Copy local Helix LLM provider keys into the workspace")}
+  mutagent helix -p "<task>"              ${chalk47.dim("Run Helix in the cloud")}
+  mutagent install helix                  ${chalk47.dim("Install the standalone Helix binary on this machine")}
+
+${chalk47.yellow("Managed agents:")}
+  mutagent agent deploy <agent.md>        ${chalk47.dim("Check, upload and activate an agent.md folder (--env names the slot)")}
+  mutagent helix agent @<slug> -p "<task>" ${chalk47.dim("Run a managed agent in the cloud")}
+  mutagent agent --help                   ${chalk47.dim("check, pack, run, deploy, activate, list, inspect, retire")}
+
+${chalk47.yellow("Workspace:")}
+  mutagent workspaces use <name>          ${chalk47.dim("Choose the workspace every later command works in")}
+  mutagent workspaces current             ${chalk47.dim("The key's scope, organization and the verified workspace")}
+  mutagent workspaces list                ${chalk47.dim("Your workspaces in the key's organization")}
+  --workspace <name|id>                   ${chalk47.dim("One command in another workspace (then MUTAGENT_WORKSPACE_ID, then the selection)")}
+  mutagent login --org <slug>             ${chalk47.dim("Sign in for another organization")}
+  mutagent providers list                 ${chalk47.dim("LLM providers in the workspace")}
+  mutagent helix models                   ${chalk47.dim("Models Helix can use in the cloud, and the workspace default model")}
+  mutagent env ls                         ${chalk47.dim("Environments: variables and secrets for tools")}
+  mutagent usage                          ${chalk47.dim("Count the workspace's LLM providers and your workspaces")}
+
+${chalk47.yellow("Automation:")}
+  MUTAGENT_API_KEY=mt_...                 ${chalk47.dim("Sign in without a browser (or --api-key <key>)")}
+  --json                                  ${chalk47.dim("Structured output")}
+  --non-interactive                       ${chalk47.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                           ${chalk47.dim("CLI version (only before a subcommand)")}
+
+${chalk47.yellow("Report a problem:")}
   mutagent feedback send "<what happened>" --category cli
-  ${chalk38.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
+  ${chalk47.dim("--category accepts: cli | helix | stage:<spec|build|evaluate|diagnose|optimize>")}
 
-${chalk38.dim("For CLI usage guidance for AI agents, see the Skill at")}
-${chalk38.cyan(".claude/skills/mutagent-cli/SKILL.md")}
+${chalk47.dim("For CLI usage guidance for AI agents, see the Skill at")}
+${chalk47.cyan(".claude/skills/mutagent-cli/SKILL.md")}
 
-${chalk38.yellow("Directive System:")}
+${chalk47.yellow("Directive System:")}
   A --json response may include:
-  ${chalk38.bold("_directive.renderedCard")}  A status card: copy it into your chat reply verbatim before running another command
-  ${chalk38.bold("_directive.instruction")}   What to do next
-  ${chalk38.bold("_directive.next")}          Suggested follow-up commands
-  ${chalk38.bold("_links")}                   Dashboard and API URLs
-  ${chalk38.bold("_compat")}                  cliVersion, skillVersion, skillMinCliVersion
+  ${chalk47.bold("_directive.renderedCard")}  A status card: copy it into your chat reply verbatim before running another command
+  ${chalk47.bold("_directive.instruction")}   What to do next
+  ${chalk47.bold("_directive.next")}          Suggested follow-up commands
+  ${chalk47.bold("_links")}                   Dashboard and API URLs
+  ${chalk47.bold("_compat")}                  cliVersion, skillVersion, skillMinCliVersion
 
-${chalk38.yellow("AI Agent Rules (MANDATORY for coding agents):")}
+${chalk47.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.
@@ -29573,11 +31894,11 @@ ${chalk38.yellow("AI Agent Rules (MANDATORY for coding agents):")}
   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() ? `
-` + chalk38.yellow("  Warning: Not authenticated. Run: mutagent login") + `
+` + chalk47.yellow("  Warning: Not authenticated. Run: mutagent login") + `
 ` : ""}${!hasRcConfig() ? `
-` + chalk38.green("  Get started: mutagent init") + `
+` + chalk47.green("  Get started: mutagent init") + `
 ` : ""}`);
-var rawArgs = process.argv.slice(2);
+var rawArgs = rescopeProviderApiKeyFlag(process.argv.slice(2));
 if (isGlobalVersionFlag(rawArgs)) {
   if (rawArgs.includes("--json")) {
     console.log(JSON.stringify({
@@ -29629,6 +31950,7 @@ program.addCommand(createHooksCommand());
 program.addCommand(createInstallCommand());
 program.addCommand(createSandboxCommand());
 program.addCommand(createEnvCommand());
+program.addCommand(createGatewayCommand());
 program.addCommand(createHelixCommand());
 program.addCommand(createFeedbackCommand());
 program.addCommand(createTraceCommand());
@@ -29656,4 +31978,4 @@ if (isAgentInvocation(rawArgs)) {
   program.parse(argvForCommander, { from: "user" });
 }
 
-//# debugId=E046D4F47E19C00364756E2164756E21
+//# debugId=208B56617BAAF0E964756E2164756E21