@mycadet/cli 0.12.7 → 0.12.8

package/src/lib/cloud-login.ts

@@ -10,7 +10,7 @@ import { randomBytes } from "crypto";
 import { createServer } from "http";
 import type { AddressInfo } from "net";
 
-import { isManagedCloud } from "./managed-cloud.js";
+import { isCloudHome } from "./cloud-values.js";
 import {
   resolveAssistant,
   saveAssistantEntry,
@@ -22,11 +22,11 @@ import {
   fetchCurrentUser,
   fetchOrganizationId,
   ensureSelfHostedLocalRegistration,
-  getPlatformUrl,
+  getCloudUrl,
   injectCredentialsIntoAssistant,
-  readPlatformToken,
-  savePlatformToken,
-} from "./platform-client.js";
+  readCloudToken,
+  saveCloudToken,
+} from "./cloud-client.js";
 import { fetchAssistantIngressUrl, fetchCurrentVersion } from "./upgrade-lifecycle.js";
 import {
   CALLBACK_PATH,
@@ -257,8 +257,8 @@ export function startLoopbackListener(
 }
 
 /** App-held WorkOS PKCE login */
-export async function workosPkceLogin(platformUrl: string): Promise<string> {
-  const clientId = await fetchWorkosClientId(platformUrl);
+export async function workosPkceLogin(cloudUrl: string): Promise<string> {
+  const clientId = await fetchWorkosClientId(cloudUrl);
   const { verifier, challenge } = generatePkcePair();
   const state = randomBytes(32).toString("hex");
 
@@ -286,7 +286,7 @@ export async function workosPkceLogin(platformUrl: string): Promise<string> {
       verifier,
     });
     return await exchangeAccessTokenForSession(
-      platformUrl,
+      cloudUrl,
       clientId,
       accessToken,
     );
@@ -307,7 +307,7 @@ export interface CloudLoginSession {
  * validates the resulting token, and persists it.
  */
 export async function ensureCloudLoginInteractive(): Promise<CloudLoginSession> {
-  const existingToken = readPlatformToken();
+  const existingToken = readCloudToken();
   if (existingToken) {
     try {
       const user = await fetchCurrentUser(existingToken);
@@ -317,16 +317,16 @@ export async function ensureCloudLoginInteractive(): Promise<CloudLoginSession>
     }
   }
 
-  const token = await workosPkceLogin(getPlatformUrl());
+  const token = await workosPkceLogin(getCloudUrl());
   const user = await fetchCurrentUser(token);
-  savePlatformToken(token);
+  saveCloudToken(token);
   return { token, user };
 }
 
 /**
  * TLS failures surface as opaque messages like "unknown certificate
  * verification error" from Bun's fetch. Translate the recognizable ones into
- * something actionable — most commonly the platform host's managed
+ * something actionable — most commonly the cloud host's managed
  * certificate is still provisioning.
  */
 export function describeLoginError(error: unknown): string {
@@ -335,13 +335,13 @@ export function describeLoginError(error: unknown): string {
   if (!tlsish) return raw;
   return (
     `Cadet Cloud is unreachable (${raw}). This usually means ` +
-    `${getPlatformUrl()}'s TLS certificate is missing or still provisioning. ` +
-    "Retry in a few minutes, or point CADET_PLATFORM_URL at a reachable host."
+    `${getCloudUrl()}'s TLS certificate is missing or still provisioning. ` +
+    "Retry in a few minutes, or point CADET_CLOUD_URL at a reachable host."
   );
 }
 
 /**
- * Register the active self-hosted assistant with the platform and inject
+ * Register the active self-hosted assistant with the cloud and inject
  * cloud credentials into its runtime — the post-login half of the desktop
  * app's LocalAssistantBootstrapService flow. Extracted so `cadet hatch` can
  * complete the same flow right after an interactive login on the Cadet Cloud
@@ -355,8 +355,8 @@ export async function registerLocalAssistantWithPlatform(
   const log = options.log ?? console.log;
   const entry = resolveAssistant();
 
-  // Skip managed ("cadet") assistants — they are handled by the platform.
-  if (!entry || isManagedCloud(entry.cloud)) return;
+  // Skip managed ("cadet") assistants — they are handled by the cloud.
+  if (!entry || isCloudHome(entry.cloud)) return;
 
   const orgId = await fetchOrganizationId(token);
   const clientInstallationId = computeDeviceId();
@@ -364,7 +364,7 @@ export async function registerLocalAssistantWithPlatform(
     fetchCurrentVersion(entry.runtimeUrl),
     fetchAssistantIngressUrl(entry.runtimeUrl, options.bearerToken ?? entry.bearerToken),
   ]);
-  const platformUrl = getPlatformUrl();
+  const cloudUrl = getCloudUrl();
   const registration = await ensureSelfHostedLocalRegistration(
     token,
     orgId,
@@ -372,14 +372,14 @@ export async function registerLocalAssistantWithPlatform(
     entry.assistantId,
     "cli",
     assistantVersion,
-    platformUrl,
+    cloudUrl,
     ingressUrl,
   );
   saveAssistantEntry({
     ...entry,
-    platformAssistantId: registration.assistant.id,
-    platformBaseUrl: platformUrl,
-    platformOrganizationId: orgId,
+    cloudAssistantId: registration.assistant.id,
+    cloudBaseUrl: cloudUrl,
+    cloudOrganizationId: orgId,
   });
   log(
     `Registered assistant: ${registration.assistant.name} (${registration.assistant.id})`,
@@ -408,8 +408,8 @@ export async function registerLocalAssistantWithPlatform(
     gatewayUrl: entry.runtimeUrl,
     bearerToken: options.bearerToken ?? entry.bearerToken,
     assistantApiKey,
-    platformAssistantId: registration.assistant.id,
-    platformBaseUrl: platformUrl,
+    cloudAssistantId: registration.assistant.id,
+    cloudBaseUrl: cloudUrl,
     organizationId: orgId,
     userId: user.id,
     webhookSecret: registration.webhook_secret,

package/src/lib/{platform-releases.ts → cloud-releases.ts}

@@ -1,4 +1,4 @@
-import { getPlatformUrl } from "./platform-client.js";
+import { getCloudUrl } from "./cloud-client.js";
 import { dockerhubImages } from "./docker.js";
 import type { ServiceName } from "./docker.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
@@ -40,20 +40,20 @@ const RELEASES_FETCH_LIMIT = 100;
 /**
  * Fetch the releases list from Cadet Cloud, optionally filtered by channel
  * (the `channel` param takes precedence over `stable` server-side).
- * `platformUrl` overrides the lockfile/env-resolved default — pass the
+ * `cloudUrl` overrides the lockfile/env-resolved default — pass the
  * target assistant's platform URL when it may differ from the active one.
  * Returns `null` when Cadet Cloud is unreachable or responds non-OK —
  * distinct from `[]` (it answered, no releases).
  */
 export async function fetchReleases(opts?: {
   channel?: "stable" | "preview";
-  platformUrl?: string;
+  cloudUrl?: string;
 }): Promise<ReleaseListItem[] | null> {
   try {
-    const platformUrl = opts?.platformUrl || getPlatformUrl();
+    const cloudUrl = opts?.cloudUrl || getCloudUrl();
     const filter = opts?.channel ? `channel=${opts.channel}` : "stable=true";
     const response = await loopbackSafeFetch(
-      `${platformUrl}/v1/releases/?${filter}&limit=${RELEASES_FETCH_LIMIT}`,
+      `${cloudUrl}/v1/releases/?${filter}&limit=${RELEASES_FETCH_LIMIT}`,
       { signal: AbortSignal.timeout(10_000) },
     );
     if (!response.ok) return null;

package/src/lib/cloud-values.ts

@@ -0,0 +1,3 @@
+export function isCloudHome(cloud: unknown): boolean {
+  return cloud === "cloud" || cloud === "cadet";
+}

package/src/lib/config-utils.ts

@@ -34,7 +34,7 @@ export function buildNestedConfig(
 
 /**
  * Ensure hatch always provides enough initial LLM config for the assistant to
- * detect a fresh off-platform hatch and seed BYOK profiles.
+ * detect a fresh off-cloud hatch and seed BYOK profiles.
  *
  * @deprecated Part of the workspace-config overlay path — a CLI→Assistant
  * side channel that bypasses the Assistant's public APIs and has no

package/src/lib/detached-process.ts

@@ -6,7 +6,7 @@ import { isCompiledCli } from "./local.js";
 import { getLogDir, openLogFile, resetLogFile } from "./xdg-log.js";
 
 export interface RelaunchDetachedOptions {
-  /** argv for the re-invoked CLI command, e.g. ["tunnel", "--provider", "ngrok"]. */
+  /** argv for the re-invoked CLI command, e.g. ["tunnel", "--provider", "cloudflare"]. */
   args: string[];
   /** Log file basename under the XDG log dir; truncated before spawn. */
   logFile: string;

package/src/lib/docker.ts

@@ -37,7 +37,7 @@ import {
   isLocalBuildRef,
   loadImageViaHost,
 } from "./host-image-loader.js";
-import { resolveOwnImageRefs } from "./platform-releases.js";
+import { resolveOwnImageRefs } from "./cloud-releases.js";
 import { isDevVersion } from "./version-compat.js";
 import {
   configureHatchProviderApiKey,
@@ -785,6 +785,113 @@ export async function wakeContainers(
   }
 }
 
+/** The `docker start` failure for a container that was never created. */
+export function isNoSuchContainerError(err: unknown): boolean {
+  const msg = err instanceof Error ? err.message : String(err);
+  return msg.includes("No such container");
+}
+
+/**
+ * Recreate a docker instance's service group from its lockfile entry — the
+ * wake path for containers that don't exist yet. A migrated install has its
+ * data in the volumes but no containers: nothing ever ran `docker run` for
+ * it (v0.0.10 run feedback: `wake --all` died on "No such container:
+ * <name>-assistant").
+ *
+ * Network and volume creates are idempotent; the three service containers
+ * come up from the entry's recorded images (the migrator points those at
+ * the installed cadet's release). The guardian bootstrap secret rides
+ * through from the entry; the signing key and CES token are deliberately
+ * NOT invented — with no env value the gateway and assistant load the
+ * persisted trust material from their security volumes (a migrated install
+ * keeps its own), matching the gateway's resolution order (env → file →
+ * generate). Empty volumes just get fresh state on first boot.
+ */
+export async function recreateDockerContainers(entry: AssistantEntry): Promise<void> {
+  const info = entry.containerInfo;
+  if (!info?.assistantImage || !info.gatewayImage || !info.cesImage) {
+    throw new Error(
+      `no container images recorded for '${entry.assistantId}' — re-hatch or run \`cadet upgrade\` to set them`,
+    );
+  }
+  const res = dockerResourceNames(entry.assistantId);
+  const log = (msg: string): void => console.log(msg);
+
+  // Clean slate for the create: an existing container (even a stopped one)
+  // would collide with `docker run --name` (the upgrade path does the same).
+  await stopContainers(res);
+
+  try {
+    await exec("docker", ["network", "inspect", res.network]);
+  } catch {
+    await exec("docker", ["network", "create", res.network]);
+  }
+  for (const vol of [
+    res.socketVolume,
+    res.assistantIpcVolume,
+    res.gatewayIpcVolume,
+    res.workspaceVolume,
+    res.gatewaySecurityVolume,
+    res.cesSecurityVolume,
+  ]) {
+    try {
+      await exec("docker", ["volume", "inspect", vol]);
+    } catch {
+      await exec("docker", ["volume", "create", vol]);
+    }
+  }
+
+  // The recorded images may not be on the machine yet (a migrated install
+  // gets its refs written before anything pulled them) — a pull of an
+  // already-present image is a cheap no-op.
+  for (const image of [info.assistantImage, info.gatewayImage, info.cesImage]) {
+    log(`📦 Pulling ${image}...`);
+    await exec("docker", ["pull", image]);
+  }
+
+  const gatewayPort = parseGatewayPort(entry.runtimeUrl) ??
+    getDefaultPorts(getCurrentEnvironment()).gateway;
+  const assistantPort = info.assistantPort ?? ASSISTANT_INTERNAL_PORT;
+  const device = getOrCreateHostDeviceId();
+  await startContainers(
+    {
+      bootstrapSecret: entry.guardianBootstrapSecret,
+      extraAssistantEnv: { CADET_DEVICE_ID: device },
+      extraGatewayEnv: { CADET_DEVICE_ID: device },
+      gatewayPort,
+      assistantPort,
+      imageTags: {
+        assistant: info.assistantImage,
+        gateway: info.gatewayImage,
+        "credential-executor": info.cesImage,
+      },
+      instanceName: entry.assistantId,
+      res,
+    },
+    log,
+  );
+
+  // Persist what the recreation decided (the gateway port in the runtime
+  // url, the assistant port when it defaulted) so plain `docker start`
+  // wakes work and clients reach the right endpoints.
+  saveAssistantEntry({
+    ...entry,
+    runtimeUrl: `http://localhost:${gatewayPort}`,
+    containerInfo: { ...info, assistantPort },
+  });
+}
+
+/** The port of the CLI's own runtime url form (`http://localhost:7830`). */
+function parseGatewayPort(runtimeUrl: string): number | null {
+  try {
+    const port = new URL(runtimeUrl).port;
+    const parsed = parseInt(port, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Ensure a Docker daemon is reachable before waking an instance's containers
  * (macOS only — on Linux the daemon runs natively).
@@ -1434,9 +1541,9 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
       : ownSecret;
 
     emitProgress(4, 6, "Starting containers...");
-    if (flagEnvVars.CADET_DISABLE_PLATFORM) {
-      extraAssistantEnv.CADET_DISABLE_PLATFORM =
-        flagEnvVars.CADET_DISABLE_PLATFORM;
+    if (flagEnvVars.CADET_DISABLE_CLOUD) {
+      extraAssistantEnv.CADET_DISABLE_CLOUD =
+        flagEnvVars.CADET_DISABLE_CLOUD;
     }
     const hostDeviceId = getOrCreateHostDeviceId();
     extraAssistantEnv.CADET_DEVICE_ID = hostDeviceId;
@@ -1478,8 +1585,6 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
     );
     const containersUpAt = Date.now();
 
-    const imageDigests = await captureImageRefs(res);
-
     const runtimeUrl = `http://localhost:${gatewayPort}`;
     const dockerEntry: AssistantEntry = {
       assistantId: instanceName,
@@ -1491,10 +1596,6 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
         assistantImage: imageTags.assistant,
         gatewayImage: imageTags.gateway,
         cesImage: imageTags["credential-executor"],
-        assistantDigest: imageDigests?.assistant,
-        gatewayDigest: imageDigests?.gateway,
-        cesDigest: imageDigests?.["credential-executor"],
-        networkName: res.network,
         assistantPort,
       },
     };

package/src/lib/environments/__tests__/paths.test.ts

@@ -48,13 +48,13 @@ type EnvironmentDefinition =
 
 const prod: EnvironmentDefinition = {
   name: "production",
-  platformUrl: "https://cloud.mycadet.ai",
+  cloudUrl: "https://cloud.mycadet.ai",
   webUrl: "https://mycadet.ai",
 };
 
 const dev: EnvironmentDefinition = {
   name: "dev",
-  platformUrl: "https://dev-cloud.mycadet.ai",
+  cloudUrl: "https://dev-cloud.mycadet.ai",
   webUrl: "https://dev.mycadet.ai",
 };
 

package/src/lib/environments/__tests__/resolve.test.ts

@@ -8,7 +8,7 @@ import {
 
 const ENV_VARS_TO_SAVE = [
   "CADET_ENVIRONMENT",
-  "CADET_PLATFORM_URL",
+  "CADET_CLOUD_URL",
   "CADET_ASSISTANT_PLATFORM_URL",
   "CADET_LOCKFILE_DIR",
 ] as const;
@@ -37,33 +37,33 @@ describe("getCurrentEnvironment", () => {
   test("returns production seed when no override, no env var", () => {
     const env = getCurrentEnvironment();
     expect(env.name).toBe("production");
-    expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
   });
 
   test("returns dev seed when CADET_ENVIRONMENT=dev", () => {
     process.env.CADET_ENVIRONMENT = "dev";
     const env = getCurrentEnvironment();
     expect(env.name).toBe("dev");
-    expect(env.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://dev-cloud.mycadet.ai");
   });
 
   test("returns staging seed when CADET_ENVIRONMENT=staging", () => {
     process.env.CADET_ENVIRONMENT = "staging";
-    expect(getCurrentEnvironment().platformUrl).toBe(
+    expect(getCurrentEnvironment().cloudUrl).toBe(
       "https://staging-cloud.mycadet.ai",
     );
   });
 
   test("returns local seed with localhost URL", () => {
     process.env.CADET_ENVIRONMENT = "local";
-    expect(getCurrentEnvironment().platformUrl).toBe("http://localhost:8000");
+    expect(getCurrentEnvironment().cloudUrl).toBe("http://localhost:8000");
   });
 
   test("override argument takes priority over CADET_ENVIRONMENT env var", () => {
     process.env.CADET_ENVIRONMENT = "staging";
     const env = getCurrentEnvironment("dev");
     expect(env.name).toBe("dev");
-    expect(env.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://dev-cloud.mycadet.ai");
   });
 
   test("empty override argument falls through to env var", () => {
@@ -85,7 +85,7 @@ describe("getCurrentEnvironment", () => {
     try {
       const env = getCurrentEnvironment("no-such-env");
       expect(env.name).toBe("production");
-      expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+      expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
       expect(stderr).toHaveBeenCalledWith(
         expect.stringContaining('unknown environment "no-such-env"'),
       );
@@ -105,7 +105,7 @@ describe("getCurrentEnvironment", () => {
     try {
       const env = getCurrentEnvironment();
       expect(env.name).toBe("production");
-      expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+      expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
       expect(stderr).toHaveBeenCalledWith(
         expect.stringContaining('unknown environment "nope"'),
       );
@@ -128,49 +128,49 @@ describe("getCurrentEnvironment", () => {
     }
   });
 
-  test("CADET_PLATFORM_URL overrides platformUrl on the resolved definition", () => {
+  test("CADET_CLOUD_URL overrides cloudUrl on the resolved definition", () => {
     process.env.CADET_ENVIRONMENT = "dev";
-    process.env.CADET_PLATFORM_URL = "https://custom.example.com";
+    process.env.CADET_CLOUD_URL = "https://custom.example.com";
     const env = getCurrentEnvironment();
     expect(env.name).toBe("dev");
-    expect(env.platformUrl).toBe("https://custom.example.com");
+    expect(env.cloudUrl).toBe("https://custom.example.com");
   });
 
-  test("CADET_PLATFORM_URL override does not affect the seed table", () => {
-    process.env.CADET_PLATFORM_URL = "https://custom.example.com";
+  test("CADET_CLOUD_URL override does not affect the seed table", () => {
+    process.env.CADET_CLOUD_URL = "https://custom.example.com";
     getCurrentEnvironment();
-    delete process.env.CADET_PLATFORM_URL;
+    delete process.env.CADET_CLOUD_URL;
     const env = getCurrentEnvironment();
-    expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
   });
 
-  test("CADET_ASSISTANT_PLATFORM_URL overrides assistantPlatformUrl", () => {
+  test("CADET_ASSISTANT_PLATFORM_URL overrides assistantCloudUrl", () => {
     process.env.CADET_ASSISTANT_PLATFORM_URL =
       "http://host.docker.internal:8000";
     const env = getCurrentEnvironment();
-    expect(env.assistantPlatformUrl).toBe("http://host.docker.internal:8000");
+    expect(env.assistantCloudUrl).toBe("http://host.docker.internal:8000");
   });
 
-  test("CADET_ASSISTANT_PLATFORM_URL does not shadow platformUrl", () => {
+  test("CADET_ASSISTANT_PLATFORM_URL does not shadow cloudUrl", () => {
     process.env.CADET_ASSISTANT_PLATFORM_URL = "http://override";
     const env = getCurrentEnvironment();
-    expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+    expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
   });
 
-  test("does not auto-materialize a new environment from CADET_PLATFORM_URL alone", () => {
+  test("does not auto-materialize a new environment from CADET_CLOUD_URL alone", () => {
     // Unknown env names fall back to production (parity with daemon + Swift).
-    // The per-field CADET_PLATFORM_URL override is intentionally dropped on
+    // The per-field CADET_CLOUD_URL override is intentionally dropped on
     // the fallback path — fallback returns a pristine production seed so a
     // typo'd env var can't accidentally stitch together a new environment.
     process.env.CADET_ENVIRONMENT = "my-custom";
-    process.env.CADET_PLATFORM_URL = "https://my-custom.example.com";
+    process.env.CADET_CLOUD_URL = "https://my-custom.example.com";
     const stderr = spyOn(process.stderr, "write").mockImplementation(
       () => true,
     );
     try {
       const env = getCurrentEnvironment();
       expect(env.name).toBe("production");
-      expect(env.platformUrl).toBe("https://cloud.mycadet.ai");
+      expect(env.cloudUrl).toBe("https://cloud.mycadet.ai");
       expect(stderr).toHaveBeenCalledWith(
         expect.stringContaining('unknown environment "my-custom"'),
       );
@@ -232,7 +232,7 @@ describe("getSeed", () => {
     const seed = getSeed("dev");
     expect(seed).toBeDefined();
     expect(seed?.name).toBe("dev");
-    expect(seed?.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+    expect(seed?.cloudUrl).toBe("https://dev-cloud.mycadet.ai");
   });
 
   test("returns undefined for an unknown name", () => {
@@ -242,10 +242,10 @@ describe("getSeed", () => {
   test("returned seed is a copy — mutations do not affect the table", () => {
     const seed = getSeed("dev");
     if (seed) {
-      seed.platformUrl = "mutated";
+      seed.cloudUrl = "mutated";
     }
     const second = getSeed("dev");
-    expect(second?.platformUrl).toBe("https://dev-cloud.mycadet.ai");
+    expect(second?.cloudUrl).toBe("https://dev-cloud.mycadet.ai");
   });
 
   test("all five canonical seeds exist", () => {

package/src/lib/environments/resolve.ts

@@ -43,9 +43,9 @@ export function environmentFromVersion(version: string): string {
  *
  * Per-field env-var overrides are honored on the resolved definition as
  * ad-hoc escape hatches (they do not materialize new environments):
- *   - `CADET_PLATFORM_URL` overrides `platformUrl`
+ *   - `CADET_CLOUD_URL` overrides `cloudUrl`
  *   - `CADET_WEB_URL` overrides `webUrl`
- *   - `CADET_ASSISTANT_PLATFORM_URL` overrides `assistantPlatformUrl`
+ *   - `CADET_ASSISTANT_PLATFORM_URL` overrides `assistantCloudUrl`
  *   - `CADET_LOCKFILE_DIR` overrides `lockfileDirOverride` (legacy e2e
  *     test hook)
  *
@@ -87,9 +87,9 @@ export function getCurrentEnvironment(
 
   const resolved: EnvironmentDefinition = { ...seed };
 
-  const platformUrlOverride = process.env.CADET_PLATFORM_URL?.trim();
-  if (platformUrlOverride) {
-    resolved.platformUrl = platformUrlOverride;
+  const cloudUrlOverride = process.env.CADET_CLOUD_URL?.trim();
+  if (cloudUrlOverride) {
+    resolved.cloudUrl = cloudUrlOverride;
   }
 
   const webUrlOverride = process.env.CADET_WEB_URL?.trim();
@@ -97,10 +97,10 @@ export function getCurrentEnvironment(
     resolved.webUrl = webUrlOverride;
   }
 
-  const assistantPlatformUrlOverride =
+  const assistantCloudUrlOverride =
     process.env.CADET_ASSISTANT_PLATFORM_URL?.trim();
-  if (assistantPlatformUrlOverride) {
-    resolved.assistantPlatformUrl = assistantPlatformUrlOverride;
+  if (assistantCloudUrlOverride) {
+    resolved.assistantCloudUrl = assistantCloudUrlOverride;
   }
 
   const lockfileDirOverride = process.env.CADET_LOCKFILE_DIR?.trim();

package/src/lib/guardian-token.ts

@@ -49,7 +49,11 @@ const GuardianTokenFieldsSchema = z
       .union([z.string(), z.number()])
       .optional()
       .catch(undefined),
-    refreshAfter: z.string().optional().catch(undefined),
+    refreshAfter: z
+      .union([z.string(), z.number()])
+      .transform((v) => (typeof v === "number" ? new Date(v).toISOString() : v))
+      .optional()
+      .catch(undefined),
     isNew: z.boolean().optional().catch(undefined),
     deviceId: z.string().optional().catch(undefined),
   })
@@ -590,6 +594,20 @@ async function waitForGatewayReady(gatewayUrl: string): Promise<void> {
   }
 }
 
+export class GuardianLeasePermanentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "GuardianLeasePermanentError";
+  }
+}
+
+function describeJsonType(value: unknown): string {
+  if (value === undefined) return "absent";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
 export async function leaseGuardianToken(
   gatewayUrl: string,
   assistantId: string,
@@ -621,7 +639,8 @@ export async function leaseGuardianToken(
     throw new Error(`guardian/init failed (${response.status}): ${body}`);
   }
 
-  const parsed = parseGuardianTokenFields(await response.json());
+  const rawBody: unknown = await response.json();
+  const parsed = parseGuardianTokenFields(rawBody);
   if (
     parsed.guardianPrincipalId == null ||
     parsed.accessToken == null ||
@@ -631,8 +650,21 @@ export async function leaseGuardianToken(
     parsed.refreshAfter == null ||
     parsed.isNew == null
   ) {
-    throw new Error(
-      `guardian/init returned a malformed token response (${response.status})`,
+    const raw = z.record(z.string(), z.unknown()).catch({}).parse(rawBody);
+    const requiredFields: (keyof typeof parsed)[] = [
+      "guardianPrincipalId",
+      "accessToken",
+      "accessTokenExpiresAt",
+      "refreshToken",
+      "refreshTokenExpiresAt",
+      "refreshAfter",
+      "isNew",
+    ];
+    const unusable = requiredFields
+      .filter((field) => parsed[field] == null)
+      .map((field) => `${field} arrived as ${describeJsonType(raw[field])}`);
+    throw new GuardianLeasePermanentError(
+      `guardian/init returned a malformed token response (${response.status}) — ${unusable.join(", ")}`,
     );
   }
   const tokenData: GuardianTokenData = {