@cursor/july 0.1.95 → 0.1.97

package/src/channels/slack/tool-approval-events.ts

@@ -21,8 +21,11 @@
 import type { ChannelEventHandlers } from "../../types.js";
 import { postMessage, setThreadStatus, updateMessage } from "./api.js";
 import {
+  authThreadStatus,
   buildApprovalBlocks,
+  buildAuthBlocks,
   buildResolvedApprovalBlocks,
+  buildResolvedAuthBlocks,
 } from "./approvals.js";
 import { SLACK_DEFAULT_LOADING_MESSAGES } from "./constants.js";
 import { defaultSlackLog, type SlackLog } from "./log.js";
@@ -132,5 +135,95 @@ export function buildToolApprovalEvents(
         decision: event.data.decision,
       });
     },
+
+    async "action.auth_requested"(event, channel, ctx) {
+      const log = getLog();
+      const state = channel.state;
+      if (state.channelId === null || state.threadTs === null) {
+        return;
+      }
+      const blocks = buildAuthBlocks({
+        sessionId: ctx.session.id,
+        callId: event.data.callId,
+        toolName: event.data.toolName,
+        connection: event.data.connection,
+        authUrl: event.data.authUrl,
+      });
+      try {
+        const posted = await postMessage({
+          botToken,
+          channel: state.channelId,
+          threadTs: state.threadTs,
+          text: `Authorization required for \`${event.data.connection}\``,
+          blocks,
+        });
+        channel.state.approvalMessageByCallId = {
+          ...(state.approvalMessageByCallId ?? {}),
+          [event.data.callId]: posted.ts,
+        };
+        await setThreadStatus({
+          botToken,
+          channelId: state.channelId,
+          threadTs: state.threadTs,
+          status: authThreadStatus(event.data.connection),
+          loadingMessages: [
+            authThreadStatus(event.data.connection),
+            ...SLACK_DEFAULT_LOADING_MESSAGES,
+          ],
+        });
+        log.info("auth card posted", {
+          call_id: event.data.callId,
+          connection: event.data.connection,
+          message_ts: posted.ts,
+        });
+      } catch (error) {
+        log.warn("auth card post failed", {
+          call_id: event.data.callId,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    },
+
+    async "action.auth_resolved"(event, channel) {
+      const log = getLog();
+      const state = channel.state;
+      const messageTs = state.approvalMessageByCallId?.[event.data.callId];
+      if (
+        state.channelId !== null &&
+        messageTs !== undefined &&
+        messageTs !== ""
+      ) {
+        const blocks = buildResolvedAuthBlocks({
+          connection: event.data.connection,
+          decision: event.data.decision,
+          byUserId: event.data.by,
+        });
+        const verb =
+          event.data.decision === "approve" ? "Connected" : "Cancelled";
+        await updateMessage({
+          botToken,
+          channel: state.channelId,
+          ts: messageTs,
+          text: `${verb} — ${event.data.connection}`,
+          blocks,
+        });
+        const next = { ...(state.approvalMessageByCallId ?? {}) };
+        delete next[event.data.callId];
+        channel.state.approvalMessageByCallId = next;
+      }
+      if (state.channelId !== null && state.threadTs !== null) {
+        await setThreadStatus({
+          botToken,
+          channelId: state.channelId,
+          threadTs: state.threadTs,
+          status: "Working…",
+          loadingMessages: [...SLACK_DEFAULT_LOADING_MESSAGES],
+        });
+      }
+      log.info("auth resolved in slack", {
+        call_id: event.data.callId,
+        decision: event.data.decision,
+      });
+    },
   };
 }

package/src/evals/run-facts.ts

@@ -182,6 +182,38 @@ export function deriveRunFacts(events: readonly SessionEvent[]): EvalRunFacts {
         }
         break;
       }
