@mycadet/cli 0.12.7 → 0.12.9-dev.202610131452.9acab64

package/src/lib/hatch-local.ts

@@ -21,6 +21,7 @@ import {
   setActiveAssistant,
 } from "./assistant-config.js";
 import type { AssistantEntry } from "./assistant-config.js";
+import { green, yellow } from "./color.js";
 import { buildHatchConfigValues, writeInitialConfig } from "./config-utils.js";
 import {
   generateLocalSigningKey,
@@ -32,7 +33,10 @@ import {
 } from "./local.js";
 
 import { generateInstanceName } from "./random-name.js";
-import { leaseGuardianToken } from "./guardian-token.js";
+import {
+  GuardianLeasePermanentError,
+  leaseGuardianToken,
+} from "./guardian-token.js";
 import { archiveLogFile, resetLogFile } from "./xdg-log.js";
 import {
   consoleLifecycleReporter,
@@ -54,7 +58,7 @@ import {
   ensureCloudLoginInteractive,
   registerLocalAssistantWithPlatform,
 } from "./cloud-login.js";
-import { fetchCurrentUser, readPlatformToken } from "./platform-client.js";
+import { fetchCurrentUser, readCloudToken } from "./cloud-client.js";
 import { withLocalHatchLock } from "./local-hatch-lock.js";
 
 /**
@@ -185,8 +189,6 @@ export interface HatchLocalResult {
   guardianAccessToken?: string;
 }
 
-
-
 export async function hatchLocal(
   params: HatchLocalParams = {},
 ): Promise<HatchLocalResult> {
@@ -199,8 +201,7 @@ export async function hatchLocal(
   } = params;
   const reporter = params.reporter ?? consoleLifecycleReporter;
   const verbose = params.verbose ?? false;
-  const setupProviderCredentials =
-    params.setupProviderCredentials !== false;
+  const setupProviderCredentials = params.setupProviderCredentials !== false;
   setStartupLogging(verbose);
   let provider = setupProviderCredentials
     ? resolveHatchProvider(configValues)
@@ -226,12 +227,7 @@ export async function hatchLocal(
 
       const resources = await allocateLocalResources(instanceName);
 
-      const logsDir = join(
-        resources.instanceDir,
-        "workspace",
-        "data",
-        "logs",
-      );
+      const logsDir = join(resources.instanceDir, "workspace", "data", "logs");
       archiveLogFile("hatch.log", logsDir);
       resetLogFile("hatch.log");
 
@@ -263,7 +259,7 @@ export async function hatchLocal(
             picked === "cadet" &&
             !process.env.CADET_DESKTOP_APP &&
             process.stdin.isTTY &&
-            !readPlatformToken()
+            !readCloudToken()
           ) {
             reporter.log("");
             reporter.log(
@@ -276,9 +272,7 @@ export async function hatchLocal(
               reporter.warn(
                 `⚠️  Cadet Cloud login failed: ${describeLoginError(error)}`,
               );
-              reporter.warn(
-                "   You can retry later with `cadet login`.",
-              );
+              reporter.warn("   You can retry later with `cadet login`.");
             }
           }
         }
@@ -380,17 +374,24 @@ export async function hatchLocal(
       guardianAccessToken = tokenData.accessToken;
       break;
     } catch (err) {
-      if (attempt < maxLeaseAttempts) {
+      if (
+        attempt < maxLeaseAttempts &&
+        !(err instanceof GuardianLeasePermanentError)
+      ) {
         const delayMs = 2000 * 2 ** (attempt - 1);
         reporter.error(
-          `⚠️  Guardian token lease attempt ${attempt}/${maxLeaseAttempts} failed — retrying in ${delayMs / 1000}s: ${err}`,
+          yellow(
+            `⚠️  Guardian token lease attempt ${attempt}/${maxLeaseAttempts} failed — retrying in ${delayMs / 1000}s: ${err}`,
+          ),
         );
         await new Promise((r) => setTimeout(r, delayMs));
       } else {
         reporter.error(
-          `⚠️  Guardian token lease failed after ${maxLeaseAttempts} attempts: ${err}\n` +
-            `   The assistant is running but guardian-token.json was not written.\n` +
-            `   If the desktop app loses its stored credentials, re-hatch to recover.`,
+          yellow(
+            `⚠️  Guardian token lease failed${err instanceof GuardianLeasePermanentError ? ", not retrying — a malformed 200 will not fix itself" : ` after ${maxLeaseAttempts} attempts`}: ${err}\n` +
+              `   The assistant is running but guardian-token.json was not written.\n` +
+              `   Run \`cadet restart ${JSON.stringify(instanceName)} --repair-guardian\` to re-lease a token.`,
+          ),
         );
       }
     }
@@ -402,8 +403,10 @@ export async function hatchLocal(
 
   if (provider !== undefined && provider !== null && !guardianAccessToken) {
     reporter.error(
-      `⚠️  Provider credential setup skipped because the guardian token was not leased.\n` +
-        `   The assistant is still hatched. Run \`cadet setup --provider ${provider}\` after fixing the connection.`,
+      yellow(
+        `⚠️  Provider credential setup skipped because the guardian token was not leased.\n` +
+          `   The assistant is still hatched. Run \`cadet setup --provider ${provider}\` after fixing the connection.`,
+      ),
     );
   } else if (provider !== undefined) {
     await configureHatchProviderApiKey({
@@ -415,13 +418,13 @@ export async function hatchLocal(
     });
   }
 
-  // Picking Cadet Cloud ends with the assistant registered on the platform
+  // Picking Cadet Cloud ends with the assistant registered on the cloud
   // and its cloud credentials injected — the same post-login flow
-  // `cadet login` runs — so messages route through the managed connection
+  // `cadet login` runs — so messages route through the cloud connection
   // immediately after hatch. Non-fatal: the assistant is up either way.
-  if (provider === "cadet" && readPlatformToken()) {
+  if (provider === "cadet" && readCloudToken()) {
     try {
-      const token = readPlatformToken()!;
+      const token = readCloudToken()!;
       const user = await fetchCurrentUser(token);
       await registerLocalAssistantWithPlatform(token, user, {
         bearerToken: guardianAccessToken,
@@ -433,7 +436,7 @@ export async function hatchLocal(
   }
 
   reporter.log("");
-  reporter.log(`✅ Local assistant hatched!`);
+  reporter.log(green(`✅ Local assistant hatched!`, process.stdout));
   printInstanceDetails(
     {
       name: instanceName,
@@ -442,7 +445,7 @@ export async function hatchLocal(
     },
     (message) => reporter.log(message),
   );
-  logHatchNextSteps((message) => reporter.log(message), verbose);
+  logHatchNextSteps((message) => reporter.log(message));
 
   const result: HatchLocalResult = {
     assistantId: instanceName,

package/src/lib/hatch-next-steps.ts

@@ -1,12 +1,8 @@
-export function logHatchNextSteps(
-  log: (message: string) => void,
-  verbose = false,
-): void {
+export function logHatchNextSteps(log: (message: string) => void): void {
   log("Next steps:");
-  log("  cadet client");
-  if (verbose) {
-    log('  cadet message "hello"');
-    log("  cadet events");
-  }
+  log("  - Run `cadet client` to interact with your cadet via the terminal");
+  log(
+    "  - Run `cadet tunnel` to make your cadet publicly accessible and interact with it via the browser",
+  );
   log("");
 }

package/src/lib/health-check.ts

@@ -19,8 +19,8 @@ export async function checkManagedHealth(
   runtimeUrl: string,
   assistantId: string,
 ): Promise<HealthCheckResult> {
-  const { readPlatformToken } = await import("./platform-client.js");
-  const token = readPlatformToken();
+  const { readCloudToken } = await import("./cloud-client.js");
+  const token = readCloudToken();
   if (!token) {
     return {
       status: "error (auth)",
@@ -30,7 +30,7 @@ export async function checkManagedHealth(
 
   let headers: Record<string, string>;
   try {
-    const { authHeaders } = await import("./platform-client.js");
+    const { authHeaders } = await import("./cloud-client.js");
     headers = await authHeaders(token, runtimeUrl);
   } catch (err) {
     return {
@@ -130,9 +130,9 @@ export async function fetchManagedPs(
   runtimeUrl: string,
   assistantId: string,
 ): Promise<ManagedPsResponse | null> {
-  const { readPlatformToken, authHeaders } =
-    await import("./platform-client.js");
-  const token = readPlatformToken();
+  const { readCloudToken, authHeaders } =
+    await import("./cloud-client.js");
+  const token = readCloudToken();
   if (!token) return null;
 
   let headers: Record<string, string>;

package/src/lib/ingress-config.ts

@@ -18,14 +18,13 @@ import { getStateDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 
 /**
- * Shared workspace-config helpers for tunnel providers (ngrok, cloudflare,
- * tailscale) and the nginx ingress proxy. Each provider fronts the local edge
- * and records the resulting public URL under `ingress.publicBaseUrl` so webhook
- * integrations can reach the assistant. The workspace config is the
- * gateway-facing contract; when an `assistantId` is supplied, the URL is also
- * mirrored onto the lockfile entry (`ingressUrl`) — the CLI-owned contract
- * that CLI features (e.g. remote-web pairing defaults) read, per the
- * no-`.cadet/`-reads boundary in cli/AGENTS.md.
+ * Shared workspace-config helpers for tunnel providers and the nginx ingress
+ * proxy. Each provider fronts the local edge and records the resulting public
+ * URL under `ingress.publicBaseUrl` so webhook integrations can reach the
+ * assistant. The workspace config is the gateway-facing contract; when an
+ * `assistantId` is supplied, the URL is also mirrored onto the lockfile entry
+ * (`ingressUrl`) — the CLI-owned contract that CLI features (e.g. remote-web
+ * pairing defaults) read, per the no-`.cadet/`-reads boundary in cli/AGENTS.md.
  */
 
 function parsePortFromUrl(url: unknown): number | undefined {
@@ -48,7 +47,7 @@ export function isLocalContainerEntry(entry: AssistantEntry): boolean {
 /**
  * Derive the gateway port from an entry's recorded URLs, preferring the
  * loopback `localUrl` over `runtimeUrl`. Undefined when neither carries an
- * explicit port (e.g. a platform-hosted https runtime URL).
+ * explicit port (e.g. a cloud-hosted https runtime URL).
  */
 export function parseGatewayPortFromEntryUrls(
   entry: AssistantEntry | undefined,
@@ -186,32 +185,6 @@ export function savePairingTunnel(
   saveRawConfig(workspaceDir, config);
 }
 
-/** Persist a reserved ngrok domain under `ingress.ngrok.domain`; null clears it. */
-export function saveNgrokDomain(
-  workspaceDir: string,
-  domain: string | null,
-): void {
-  const config = loadRawConfig(workspaceDir);
-  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
-  if (domain) {
-    ingress.ngrok = { domain };
-  } else {
-    delete ingress.ngrok;
-  }
-  config.ingress = ingress;
-  saveRawConfig(workspaceDir, config);
-}
-
-/** Read the reserved ngrok domain from the workspace config, if saved. */
-export function loadNgrokDomain(workspaceDir: string): string | null {
-  const ingress = loadRawConfig(workspaceDir).ingress as
-    | Record<string, unknown>
-    | undefined;
-  const ngrok = ingress?.ngrok as Record<string, unknown> | undefined;
-  const domain = ngrok?.domain;
-  return typeof domain === "string" && domain.trim() ? domain : null;
-}
-
 /** Clear the ingress public base URL from the workspace config. */
 export function clearIngressUrl(
   workspaceDir: string,

package/src/lib/job-polling.ts

@@ -1,4 +1,4 @@
-import type { UnifiedJobStatus } from "./platform-client.js";
+import type { UnifiedJobStatus } from "./cloud-client.js";
 
 /**
  * Terminal status returned by {@link pollJobUntilDone}. Callers decide
@@ -166,7 +166,7 @@ export async function pollJobUntilDone(
         throw err;
       }
       const msg = err instanceof Error ? err.message : String(err);
-      console.warn(`${options.label} polling failed, retrying... (${msg})`);
+      console.warn(`${options.label} polling failed: ${msg}. Retrying...`);
       if (Date.now() >= deadline) {
         throw new Error(
           `Timed out waiting for ${options.label} after ${Math.round(

package/src/lib/live-voice/connection.ts

@@ -25,7 +25,7 @@
  * passes by construction, and there is nothing new to provision here.
  */
 
-import { isManagedCloud } from "../managed-cloud.js";
+import { isCloudHome } from "../cloud-values.js";
 import {
   formatAssistantLookupError,
   formatAssistantReference,
@@ -33,7 +33,7 @@ import {
   resolveTargetAssistant,
   type AssistantEntry,
 } from "../assistant-config.js";
-import { getPlatformUrl, readPlatformToken } from "../platform-client.js";
+import { getCloudUrl, readCloudToken } from "../cloud-client.js";
 import {
   guardianTokenDueForRenewal,
   loadGuardianToken,
@@ -88,11 +88,11 @@ export async function resolveLiveVoiceConnection(
     ? resolveNamedAssistant(assistantIdArg)
     : resolveTargetAssistant();
 
-  // Platform-cloud assistants are reached the other way round. Their gateway
+  // Cloud assistants are reached the other way round. Their gateway
   // is behind tunnel, which authenticates nobody and forwards an attestation
   // the gateway trusts, so the credential is not the guardian JWT below but a
-  // WS token minted from the platform session the CLI already holds.
-  if (isManagedCloud(entry.cloud)) {
+  // WS token minted from the cloud session the CLI already holds.
+  if (isCloudHome(entry.cloud)) {
     return await resolveCloudConnection(entry);
   }
 
@@ -126,7 +126,7 @@ export async function resolveLiveVoiceConnection(
 }
 
 /**
- * Resolve a live-voice connection to a platform-hosted assistant.
+ * Resolve a live-voice connection to a cloud-hosted assistant.
  *
  * The session token is the CLI's own cloud login, not anything specific to
  * this assistant, so a missing one is a `cadet login` problem rather than an
@@ -139,7 +139,7 @@ export async function resolveLiveVoiceConnection(
 async function resolveCloudConnection(
   entry: AssistantEntry,
 ): Promise<LiveVoiceConnection> {
-  const sessionToken = readPlatformToken();
+  const sessionToken = readCloudToken();
   if (!sessionToken) {
     throw new LiveVoiceConnectionError(
       `${formatAssistantReference(entry)} is a Cadet cloud assistant, which ` +
@@ -147,10 +147,10 @@ async function resolveCloudConnection(
     );
   }
 
-  // `runtimeUrl` is the platform this entry was hatched against, which is the
-  // one that can mint for it. `getPlatformUrl()` is the fallback for an entry
+  // `runtimeUrl` is the cloud this entry was hatched against, which is the
+  // one that can mint for it. `getCloudUrl()` is the fallback for an entry
   // written before that field was recorded.
-  const platformUrl = (entry.runtimeUrl || getPlatformUrl()).replace(
+  const cloudUrl = (entry.runtimeUrl || getCloudUrl()).replace(
     /\/+$/,
     "",
   );
@@ -158,7 +158,7 @@ async function resolveCloudConnection(
   let token: string;
   try {
     token = await mintTunnelWsToken({
-      platformUrl,
+      cloudUrl,
       assistantId: entry.assistantId,
       sessionToken,
     });
@@ -171,7 +171,7 @@ async function resolveCloudConnection(
 
   return {
     url: buildTunnelLiveVoiceUrl({
-      platformUrl,
+      cloudUrl,
       assistantId: entry.assistantId,
       token,
     }),

package/src/lib/live-voice/tunnel.test.ts

@@ -2,7 +2,7 @@ import { afterEach, describe, expect, test } from "bun:test";
 
 import {
   buildTunnelLiveVoiceUrl,
-  tunnelHostForPlatformUrl,
+  tunnelHostForCloudUrl,
   tunnelWsScheme,
 } from "./tunnel.js";
 
@@ -16,13 +16,13 @@ afterEach(() => {
   }
 });
 
-describe("tunnelHostForPlatformUrl", () => {
-  test("maps a platform host onto its environment's tunnel", () => {
+describe("tunnelHostForCloudUrl", () => {
+  test("maps a cloud host onto its environment's tunnel", () => {
     delete process.env.CADET_TUNNEL_HOST;
-    expect(tunnelHostForPlatformUrl("https://cloud.mycadet.ai")).toBe(
+    expect(tunnelHostForCloudUrl("https://cloud.mycadet.ai")).toBe(
       "tunnel.mycadet.ai",
     );
-    expect(tunnelHostForPlatformUrl("https://dev-cloud.mycadet.ai")).toBe(
+    expect(tunnelHostForCloudUrl("https://dev-cloud.mycadet.ai")).toBe(
       "tunnel-dev.mycadet.ai",
     );
   });
@@ -31,15 +31,15 @@ describe("tunnelHostForPlatformUrl", () => {
     delete process.env.CADET_TUNNEL_HOST;
     // A local platform predicts no tunnel of its own; guessing one would be
     // worse than dialing the host that certainly exists.
-    expect(tunnelHostForPlatformUrl("http://localhost:8000")).toBe(
+    expect(tunnelHostForCloudUrl("http://localhost:8000")).toBe(
       "tunnel.mycadet.ai",
     );
-    expect(tunnelHostForPlatformUrl("not a url")).toBe("tunnel.mycadet.ai");
+    expect(tunnelHostForCloudUrl("not a url")).toBe("tunnel.mycadet.ai");
   });
 
   test("the env override wins, which is how a local vel up tunnel is reached", () => {
     process.env.CADET_TUNNEL_HOST = "localhost:8501";
-    expect(tunnelHostForPlatformUrl("https://cloud.mycadet.ai")).toBe(
+    expect(tunnelHostForCloudUrl("https://cloud.mycadet.ai")).toBe(
       "localhost:8501",
     );
   });
@@ -58,7 +58,7 @@ describe("buildTunnelLiveVoiceUrl", () => {
     delete process.env.CADET_TUNNEL_HOST;
     const url = new URL(
       buildTunnelLiveVoiceUrl({
-        platformUrl: "https://cloud.mycadet.ai",
+        cloudUrl: "https://cloud.mycadet.ai",
         assistantId: "01a02514-e452-7019-88d5-30828f42cf17",
         token: "tok_abc",
       }),
@@ -76,7 +76,7 @@ describe("buildTunnelLiveVoiceUrl", () => {
     delete process.env.CADET_TUNNEL_HOST;
     const url = new URL(
       buildTunnelLiveVoiceUrl({
-        platformUrl: "https://cloud.mycadet.ai",
+        cloudUrl: "https://cloud.mycadet.ai",
         assistantId: "a1",
         token: "a+b/c=&d",
       }),
@@ -88,7 +88,7 @@ describe("buildTunnelLiveVoiceUrl", () => {
     process.env.CADET_TUNNEL_HOST = "localhost:8501";
     const url = new URL(
       buildTunnelLiveVoiceUrl({
-        platformUrl: "http://localhost:8000",
+        cloudUrl: "http://localhost:8000",
         assistantId: "a1",
         token: "t",
       }),

package/src/lib/live-voice/tunnel.ts

@@ -2,17 +2,17 @@
  * The cloud leg of a live-voice session: minting a tunnel WS token and building
  * the URL it opens.
  *
- * A platform-hosted assistant is not reachable the way a local one is. Its
+ * A cloud-hosted assistant is not reachable the way a local one is. Its
  * gateway sits behind tunnel, tunnel performs no user authentication of its own,
  * and the gateway upstream accepts only an actor edge JWT or a tunnel
  * attestation. The CLI holds neither for a cloud instance: what it has is a
  * platform session token, which is the wrong credential for the socket but the
- * right one for the platform.
+ * right one for the cloud.
  *
  * So the connection is made in two hops, the same two the web voice room makes
  * (`clients/web/src/domains/chat/voice/live-voice/connection.ts`):
  *
- *  1. POST the platform for a short-lived, org+assistant-scoped WS token.
+ *  1. POST the cloud for a short-lived, org+assistant-scoped WS token.
  *  2. Open `wss://<tunnel>/<assistantId>/v1/live-voice?token=<wsToken>`.
  *
  * tunnel consumes the token on the upgrade and injects the authenticated user
@@ -30,9 +30,9 @@
 
 import { tunnelHostForPlatformHost } from "@mycadet/service-contracts/ingress";
 
-import { authHeaders } from "../platform-client.js";
+import { authHeaders } from "../cloud-client.js";
 
-/** Production tunnel, when the platform host implies nothing more specific. */
+/** Production tunnel, when the cloud host implies nothing more specific. */
 const DEFAULT_TUNNEL_HOST = "tunnel.mycadet.ai";
 
 /** Give up on the mint rather than hang the session behind a stalled platform. */
@@ -53,20 +53,20 @@ export class TunnelWsTokenError extends Error {
  *
  * `CADET_TUNNEL_HOST` wins when set, which is how a local `vel up` stack is
  * reached: its tunnel is a loopback port that no naming convention predicts.
- * Otherwise the deployment convention maps the platform host onto its sibling
+ * Otherwise the deployment convention maps the cloud host onto its sibling
  * (`cloud.mycadet.ai` to `tunnel.mycadet.ai`, `dev-cloud.mycadet.ai` to
  * `tunnel-dev.mycadet.ai`). A host outside that convention, including localhost,
  * yields the production default, because guessing a tunnel for it would be
  * worse than dialing the one host that certainly exists.
  */
-export function tunnelHostForPlatformUrl(platformUrl: string): string {
+export function tunnelHostForCloudUrl(cloudUrl: string): string {
   const override = process.env.CADET_TUNNEL_HOST?.trim();
   if (override) {
     return override;
   }
   try {
     return (
-      tunnelHostForPlatformHost(new URL(platformUrl).host) ??
+      tunnelHostForPlatformHost(new URL(cloudUrl).host) ??
       DEFAULT_TUNNEL_HOST
     );
   } catch {
@@ -106,11 +106,11 @@ export function tunnelWsScheme(host: string): "ws" | "wss" {
  * credential anywhere tunnel reads except the query string.
  */
 export function buildTunnelLiveVoiceUrl(args: {
-  platformUrl: string;
+  cloudUrl: string;
   assistantId: string;
   token: string;
 }): string {
-  const host = tunnelHostForPlatformUrl(args.platformUrl);
+  const host = tunnelHostForCloudUrl(args.cloudUrl);
   const url = new URL(
     `${tunnelWsScheme(host)}://${host}/${args.assistantId}/v1/live-voice`,
   );
@@ -131,22 +131,22 @@ interface LiveVoiceTokenResponse {
  * (`SessionAuthentication` and `XSessionTokenAuthentication`) and deliberately
  * excludes API-key auth, so `X-Session-Token` is the CLI's way in and a
  * `vak_` key is not: a caller holding only an API key cannot mint here, by
- * design on the platform's side.
+ * design on the cloud's side.
  *
  * Throws {@link TunnelWsTokenError} carrying the HTTP status, so the caller can
- * tell "sign in again" (401) from "not your assistant" (403) from a platform
+ * tell "sign in again" (401) from "not your assistant" (403) from a cloud
  * that is simply down.
  */
 export async function mintTunnelWsToken(args: {
-  platformUrl: string;
+  cloudUrl: string;
   assistantId: string;
   sessionToken: string;
 }): Promise<string> {
-  const url = `${args.platformUrl.replace(/\/+$/, "")}/v1/auth/live-voice-token/`;
+  const url = `${args.cloudUrl.replace(/\/+$/, "")}/v1/auth/live-voice-token/`;
   // `authHeaders` resolves `Cadet-Organization-Id`, which the endpoint needs
   // to scope the token, and which is cached per token so a session does not
   // pay for an extra round trip.
-  const headers = await authHeaders(args.sessionToken, args.platformUrl);
+  const headers = await authHeaders(args.sessionToken, args.cloudUrl);
 
   let response: Response;
   try {

package/src/lib/local-runtime-client.ts

@@ -1,11 +1,11 @@
-import { isManagedCloud } from "./managed-cloud.js";
+import { isCloudHome } from "./cloud-values.js";
 import type { AssistantEntry } from "./assistant-config.js";
 import {
   authHeaders,
   invalidateOrgIdCache,
   parseUnifiedJobStatus,
   type UnifiedJobStatus,
-} from "./platform-client.js";
+} from "./cloud-client.js";
 import {
   resolveRuntimeMigrationUrl,
   resolveRuntimeUrl,
@@ -49,7 +49,7 @@ function bearerHeaders(token: string): Record<string, string> {
 /**
  * Build the auth + content headers for a runtime migration request.
  *
- * - For `isManagedCloud(cloud)` we go through the platform's wildcard runtime
+ * - For `isCloudHome(cloud)` we go through the cloud's wildcard runtime
  *   proxy, which authenticates user-session / vak_ tokens via DRF's default
  *   authentication classes — `authHeaders()` produces the right combination
  *   (`X-Session-Token` + `Cadet-Organization-Id`, or `Authorization: Bearer
@@ -60,7 +60,7 @@ async function migrationRequestHeaders(
   entry: Pick<AssistantEntry, "cloud" | "runtimeUrl">,
   token: string,
 ): Promise<Record<string, string>> {
-  if (isManagedCloud(entry.cloud)) {
+  if (isCloudHome(entry.cloud)) {
     return {
       ...(await authHeaders(token, entry.runtimeUrl)),
       Accept: "application/json",
@@ -116,10 +116,10 @@ async function throwIfInProgress(
  *
  * For local/docker assistants this POSTs to
  * `{runtimeUrl}/v1/migrations/export-to-gcs` with guardian-token bearer
- * auth. For platform-managed (cloud="cadet") assistants the URL is rewritten
+ * auth. For cloud-managed (cloud="cadet") assistants the URL is rewritten
  * to the wildcard-runtime-proxy shape
- * `{platformUrl}/v1/assistants/<assistantId>/migrations/export-to-gcs` and
- * authenticated via the platform-token header set the platform's DRF auth
+ * `{cloudUrl}/v1/assistants/<assistantId>/migrations/export-to-gcs` and
+ * authenticated via the cloud-token header set the cloud's DRF auth
  * accepts (session / vak_).
  *
  * Returns the 202-accepted `job_id`. On 409 (another export in flight)
@@ -179,10 +179,10 @@ export async function localRuntimeExportToGcs(
  *
  * For local/docker assistants this POSTs to
  * `{runtimeUrl}/v1/migrations/import-from-gcs` with guardian-token bearer
- * auth. For platform-managed (cloud="cadet") assistants the URL is rewritten
+ * auth. For cloud-managed (cloud="cadet") assistants the URL is rewritten
  * to the wildcard-runtime-proxy shape
- * `{platformUrl}/v1/assistants/<assistantId>/migrations/import-from-gcs` and
- * authenticated via the platform token. On 409 throws
+ * `{cloudUrl}/v1/assistants/<assistantId>/migrations/import-from-gcs` and
+ * authenticated via the cloud token. On 409 throws
  * {@link MigrationInProgressError}.
  */
 export async function localRuntimeImportFromGcs(
@@ -261,10 +261,10 @@ export async function localRuntimePreflightFromGcs(
  *
  * For local/docker assistants this GETs
  * `{runtimeUrl}/v1/migrations/jobs/{jobId}` directly (guardian-token
- * bearer). For platform-managed assistants it routes through the wildcard
+ * bearer). For cloud assistants it routes through the wildcard
  * runtime proxy at
- * `{platformUrl}/v1/assistants/<assistantId>/migrations/jobs/{jobId}` with
- * platform-token auth — important: the platform's dedicated
+ * `{cloudUrl}/v1/assistants/<assistantId>/migrations/jobs/{jobId}` with
+ * platform-token auth — important: the cloud's dedicated
  * `/v1/migrations/jobs/{id}/` endpoint queries platform-side ImportJob
  * records and would 404 on runtime-created job IDs.
  */
@@ -320,15 +320,15 @@ export interface RuntimeIdentity {
  * (no filesystem reads), so it's safe to call against any running runtime.
  *
  * For local/docker assistants this GETs `{runtimeUrl}/v1/health` with
- * guardian-token bearer auth. For platform-managed (cloud="cadet")
+ * guardian-token bearer auth. For cloud-managed (cloud="cadet")
  * assistants the URL is rewritten to the wildcard runtime proxy shape
- * `{platformUrl}/v1/assistants/<assistantId>/health` and authenticated via
- * the platform token.
+ * `{cloudUrl}/v1/assistants/<assistantId>/health` and authenticated via
+ * the cloud token.
  *
  * For the cadet target this is the FIRST network call in the
  * teleport/backup export flow, so a stale `Cadet-Organization-Id` cache
  * entry would surface as a hard abort before any retry-friendly call (like
- * `platformRequestSignedUrl`) gets a chance to recover. Mirror that helper's
+ * `cloudRequestSignedUrl`) gets a chance to recover. Mirror that helper's
  * one-shot 401-retry: invalidate the org-ID cache and retry once. Local /
  * docker entries do not use the org-ID cache and are wrapped in
  * `callRuntimeWithAuthRetry` by callers for guardian-token refresh, so the
@@ -353,10 +353,10 @@ export async function localRuntimeIdentity(
     });
 
   let response = await doRequest();
-  if (response.status === 401 && isManagedCloud(entry.cloud)) {
-    // `entry.runtimeUrl` is the platform host for cadet-cloud entries
+  if (response.status === 401 && isCloudHome(entry.cloud)) {
+    // `entry.runtimeUrl` is the cloud host for cadet-cloud entries
     // (the wildcard runtime proxy lives there). Pass it as the cache key
-    // platformUrl so we invalidate the same entry that authHeaders cached.
+    // cloudUrl so we invalidate the same entry that authHeaders cached.
     invalidateOrgIdCache(token, entry.runtimeUrl);
     response = await doRequest();
   }