@mycadet/cli 0.12.10 → 0.13.0

package/src/commands/debug.ts

@@ -1,16 +1,4 @@
-/**
- * `cadet debug [name]`
- *
- * Send Cadet staff a debug bundle of a self-hosted assistant: the
- * workspace, its logs, and the gateway's own database, with no credentials.
- * Staff open it on a throwaway debug clone. The cloud only hands out the
- * upload URL while "Allow Staff Access" is on, and the bundle is deleted
- * after seven days.
- *
- * Steps: the daemon is checked for the debug profile, the cloud mints
- * the upload URL, the daemon exports with the debug profile, and this
- * command waits for the job so the result is real.
- */
+import { z } from "zod";
 import { isCloudHome } from "../lib/cloud-values.js";
 import {
   formatAssistantReference,
@@ -18,13 +6,6 @@ import {
 } from "../lib/assistant-config.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import { loadGuardianToken, leaseGuardianToken } from "../lib/guardian-token";
-import { pollJobUntilDone } from "../lib/job-polling.js";
-import {
-  MigrationInProgressError,
-  localRuntimeExportToGcs,
-  localRuntimeIdentity,
-  localRuntimePollJobStatus,
-} from "../lib/local-runtime-client.js";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 import {
   authHeaders,
@@ -32,16 +13,7 @@ import {
   getCloudUrl,
   readCloudToken,
 } from "../lib/cloud-client.js";
-import { compareVersions } from "../lib/version-compat.js";
 
-// Matches the daemon's own upload deadline (EXPORT_TO_GCS_PUT_TIMEOUT_MS in
-// assistant/src/runtime/routes/migration-routes.ts), so a slow but healthy
-// export is never reported as failed while it is still uploading.
-const EXPORT_TIMEOUT_MS = 60 * 60 * 1000;
-// The daemon release that added `profile: "debug"`. An older daemon strips
-// the field and exports a normal teleport bundle, which carries the owner's
-// credentials. That must never reach the staff bucket.
-export const DEBUG_PROFILE_MIN_VERSION = "0.12.3";
 // Renew a cached guardian token that is about to lapse instead of starting
 // a long export on it.
 const TOKEN_EXPIRY_MARGIN_MS = 60 * 1000;
@@ -50,8 +22,8 @@ function printHelp(): void {
   console.log(`Usage: cadet debug [name]
 
 Send Cadet staff a debug bundle of a self-hosted assistant so they can
-inspect a copy of it. The bundle holds the assistant's workspace, its
-logs, and the gateway's own database. It never holds credentials.
+inspect its diagnostic logs and sanitized configuration. The archive
+never holds credentials.
 
 Arguments:
   name    Assistant ID or unique display name. Defaults to the active
@@ -61,7 +33,6 @@ Requirements:
   - 'Allow Staff Access' is on for the assistant (Settings > Privacy).
   - You are logged in ('cadet login'), which also registers the
     assistant with the cloud.
-  - The assistant runs version ${DEBUG_PROFILE_MIN_VERSION} or newer.
   - The assistant is self-hosted. Cadet-hosted assistants need no bundle;
     staff clone them directly.
 
@@ -69,7 +40,7 @@ Side effects:
   - Uploads the bundle to Cadet's debug-bundle storage, where it is
     deleted after 7 days. Nothing on this machine changes.
   - Records a 'debug bundle exported' entry in your account's audit history.
-  - Waits for the upload to finish (up to 60 minutes for a large workspace).
+  - Waits for the diagnostic upload to finish.
 
 Examples:
   cadet debug
@@ -80,114 +51,87 @@ Examples:
 
 export const debug = Object.assign(
   async function debug(): Promise<void> {
-  const args = process.argv.slice(3);
-  if (args.includes("--help") || args.includes("-h")) {
-    printHelp();
-    return;
-  }
-
-  const entry = resolveTargetAssistant(parseAssistantTargetArg(args));
-  const reference = formatAssistantReference(entry);
-  if (isCloudHome(entry.cloud)) {
-    console.error(
-      `${reference} is hosted by Cadet, so staff can clone it directly. No bundle is needed.`,
-    );
-    process.exit(1);
-  }
-
-  const cloudToken = readCloudToken();
-  if (!cloudToken) {
-    console.error("Not logged in. Run 'cadet login' first.");
-    process.exit(1);
-  }
-  const cloudAssistantId = entry.cloudAssistantId?.trim();
-  if (!cloudAssistantId) {
-    console.error(
-      `${reference} is not registered with the cloud yet. Run 'cadet login' and retry.`,
-    );
-    process.exit(1);
-  }
-  const cloudUrl = entry.cloudBaseUrl?.trim() || getCloudUrl();
-  const organizationId = entry.cloudOrganizationId?.trim();
+    const args = process.argv.slice(3);
+    if (args.includes("--help") || args.includes("-h")) {
+      printHelp();
+      return;
+    }
 
-  // Step 1: a guardian token for the daemon, and a check that the daemon
-  // knows the debug profile. This comes before the cloud call so a
-  // daemon that would export credentials is refused before any URL exists.
-  let accessToken = await daemonAccessToken(entry, reference, false);
-  const { version } = await localRuntimeIdentity(entry, accessToken);
-  const comparison = compareVersions(version, DEBUG_PROFILE_MIN_VERSION);
-  if (comparison === null || comparison < 0) {
-    console.error(
-      `${reference} runs version ${version || "unknown"}, which cannot build a debug bundle. Update it to ${DEBUG_PROFILE_MIN_VERSION} or newer ('cadet upgrade') and retry.`,
-    );
-    process.exit(1);
-  }
+    const entry = resolveTargetAssistant(parseAssistantTargetArg(args));
+    const reference = formatAssistantReference(entry);
+    if (isCloudHome(entry.cloud)) {
+      console.error(
+        `${reference} is hosted by Cadet, so staff can clone it directly. No bundle is needed.`,
+      );
+      process.exit(1);
+    }
 
-  // Step 2: the cloud mints the upload URL, and refuses unless the
-  // owner's staff access grant is active.
-  const headers = organizationId
-    ? authHeadersForKnownOrganization(cloudToken, organizationId)
-    : await authHeaders(cloudToken, cloudUrl);
-  const urlResponse = await loopbackSafeFetch(
-    `${cloudUrl}/v1/assistants/${encodeURIComponent(cloudAssistantId)}/debug-bundle-upload-url/`,
-    { method: "POST", headers },
-  );
-  if (urlResponse.status === 403) {
-    console.error(
-      "Staff access is off for this assistant. Turn on 'Allow Staff Access' in Settings > Privacy, then retry.",
-    );
-    process.exit(1);
-  }
-  if (!urlResponse.ok) {
-    const detail = await urlResponse.text().catch(() => "");
-    console.error(
-      `Error: Could not get an upload URL (${urlResponse.status}): ${detail || urlResponse.statusText}`,
+    const cloudToken = readCloudToken();
+    if (!cloudToken) {
+      console.error("Not logged in. Run 'cadet login' first.");
+      process.exit(1);
+    }
+    const cloudAssistantId = entry.cloudAssistantId?.trim();
+    if (!cloudAssistantId) {
+      console.error(
+        `${reference} is not registered with the cloud yet. Run 'cadet login' and retry.`,
+      );
+      process.exit(1);
+    }
+    const cloudUrl = entry.cloudBaseUrl?.trim() || getCloudUrl();
+    const organizationId = entry.cloudOrganizationId?.trim();
+
+    const accessToken = await daemonAccessToken(entry, reference, false);
+    const headers = organizationId
+      ? authHeadersForKnownOrganization(cloudToken, organizationId)
+      : await authHeaders(cloudToken, cloudUrl);
+    const urlResponse = await loopbackSafeFetch(
+      `${cloudUrl}/v1/assistants/${encodeURIComponent(cloudAssistantId)}/debug-bundle-upload-url/`,
+      { method: "POST", headers },
     );
-    process.exit(1);
-  }
-  const { url: uploadUrl } = (await urlResponse.json()) as { url: string };
-
-  // Step 3: the daemon builds and uploads the bundle.
-  let jobId: string;
-  try {
-    ({ jobId } = await localRuntimeExportToGcs(entry, accessToken, {
-      uploadUrl,
-      description: "debug bundle for Cadet staff",
-      profile: "debug",
-    }));
-  } catch (err) {
-    if (err instanceof MigrationInProgressError) {
+    if (urlResponse.status === 403) {
       console.error(
-        `Error: Another export is already in progress (job ${err.existingJobId}). Wait for it to finish, then retry.`,
+        "Staff access is off for this assistant. Turn on 'Allow Staff Access' in Settings > Privacy, then retry.",
       );
       process.exit(1);
     }
-    throw err;
-  }
-  console.log(`Export started (job ${jobId})...`);
-
-  // Step 4: wait for the upload so the owner sees a real result. A large
-  // export can outlive the guardian token, so a 401 mid-poll re-leases one.
-  const terminal = await pollJobUntilDone({
-    label: "debug bundle export",
-    poll: () => localRuntimePollJobStatus(entry, accessToken, jobId),
-    timeoutMs: EXPORT_TIMEOUT_MS,
-    refreshOn401: async () => {
-      accessToken = await daemonAccessToken(entry, reference, true);
-    },
-  });
-  if (terminal.status === "failed") {
-    console.error(`Error: Export failed: ${terminal.error}`);
-    process.exit(1);
-  }
-  console.log(
-    "Debug bundle sent to Cadet. Staff can open it for the next 7 days.",
-  );
-},
+    if (!urlResponse.ok) {
+      const detail = await urlResponse.text().catch(() => "");
+      console.error(
+        `Error: Could not get an upload URL (${urlResponse.status}): ${detail || urlResponse.statusText}`,
+      );
+      process.exit(1);
+    }
+    const { url: uploadUrl } = z
+      .object({ url: z.string().url() })
+      .parse(await urlResponse.json());
+    const logs = await loopbackSafeFetch(
+      `${entry.runtimeUrl.replace(/\/+$/, "")}/v1/logs/export`,
+      {
+        method: "POST",
+        signal: AbortSignal.timeout(180_000),
+        headers: { Authorization: `Bearer ${accessToken}` },
+      },
+    );
+    if (!logs.ok) {
+      throw new Error(`Diagnostic export failed (HTTP ${logs.status}).`);
+    }
+    const upload = await fetch(uploadUrl, {
+      method: "PUT",
+      signal: AbortSignal.timeout(300_000),
+      headers: { "Content-Type": "application/octet-stream" },
+      body: await logs.blob(),
+    });
+    if (!upload.ok) {
+      throw new Error(`Diagnostic upload failed (HTTP ${upload.status}).`);
+    }
+    console.log(
+      "Debug bundle sent to Cadet. Staff can open it for the next 7 days.",
+    );
+  },
   { description: "Send Cadet staff a debug bundle of a self-hosted assistant" },
 );
 
-
 async function daemonAccessToken(
   entry: {
     assistantId: string;

package/src/commands/devices.ts

@@ -7,13 +7,11 @@
  * which self-guard loopback + reject any browser/WebView Origin. The gateway
  * only ever stores the HASHED device id, so list returns and revoke accepts the
  * same `hashedDeviceId` (the raw device id is never persisted anywhere).
- *
- * This is the counterpart to `cadet unpair`: `unpair` forgets a connection on
- * the *paired* machine (client side); `devices` revokes a device from the *host*
- * that runs the assistant (server side).
  */
 
+import { z } from "zod";
 import { createHash } from "node:crypto";
+import { hostname } from "node:os";
 
 import type { DeviceRecord } from "@mycadet/local-mode";
 
@@ -23,7 +21,11 @@ import {
   getAssistantDisplayName,
   resolveTargetAssistant,
 } from "../lib/assistant-config";
-import { computeDeviceId } from "../lib/guardian-token.js";
+import {
+  type GuardianTokenData,
+  computeDeviceId,
+  loadGuardianToken,
+} from "../lib/guardian-token.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
 import {
   CLI_INTERFACE_ID,
@@ -33,10 +35,18 @@ import {
   canPromptForConfirmation,
   confirmAction,
 } from "../lib/confirm-action.js";
+import { GATEWAY_INTERNAL_PORT } from "../lib/environments/paths.js";
+import { execOutput } from "../lib/step-runner.js";
+import { dockerResourceNames } from "../lib/docker.js";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
+const dockerGatewayResponseSchema = z.object({
+  status: z.number().int().min(200).max(599),
+  body: z.string(),
+});
+
 function printUsage(): void {
-  console.log(`cadet devices [beta] - List and revoke devices paired to a local assistant
+  console.log(`cadet devices - List and revoke devices paired to a local assistant
 
 USAGE:
     cadet devices [name]
@@ -51,8 +61,7 @@ OPTIONS:
     --json             Print machine-readable JSON on stdout (revoke requires --yes)
 
 Lists the devices paired to a local (host-side) assistant, or revokes one by its
-hashed id. Runs on the machine that hosts the assistant — paired connections
-imported from another machine are managed with 'cadet unpair' instead.
+hashed id. Runs on the machine that hosts the assistant.
 
 EXAMPLES:
     cadet devices
@@ -77,10 +86,12 @@ function resolveLoopbackBase(entry: AssistantEntry): string {
     console.error(
       "Run `cadet devices` on the host that runs the assistant to manage its devices.",
     );
-    console.error("To forget this connection here, use `cadet unpair`.");
     process.exit(1);
   }
 
+  if (entry.cloud === "docker")
+    return `http://127.0.0.1:${GATEWAY_INTERNAL_PORT}`;
+
   const base =
     entry.localUrl ||
     (entry.resources?.gatewayPort
@@ -96,15 +107,66 @@ function resolveLoopbackBase(entry: AssistantEntry): string {
   return base.replace(/\/+$/, "");
 }
 
+/** Docker host management enters the gateway network namespace before calling loopback-only routes. */
+async function deviceRequest(
+  entry: AssistantEntry,
+  url: string,
+  init: RequestInit,
+): Promise<Response> {
+  if (entry.cloud !== "docker") return loopbackSafeFetch(url, init);
+  const script = `const r = await fetch(process.argv[1], {...JSON.parse(process.argv[2]), signal: AbortSignal.timeout(10000)}); console.log(JSON.stringify({status:r.status, body:await r.text()}));`;
+  const output = await execOutput(
+    "docker",
+    [
+      "exec",
+      dockerResourceNames(entry.assistantId).gatewayContainer,
+      "bun",
+      "-e",
+      script,
+      url,
+      JSON.stringify(init),
+    ],
+    { timeoutMs: 15000 },
+  );
+  const result = dockerGatewayResponseSchema.parse(JSON.parse(output));
+  return new Response(result.body, { status: result.status });
+}
+
 /**
  * The hashed device id the gateway stores for THIS machine's own guardian
  * credential (`leaseGuardianToken` registers it device-bound as
- * sha256(deviceId)). It shows up in `/v1/devices` next to remotely paired
- * devices; revoking it locks this host out of its own assistant until
- * guardian repair.
+ * sha256(deviceId)). The gateway's row hashes the deviceId the token was
+ * leased with, so prefer the stored token's deviceId and fall back to the
+ * current machine id for tokens persisted before the field was stored. It
+ * shows up in `/v1/devices` next to remotely paired devices; revoking it
+ * locks this host out of its own assistant until guardian repair.
  */
-function currentHostHashedDeviceId(): string {
-  return createHash("sha256").update(computeDeviceId()).digest("hex");
+function currentHostHashedDeviceId(token?: GuardianTokenData | null): string {
+  const deviceId = token?.deviceId || computeDeviceId();
+  return createHash("sha256").update(deviceId).digest("hex");
+}
+
+/**
+ * The local guardian token.json IS a paired device even when the gateway has
+ * no record of it (fresh gateway DB, a lease that predates device tracking).
+ * Rebuild the row it would have — same identity the gateway would have
+ * stored — so it always shows up in `cadet devices` and stays revocable.
+ */
+function localHostDeviceRow(
+  token: GuardianTokenData,
+  hashedDeviceId: string,
+): DeviceRecord {
+  const leasedAtMs = Date.parse(token.leasedAt);
+  return {
+    hashedDeviceId,
+    platform: "cli",
+    issuedAt: Number.isFinite(leasedAtMs) ? leasedAtMs : null,
+    expiresAt: null,
+    lastUsedAt: null,
+    pairingUserAgent: null,
+    clientReportedName: hostname(),
+    isCurrentHost: true,
+  };
 }
 
 /** Format an epoch-ms timestamp as ISO, or a placeholder when absent. */
@@ -122,7 +184,7 @@ async function listDevices(
 
   let response: Response;
   try {
-    response = await loopbackSafeFetch(`${base}/v1/devices`, {
+    response = await deviceRequest(entry, `${base}/v1/devices`, {
       method: "GET",
       headers: getClientRegistrationHeaders(CLI_INTERFACE_ID),
     });
@@ -143,13 +205,21 @@ async function listDevices(
   }
 
   const body = (await response.json()) as { devices?: DeviceRecord[] };
-  const hostHash = currentHostHashedDeviceId();
+  const token = loadGuardianToken(entry.assistantId);
+  const hostHash = currentHostHashedDeviceId(token);
   const devices = (body.devices ?? []).map((device) =>
     device.hashedDeviceId === hostHash
       ? { ...device, isCurrentHost: true as const }
       : device,
   );
 
+  // The local guardian token.json IS a paired device even when the gateway
+  // has no record of it (fresh gateway DB, lease predating device tracking):
+  // synthesize the row it would have so it stays visible and revocable here.
+  if (token && !devices.some((device) => device.hashedDeviceId === hostHash)) {
+    devices.push(localHostDeviceRow(token, hostHash));
+  }
+
   if (jsonOutput) {
     console.log(JSON.stringify({ devices }));
     return;
@@ -213,7 +283,8 @@ async function revokeDevice(
   // Warn (don't block; recoverable via guardian repair) when the target is
   // this machine's own host credential. --json is app-driven; the UI disables
   // the host row, so the warning stays out of automation transcripts.
-  if (!jsonOutput && hashedDeviceId === currentHostHashedDeviceId()) {
+  const localToken = loadGuardianToken(entry.assistantId);
+  if (!jsonOutput && hashedDeviceId === currentHostHashedDeviceId(localToken)) {
     console.error(
       "Warning: this is this machine's own host credential. Revoking it locks this host out of the assistant until guardian repair.",
     );
@@ -239,7 +310,7 @@ async function revokeDevice(
 
   let response: Response;
   try {
-    response = await loopbackSafeFetch(`${base}/v1/devices/revoke`, {
+    response = await deviceRequest(entry, `${base}/v1/devices/revoke`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -281,38 +352,37 @@ async function revokeDevice(
 
 export const devices = Object.assign(
   async function devices(): Promise<void> {
-  const rawArgs = process.argv.slice(3);
-
-  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
-    printUsage();
-    return;
-  }
+    const rawArgs = process.argv.slice(3);
 
-  const jsonOutput = rawArgs.includes("--json");
-  const args = rawArgs.filter((a) => a !== "--json");
-
-  if (args[0] === "revoke") {
-    const rest = args.slice(1);
-    const yes = rest.includes("--yes");
-    const positionals = rest.filter((a) => !a.startsWith("-"));
-    const hashedDeviceId = positionals[0];
-    if (!hashedDeviceId) {
-      console.error("Error: a hashedDeviceId is required to revoke.");
+    if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
       printUsage();
-      process.exit(1);
+      return;
     }
-    const nameArg = positionals.slice(1).join(" ") || undefined;
+
+    const jsonOutput = rawArgs.includes("--json");
+    const args = rawArgs.filter((a) => a !== "--json");
+
+    if (args[0] === "revoke") {
+      const rest = args.slice(1);
+      const yes = rest.includes("--yes");
+      const positionals = rest.filter((a) => !a.startsWith("-"));
+      const hashedDeviceId = positionals[0];
+      if (!hashedDeviceId) {
+        console.error("Error: a hashedDeviceId is required to revoke.");
+        printUsage();
+        process.exit(1);
+      }
+      const nameArg = positionals.slice(1).join(" ") || undefined;
+      const entry = resolveTargetAssistant(nameArg);
+      const base = resolveLoopbackBase(entry);
+      await revokeDevice(entry, base, hashedDeviceId, yes, jsonOutput);
+      return;
+    }
+
+    const nameArg = parseAssistantTargetArg(args, []);
     const entry = resolveTargetAssistant(nameArg);
     const base = resolveLoopbackBase(entry);
-    await revokeDevice(entry, base, hashedDeviceId, yes, jsonOutput);
-    return;
-  }
-
-  const nameArg = parseAssistantTargetArg(args, []);
-  const entry = resolveTargetAssistant(nameArg);
-  const base = resolveLoopbackBase(entry);
-  await listDevices(entry, base, jsonOutput);
-},
-  { description: "List or revoke devices paired to a local assistant [beta]" },
+    await listDevices(entry, base, jsonOutput);
+  },
+  { description: "List or revoke devices paired to a local assistant" },
 );
-

package/src/commands/gateway/token.ts

@@ -1,22 +1,67 @@
 import { formatGuardianRefreshCliFailure } from "@mycadet/local-mode";
 
 import {
-  lookupAssistantByIdentifier,
-  formatAssistantLookupError,
+  type AssistantEntry,
+  resolveTargetAssistant,
+  saveAssistantEntry,
 } from "../../lib/assistant-config.js";
 import {
+  GuardianLeasePermanentError,
+  leaseGuardianToken,
   loadGuardianToken,
   refreshGuardianTokenResult,
+  resetGuardianBootstrap,
 } from "../../lib/guardian-token.js";
+import { generateLocalSigningKey } from "../../lib/local.js";
 
 function printUsage(): void {
-  console.log("Usage: cadet gateway token <subcommand> <assistantId>");
+  console.log("Usage: cadet gateway token <subcommand> [assistantId]");
   console.log("");
   console.log("Manage gateway authentication tokens.");
   console.log("");
+  console.log(
+    "Omit the assistant id to target the active (or sole) assistant.",
+  );
+  console.log("");
   console.log("Subcommands:");
   console.log("  get       Print the current guardian access token");
-  console.log("  refresh   Refresh an expired access token and print it");
+  console.log(
+    "  refresh   Refresh an expired access token and print it (self-repairs a spent credential)",
+  );
+}
+
+/**
+ * Re-provision the guardian credential in place via the gateway's bootstrap
+ * reset — the same machinery `cadet wake --repair-guardian` runs, minus the
+ * wake. NEVER points at `cadet hatch`: hatching creates a different assistant.
+ * A fresh lease revokes other devices' paired tokens; callers say so on
+ * stderr. Returns true on success (the newly leased token is persisted).
+ */
+async function repairGuardianCredential(
+  entry: AssistantEntry,
+  gatewayUrl: string,
+): Promise<boolean> {
+  let bootstrapSecret = entry.guardianBootstrapSecret;
+  if (!bootstrapSecret) {
+    bootstrapSecret = generateLocalSigningKey();
+    entry.guardianBootstrapSecret = bootstrapSecret;
+    saveAssistantEntry(entry);
+  }
+
+  const maxAttempts = 3;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await resetGuardianBootstrap(gatewayUrl, bootstrapSecret);
+      await leaseGuardianToken(gatewayUrl, entry.assistantId, bootstrapSecret);
+      return true;
+    } catch (err) {
+      if (err instanceof GuardianLeasePermanentError) return false;
+      if (attempt < maxAttempts) {
+        await new Promise((r) => setTimeout(r, 2000 * 2 ** (attempt - 1)));
+      }
+    }
+  }
+  return false;
 }
 
 export async function gatewayToken(): Promise<void> {
@@ -34,27 +79,15 @@ export async function gatewayToken(): Promise<void> {
     process.exit(1);
   }
 
-  const assistantId = args[1];
-  if (!assistantId) {
-    console.error("Missing required argument: <assistantId>");
-    printUsage();
-    process.exit(1);
-  }
-
-  const result = lookupAssistantByIdentifier(assistantId);
-  if (result.status !== "found") {
-    console.error(formatAssistantLookupError(assistantId, result));
-    process.exit(1);
-  }
-  const entry = result.entry;
-
-  const tokenData = loadGuardianToken(entry.assistantId);
-  if (!tokenData) {
-    console.error("No guardian token found for this assistant.");
-    process.exit(1);
-  }
+  const nameArg = args[1];
+  const entry = resolveTargetAssistant(nameArg);
 
   if (subcommand === "get") {
+    const tokenData = loadGuardianToken(entry.assistantId);
+    if (!tokenData) {
+      console.error("No guardian token found for this assistant.");
+      process.exit(1);
+    }
     console.log(tokenData.accessToken);
     return;
   }
@@ -70,6 +103,27 @@ export async function gatewayToken(): Promise<void> {
     entry.assistantId,
   );
   if (!refreshed.ok) {
+    // A spent credential (401 — expired/revoked refresh token) or a missing
+    // token file (404) is recoverable in place: re-lease via the gateway's
+    // bootstrap reset. The user explicitly invoked a refresh — this is the
+    // sanctioned recovery, never `cadet hatch` (a different assistant).
+    if (refreshed.status === 401 || refreshed.status === 404) {
+      const repaired = await repairGuardianCredential(entry, gatewayUrl);
+      if (repaired) {
+        const freshToken = loadGuardianToken(entry.assistantId);
+        if (freshToken) {
+          console.error(
+            "Re-provisioned guardian token (this revoked other devices' paired tokens).",
+          );
+          console.log(freshToken.accessToken);
+          return;
+        }
+      }
+      console.error("Guardian token could not be re-provisioned.");
+      console.error(
+        `Run \`cadet wake ${entry.assistantId} --repair-guardian\` to recover access.`,
+      );
+    }
     console.error(refreshed.error);
     console.error(
       formatGuardianRefreshCliFailure(refreshed.status, refreshed.error),