+      case "action.auth_requested": {
+        const request: EvalInputRequestFact = {
+          callId: event.data.callId,
+          toolName: event.data.toolName,
+          args: {
+            connection: event.data.connection,
+            authUrl: event.data.authUrl,
+          },
+          resolved: false,
+        };
+        inputRequests.push(request);
+        inputRequestsByCallId.set(event.data.callId, request);
+        break;
+      }
+      case "action.auth_resolved": {
+        const request = inputRequestsByCallId.get(event.data.callId);
+        if (request !== undefined) {
+          request.resolved = true;
+          request.decision = event.data.decision;
+        }
+        const fact = ensureCall(
+          event.data.callId,
+          event.data.toolName,
+          event.turnId,
+          event.data.parentCallId
+        );
+        fact.approvalDecision = event.data.decision;
+        if (event.data.decision === "deny") {
+          fact.status = "rejected";
+        }
+        break;
+      }
       case "subagent.called": {
         const existing = subagentsByCallId.get(event.data.callId);
         if (existing === undefined) {

package/src/files-backends/cursor-hosted.ts

@@ -71,6 +71,19 @@ const AGENT_SERVE_FILES_PATH = "/v0/agent-serve-files";
 export const AGENT_SERVE_STORE_SOURCE_ID_ENV_VAR =
   "AGENT_SERVE_STORE_SOURCE_ID";
 
+/**
+ * The deployment's **framework-level** file store, distinct from the
+ * user-level store above. The user store carries author-facing bytes
+ * (`ctx.host.files`, skills, memory, artifacts) and is browsable and
+ * mountable; the framework store carries engine-owned session state —
+ * session records, event transcripts, continuation index, and the SDK
+ * conversation mirror — and is never exposed to authors or models.
+ * Provisioned by the v2 deploy pipeline alongside the user store; v1
+ * deployments have only the user store.
+ */
+export const AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_ENV_VAR =
+  "AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID";
+
 /** Cap on the per-process etag cache; a miss costs a lookup, not correctness. */
 const MAX_REMEMBERED_ETAGS = 1_000;
 
@@ -101,6 +114,20 @@ export function isCursorHostedFilesAvailable(
   return sourceId !== undefined && sourceId !== "";
 }
 
+/**
+ * The framework-level store's source id, or `undefined` when the deployment
+ * has none (v1, self-hosted, or a v2 deploy predating framework-store
+ * provisioning). Same detection posture as
+ * {@link isCursorHostedFilesAvailable}: keyed on the id alone — a missing
+ * credential must fail loudly at use, not silently deselect the store.
+ */
+export function cursorFrameworkStoreSourceId(
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  const sourceId = env[AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID_ENV_VAR]?.trim();
+  return sourceId === undefined || sourceId === "" ? undefined : sourceId;
+}
+
 /**
  * Local `serve`/`run` with a personal `CURSOR_API_KEY` can address
  * `/v0/agent-serve-files/user`. Hosted deployments have a store source id
@@ -125,12 +152,15 @@ export function isCursorUserStoreFilesAvailable(
 export interface CursorHostedFilesOptions {
   /** Control-plane base URL (default: `CURSOR_API_BASE_URL`, else api.cursor.com). */
   baseUrl?: string;
+  /** Bearer credential (default: `CURSOR_API_KEY`). */
+  apiKey?: string;
   /**
-   * Bearer credential (default: `CURSOR_API_KEY`). A function is re-resolved
-   * on every call — hosted freeze snapshots listen unsigned and bind the key
-   * file after serve start.
+   * Lazy credential, re-resolved on every call and preferred over
+   * {@link apiKey} — hosted freeze snapshots listen unsigned and bind the
+   * key file after serve start. Kept separate so `apiKey` stays a plain
+   * string.
    */
-  apiKey?: string | (() => string | undefined);
+  resolveApiKey?: () => string | undefined;
   /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
   storeSourceId?: string;
   /** Test seam; defaults to global fetch. */
@@ -253,7 +283,11 @@ export function cursorHostedFiles(
           }
           out.push(toEntry(file, file.path));
         }
-        return out;
+        // The FileSink contract promises key order, and transcript-chunk
+        // consumers depend on it (chunk keys are zero-padded so key order
+        // is append order). The server happens to scan in order today; do
+        // not let that be the only thing holding the contract.
+        return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
       }
       // The unscoped listing was truncated (`complete: false`) and has no
       // continuation to follow. `list()` promises the whole scope, so rather
