@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/cli-deploy.ts

@@ -1,2519 +0,0 @@
-/**
- * `agent-sdk deploy | deployments | deployment | stop | rollback | delete | rotate-token |
- * secrets set|list|unset` — Heroku-style deploys
- * onto Cursor's managed agent-serve hosting.
- *
- * All intelligence is server-side (backend/server/src/agentServe/); these
- * handlers resolve parameters (credentials, team, slug, the project's
- * `hosting` / `architecture` manifest block), call the v1 agent-serve or
- * v2 agentsdk management API through `deploy-client.ts`, poll status, and
- * render.
- */
-
-import { basename, resolve } from "node:path";
-import { catchAuthDeclaration, isPublicEndpointPolicy } from "../channels.js";
-import {
-  type AgentArchitecture,
-  type AgentHostingOptions,
-  isCursorAccountTransport,
-} from "../types.js";
-import { CursorBackendClient } from "./cursor/backend-client.js";
-import { cursorExternalApiUrl, resolveApiKey, SIGN_IN_HINT } from "./cursor/credentials.js";
-import { authorizeCursorAccountConnectors } from "./cursor-account-mcp-auth.js";
-import { readDeployTemplate } from "./cursor-agent-template.js";
-import {
-  type AgentkitCancelRunsResult,
-  type AgentkitDeployAccepted,
-  type AgentkitDeployComponent,
-  type AgentkitDeploymentListItem,
-  type AgentkitDeployStatus,
-  type AgentkitStopAccepted,
-  AgentServeDeployClient,
-  type DeleteAccepted,
-  type DeployAccepted,
-  DeployApiError,
-  type Deployment,
-  type DeploymentDetail,
-  type DeploymentProgress,
-  type DeploySource,
-  deploymentServiceAccountId,
-  type SecretInfo,
-  type StopAccepted,
-  slugFromDirectoryName,
-  TERMINAL_AGENTKIT_DEPLOY_STATUSES,
-  TERMINAL_DEPLOY_STATUSES,
-  validateDeploymentSlug,
-} from "./deploy-client.js";
-import { type GitRunner, inferDeployGitSource } from "./deploy-source.js";
-import { describeError } from "./describe-error.js";
-import {
-  type ChildAgentDir,
-  formatDiagnostics,
-  hasErrorDiagnostics,
-  isAgentProjectDir,
-  listChildAgentDirs,
-  loadAgentProject,
-} from "./discovery.js";
-import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
-import {
-  isReservedSecretName,
-  isValidCursorEventRepo,
-  validateSettableSecretName,
-} from "./hosting.js";
-import { deploymentArchitecture, rejectV2ForLegacyCommand } from "./legacy-command-guard.js";
-import { deployProgressLabel, sanitizeCustomerError } from "./logs-client.js";
-import { sleep } from "./sleep.js";
-import { stderrPalette } from "./terminal-style.js";
-
-const DEFAULT_POLL_INTERVAL_MS = 3_000;
-const DEFAULT_DEPLOY_TIMEOUT_MS = 10 * 60 * 1000;
-/** `--multi-tenant` HTTP deploy is Anysphere-only (team id 1). */
-const MULTI_TENANT_HTTP_DEPLOY_TEAM_ID = 1;
-
-/** One agent directory selected for deploy (single or multi-agent parent). */
-export type DeployTarget = ChildAgentDir;
-
-/**
- * Interactive / test seam: pick which agents under a multi-agent parent to
- * deploy. Return `null` to cancel.
- */
-export type ChooseDeployTargets = (
-  agents: readonly DeployTarget[],
-) => Promise<DeployTarget[] | null>;
-
-export interface DeployCliOptions {
-  dir?: string;
-  slug?: string;
-  /**
-   * deploy `--all`: when `--dir` is a multi-agent parent, deploy every
-   * child agent (skips the interactive picker).
-   */
-  all?: boolean;
-  /** `--team <id>`; resolved from the account when omitted. */
-  team?: string;
-  json?: boolean;
-  noWait?: boolean;
-  /** v2 stop: also request cancellation for every active session run. */
-  cancelRuns?: boolean;
-  apiKey?: string;
-  /**
-   * deploy `--repo <url>`: https git repo the control plane builds from.
-   * Optional — inferred from `git remote origin` when omitted inside an
-   * agent project checkout.
-   */
-  repo?: string;
-  /**
-   * deploy `--ref <ref>`: git ref to build. Optional — inferred from the
-   * current branch (or HEAD SHA if detached) when omitted; otherwise the
-   * server uses the repo's default branch.
-   */
-  ref?: string;
-  /**
-   * deploy `--path <agentPath>`: agent directory relative to the repo root.
-   * Optional — inferred from `--dir` vs the git toplevel when omitted.
-   */
-  path?: string;
-  /** deploy `--cursor-events-repo <owner/name>` (repeatable). */
-  cursorEventsRepos?: string[];
-  /** deploy `--allow-domain <domain>` (repeatable; unioned with the manifest). */
-  allowDomains?: string[];
-  /**
-   * deploy `--multi-tenant`: add a release to an existing Cursor-managed
-   * (multi-tenant) product. Hidden Anysphere-only flag. Cannot create a
-   * new multi-tenant application.
-   */
-  multiTenant?: boolean;
-  /** Test seams. */
-  fetchImpl?: typeof fetch;
-  /** Inject the connector-auth browser opener (tests; also forces interactive). */
-  openBrowserImpl?: (url: string) => void;
-  sleepImpl?: (ms: number) => Promise<void>;
-  connectorPollIntervalMs?: number;
-  connectorPollTimeoutMs?: number;
-  /** Inject git probing for deploy source inference (tests). */
-  git?: GitRunner;
-  /** Inject the multi-agent picker (tests / non-interactive hosts). */
-  chooseTargets?: ChooseDeployTargets;
-  pollIntervalMs?: number;
-  timeoutMs?: number;
-  out?: (text: string) => void;
-  err?: (text: string) => void;
-  /** `secrets set` value input (hidden prompt on a TTY, lines otherwise). */
-  stdin?: SecretInputStream;
-  /**
-   * Opt in to `NAME=VALUE` argv secrets. Default is names only (hidden
-   * prompt / stdin) so values never land in shell history or agent-captured
-   * terminals.
-   */
-  fromArgv?: boolean;
-}
-
-/** Minimal stdin surface `secrets set` reads values from (test-injectable). */
-export type SecretInputStream = NodeJS.ReadableStream & {
-  isTTY?: boolean;
-  setRawMode?: (mode: boolean) => void;
-};
-
-export interface DeployCliContext {
-  client: AgentServeDeployClient;
-  teamId: number;
-  apiKey: string;
-  backendUrl: string;
-  json: boolean;
-  noWait: boolean;
-  pollIntervalMs: number;
-  timeoutMs: number;
-  out: (text: string) => void;
-  err: (text: string) => void;
-}
-
-export interface ResolveDeployAuthOptions {
-  team?: string;
-  apiKey?: string;
-  fetchImpl?: typeof fetch;
-  /** Quiet team-resolution chatter (default: write to stderr). */
-  err?: (text: string) => void;
-}
-
-export interface ResolvedDeployAuth {
-  client: AgentServeDeployClient;
-  teamId: number;
-  /** The resolved account credential, for dashboard RPCs beside the deploy API. */
-  apiKey: string;
-  backendUrl: string;
-}
-
-/**
- * Credentials → deploy client → team id. Shared by deploy commands and
- * `--prod` AX routing. Returns an exit code (error already rendered) on
- * failure.
- */
-export async function resolveDeployAuth(
-  options: ResolveDeployAuthOptions,
-): Promise<ResolvedDeployAuth | number> {
-  const err = options.err ?? ((text: string) => void process.stderr.write(text));
-
-  const resolved = await resolveApiKey(
-    options.apiKey === undefined ? undefined : { apiKey: options.apiKey },
-  );
-  if (resolved === undefined) {
-    err(`Not signed in to Cursor. ${SIGN_IN_HINT}\n`);
-    return 1;
-  }
-  // The deployment management routes live on the external API host
-  // (api.cursor.com), not the default backend (api2.cursor.sh) — see
-  // cursorExternalApiUrl. GetMe below stays on the resolved backend.
-  const client = new AgentServeDeployClient({
-    backendUrl: cursorExternalApiUrl(),
-    apiKey: resolved.apiKey,
-    fetchImpl: options.fetchImpl,
-  });
-
-  let teamId: number;
-  if (options.team !== undefined) {
-    teamId = Number.parseInt(options.team, 10);
-    if (Number.isNaN(teamId) || teamId <= 0) {
-      err(`Invalid --team: ${options.team} (expected a positive team id)\n`);
-      return 1;
-    }
-  } else {
-    const account = new CursorBackendClient({
-      backendUrl: resolved.backendUrl,
-      apiKey: resolved.apiKey,
-      fetchImpl: options.fetchImpl,
-    });
-    let identity: Awaited<ReturnType<CursorBackendClient["getMe"]>>;
-    try {
-      identity = await account.getMe();
-    } catch (error) {
-      err(
-        `Could not resolve your team from the Cursor account: ${describeError(error)}\nPass --team <id> explicitly.\n`,
-      );
-      return 1;
-    }
-    if (identity.teamId === undefined || identity.teamId <= 0) {
-      err(
-        "This Cursor account has no default team; pass --team <id> (find it in the Cursor dashboard URL).\n",
-      );
-      return 1;
-    }
-    teamId = identity.teamId;
-    const dim = stderrPalette().dim;
-    err(
-      `${dim(
-        `Using team ${teamId}${identity.teamName === undefined ? "" : ` (${identity.teamName})`}`,
-      )}\n${dim("  the account's team — pass --team to override.")}\n`,
-    );
-  }
-
-  return {
-    client,
-    teamId,
-    apiKey: resolved.apiKey,
-    backendUrl: resolved.backendUrl,
-  };
-}
-
-/**
- * Shared preamble: credentials → client → team id. Returns an exit code
- * (with the error already rendered) when resolution fails.
- */
-export async function prepare(options: DeployCliOptions): Promise<DeployCliContext | number> {
-  const out = options.out ?? ((text: string) => void process.stdout.write(text));
-  const err = options.err ?? ((text: string) => void process.stderr.write(text));
-
-  const auth = await resolveDeployAuth({
-    team: options.team,
-    apiKey: options.apiKey,
-    fetchImpl: options.fetchImpl,
-    err,
-  });
-  if (typeof auth === "number") {
-    return auth;
-  }
-
-  return {
-    client: auth.client,
-    teamId: auth.teamId,
-    apiKey: auth.apiKey,
-    backendUrl: auth.backendUrl,
-    json: options.json === true,
-    noWait: options.noWait === true,
-    pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
-    timeoutMs: options.timeoutMs ?? DEFAULT_DEPLOY_TIMEOUT_MS,
-    out,
-    err,
-  };
-}
-
-// ============================================================================
-// deploy
-// ============================================================================
-
-export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-
-  if (options.multiTenant === true && ctx.teamId !== MULTI_TENANT_HTTP_DEPLOY_TEAM_ID) {
-    ctx.err("--multi-tenant is not available for this team.\n");
-    return 1;
-  }
-
-  const targets = await resolveDeployTargets(options, ctx);
-  if (typeof targets === "number") {
-    return targets;
-  }
-
-  if (targets.length === 1) {
-    return deployOne(ctx, options, targets[0]!);
-  }
-
-  // Multi-agent parent: when every child declares `architecture: "v2"`,
-  // the v2 control plane models sibling agents as release components of
-  // ONE application, so deploy them together (one app, one component per
-  // child) instead of minting a separate application per child. Mixed and
-  // v1 parents keep the per-child sequential deploys.
-  const manifests: DeployManifest[] = [];
-  for (const target of targets) {
-    manifests.push(await readDeployManifest(target.dir));
-  }
-  if (manifests.every(manifest => manifest.architecture === "v2")) {
-    return deployAgentsdkApplication(ctx, options, targets, {
-      // `persistent` is per child agent, like `agentPath`: each release
-      // component carries its own.
-      componentPersistent: Object.fromEntries(
-        targets.map((target, index) => [target.slug, manifests[index]?.persistent === true]),
-      ),
-      componentImage: Object.fromEntries(
-        targets.flatMap((target, index) =>
-          manifests[index]?.image === undefined ? [] : [[target.slug, manifests[index].image]],
-        ),
-      ),
-      hasScmChannels: manifests.some(manifest => manifest.hasScmChannels),
-      declaredSecretNames: [
-        ...new Set(manifests.flatMap(manifest => manifest.hosting?.secretNames ?? [])),
-      ],
-      hasDeploymentsChannels: manifests.some(manifest => manifest.hasDeploymentsChannels),
-    });
-  }
-  if (!ctx.json && manifests.some(manifest => manifest.architecture === "v2")) {
-    ctx.err(
-      `warning: agents under this parent mix architectures; deploying each separately (v2 children become standalone single-component applications).\n`,
-    );
-  }
-
-  // --path is per-agent (relative to the repo root). When deploying several
-  // agents, ignore a shared --path so each target can infer its own path.
-  let deployOptions = options;
-  if (options.path !== undefined) {
-    if (!ctx.json) {
-      ctx.err(
-        `warning: ignoring --path ${JSON.stringify(options.path)} for a multi-agent deploy; each agent infers its own path from git.\n`,
-      );
-    }
-    deployOptions = { ...options, path: undefined };
-  }
-
-  // Multi-agent batch: deploy sequentially; --json emits an array.
-  const jsonResults: unknown[] = [];
-  let failures = 0;
-  for (const [index, target] of targets.entries()) {
-    if (!ctx.json) {
-      ctx.err(`\n=== [${index + 1}/${targets.length}] Deploying ${target.slug} ===\n`);
-    }
-    const before = jsonResults.length;
-    const code = await deployOne(ctx, deployOptions, target, {
-      jsonCollect: ctx.json ? jsonResults : undefined,
-    });
-    if (code !== 0) {
-      failures += 1;
-      if (ctx.json && jsonResults.length === before) {
-        jsonResults.push({ slug: target.slug, error: "deploy failed" });
-      }
-    }
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify(jsonResults, null, 2)}\n`);
-  } else if (failures > 0) {
-    ctx.err(`\n${failures} of ${targets.length} deploy(s) failed.\n`);
-  } else {
-    ctx.err(`\nDeployed ${targets.length} agents.\n`);
-  }
-  return failures === 0 ? 0 : 1;
-}
-
-/**
- * Resolve which agent directory(ies) to deploy from `--dir` / `--slug` /
- * `--all`, with an interactive picker when a multi-agent parent is on a TTY.
- */
-async function resolveDeployTargets(
-  options: DeployCliOptions,
-  ctx: DeployCliContext,
-): Promise<DeployTarget[] | number> {
-  const dir = resolve(options.dir ?? ".");
-
-  if (options.slug !== undefined) {
-    const slugError = validateDeploymentSlug(options.slug);
-    if (slugError !== undefined) {
-      ctx.err(`${slugError}\n`);
-      return 1;
-    }
-  }
-  if (options.all === true && options.slug !== undefined) {
-    ctx.err("Pass either --slug or --all, not both.\n");
-    return 1;
-  }
-
-  if (await isAgentProjectDir(dir)) {
-    if (options.all === true) {
-      ctx.err(
-        `--all requires a multi-agent parent directory (several child agents under --dir); ${dir} is a single agent project.\n`,
-      );
-      return 1;
-    }
-    let slug: string;
-    if (options.slug !== undefined) {
-      slug = options.slug;
-    } else {
-      const derived = slugFromDirectoryName(basename(dir));
-      if (derived === undefined) {
-        ctx.err(
-          `Could not derive a deployment slug from the directory name ${JSON.stringify(basename(dir))}; pass --slug.\n`,
-        );
-        return 1;
-      }
-      slug = derived;
-      if (!ctx.json) {
-        ctx.err(`Deploying as "${slug}" (from the directory name).\n`);
-      }
-    }
-    return [{ slug, dir }];
-  }
-
-  let children: ChildAgentDir[];
-  try {
-    children = await listChildAgentDirs(dir);
-  } catch (error) {
-    ctx.err(`${describeError(error)}\n`);
-    return 1;
-  }
-  // Deploy slugs are lowercase-only; normalize directory names the same way
-  // single-agent deploy does so MixedCase child dirs still deploy.
-  children = children.flatMap(child => {
-    const slug = slugFromDirectoryName(basename(child.dir));
-    if (slug === undefined) {
-      return [];
-    }
-    return [{ slug, dir: child.dir }];
-  });
-
-  if (children.length === 0) {
-    if (options.all === true) {
-      ctx.err(`--all requires child agent projects under --dir; none found in ${dir}.\n`);
-      return 1;
-    }
-    // Bare-slug deploy against a non-agent directory (still requires --repo).
-    let slug: string;
-    if (options.slug !== undefined) {
-      slug = options.slug;
-    } else {
-      const derived = slugFromDirectoryName(basename(dir));
-      if (derived === undefined) {
-        ctx.err(
-          `No agent projects under ${dir}, and could not derive a slug from ${JSON.stringify(basename(dir))}; pass --slug or --dir <agent>.\n`,
-        );
-        return 1;
-      }
-      slug = derived;
-      if (!ctx.json) {
-        ctx.err(`Deploying as "${slug}" (no agent project at ${dir}).\n`);
-      }
-    }
-    return [{ slug, dir }];
-  }
-
-  if (children.length === 1) {
-    const only = children[0]!;
-    if (options.all === true) {
-      // One child is fine for --all (degenerate multi-agent parent).
-    } else if (options.slug !== undefined && options.slug.toLowerCase() !== only.slug) {
-      ctx.err(`No agent "${options.slug}" under ${dir}; found "${only.slug}".\n`);
-      return 1;
-    }
-    if (!ctx.json) {
-      ctx.err(`Deploying "${only.slug}" (only agent under ${basename(dir)}).\n`);
-    }
-    return [only];
-  }
-
-  // Multiple children.
-  if (options.all === true) {
-    if (!ctx.json) {
-      ctx.err(
-        `Deploying all ${children.length} agents under ${basename(dir)}: ${children.map(c => c.slug).join(", ")}.\n`,
-      );
-    }
-    return [...children];
-  }
-
-  if (options.slug !== undefined) {
-    const wanted = options.slug.toLowerCase();
-    const match = children.find(child => child.slug === wanted);
-    if (match === undefined) {
-      ctx.err(
-        `No agent "${options.slug}" under ${dir}.\n` +
-          formatAgentList(children) +
-          `Pass --slug <name> or --all.\n`,
-      );
-      return 1;
-    }
-    return [match];
-  }
-
-  // An all-v2 parent deploys as ONE application (siblings are components
-  // of a single app on the v2 control plane), so "deploy the parent" is
-  // unambiguous and needs no picker or --all. A child that is v1 — or
-  // fails to load — keeps the interactive picker below.
-  if (await allChildrenAreV2(children)) {
-    if (!ctx.json) {
-      ctx.err(
-        `Deploying all ${children.length} v2 agents under ${basename(dir)} as one application (pass --slug <name> to deploy a single agent standalone).\n`,
-      );
-    }
-    return [...children];
-  }
-
-  const chooser =
-    options.chooseTargets ??
-    (agents =>
-      promptChooseDeployTargets(agents, {
-        err: ctx.err,
-        stdin: options.stdin ?? process.stdin,
-        interactive:
-          ctx.json !== true &&
-          (options.stdin ?? process.stdin).isTTY === true &&
-          process.stderr.isTTY === true,
-      }));
-  const chosen = await chooser(children);
-  if (chosen === null) {
-    ctx.err("Deploy cancelled.\n");
-    return 1;
-  }
-  if (chosen.length === 0) {
-    ctx.err(
-      `Multiple agents under ${dir}:\n` +
-        formatAgentList(children) +
-        `Pass --slug <name> or --all (or re-run on a TTY to pick interactively).\n`,
-    );
-    return 1;
-  }
-  return chosen;
-}
-
-function formatAgentList(agents: readonly DeployTarget[]): string {
-  return agents.map((agent, i) => `  ${i + 1}) ${agent.slug}\n`).join("");
-}
-
-/**
- * True when every child agent project loads and declares
- * `architecture: "v2"`. Broken projects count as not-v2 so target
- * resolution falls back to the picker instead of failing the whole deploy
- * on a child the user might not even select.
- */
-async function allChildrenAreV2(children: readonly DeployTarget[]): Promise<boolean> {
-  for (const child of children) {
-    try {
-      if ((await readDeployManifest(child.dir)).architecture !== "v2") {
-        return false;
-      }
-    } catch {
-      return false;
-    }
-  }
-  return true;
-}
-
-/**
- * TTY picker for multi-agent parents. Non-interactive callers get `[]`
- * so {@link resolveDeployTargets} can print the --slug/--all hint.
- */
-export async function promptChooseDeployTargets(
-  agents: readonly DeployTarget[],
-  options: {
-    err: (text: string) => void;
-    stdin: SecretInputStream;
-    interactive: boolean;
-  },
-): Promise<DeployTarget[] | null> {
-  options.err(`Multiple agents (${agents.length}):\n` + formatAgentList(agents) + `  a) all\n`);
-  if (!options.interactive) {
-    return [];
-  }
-  options.err('Deploy which? Enter a number, slug, "all", or "q" to cancel: ');
-  const readLine = createLineReader(options.stdin);
-  // createLineReader pauses until data; ensure stdin is flowing on a TTY.
-  options.stdin.resume?.();
-  const answer = (await readLine())?.trim().toLowerCase();
-  if (answer === undefined || answer === "q" || answer === "quit") {
-    return null;
-  }
-  if (answer === "a" || answer === "all" || answer === "*") {
-    return [...agents];
-  }
-  const asIndex = Number.parseInt(answer, 10);
-  if (
-    !Number.isNaN(asIndex) &&
-    String(asIndex) === answer &&
-    asIndex >= 1 &&
-    asIndex <= agents.length
-  ) {
-    return [agents[asIndex - 1]!];
-  }
-  const bySlug = agents.find(agent => agent.slug.toLowerCase() === answer);
-  if (bySlug !== undefined) {
-    return [bySlug];
-  }
-  options.err(
-    `Unrecognized choice ${JSON.stringify(answer)} — expected 1–${agents.length}, a slug, "all", or "q". Aborting.\n`,
-  );
-  return null;
-}
-
-async function deployOne(
-  ctx: DeployCliContext,
-  options: DeployCliOptions,
-  target: DeployTarget,
-  extras?: { jsonCollect?: unknown[] },
-): Promise<number> {
-  const { dir, slug } = target;
-
-  // Fill --repo/--ref/--path from the local git checkout when omitted so
-  // `agent-sdk deploy` inside an agent directory is enough. Only probe git
-  // for real agent projects (avoids ambient monorepo remotes when someone
-  // deploys a bare --slug). Explicit flags always win.
-  const isAgent = await isAgentProjectDir(dir);
-  const needsGitInference =
-    isAgent &&
-    (options.repo === undefined || options.ref === undefined || options.path === undefined);
-  const inferred = needsGitInference
-    ? await inferDeployGitSource(dir, {
-        ...(options.git === undefined ? {} : { git: options.git }),
-      })
-    : {};
-  const gitRepoUrl = options.repo ?? inferred.gitRepoUrl;
-  const gitRef = options.ref ?? inferred.gitRef;
-  const agentPath = options.path ?? inferred.agentPath;
-
-  if (gitRepoUrl !== undefined && !gitRepoUrl.startsWith("https://")) {
-    ctx.err(`Invalid --repo: ${gitRepoUrl} (expected an https:// git repository URL)\n`);
-    return 1;
-  }
-  if (gitRepoUrl === undefined) {
-    ctx.err(
-      `Could not resolve an https:// git repository URL for this deploy.\n` +
-        `  Pass --repo https://github.com/<owner>/<repo> (inferred from origin when possible).\n`,
-    );
-    return 1;
-  }
-  for (const repo of options.cursorEventsRepos ?? []) {
-    if (!isValidCursorEventRepo(repo)) {
-      ctx.err(`Invalid --cursor-events-repo: ${repo} (expected owner/name)\n`);
-      return 1;
-    }
-  }
-
-  if (!ctx.json && gitRepoUrl !== undefined) {
-    const inferredBits: string[] = [];
-    if (options.repo === undefined && inferred.gitRepoUrl !== undefined) {
-      inferredBits.push("repo");
-    }
-    if (options.ref === undefined && inferred.gitRef !== undefined) {
-      inferredBits.push("ref");
-    }
-    if (options.path === undefined && inferred.agentPath !== undefined) {
-      inferredBits.push("path");
-    }
-    ctx.err(
-      `  source: ${gitRepoUrl}${gitRef === undefined ? "" : ` @ ${gitRef}`}\n` +
-        (agentPath === undefined ? "" : `  path:   ${agentPath}\n`) +
-        (inferredBits.length === 0
-          ? ""
-          : `  (inferred ${inferredBits.join(", ")} from git; pass --repo/--ref/--path to override)\n`),
-    );
-  }
-
-  // The package manifest (`defineAgent({ hosting })`) is the source of
-  // truth for egress domains and expected secret names; flags override or
-  // augment it. Directories without an agent project have no manifest. The same load supplies the
-  // cursorAccount connection refs for the post-deploy connector auth and
-  // the channels declared public via `publicEndpoint()`.
-  const manifest = isAgent ? await readDeployManifest(dir) : undefined;
-  const hosting = manifest?.hosting;
-  const egressAllowedDomains = [
-    ...new Set([...(hosting?.egressDomains ?? []), ...(options.allowDomains ?? [])]),
-  ];
-  const publicRoutePaths = (manifest?.publicChannelIds ?? []).map(
-    channelId => `/v1/channels/${channelId}`,
-  );
-  if (!ctx.json && manifest?.httpChannelPublicEndpoint === true) {
-    ctx.err(
-      `warning: publicEndpoint() on the built-in HTTP channel has no effect on hosting — only custom channels (/v1/channels/…) can be public; the session API always requires the alias token.\n`,
-    );
-  }
-  if (!ctx.json && publicRoutePaths.length > 0) {
-    // Security-relevant surface change: say exactly what will be reachable
-    // without the alias token before the deploy is accepted.
-    ctx.err(
-      `  public: ${publicRoutePaths.join(", ")} (served WITHOUT the alias token — these channels authenticate requests themselves)\n`,
-    );
-  }
-  const deadSecretChannels = manifest?.publicChannelIdsWithDeadSecretPolicies ?? [];
-  if (!ctx.json && deadSecretChannels.length > 0) {
-    ctx.err(
-      `warning: ${deadSecretChannels
-        .map(channelId => `/v1/channels/${channelId}`)
-        .join(
-          ", ",
-        )}: publicEndpoint() sits beside sharedSecretAuth()/hmacSignatureAuth() — auth chains are any-of, so every request is admitted and those secret policies never run. Drop publicEndpoint() to enforce them, or drop them to make the intent explicit.\n`,
-    );
-  }
-
-  if (manifest?.architecture === "v2") {
-    if (!ctx.json) {
-      ctx.err(
-        `  architecture: v2${manifest.persistent ? " (persistent)" : ""}${manifest.image === undefined ? "" : `\n  image: ${manifest.image}`}\n`,
-      );
-    }
-    return deployOneAgentsdk(ctx, extras, {
-      persistent: manifest.persistent,
-      image: manifest.image,
-      slug,
-      gitRepoUrl,
-      gitRef,
-      agentPath,
-      repositories: options.cursorEventsRepos,
-      hasScmChannels: manifest.hasScmChannels,
-      declaredSecretNames: hosting?.secretNames,
-      hasDeploymentsChannels: manifest.hasDeploymentsChannels,
-      multiTenant: options.multiTenant === true,
-    });
-  }
-
-  if (options.multiTenant === true) {
-    ctx.err(
-      "--multi-tenant is only valid for architecture: v2 deploys (Cursor-managed products).\n",
-    );
-    return 1;
-  }
-
-  // Today's only source shape: the control plane builds from a git ref.
-  // See DeploySource for the artifact seam.
-  const source: DeploySource = {
-    kind: "git-ref",
-    gitRepoUrl,
-    ...(gitRef === undefined ? {} : { gitRef }),
-    ...(agentPath === undefined ? {} : { agentPath }),
-    ...(options.cursorEventsRepos === undefined || options.cursorEventsRepos.length === 0
-      ? {}
-      : { cursorEventRepos: options.cursorEventsRepos }),
-    ...(egressAllowedDomains.length === 0 ? {} : { egressAllowedDomains }),
-    publicRoutePaths: publicRoutePaths.length === 0 ? undefined : publicRoutePaths,
-    // Deliberately NO manifest here: the control plane captures it from the
-    // provisioned engine (`GET /v1/manifest` after the health probe), which
-    // is the single write path for deploy manifests. `july manifest` remains
-    // available for local visibility only.
-  };
-
-  let accepted: DeployAccepted;
-  try {
-    accepted = await ctx.client.deploy({
-      teamId: ctx.teamId,
-      slug,
-      source,
-      template: readDeployTemplate(dir),
-    });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-
-  const aliasUrl = ctx.client.aliasUrl(accepted.engineAlias);
-  if (!ctx.json && accepted.aliasToken !== undefined) {
-    ctx.out(aliasTokenBlock(accepted.aliasToken));
-  }
-
-  if (ctx.noWait) {
-    if (extras?.jsonCollect !== undefined) {
-      extras.jsonCollect.push(accepted);
-    } else if (ctx.json) {
-      ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
-    } else {
-      ctx.out(
-        `Deploy accepted: ${slug} (team ${ctx.teamId}, generation ${accepted.generation}, ${accepted.deploymentKind})\n` +
-          `  alias: ${aliasUrl}\n` +
-          `Check progress with \`${CLI} deployment ${slug} --team ${ctx.teamId}\`.\n`,
-      );
-    }
-    return 0;
-  }
-
-  let detail: DeploymentDetail;
-  try {
-    detail = await pollUntil(ctx, slug, TERMINAL_DEPLOY_STATUSES, () =>
-      ctx.client.getDeployment({ teamId: ctx.teamId, slug }),
-    );
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-
-  warnMissingSecrets(ctx, slug, hosting?.secretNames, detail.secretNames);
-
-  const payload =
-    accepted.aliasToken === undefined ? detail : { ...detail, aliasToken: accepted.aliasToken };
-
-  if (extras?.jsonCollect !== undefined) {
-    extras.jsonCollect.push(payload);
-    return detail.status === "running" ? 0 : 1;
-  }
-
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify(payload, null, 2)}\n`);
-    return detail.status === "running" ? 0 : 1;
-  }
-
-  if (detail.status !== "running") {
-    ctx.err(`Deployment ${slug} ended ${detail.status}${deployFailureDetail(detail.lastError)}\n`);
-    return 1;
-  }
-  const deployedPublicRoutes = detail.publicRoutePaths ?? [];
-  ctx.out(
-    `Deployed ${slug} (team ${ctx.teamId})\n` +
-      `  status:      running\n` +
-      `  generation:  ${detail.generation}\n` +
-      `  kind:        ${detail.deploymentKind}\n` +
-      `  alias:       ${aliasUrl}\n` +
-      `  playground:  ${aliasUrl}/playground (sign in with the alias token)\n` +
-      `               open: ${CLI} playground --prod --slug ${slug} --team ${ctx.teamId}\n` +
-      // Paste-ready webhook URLs: these subtrees skip the alias token, so
-      // the channel handler must verify deliveries (webhook signatures).
-      deployedPublicRoutes
-        .map(path => `  public:      ${aliasUrl}${path} (no alias token)\n`)
-        .join(""),
-  );
-
-  await runPostDeployConnectorAuth(ctx, options, {
-    slug,
-    connections: manifest?.cursorAccountConnections ?? [],
-    serviceAccountId: deploymentServiceAccountId(detail),
-  });
-  return 0;
-}
-
-/**
- * Multi-agent parent whose children all declare `architecture: "v2"`:
- * deploy ONE application whose release carries a component per child. The
- * application slug derives from the parent directory name; each component
- * key is the child's slug and its path is the child directory relative to
- * the repo root (a shared --path names the parent's directory in the repo).
- */
-async function deployAgentsdkApplication(
-  ctx: DeployCliContext,
-  options: DeployCliOptions,
-  targets: readonly DeployTarget[],
-  declarations: {
-    /** Per child slug: `persistent: true` on that agent's manifest. */
-    componentPersistent: Record<string, boolean>;
-    /** Per child slug: `hosting.image` on that agent's manifest. */
-    componentImage: Record<string, string>;
-    hasScmChannels: boolean;
-    declaredSecretNames: string[];
-    hasDeploymentsChannels: boolean;
-  },
-): Promise<number> {
-  const parentDir = resolve(options.dir ?? ".");
-  const slug = slugFromDirectoryName(basename(parentDir));
-  if (slug === undefined) {
-    ctx.err(
-      `Could not derive an application slug from the parent directory name ${JSON.stringify(basename(parentDir))} — rename it (deploy slugs use lowercase letters, digits, '-' or '_').\n`,
-    );
-    return 1;
-  }
-
-  const needsGitInference =
-    options.repo === undefined || options.ref === undefined || options.path === undefined;
-  const inferred = needsGitInference
-    ? await inferDeployGitSource(parentDir, {
-        ...(options.git === undefined ? {} : { git: options.git }),
-      })
-    : {};
-  const gitRepoUrl = options.repo ?? inferred.gitRepoUrl;
-  const gitRef = options.ref ?? inferred.gitRef;
-  const parentPath = options.path ?? inferred.agentPath;
-
-  if (gitRepoUrl !== undefined && !gitRepoUrl.startsWith("https://")) {
-    ctx.err(`Invalid --repo: ${gitRepoUrl} (expected an https:// git repository URL)\n`);
-    return 1;
-  }
-  if (gitRepoUrl === undefined) {
-    ctx.err(
-      `Could not resolve an https:// git repository URL for this deploy.\n` +
-        `  Pass --repo https://github.com/<owner>/<repo> (inferred from origin when possible).\n`,
-    );
-    return 1;
-  }
-  for (const repo of options.cursorEventsRepos ?? []) {
-    if (!isValidCursorEventRepo(repo)) {
-      ctx.err(`Invalid --cursor-events-repo: ${repo} (expected owner/name)\n`);
-      return 1;
-    }
-  }
-
-  const components: AgentkitDeployComponent[] = targets.map(target => ({
-    componentKey: target.slug,
-    agentPath: [parentPath, basename(target.dir)]
-      .filter((part): part is string => part !== undefined && part !== "")
-      .join("/"),
-    persistent: declarations.componentPersistent[target.slug] === true,
-    image: declarations.componentImage[target.slug],
-  }));
-
-  if (!ctx.json) {
-    ctx.err(
-      `Deploying "${slug}" as one v2 application with ${targets.length} components (slug from the parent directory name).\n` +
-        `  architecture: v2\n` +
-        `  source: ${gitRepoUrl}${gitRef === undefined ? "" : ` @ ${gitRef}`}\n` +
-        components
-          .map(
-            component =>
-              `  component: ${component.componentKey} (${component.agentPath ?? "."})${component.persistent ? " persistent" : ""}${component.image === undefined ? "" : ` image ${component.image}`}\n`,
-          )
-          .join(""),
-    );
-  }
-
-  return deployOneAgentsdk(ctx, undefined, {
-    // Multi-component: the flag travels on each component instead.
-    persistent: false,
-    slug,
-    gitRepoUrl,
-    gitRef,
-    agentPath: undefined,
-    components,
-    repositories: options.cursorEventsRepos,
-    hasScmChannels: declarations.hasScmChannels,
-    declaredSecretNames: declarations.declaredSecretNames,
-    hasDeploymentsChannels: declarations.hasDeploymentsChannels,
-    multiTenant: options.multiTenant === true,
-  });
-}
-
-/**
- * `architecture: "v2"` deploy: POST `/internal/agentsdk/deployments` and
- * poll the matching GET. The v2 accept path starts freeze bake; it does
- * not mint an engine alias or alias token.
- */
-async function deployOneAgentsdk(
-  ctx: DeployCliContext,
-  extras: { jsonCollect?: unknown[] } | undefined,
-  args: {
-    slug: string;
-    gitRepoUrl: string;
-    gitRef: string | undefined;
-    agentPath: string | undefined;
-    components?: AgentkitDeployComponent[];
-    repositories: string[] | undefined;
-    /** Any component declares a GitHub/Origin channel. */
-    hasScmChannels: boolean;
-    /** Union of application component secret declarations. */
-    declaredSecretNames?: string[];
-    /** Any component declares a deployments channel (same repo scope). */
-    hasDeploymentsChannels?: boolean;
-    /** Redeploy an existing Cursor-managed product. */
-    multiTenant: boolean;
-    /**
-     * `persistent: true` in a single agent's manifest. Multi-component
-     * deploys pass `false` here and flag each component instead.
-     */
-    persistent: boolean;
-    /** `hosting.image` of a single agent; components carry their own. */
-    image?: string;
-  },
-): Promise<number> {
-  const { slug } = args;
-  const componentsLine =
-    args.components === undefined
-      ? ""
-      : `  components:  ${args.components.map(component => component.componentKey).join(", ")}\n`;
-  if (args.multiTenant && !ctx.json) {
-    ctx.err("  multi-tenant: existing product\n");
-  }
-  let accepted: AgentkitDeployAccepted;
-  try {
-    accepted = await ctx.client.deployAgentkit({
-      teamId: ctx.teamId,
-      slug,
-      gitRepoUrl: args.gitRepoUrl,
-      gitRef: args.gitRef,
-      agentPath: args.agentPath,
-      components: args.components,
-      repositories: args.repositories,
-      ...(args.multiTenant ? { multiTenant: true } : {}),
-      persistent: args.persistent,
-      image: args.image,
-    });
-  } catch (error) {
-    return renderApiError(error, ctx.err, {
-      multiTenant: args.multiTenant,
-      teamId: ctx.teamId,
-    });
-  }
-
-  if (ctx.noWait) {
-    if (extras?.jsonCollect !== undefined) {
-      extras.jsonCollect.push(accepted);
-    } else if (ctx.json) {
-      ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
-    } else {
-      ctx.out(
-        `Deploy accepted: ${slug} (team ${ctx.teamId}, v2)\n` +
-          `  application: ${accepted.applicationId}\n` +
-          `  release:     ${accepted.releaseId}\n` +
-          componentsLine,
-      );
-    }
-    return 0;
-  }
-
-  let detail: AgentkitDeployStatus;
-  try {
-    detail = await pollUntil(ctx, slug, TERMINAL_AGENTKIT_DEPLOY_STATUSES, () =>
-      ctx.client.getAgentkitDeploy({ teamId: ctx.teamId, slug }),
-    );
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-
-  if (extras?.jsonCollect !== undefined) {
-    extras.jsonCollect.push(detail);
-    return detail.status === "running" ? 0 : 1;
-  }
-
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
-    return detail.status === "running" ? 0 : 1;
-  }
-
-  if (detail.status !== "running") {
-    ctx.err(`Deployment ${slug} ended ${detail.status}${deployFailureDetail(detail.lastError)}\n`);
-    return 1;
-  }
-  warnMissingSecrets(ctx, slug, args.declaredSecretNames, detail.secretNames);
-  const watchesRepositories = args.hasScmChannels || args.hasDeploymentsChannels === true;
-  ctx.out(
-    `Deployed ${slug} (team ${ctx.teamId})\n` +
-      `  status:       running\n` +
-      `  architecture: v2\n` +
-      `  application:  ${detail.applicationId}\n` +
-      `  release:      ${detail.releaseId}\n` +
-      (args.components === undefined
-        ? ""
-        : `  components:   ${args.components
-            .map(component => component.componentKey)
-            .join(", ")}\n`) +
-      (detail.repositories === undefined || !watchesRepositories
-        ? ""
-        : `  watching:     ${detail.repositories.length === 0 ? "(nothing)" : detail.repositories.join(", ")}\n`),
-  );
-  // An agent with GitHub/Origin/deployments channels bound to no repository
-  // scope gets no deliveries at all (deployments channels receive the
-  // watched repos' deployment events), which is otherwise invisible here.
-  if (watchesRepositories && detail.repositories?.length === 0) {
-    ctx.err(
-      `warning: ${slug} watches no repositories, so its GitHub/Origin/deployments channels receive no events.\n` +
-        `  Redeploy with --cursor-events-repo <owner>/<name> to set the scope.\n`,
-    );
-  }
-  return 0;
-}
-
-/**
- * Post-deploy connector authorization for `cursorAccount` connections: the
- * agent's connectors execute with tokens owned by the deployment's service
- * account, which start out unauthorized. On a TTY this runs the dashboard's
- * Authenticate flow inline (browser OAuth per connector, already-authorized
- * ones skipped); otherwise it reports status only. Never affects the deploy
- * outcome — anything left unauthorized just gets a playground-page pointer.
- */
-async function runPostDeployConnectorAuth(
-  ctx: DeployCliContext,
-  options: DeployCliOptions,
-  args: {
-    slug: string;
-    connections: DeployManifest["cursorAccountConnections"];
-    serviceAccountId: string | undefined;
-  },
-): Promise<void> {
-  if (args.connections.length === 0) {
-    return;
-  }
-
-  const { serviceAccountId } = args;
-  if (serviceAccountId === undefined) {
-    ctx.err(
-      `warning: this agent uses Cursor account connectors, but the deployment has no service account; redeploy to mint one.\n`,
-    );
-    return;
-  }
-
-  const backendClient = new CursorBackendClient({
-    backendUrl: ctx.backendUrl,
-    apiKey: ctx.apiKey,
-    fetchImpl: options.fetchImpl,
-  });
-
-  const interactive =
-    options.openBrowserImpl !== undefined ||
-    (process.stdout.isTTY === true && process.stdin.isTTY === true);
-
-  let anyUnauthorized = false;
-  for (const ref of args.connections) {
-    ctx.out(
-      `\nThis agent uses Cursor account connectors (connection "${ref.name}"${
-        ref.servers === undefined || ref.servers.length === 0 ? "" : `: ${ref.servers.join(", ")}`
-      }).\n`,
-    );
-    try {
-      const result = await authorizeCursorAccountConnectors({
-        backendClient,
-        teamId: ctx.teamId,
-        slug: args.slug,
-        serviceAccountId,
-        connectionName: ref.name,
-        servers: ref.servers,
-        interactive,
-        out: ctx.out,
-        err: ctx.err,
-        openBrowserImpl: options.openBrowserImpl,
-        sleep: options.sleepImpl,
-        pollIntervalMs: options.connectorPollIntervalMs,
-        pollTimeoutMs: options.connectorPollTimeoutMs,
-      });
-      if (result.pending.length > 0 || result.errored.length > 0) {
-        anyUnauthorized = true;
-        if (result.pending.length > 0) {
-          ctx.out(`Connectors not authorized yet: ${result.pending.join(", ")}.\n`);
-        }
-      }
-    } catch (error) {
-      anyUnauthorized = true;
-      ctx.err(
-        `warning: could not check connector authorization for "${ref.name}": ${describeError(error)}\n`,
-      );
-    }
-  }
-
-  if (anyUnauthorized) {
-    ctx.out(
-      `You can authorize connectors at the playground page (cursor.com dashboard → Deployed Agents → ${args.slug}) or with \`${CLI} mcp oauth <connection>\`.\n`,
-    );
-  }
-}
-
-interface DeployManifest {
-  hosting: AgentHostingOptions | undefined;
-  architecture: AgentArchitecture | undefined;
-  persistent: boolean;
-  /** `hosting.image`, the team container image this agent runs in. */
-  image: string | undefined;
-  /** `cursorAccount` connections declared by the agent. */
-  cursorAccountConnections: Array<{
-    name: string;
-    servers: string[] | undefined;
-  }>;
-  /**
-   * Channels whose authored auth chain contains `publicEndpoint()`: their
-   * `/v1/channels/<id>` subtree is served through the stable alias WITHOUT
-   * `X-Agent-Alias-Token` (the channel authenticates deliveries itself).
-   */
-  publicChannelIds: string[];
-  /**
-   * Public channels whose auth chain also carries `sharedSecretAuth` /
-   * `hmacSignatureAuth`. Chains are any-of, so `publicEndpoint()` admits
-   * every request and those secret policies never gate anything — locally
-   * or on the control plane; surfaced as a warning.
-   */
-  publicChannelIdsWithDeadSecretPolicies: string[];
-  /**
-   * `publicEndpoint()` on the built-in HTTP channel — a no-op on hosting
-   * (only `/v1/channels/…` subtrees can be public); surfaced as a warning.
-   */
-  httpChannelPublicEndpoint: boolean;
-  /**
-   * The agent has GitHub/Origin channels, so it only receives deliveries
-   * while the deployment is bound to at least one `owner/name` scope.
-   */
-  hasScmChannels: boolean;
-  /**
-   * The agent has deployments channels; deploy-source edges derive from
-   * the same watched-repo set as GitHub/Origin, so it too receives
-   * nothing while the deployment watches no repositories.
-   */
-  hasDeploymentsChannels: boolean;
-}
-
-/**
- * Read the deploy-relevant bits of the project manifest at `dir` in one
- * load: the `hosting` block, the agent's cursorAccount connections, and the
- * channels declared public via `publicEndpoint()`.
- */
-async function readDeployManifest(dir: string): Promise<DeployManifest> {
-  const project = await loadAgentProject(dir);
-  // Fail here, before anything is dispatched: a project with error
-  // diagnostics (e.g. agent/storage.ts on architecture v2) would only be
-  // refused later by `serve` inside the hosted build, wasting a bake.
-  if (hasErrorDiagnostics(project)) {
-    throw new Error(
-      `Refusing to deploy ${project.name} — it has errors:\n${formatDiagnostics(
-        project.diagnostics.filter(d => d.severity === "error"),
-      )}`,
-    );
-  }
-  return {
-    hosting: project.agent.hosting,
-    architecture: project.agent.architecture,
-    persistent: project.agent.persistent === true,
-    image: project.agent.hosting?.image,
-    cursorAccountConnections: project.agent.connections.flatMap(connection =>
-      isCursorAccountTransport(connection.transport)
-        ? [{ name: connection.name, servers: connection.transport.servers }]
-        : [],
-    ),
-    publicChannelIds: project.channels
-      .filter(channel => (channel.definition.auth ?? []).some(isPublicEndpointPolicy))
-      .map(channel => channel.id),
-    publicChannelIdsWithDeadSecretPolicies: project.channels
-      .filter(channel => {
-        const auth = channel.definition.auth ?? [];
-        return (
-          auth.some(isPublicEndpointPolicy) &&
-          auth.some(policy => {
-            const kind = catchAuthDeclaration(policy)?.kind;
-            return kind !== undefined && kind !== "public";
-          })
-        );
-      })
-      .map(channel => channel.id),
-    httpChannelPublicEndpoint: (project.httpChannel.auth ?? []).some(isPublicEndpointPolicy),
-    hasScmChannels: project.channels.some(channel => {
-      const kind = channel.definition.meta?.kind;
-      return kind === "github" || kind === "origin";
-    }),
-    hasDeploymentsChannels: project.channels.some(
-      channel => channel.definition.meta?.kind === "deployments",
-    ),
-  };
-}
-
-/**
- * Friendly post-deploy nudge: the manifest declares secrets the agent
- * expects, but the deployment does not have them all set yet.
- */
-function warnMissingSecrets(
-  ctx: DeployCliContext,
-  slug: string,
-  declared: string[] | undefined,
-  set: string[] | undefined,
-): void {
-  if (declared === undefined || declared.length === 0) {
-    return;
-  }
-  const setNames = new Set(set ?? []);
-  // Platform-managed names (CURSOR_*, hosted storage) are injected by the
-  // control plane and never appear in secrets list — do not warn on them.
-  const missing = declared.filter(name => !setNames.has(name) && !isReservedSecretName(name));
-  if (missing.length === 0) {
-    return;
-  }
-  ctx.err(
-    `warning: secrets declared in the agent manifest but not set on ${slug}: ${missing.join(", ")}\n` +
-      `  set them with \`${CLI} secrets set ${slug} ${missing.join(" ")}\`\n`,
-  );
-}
-
-// ============================================================================
-// deployments (list)
-// ============================================================================
-
-export async function cmdDeployments(options: DeployCliOptions): Promise<number> {
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  let deployments: Deployment[];
-  try {
-    deployments = await ctx.client.listDeployments({ teamId: ctx.teamId });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  let applications: AgentkitDeploymentListItem[] = [];
-  try {
-    applications = await ctx.client.listAgentkitDeployments({
-      teamId: ctx.teamId,
-    });
-  } catch (error) {
-    // Older control planes 404 this route; keep listing v1.
-    if (!(error instanceof DeployApiError && error.status === 404)) {
-      return renderApiError(error, ctx.err);
-    }
-  }
-  if (ctx.json) {
-    // Empty v2 list keeps `{ deployments }` for v1-only parsers.
-    ctx.out(
-      `${JSON.stringify(
-        applications.length === 0 ? { deployments } : { deployments, applications },
-        null,
-        2,
-      )}\n`,
-    );
-    return 0;
-  }
-  if (deployments.length === 0 && applications.length === 0) {
-    ctx.out(`No deployments on team ${ctx.teamId}. Create one with \`${CLI} deploy\`.\n`);
-    return 0;
-  }
-  ctx.out(
-    `${renderTable(
-      ["SLUG", "ARCH", "STATUS", "GEN", "KIND", "UPDATED"],
-      [
-        ...deployments.map(d => [
-          d.slug,
-          "v1",
-          d.status,
-          String(d.generation),
-          d.deploymentKind,
-          d.desiredUpdatedAt ?? "",
-        ]),
-        ...applications.map(application => [
-          application.slug,
-          "v2",
-          application.status,
-          "-",
-          "application",
-          application.deployments
-            .map(row => row.desiredUpdatedAt)
-            .sort()
-            .at(-1) ?? "",
-        ]),
-      ],
-    )}\n`,
-  );
-  return 0;
-}
-
-// ============================================================================
-// deployment <slug> (detail)
-// ============================================================================
-
-export async function cmdDeploymentStatus(
-  slug: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((t: string) => void process.stderr.write(t)))(
-      `Usage: ${CLI} deployment <slug> [--team <id>] [--json]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  // Same dispatch as `stop`: v1 409s architecture-v2 slugs, so the v2
-  // GET goes first. A v2 404 (missing slug, or an older backend) falls
-  // through to the v1 agent-serve detail.
-  try {
-    const detail = await ctx.client.getAgentkitDeploy({
-      teamId: ctx.teamId,
-      slug,
-    });
-    renderAgentkitDeploymentStatus(ctx, detail);
-    return 0;
-  } catch (error) {
-    if (!(error instanceof DeployApiError) || error.status !== 404) {
-      return renderApiError(error, ctx.err);
-    }
-  }
-  let detail: DeploymentDetail;
-  try {
-    detail = await ctx.client.getDeployment({ teamId: ctx.teamId, slug });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
-    return 0;
-  }
-  const aliasUrl = ctx.client.aliasUrl(detail.engineAlias);
-  const lines = [`${detail.slug} (team ${detail.teamId})`, `  status:      ${detail.status}`];
-  if (detail.progress !== undefined) {
-    lines.push(`  progress:    ${detail.progress}`);
-  }
-  if (
-    detail.statusMessage !== null &&
-    detail.statusMessage !== undefined &&
-    detail.statusMessage.trim() !== ""
-  ) {
-    lines.push(`  step:        ${detail.statusMessage}`);
-  }
-  lines.push(
-    `  generation:  ${detail.generation}`,
-    `  kind:        ${detail.deploymentKind}`,
-    `  alias:       ${aliasUrl}`,
-    `  playground:  ${aliasUrl}/playground`,
-  );
-  if (detail.gitRepoUrl !== null && detail.gitRepoUrl !== undefined) {
-    lines.push(`  repo:        ${detail.gitRepoUrl} @ ${detail.gitRef ?? ""}`);
-  }
-  if (detail.serviceAccountId !== undefined && detail.serviceAccountId !== null) {
-    lines.push(`  service account: ${detail.serviceAccountId}`);
-  }
-  if (detail.agentStoreSourceId !== undefined) {
-    // The durable file store's address: GET /v0/agent-serve-files/<id> lists
-    // it, and the pod sees it as AGENT_SERVE_STORE_SOURCE_ID.
-    lines.push(`  file store:  ${detail.agentStoreSourceId}`);
-  }
-  if (detail.egressAllowedDomains !== undefined && detail.egressAllowedDomains.length > 0) {
-    lines.push(`  egress:      ${detail.egressAllowedDomains.join(", ")}`);
-  }
-  if (detail.publicRoutePaths !== undefined && detail.publicRoutePaths.length > 0) {
-    // Served through the alias WITHOUT X-Agent-Alias-Token (the channel
-    // authenticates deliveries itself).
-    for (const path of detail.publicRoutePaths) {
-      lines.push(`  public:      ${aliasUrl}${path} (no alias token)`);
-    }
-  }
-  if (detail.secretNames !== undefined && detail.secretNames.length > 0) {
-    lines.push(`  secrets:     ${detail.secretNames.join(", ")}`);
-  }
-  if (detail.podCredentialMaskedKey !== undefined && detail.podCredentialMaskedKey !== null) {
-    lines.push(`  pod credential: ${detail.podCredentialMaskedKey}`);
-  }
-  if (detail.engineUrl !== null && detail.engineUrl !== undefined) {
-    lines.push(`  engine:      ${detail.engineUrl}`);
-  }
-  if (
-    detail.engineAccess !== null &&
-    detail.engineAccess !== undefined &&
-    typeof detail.engineAccess === "object"
-  ) {
-    lines.push(
-      `  engine access: ${detail.engineAccess.url} (expires ${detail.engineAccess.expiresAt})`,
-    );
-  }
-  if (detail.lastError !== null && detail.lastError !== undefined) {
-    lines.push(`  last error:  ${sanitizeCustomerError(detail.lastError)}`);
-  }
-  if (detail.desiredUpdatedAt !== undefined) {
-    lines.push(`  updated:     ${detail.desiredUpdatedAt}`);
-  }
-  ctx.out(`${lines.join("\n")}\n`);
-  return 0;
-}
-
-function renderAgentkitDeploymentStatus(ctx: DeployCliContext, detail: AgentkitDeployStatus): void {
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
-    return;
-  }
-  const lines = [
-    `${detail.slug} (team ${detail.teamId})`,
-    `  status:       ${detail.status}`,
-    `  architecture: v2`,
-    `  application:  ${detail.applicationId}`,
-    `  release:      ${detail.releaseId}`,
-    `  progress:     ${detail.progress}`,
-  ];
-  if (detail.statusMessage !== null && detail.statusMessage.trim() !== "") {
-    lines.push(`  step:         ${detail.statusMessage}`);
-  }
-  if (detail.repositories !== undefined) {
-    lines.push(
-      `  watching:     ${
-        detail.repositories.length === 0 ? "(nothing)" : detail.repositories.join(", ")
-      }`,
-    );
-  }
-  if (detail.secretNames !== undefined && detail.secretNames.length > 0) {
-    lines.push(`  secrets:      ${detail.secretNames.join(", ")}`);
-  }
-  if (detail.lastError !== null && detail.lastError !== undefined) {
-    lines.push(`  last error:   ${sanitizeCustomerError(detail.lastError)}`);
-  }
-  ctx.out(`${lines.join("\n")}\n`);
-}
-
-// ============================================================================
-// stop <slug>
-// ============================================================================
-
-export async function cmdStop(
-  slug: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((t: string) => void process.stderr.write(t)))(
-      `Usage: ${CLI} stop <slug> [--team <id>] [--json] [--no-wait]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  // Stop takes only a slug, so there is no manifest to dispatch on (unlike
-  // deploy). The v2 agentsdk control plane goes first: v1 endpoints refuse
-  // `architecture: "v2"` slugs with a 409 rather than a 404, so v1-first
-  // could not fall through. A v2 404 (including an older backend without
-  // the `/internal/agentsdk` mount) falls back to the v1 stop.
-  let architecture: "v1" | "v2" = "v2";
-  let accepted: StopAccepted | AgentkitStopAccepted;
-  try {
-    accepted = await ctx.client.stopAgentkit({
-      teamId: ctx.teamId,
-      slug,
-      cancelRuns: options.cancelRuns,
-    });
-  } catch (error) {
-    if (!(error instanceof DeployApiError) || error.status !== 404) {
-      return renderApiError(error, ctx.err);
-    }
-    if (options.cancelRuns === true) {
-      ctx.err(
-        `Canceling active runs while stopping is supported only for Agent SDK v2 deployments.\n`,
-      );
-      return 1;
-    }
-    try {
-      accepted = await ctx.client.stopDeployment({ teamId: ctx.teamId, slug });
-      architecture = "v1";
-    } catch (v1Error) {
-      return renderApiError(v1Error, ctx.err);
-    }
-  }
-  const cancellation = "cancellation" in accepted ? accepted.cancellation : undefined;
-  const stoppedGlobally = "scope" in accepted && accepted.scope === "global";
-  if (ctx.noWait) {
-    if (ctx.json) {
-      ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
-    } else {
-      ctx.out(
-        stoppedGlobally
-          ? `Stop accepted for ${slug} across all tenants (status: ${accepted.status}).\n`
-          : `Stop accepted for ${slug} (status: ${accepted.status}).\n`,
-      );
-    }
-    return cancellation?.failed === 0 || cancellation === undefined ? 0 : 1;
-  }
-  let detail: DeploymentDetail | AgentkitDeployStatus;
-  try {
-    detail =
-      architecture === "v2"
-        ? await pollUntil(ctx, slug, new Set(["stopped"]), () =>
-            ctx.client.getAgentkitDeploy({ teamId: ctx.teamId, slug }),
-          )
-        : await pollUntil(ctx, slug, new Set(["stopped"]), () =>
-            ctx.client.getDeployment({ teamId: ctx.teamId, slug }),
-          );
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
-  } else if (stoppedGlobally) {
-    ctx.out(
-      `Stopped ${slug} across all tenants (team ${ctx.teamId}); resume with \`${CLI} start ${slug}\`.\n`,
-    );
-  } else {
-    ctx.out(`Stopped ${slug} (team ${ctx.teamId}).\n`);
-  }
-  if (cancellation !== undefined) {
-    return writeCancellationStarted(ctx, cancellation, slug);
-  }
-  return 0;
-}
-
-function writeCancellationStarted(
-  ctx: { out: (text: string) => void; err: (text: string) => void },
-  cancellation: AgentkitCancelRunsResult,
-  slug: string,
-): number {
-  ctx.out(`Started cancellation across ${cancellation.batchesStarted} deployment batch(es).\n`);
-  if (cancellation.sessionsMarkedFailed !== undefined) {
-    ctx.out(`Marked ${cancellation.sessionsMarkedFailed} factory session(s) failed.\n`);
-  }
-  if (cancellation.failed > 0) {
-    ctx.err(
-      `Failed to start ${cancellation.failed} cancellation batch(es); retry with \`${CLI} cancel-runs ${slug}\`.\n`,
-    );
-    return 1;
-  }
-  return 0;
-}
-
-export async function cmdStart(
-  slug: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((t: string) => void process.stderr.write(t)))(
-      `Usage: ${CLI} start <slug> [--team <id>] [--json]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  try {
-    const accepted = await ctx.client.startAgentkit({
-      teamId: ctx.teamId,
-      slug,
-    });
-    if (ctx.json) {
-      ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
-    } else {
-      ctx.out(`Started ${slug} (team ${ctx.teamId}).\n`);
-    }
-    return 0;
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-}
-
-export async function cmdKill(
-  slug: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((t: string) => void process.stderr.write(t)))(
-      `Usage: ${CLI} kill <slug> [--team <id>] [--json]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  let accepted: AgentkitStopAccepted;
-  try {
-    accepted = await ctx.client.killAgentkit({ teamId: ctx.teamId, slug });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
-  } else {
-    ctx.out(
-      accepted.scope === "global"
-        ? `Killed ${slug} across all tenants (team ${ctx.teamId}): deploys locked, admission stopped.\n`
-        : `Killed ${slug} (team ${ctx.teamId}): deploys locked, admission stopped.\n`,
-    );
-    ctx.out(
-      `Resume traffic with \`${CLI} unlock-deploys ${slug}\` then \`${CLI} start ${slug}\`.\n`,
-    );
-    ctx.out(`Unlock deploys with \`${CLI} unlock-deploys ${slug}\`.\n`);
-  }
-  if (accepted.cancellation !== undefined) {
-    return writeCancellationStarted(ctx, accepted.cancellation, slug);
-  }
-  return 0;
-}
-
-export async function cmdUnlockDeploys(
-  slug: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((t: string) => void process.stderr.write(t)))(
-      `Usage: ${CLI} unlock-deploys <slug> [--team <id>] [--json]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  try {
-    const accepted = await ctx.client.unlockAgentkitDeploys({
-      teamId: ctx.teamId,
-      slug,
-    });
-    if (ctx.json) {
-      ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
-    } else {
-      ctx.out(`Unlocked deploys for ${slug} (team ${ctx.teamId}).\n`);
-    }
-    return 0;
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-}
-
-export async function cmdCancelRuns(
-  slug: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((text: string) => void process.stderr.write(text)))(
-      `Usage: ${CLI} cancel-runs <slug> [--team <id>] [--json]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  let result: AgentkitCancelRunsResult;
-  try {
-    result = await ctx.client.cancelAgentkitRuns({
-      teamId: ctx.teamId,
-      slug,
-    });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify(result, null, 2)}\n`);
-  } else {
-    ctx.out(`Started cancellation across ${result.batchesStarted} deployment batch(es).\n`);
-    if (result.sessionsMarkedFailed !== undefined) {
-      ctx.out(`Marked ${result.sessionsMarkedFailed} factory session(s) failed.\n`);
-    }
-  }
-  if (result.failed > 0) {
-    ctx.err(`Failed to start ${result.failed} cancellation batch(es).\n`);
-    return 1;
-  }
-  return 0;
-}
-
-// ============================================================================
-// event-repos <slug> --repo <owner/name>...
-// ============================================================================
-
-export async function cmdEventRepos(
-  slug: string | undefined,
-  repositories: string[],
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((text: string) => void process.stderr.write(text)))(
-      `Usage: ${CLI} event-repos <slug> --repo <owner/name>... [--team <id>] [--json]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  let configured: string[];
-  try {
-    configured = await ctx.client.setAgentkitEventRepositories({
-      teamId: ctx.teamId,
-      slug,
-      repositories,
-    });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify({ repositories: configured }, null, 2)}\n`);
-  } else if (configured.length === 0) {
-    ctx.out(`${slug} now watches no repositories.\n`);
-  } else {
-    ctx.out(`${slug} now watches ${configured.join(", ")}.\n`);
-  }
-  return 0;
-}
-
-// ============================================================================
-// upgrade <slug>
-// ============================================================================
-
-/** Release ids are uuids; anything else the user typed is a version. */
-const RELEASE_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-export async function cmdUpgrade(
-  args: { slug: string | undefined; release: string | undefined },
-  options: DeployCliOptions,
-): Promise<number> {
-  return cmdPinRelease(args, options, {
-    usage: `Usage: ${CLI} upgrade <slug> [--release <id|version>] [--team <id>] [--json]\n`,
-    pin: (client, request) => client.upgradeAgentkitInstall(request),
-    success: (slug, releaseId) => `${slug} now runs release ${releaseId}.\n`,
-  });
-}
-
-export async function cmdRollback(
-  args: { slug: string | undefined; release: string | undefined },
-  options: DeployCliOptions,
-): Promise<number> {
-  return cmdPinRelease(args, options, {
-    usage: `Usage: ${CLI} rollback <slug> [--release <id|version>] [--team <id>] [--json]\n`,
-    pin: (client, request) => client.rollbackAgentkitInstall(request),
-    success: (slug, releaseId) => `${slug} rolled back to release ${releaseId}.\n`,
-  });
-}
-
-async function cmdPinRelease(
-  args: { slug: string | undefined; release: string | undefined },
-  options: DeployCliOptions,
-  pin: {
-    usage: string;
-    pin: (
-      client: AgentServeDeployClient,
-      request: {
-        teamId: number;
-        slug: string;
-        releaseId?: string;
-        version?: string;
-      },
-    ) => Promise<string>;
-    success: (slug: string, releaseId: string) => string;
-  },
-): Promise<number> {
-  const { slug, release } = args;
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((text: string) => void process.stderr.write(text)))(pin.usage);
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  const selector = release?.trim() ?? "";
-  let releaseId: string;
-  try {
-    releaseId = await pin.pin(ctx.client, {
-      teamId: ctx.teamId,
-      slug,
-      ...(selector === ""
-        ? {}
-        : RELEASE_ID_RE.test(selector)
-          ? { releaseId: selector }
-          : { version: selector }),
-    });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify({ releaseId }, null, 2)}\n`);
-  } else {
-    ctx.out(pin.success(slug, releaseId));
-  }
-  return 0;
-}
-
-// ============================================================================
-// delete <slug>
-// ============================================================================
-
-export async function cmdDelete(
-  slug: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((t: string) => void process.stderr.write(t)))(
-      `Usage: ${CLI} delete <slug> [--team <id>] [--json] [--no-wait]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  // Same dispatch as `stop`: v1 409s architecture-v2 slugs, so the v2
-  // DELETE goes first. A v2 404 (missing slug, or an older backend)
-  // falls through to the v1 agent-serve delete.
-  let architecture: "v1" | "v2" = "v2";
-  let accepted: DeleteAccepted | AgentkitStopAccepted;
-  try {
-    accepted = await ctx.client.deleteAgentkit({ teamId: ctx.teamId, slug });
-  } catch (error) {
-    if (!(error instanceof DeployApiError) || error.status !== 404) {
-      return renderApiError(error, ctx.err);
-    }
-    try {
-      accepted = await ctx.client.deleteDeployment({
-        teamId: ctx.teamId,
-        slug,
-      });
-      architecture = "v1";
-    } catch (v1Error) {
-      return renderApiError(v1Error, ctx.err);
-    }
-  }
-  if (ctx.noWait) {
-    if (ctx.json) {
-      ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
-    } else {
-      ctx.out(`Delete accepted for ${slug} (status: ${accepted.status}).\n`);
-    }
-    return 0;
-  }
-  try {
-    await pollUntilGone(ctx, slug, () =>
-      architecture === "v2"
-        ? ctx.client.getAgentkitDeploy({ teamId: ctx.teamId, slug })
-        : ctx.client.getDeployment({ teamId: ctx.teamId, slug }),
-    );
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify({ slug, status: "deleted" }, null, 2)}\n`);
-  } else {
-    ctx.out(`Deleted ${slug} (team ${ctx.teamId}).\n`);
-  }
-  return 0;
-}
-
-// ============================================================================
-// rotate-token <slug>
-// ============================================================================
-
-export async function cmdRotateToken(
-  slug: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((t: string) => void process.stderr.write(t)))(
-      `Usage: ${CLI} rotate-token <slug> [--team <id>]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  let aliasToken: string;
-  try {
-    const architecture = await deploymentArchitecture({
-      client: ctx.client,
-      teamId: ctx.teamId,
-      slug,
-    });
-    aliasToken =
-      architecture === "v2"
-        ? await ctx.client.rotateAgentsdkAliasToken({
-            teamId: ctx.teamId,
-            slug,
-          })
-        : await ctx.client.rotateAliasToken({
-            teamId: ctx.teamId,
-            slug,
-          });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify({ aliasToken }, null, 2)}\n`);
-    return 0;
-  }
-  ctx.out(
-    `Rotated the alias token for ${slug}. The old token stopped working immediately.\n${aliasTokenBlock(aliasToken)}`,
-  );
-  return 0;
-}
-
-// ============================================================================
-// secrets set|list|unset
-// ============================================================================
-
-async function secretDeploymentArchitecture(
-  ctx: DeployCliContext,
-  slug: string,
-): Promise<"v1" | "v2"> {
-  return deploymentArchitecture({
-    client: ctx.client,
-    teamId: ctx.teamId,
-    slug,
-  });
-}
-
-export async function cmdSecretsSet(
-  slug: string | undefined,
-  specs: string[],
-  options: DeployCliOptions,
-): Promise<number> {
-  const usageErr = options.err ?? ((t: string) => void process.stderr.write(t));
-  if (slug === undefined || slug === "" || specs.length === 0) {
-    usageErr(
-      `Usage: ${CLI} secrets set <slug> NAME [NAME2 ...] [--team <id>] [--json]\n` +
-        `  Enter values at the hidden prompt, or pipe one line per NAME.\n` +
-        `  Opt-in (leaks into argv / agent terminals): NAME=VALUE … --from-argv\n`,
-    );
-    return 1;
-  }
-
-  // Parse and validate every name before prompting for any value, so a
-  // typo in the last name cannot waste typed-in secrets.
-  const parsed: Array<{ name: string; value?: string }> = [];
-  for (const spec of specs) {
-    const eq = spec.indexOf("=");
-    const name = eq === -1 ? spec : spec.slice(0, eq);
-    const nameError = validateSettableSecretName(name);
-    if (nameError !== undefined) {
-      usageErr(`${nameError}\n`);
-      return 1;
-    }
-    parsed.push(eq === -1 ? { name } : { name, value: spec.slice(eq + 1) });
-  }
-  const hasArgvValues = parsed.some(entry => entry.value !== undefined);
-  if (hasArgvValues && options.fromArgv !== true) {
-    usageErr(
-      `Refusing NAME=VALUE on argv (shows up in shell history and agent-captured terminals).\n` +
-        `Pass names only:\n` +
-        `  ${CLI} secrets set ${slug} NAME\n` +
-        `Hidden prompt on a TTY; one stdin line per NAME when piped.\n` +
-        `Or redirect a file: ${CLI} secrets set ${slug} NAME < ./secret.txt\n`,
-    );
-    return 1;
-  }
-  if (hasArgvValues) {
-    usageErr(
-      `warning: --from-argv puts secret values in argv (shell history and agent-captured terminals).\n`,
-    );
-  }
-
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-
-  const stdin = options.stdin ?? process.stdin;
-  const readValue = createSecretValueReader(stdin, ctx.err);
-  const secrets: Array<{ name: string; value: string }> = [];
-  for (const entry of parsed) {
-    secrets.push({
-      name: entry.name,
-      value: entry.value ?? (await readValue(entry.name)),
-    });
-  }
-
-  let secretNames: string[];
-  let architecture: "v1" | "v2";
-  try {
-    architecture = await secretDeploymentArchitecture(ctx, slug);
-    secretNames =
-      architecture === "v2"
-        ? await ctx.client.setAgentkitSecrets({
-            teamId: ctx.teamId,
-            slug,
-            secrets,
-          })
-        : await ctx.client.setSecrets({
-            teamId: ctx.teamId,
-            slug,
-            secrets,
-          });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify({ secretNames }, null, 2)}\n`);
-    return 0;
-  }
-  ctx.out(
-    `Set ${secrets.length} secret${secrets.length === 1 ? "" : "s"} on ${slug}.\n` +
-      `Secrets now set: ${secretNames.join(", ")}\n` +
-      (architecture === "v2"
-        ? `The next task picks them up; no redeploy is required.\n`
-        : `The engine picks them up on its next deploy.\n`),
-  );
-  return 0;
-}
-
-export async function cmdSecretsList(
-  slug: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "") {
-    (options.err ?? ((t: string) => void process.stderr.write(t)))(
-      `Usage: ${CLI} secrets list <slug> [--team <id>] [--json]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  let secrets: SecretInfo[];
-  try {
-    const architecture = await secretDeploymentArchitecture(ctx, slug);
-    secrets =
-      architecture === "v2"
-        ? await ctx.client.listAgentkitSecrets({ teamId: ctx.teamId, slug })
-        : await ctx.client.listSecrets({ teamId: ctx.teamId, slug });
-  } catch (error) {
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify({ secrets }, null, 2)}\n`);
-    return 0;
-  }
-  if (secrets.length === 0) {
-    ctx.out(`No secrets set on ${slug}. Add one with \`${CLI} secrets set ${slug} NAME\`.\n`);
-    return 0;
-  }
-  ctx.out(
-    `${renderTable(
-      ["NAME", "CREATED"],
-      secrets.map(secret => [secret.name, secret.createdAt]),
-    )}\n`,
-  );
-  return 0;
-}
-
-export async function cmdSecretsUnset(
-  slug: string | undefined,
-  name: string | undefined,
-  options: DeployCliOptions,
-): Promise<number> {
-  if (slug === undefined || slug === "" || name === undefined || name === "") {
-    (options.err ?? ((t: string) => void process.stderr.write(t)))(
-      `Usage: ${CLI} secrets unset <slug> NAME [--team <id>]\n`,
-    );
-    return 1;
-  }
-  const ctx = await prepare(options);
-  if (typeof ctx === "number") {
-    return ctx;
-  }
-  try {
-    const architecture = await secretDeploymentArchitecture(ctx, slug);
-    if (architecture === "v2") {
-      await ctx.client.deleteAgentkitSecret({
-        teamId: ctx.teamId,
-        slug,
-        name,
-      });
-    } else {
-      await ctx.client.deleteSecret({ teamId: ctx.teamId, slug, name });
-    }
-  } catch (error) {
-    if (error instanceof DeployApiError && error.status === 404) {
-      ctx.err(
-        `No secret named ${name} on deployment ${slug} — check \`${CLI} secrets list ${slug}\` (and the slug / --team).\n`,
-      );
-      return 1;
-    }
-    return renderApiError(error, ctx.err);
-  }
-  if (ctx.json) {
-    ctx.out(`${JSON.stringify({ removed: name }, null, 2)}\n`);
-  } else {
-    ctx.out(`Removed secret ${name} from ${slug}.\n`);
-  }
-  return 0;
-}
-
-/**
- * Returns a reader for interactive secret values: hidden (no-echo) prompt
- * when `stdin` is a TTY, otherwise one line per secret from the piped
- * stream. One reader per command so piped lines are consumed in order.
- */
-function createSecretValueReader(
-  stdin: SecretInputStream,
-  err: (text: string) => void,
-): (name: string) => Promise<string> {
-  if (stdin.isTTY === true) {
-    return name => promptHidden(stdin, err, `Value for ${name}: `);
-  }
-  const readLine = createLineReader(stdin);
-  return async name => {
-    const line = await readLine();
-    if (line === undefined) {
-      throw new DeployApiError(
-        `stdin ended before a value for ${name} was provided (pipe one line per secret).`,
-        0,
-      );
-    }
-    return line;
-  };
-}
-
-/** Longest mask run drawn while typing a secret; the count carries the rest. */
-const SECRET_MASK_MAX_WIDTH = 24;
-
-/**
- * One line of typing feedback for the hidden prompt. Echoing the value would
- * leak it, so the line carries a bounded mask plus the exact character count —
- * enough to see that keystrokes, backspaces, and pasted values landed. The
- * mask is clamped to the terminal width so the redraw stays on one line.
- */
-function renderSecretPromptLine(
-  prompt: string,
-  length: number,
-  dim: (text: string) => string,
-): string {
-  const count = `${length} char${length === 1 ? "" : "s"}`;
-  const room = (process.stderr.columns ?? 80) - prompt.length - count.length - 2;
-  const maskWidth = Math.max(0, Math.min(length, SECRET_MASK_MAX_WIDTH, room));
-  // `·` over `•`: the rest of the CLI's progress output already uses it, and
-  // fonts that ship no bullet glyph draw a tofu box in its place.
-  const mask = "·".repeat(maskWidth);
-  const body = mask === "" ? count : `${mask} ${count}`;
-  return `\r\u001b[2K${prompt}${dim(body)}`;
-}
-
-/**
- * Raw-mode hidden prompt: never echoes the value, redraws a mask + character
- * count as it is typed, supports backspace and Ctrl-C.
- */
-function promptHidden(
-  stdin: SecretInputStream,
-  err: (text: string) => void,
-  prompt: string,
-): Promise<string> {
-  return new Promise((resolvePromise, reject) => {
-    const { dim } = stderrPalette();
-    let value = "";
-    const draw = (): void => {
-      err(renderSecretPromptLine(prompt, value.length, dim));
-    };
-    draw();
-    stdin.setRawMode?.(true);
-    stdin.resume();
-    const cleanup = (): void => {
-      stdin.off("data", onData);
-      stdin.setRawMode?.(false);
-      stdin.pause();
-      draw();
-      err("\n");
-    };
-    const onData = (chunk: Buffer | string): void => {
-      const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
-      for (const ch of text) {
-        if (ch === "\r" || ch === "\n") {
-          cleanup();
-          resolvePromise(value);
-          return;
-        }
-        if (ch === "\u0003") {
-          cleanup();
-          reject(new DeployApiError("Aborted.", 0));
-          return;
-        }
-        if (ch === "\u007f" || ch === "\b") {
-          value = value.slice(0, -1);
-          continue;
-        }
-        value += ch;
-      }
-      // One redraw per chunk keeps a pasted value from flooding the terminal.
-      draw();
-    };
-    stdin.on("data", onData);
-  });
-}
-
-/** Buffered line reader over a piped stream; undefined once it ends. */
-export function createLineReader(stream: NodeJS.ReadableStream): () => Promise<string | undefined> {
-  let buffer = "";
-  let ended = false;
-  const waiters: Array<(line: string | undefined) => void> = [];
-
-  const drain = (): void => {
-    while (waiters.length > 0) {
-      const newline = buffer.indexOf("\n");
-      if (newline !== -1) {
-        const line = buffer.slice(0, newline).replace(/\r$/, "");
-        buffer = buffer.slice(newline + 1);
-        waiters.shift()?.(line);
-        continue;
-      }
-      if (!ended) {
-        return;
-      }
-      // Stream ended: a trailing unterminated line still counts once.
-      const rest = buffer;
-      buffer = "";
-      waiters.shift()?.(rest === "" ? undefined : rest.replace(/\r$/, ""));
-    }
-  };
-
-  stream.on("data", (chunk: Buffer | string) => {
-    buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
-    drain();
-  });
-  stream.on("end", () => {
-    ended = true;
-    drain();
-  });
-  stream.resume();
-
-  return () =>
-    new Promise(resolvePromise => {
-      waiters.push(resolvePromise);
-      drain();
-    });
-}
-
-// ============================================================================
-// Polling + rendering helpers
-// ============================================================================
-
-/**
- * Poll deployment status every `pollIntervalMs` until it lands in
- * `terminal` (single-line progress on a TTY, one line per transition
- * otherwise). Prefers customer `statusMessage` / `progress` over raw
- * status so create → checkout → start is visible. Throws DeployApiError
- * on request failures or timeout.
- */
-async function pollUntil<
-  T extends {
-    status: string;
-    progress?: DeploymentProgress;
-    statusMessage?: string | null;
-  },
->(
-  ctx: DeployCliContext,
-  slug: string,
-  terminal: ReadonlySet<T["status"]>,
-  fetchDetail: () => Promise<T>,
-): Promise<T> {
-  const startedAt = Date.now();
-  const tty = process.stderr.isTTY === true;
-  let lastLabel: string | undefined;
-  let sawProgress = false;
-
-  const report = (detail: T): void => {
-    if (ctx.json) {
-      return;
-    }
-    const label = deployProgressLabel(detail);
-    const elapsed = Math.round((Date.now() - startedAt) / 1000);
-    if (tty) {
-      ctx.err(`\r\x1b[2K${slug}: ${label} (${elapsed}s)`);
-      sawProgress = true;
-    } else if (label !== lastLabel) {
-      ctx.err(`${slug}: ${label}\n`);
-    }
-    lastLabel = label;
-  };
-  const finishProgressLine = (): void => {
-    if (tty && sawProgress) {
-      ctx.err("\n");
-    }
-  };
-
-  for (;;) {
-    let detail: T;
-    try {
-      detail = await fetchDetail();
-    } catch (error: unknown) {
-      // Capacity / rate-limit on GET is not a bake failure. The v2 accept
-      // already started freeze; keep polling until the wait budget expires.
-      if (isTransientDeployStatusError(error) && Date.now() - startedAt < ctx.timeoutMs) {
-        if (!ctx.json) {
-          const elapsed = Math.round((Date.now() - startedAt) / 1000);
-          const label = "Waiting for status (server busy)";
-          if (tty) {
-            ctx.err(`\r\x1b[2K${slug}: ${label} (${elapsed}s)`);
-            sawProgress = true;
-          } else if (label !== lastLabel) {
-            ctx.err(`${slug}: ${label}\n`);
-          }
-          lastLabel = label;
-        }
-        const waitMs = transientDeployStatusWaitMs(error, ctx.pollIntervalMs);
-        const remaining = ctx.timeoutMs - (Date.now() - startedAt);
-        await sleep(Math.max(0, Math.min(waitMs, remaining)));
-        continue;
-      }
-      finishProgressLine();
-      throw error;
-    }
-    report(detail);
-    if (terminal.has(detail.status)) {
-      finishProgressLine();
-      return detail;
-    }
-    if (Date.now() - startedAt >= ctx.timeoutMs) {
-      finishProgressLine();
-      const last = deployProgressLabel(detail);
-      throw new DeployApiError(
-        `Timed out after ${Math.round(ctx.timeoutMs / 1000)}s waiting for ${slug} (last: ${last}). It may still converge — check \`${CLI} deployment ${slug} --team ${ctx.teamId}\`.`,
-        0,
-      );
-    }
-    await sleep(ctx.pollIntervalMs);
-  }
-}
-
-/** Load-shed / rate-limit on status GET — the deploy itself may still be baking. */
-function isTransientDeployStatusError(error: unknown): error is DeployApiError {
-  return error instanceof DeployApiError && (error.status === 503 || error.status === 429);
-}
-
-function transientDeployStatusWaitMs(error: DeployApiError, pollIntervalMs: number): number {
-  if (
-    error.status === 429 &&
-    error.retryAfterSeconds !== undefined &&
-    error.retryAfterSeconds > 0
-  ) {
-    return Math.max(pollIntervalMs, error.retryAfterSeconds * 1000);
-  }
-  return pollIntervalMs;
-}
-
-/**
- * Wait until GET 404s (the delete reconciler purged the record). Treats
- * other errors as failures. Throws DeployApiError on timeout.
- */
-async function pollUntilGone(
-  ctx: DeployCliContext,
-  slug: string,
-  getDetail: () => Promise<{
-    status: string;
-    progress?: DeploymentProgress;
-    statusMessage?: string | null;
-  }>,
-): Promise<void> {
-  const startedAt = Date.now();
-  const tty = process.stderr.isTTY === true;
-  let sawProgress = false;
-  const report = (label: string): void => {
-    if (ctx.json) {
-      return;
-    }
-    const elapsed = Math.round((Date.now() - startedAt) / 1000);
-    if (tty) {
-      ctx.err(`\r\x1b[2K${slug}: ${label} (${elapsed}s)`);
-      sawProgress = true;
-    }
-  };
-  const finishProgressLine = (): void => {
-    if (tty && sawProgress) {
-      ctx.err("\n");
-    }
-  };
-
-  for (;;) {
-    try {
-      const detail = await getDetail();
-      report(deployProgressLabel(detail));
-    } catch (error: unknown) {
-      if (error instanceof DeployApiError && error.status === 404) {
-        finishProgressLine();
-        return;
-      }
-      finishProgressLine();
-      throw error;
-    }
-    if (Date.now() - startedAt >= ctx.timeoutMs) {
-      finishProgressLine();
-      throw new DeployApiError(
-        `Timed out after ${Math.round(ctx.timeoutMs / 1000)}s waiting for ${slug} to disappear. It may still be deleting — check \`${CLI} deployment ${slug} --team ${ctx.teamId}\`.`,
-        0,
-      );
-    }
-    await sleep(ctx.pollIntervalMs);
-  }
-}
-
-function aliasTokenBlock(aliasToken: string): string {
-  return (
-    `\n  Alias token (shown ONCE — save it now, it cannot be retrieved again):\n\n` +
-    `    ${aliasToken}\n\n` +
-    `  Send it as the X-Agent-Alias-Token header on requests to the alias URL,\n` +
-    `  or paste it into the hosted playground (<alias>/playground) sign-in gate.\n` +
-    `  Lost tokens: \`${CLI} rotate-token <slug>\` mints a replacement.\n\n`
-  );
-}
-
-/**
- * `: <reason>` suffix for a deploy that ended in a non-running state, or
- * empty when the control plane recorded no reason.
- */
-function deployFailureDetail(lastError: string | null | undefined): string {
-  if (lastError === null || lastError === undefined || lastError.trim() === "") {
-    return "";
-  }
-  return `: ${sanitizeCustomerError(lastError.trim())}`;
-}
-
-export function renderApiError(
-  error: unknown,
-  err: (text: string) => void,
-  context?: { multiTenant?: boolean; teamId?: number },
-): number {
-  if (error instanceof DeployApiError) {
-    err(`${error.message}\n`);
-    if (error.status === 409 && error.message.includes("application multiTenant does not match")) {
-      if (context?.multiTenant === true) {
-        err("This slug is a single-tenant application. Redeploy it without --multi-tenant.\n");
-      } else if (context?.teamId === MULTI_TENANT_HTTP_DEPLOY_TEAM_ID) {
-        err(
-          "This slug is a Cursor-managed (multi-tenant) product. Redeploy it with --multi-tenant.\n",
-        );
-      }
-    }
-    return 1;
-  }
-  throw error;
-}
-
-export function renderTable(header: string[], rows: string[][]): string {
-  const widths = header.map((h, i) =>
-    Math.max(h.length, ...rows.map(row => (row[i] ?? "").length)),
-  );
-  const renderRow = (row: string[]): string =>
-    row
-      .map((cell, i) => cell.padEnd(widths[i] ?? 0))
-      .join("  ")
-      .trimEnd();
-  return [renderRow(header), ...rows.map(renderRow)].join("\n");
-}