@@ -626,8 +660,7 @@ function resolveStoreSourceId(options: CursorHostedFilesOptions): string {
 }
 
 function resolveApiKey(options: CursorHostedFilesOptions): string {
-  const configured =
-    typeof options.apiKey === "function" ? options.apiKey() : options.apiKey;
+  const configured = options.resolveApiKey?.() ?? options.apiKey;
   const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
   if (key === undefined || key === "") {
     throw new Error(

package/src/internal/advertise-tools.ts

@@ -27,6 +27,8 @@
  * `defineConnection({ effects })` filters the listing before names are
  * assigned: only tools whose MCP annotations classify as an intended
  * effect are advertised. Unclassified tools are omitted, not guessed.
+ * Tools whose `annotations.title` is `do-not-call` are dropped as well
+ * (vendor host-UI / MCP Apps helpers that still carry `readOnlyHint`).
  */
 
 import type {
@@ -116,26 +118,49 @@ export async function resolveAdvertisedTools(args: {
     return [];
   }
   const sourceFor = args.sourceFor ?? sourceForConnection;
+  // Each connection's listing is a network round trip against a distinct
+  // server (auth callback, MCP initialize, tools/list), so they run
+  // concurrently; the fan-out is bounded by the agent's declared
+  // connections. Name assignment below stays in declaration order so
+  // collision suffixes do not depend on which server answered first.
+  type Listing =
+    | {
+        connection: DiscoveredConnection;
+        ok: true;
+        source: AdvertisedToolSource;
+        listed: HostMcpToolInfo[];
+      }
+    | { connection: DiscoveredConnection; ok: false; error: unknown };
+  const listings = await Promise.all(
+    advertising.map(async (connection): Promise<Listing> => {
+      try {
+        const source = await sourceFor(connection, args.session, args.hostMcp);
+        const listed = await source.listTools();
+        return { connection, ok: true, source, listed };
+      } catch (error) {
+        return { connection, ok: false, error };
+      }
+    })
+  );
   const claimed = new Set(args.agent.tools.map((tool) => tool.name));
   const resolved: DiscoveredTool[] = [];
-  for (const connection of advertising) {
-    let listed: HostMcpToolInfo[];
-    let source: AdvertisedToolSource;
-    try {
-      source = await sourceFor(connection, args.session, args.hostMcp);
-      listed = await source.listTools();
-    } catch (error) {
+  for (const listing of listings) {
+    const { connection } = listing;
+    if (!listing.ok) {
       if (args.onConnectionError !== undefined) {
-        args.onConnectionError(connection.name, error);
+        args.onConnectionError(connection.name, listing.error);
         continue;
       }
       throw new Error(
-        `Failed to list tools on advertised connection "${connection.name}": ${describeError(error)}`,
-        { cause: error }
+        `Failed to list tools on advertised connection "${connection.name}": ${describeError(listing.error)}`,
+        { cause: listing.error }
       );
     }
-    const intended = listed.filter((info) =>
-      matchesIntendedEffects(info.annotations, connection.effects)
+    const { source, listed } = listing;
+    const intended = listed.filter(
+      (info) =>
+        !isDoNotCallTool(info.annotations) &&
+        matchesIntendedEffects(info.annotations, connection.effects)
     );
     const exposed = exposeListedTools(intended, claimed);
     for (const { info, exposedName } of exposed) {
@@ -232,6 +257,18 @@ function exposeListedTools(
   }));
 }
 
+/**
+ * Vendors (Datadog MCP Apps) stamp host-UI-only helpers with this title.
+ * They still look like reads (`readOnlyHint: true`), so the effects
+ * filter would keep them. The model and agsh should not see them; the
+ * raw MCP listing stays intact for the host.
+ */
+const DO_NOT_CALL_TITLE = "do-not-call";
+
+function isDoNotCallTool(annotations: McpToolAnnotations | undefined): boolean {
+  return annotations?.title?.trim() === DO_NOT_CALL_TITLE;
+}
+
 function matchesIntendedEffects(
   annotations: McpToolAnnotations | undefined,
   effects: readonly ToolEffect[] | undefined

package/src/internal/approval-gate.ts

@@ -1,13 +1,12 @@
 /**
- * In-memory gate for human-in-the-loop tool approvals. The session
- * engine parks inside a server-tool `execute` by awaiting
- * {@link ApprovalGate.wait}; HTTP (or the playground) unblocks via
- * {@link ApprovalGate.resolve}.
+ * In-memory gate for human-in-the-loop parks. The session engine parks
+ * inside a server-tool `execute` by awaiting {@link ApprovalGate.wait};
+ * HTTP (or the playground) unblocks via {@link ApprovalGate.resolve}.
  *
- * Pending approvals are also mirrored onto {@link SessionRecord} for
- * durability of the *list* across reloads. After a process restart the
- * in-flight SDK tool callback is gone, so resolve returns false and
- * the host treats the approval as interrupted.
+ * Used for `needsApproval` and MCP on-demand auth. Pending rows are also
+ * mirrored onto {@link SessionRecord} for durability of the *list* across
+ * reloads. After a process restart the in-flight SDK tool callback is gone,
+ * so resolve returns false and the host treats the park as interrupted.
  */
 
 import type { ApprovalDecision, PendingApproval } from "../types.js";
@@ -21,33 +20,25 @@ export interface ApprovalResolution {
   by?: string;
 }
 
-interface Waiter {
-  meta: PendingApproval;
+interface Waiter<T> {
+  meta: T;
   resolve: (resolution: ApprovalResolution) => void;
 }
 
-export class ApprovalGate {
-  private readonly waiters = new Map<string, Waiter>();
+export class ApprovalGate<T extends { callId: string } = PendingApproval> {
+  private readonly waiters = new Map<string, Waiter<T>>();
 
-  wait(
-    meta: PendingApproval & { sessionId: string }
-  ): Promise<ApprovalResolution> {
-    const key = approvalKey(meta.sessionId, meta.callId);
+  wait(sessionId: string, meta: T): Promise<ApprovalResolution> {
+    const key = approvalKey(sessionId, meta.callId);
     const existing = this.waiters.get(key);
     if (existing !== undefined) {
       throw new Error(
-        `Approval already pending for session ${meta.sessionId} call ${meta.callId}`
+        `Approval already pending for session ${sessionId} call ${meta.callId}`
       );
     }
     return new Promise<ApprovalResolution>((resolveDecision) => {
       this.waiters.set(key, {
-        meta: {
-          callId: meta.callId,
-          turnId: meta.turnId,
-          toolName: meta.toolName,
-          args: meta.args,
-          requestedAt: meta.requestedAt,
-        },
+        meta,
         resolve: resolveDecision,
       });
     });
@@ -69,11 +60,11 @@ export class ApprovalGate {
       return false;
     }
     this.waiters.delete(key);
+    const by =
+      resolvedBy === undefined || resolvedBy === "" ? undefined : resolvedBy;
     waiter.resolve({
       decision,
-      ...(resolvedBy === undefined || resolvedBy === ""
-        ? {}
-        : { by: resolvedBy }),
+      by,
     });
     return true;
   }
@@ -82,9 +73,9 @@ export class ApprovalGate {
     return this.waiters.has(approvalKey(sessionId, callId));
   }
 
-  list(sessionId: string): PendingApproval[] {
+  list(sessionId: string): T[] {
     const prefix = `${sessionId}\0`;
-    const out: PendingApproval[] = [];
+    const out: T[] = [];
     for (const [key, waiter] of this.waiters) {
       if (key.startsWith(prefix)) {
         out.push(waiter.meta);

package/src/internal/bounded.ts

@@ -0,0 +1,28 @@
+/**
+ * Bounded-concurrency map, in input order. Local rather than
+ * `@anysphere/utils`: this published package cannot depend on monorepo
+ * internals.
+ */
+export async function mapBounded<T, R>(
+  items: readonly T[],
+  max: number,
+  run: (item: T) => Promise<R>
+): Promise<R[]> {
+  const out = new Array<R>(items.length);
+  let nextIndex = 0;
+  const workers = Array.from(
+    { length: Math.min(max, items.length) },
+    async () => {
+      for (;;) {
+        const index = nextIndex;
+        nextIndex += 1;
+        if (index >= items.length) {
+          return;
+        }
+        out[index] = await run(items[index] as T);
+      }
+    }
+  );
+  await Promise.all(workers);
+  return out;
+}

package/src/internal/chat-client.ts

@@ -483,6 +483,25 @@ async function streamTurn(args: StreamTurnArgs): Promise<number> {
         );
         continue;
       }
+      if (event.type === "action.auth_requested") {
+        closeAssistant();
+        write(
+          `    ${c.yellow("⏸")} ${c.bold(event.data.connection)} ${c.dim(
+            "awaiting MCP authorization"
+          )}\n`
+        );
+        continue;
+      }
+      if (event.type === "action.auth_resolved") {
+        const mark =
+          event.data.decision === "approve" ? c.green("✓") : c.red("✗");
+        write(
+          `    ${mark} ${c.bold(event.data.connection)} ${c.dim(
+            event.data.decision === "approve" ? "connected" : "denied"
+          )}\n`
+        );
+        continue;
+      }
       if (event.type === "action.result") {
         if (
           event.data.toolName === "task" &&

package/src/internal/cli-deploy.ts

@@ -49,6 +49,8 @@ import {
 import { type GitRunner, inferDeployGitSource } from "./deploy-source.js";
 import {
   type ChildAgentDir,
+  formatDiagnostics,
+  hasErrorDiagnostics,
   isAgentProjectDir,
   listChildAgentDirs,
   loadAgentProject,
@@ -110,6 +112,11 @@ export interface DeployCliOptions {
   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. Cannot create a new multi-tenant application.
+   */
+  multiTenant?: boolean;
   /** Test seams. */
   fetchImpl?: typeof fetch;
   /** Inject the connector-auth browser opener (tests; also forces interactive). */
@@ -309,7 +316,9 @@ export async function cmdDeploy(options: DeployCliOptions): Promise<number> {
     manifests.push(await readDeployManifest(target.dir));
   }
   if (manifests.every((manifest) => manifest.architecture === "v2")) {
-    return deployAgentsdkApplication(ctx, options, targets);
+    return deployAgentsdkApplication(ctx, options, targets, {
+      hasScmChannels: manifests.some((manifest) => manifest.hasScmChannels),
+    });
   }
   if (
     !ctx.json &&
@@ -720,9 +729,18 @@ async function deployOne(
       gitRef,
       agentPath,
       repositories: options.cursorEventsRepos,
+      hasScmChannels: manifest.hasScmChannels,
+      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 = {
@@ -802,11 +820,9 @@ async function deployOne(
   }
 
   if (detail.status !== "running") {
-    const errorDetail =
-      detail.lastError === null || detail.lastError === undefined
-        ? ""
-        : `: ${sanitizeCustomerError(detail.lastError)}`;
-    ctx.err(`Deployment ${slug} ended ${detail.status}${errorDetail}\n`);
+    ctx.err(
+      `Deployment ${slug} ended ${detail.status}${deployFailureDetail(detail.lastError)}\n`
+    );
     return 1;
   }
   const deployedPublicRoutes = detail.publicRoutePaths ?? [];
@@ -843,7 +859,8 @@ async function deployOne(
 async function deployAgentsdkApplication(
   ctx: DeployCliContext,
   options: DeployCliOptions,
-  targets: readonly DeployTarget[]
+  targets: readonly DeployTarget[],
+  declarations: { hasScmChannels: boolean }
 ): Promise<number> {
   const parentDir = resolve(options.dir ?? ".");
   const slug = slugFromDirectoryName(basename(parentDir));
@@ -924,6 +941,8 @@ async function deployAgentsdkApplication(
     agentPath: undefined,
     components,
     repositories: options.cursorEventsRepos,
+    hasScmChannels: declarations.hasScmChannels,
+    multiTenant: options.multiTenant === true,
   });
 }
 
@@ -942,6 +961,10 @@ async function deployOneAgentsdk(
     agentPath: string | undefined;
     components?: AgentkitDeployComponent[];
     repositories: string[] | undefined;
+    /** Any component declares a GitHub/Origin channel. */
+    hasScmChannels: boolean;
+    /** Redeploy an existing Cursor-managed product. */
+    multiTenant: boolean;
   }
 ): Promise<number> {
   const { slug } = args;
@@ -951,6 +974,9 @@ async function deployOneAgentsdk(
       : `  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({
@@ -961,6 +987,7 @@ async function deployOneAgentsdk(
       agentPath: args.agentPath,
       components: args.components,
       repositories: args.repositories,
+      ...(args.multiTenant ? { multiTenant: true } : {}),
     });
   } catch (error) {
     return renderApiError(error, ctx.err);
@@ -1002,7 +1029,9 @@ async function deployOneAgentsdk(
   }
 
   if (detail.status !== "running") {
-    ctx.err(`Deployment ${slug} ended ${detail.status}\n`);
+    ctx.err(
+      `Deployment ${slug} ended ${detail.status}${deployFailureDetail(detail.lastError)}\n`
+    );
     return 1;
   }
   ctx.out(
@@ -1015,8 +1044,19 @@ async function deployOneAgentsdk(
         ? ""
         : `  components:   ${args.components
             .map((component) => component.componentKey)
-            .join(", ")}\n`)
+            .join(", ")}\n`) +
+      (detail.repositories === undefined || !args.hasScmChannels
+        ? ""
+        : `  watching:     ${detail.repositories.length === 0 ? "(nothing)" : detail.repositories.join(", ")}\n`)
   );
+  // An agent with GitHub/Origin channels bound to no repository scope gets
+  // no deliveries at all, which is otherwise invisible in this output.
+  if (args.hasScmChannels && detail.repositories?.length === 0) {
+    ctx.err(
+      `warning: ${slug} watches no repositories, so its GitHub/Origin channels receive no events.\n` +
+        `  Redeploy with --cursor-events-repo <owner>/<name> to set the scope.\n`
+    );
+  }
   return 0;
 }
 
@@ -1126,6 +1166,11 @@ interface DeployManifest {
    * (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;
 }
 
 /**
@@ -1135,6 +1180,16 @@ interface DeployManifest {
  */
 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,
@@ -1151,6 +1206,10 @@ async function readDeployManifest(dir: string): Promise<DeployManifest> {
     httpChannelPublicEndpoint: (project.httpChannel.auth ?? []).some(
       isPublicEndpointPolicy
     ),
+    hasScmChannels: project.channels.some((channel) => {
+      const kind = channel.definition.meta?.kind;
+      return kind === "github" || kind === "origin";
+    }),
   };
 }
 
@@ -1926,9 +1985,32 @@ function aliasTokenBlock(aliasToken: string): string {
   );
 }
 
+/**
+ * `: <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())}`;
+}
+
 function renderApiError(error: unknown, err: (text: string) => void): number {
   if (error instanceof DeployApiError) {
     err(`${error.message}\n`);
+    if (
+      error.status === 409 &&
+      error.message.includes("application multiTenant does not match")
+    ) {
+      err(
+        "This slug is a Cursor-managed (multi-tenant) product. Redeploy it with --multi-tenant.\n"
+      );
+    }
     return 1;
   }
   throw error;