@mycadet/cli 0.12.8 → 0.12.9

package/src/commands/tunnel.ts

@@ -22,9 +22,10 @@ import {
 } from "../lib/ingress-config.js";
 import {
   ensureTunnelEdge,
-  formatEdgeMode,
+  getNginxVersion,
   type TunnelEdge,
 } from "../lib/nginx-ingress.js";
+import { ensureBinaryInstalled } from "../lib/ensure-binary.js";
 import { STALE_CLI_UPDATE_HINT } from "../lib/stale-cli-hint.js";
 import {
   ADOPTED_TUNNEL_RE,
@@ -73,29 +74,30 @@ function parseArgs(): TunnelArgs {
       console.log(
         "How far that URL reaches depends on the provider; omit --provider for",
       );
-      console.log("the default. A tailscale tunnel is reachable only from your");
       console.log(
-        "own tailnet; webhook integrations need a public tunnel (see Providers",
+        "the default. A tailscale tunnel is reachable only from your",
       );
-      console.log("below).");
+      console.log(
+        "own tailnet; webhook integrations need a public tunnel. See Providers",
+      );
+      console.log("below.");
       console.log("");
       console.log(
         "The tunnel always fronts the local nginx edge, which is started automatically.",
       );
       console.log(
-        "nginx must be installed (macOS: brew install nginx, Linux: sudo apt install nginx).",
+        "nginx must be installed; if it is missing, cadet offers to install it.",
       );
       console.log("");
       console.log("Arguments:");
       console.log(
-        "  <name>                        Name of the assistant (defaults to active or only local)",
+        "  <name>                        Name of the assistant, defaults to active or only local",
       );
       console.log("");
       console.log("Options:");
       console.log(
-        `  --provider <provider>         Tunnel provider: ${TUNNEL_PROVIDERS.join(", ")}`,
+        `  --provider <provider>         Tunnel provider: ${TUNNEL_PROVIDERS.join(", ")} — default ${DEFAULT_TUNNEL_PROVIDER}`,
       );
-      console.log(`                                (default: ${DEFAULT_TUNNEL_PROVIDER})`);
       console.log(
         "  --domain <domain>             Reserved domain to bind, for providers that support",
       );
@@ -137,7 +139,8 @@ function parseArgs(): TunnelArgs {
       console.log("");
       console.log("Examples:");
       console.log(`  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER}`);
-      const domainExample = PROVIDER_META[DEFAULT_TUNNEL_PROVIDER].domainExample;
+      const domainExample =
+        PROVIDER_META[DEFAULT_TUNNEL_PROVIDER].domainExample;
       if (domainExample) {
         console.log(
           `  $ cadet tunnel --provider ${DEFAULT_TUNNEL_PROVIDER} --domain ${domainExample}`,
@@ -174,7 +177,8 @@ function parseArgs(): TunnelArgs {
     } else if (arg === "--domain") {
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
-        const domainExample = PROVIDER_META[DEFAULT_TUNNEL_PROVIDER].domainExample;
+        const domainExample =
+          PROVIDER_META[DEFAULT_TUNNEL_PROVIDER].domainExample;
         console.error(
           `Error: --domain requires a value${domainExample ? `, e.g. --domain ${domainExample}` : ""}`,
         );
@@ -199,9 +203,7 @@ function parseArgs(): TunnelArgs {
 
   if (provider === null) {
     provider = DEFAULT_TUNNEL_PROVIDER;
-    console.log(
-      `Using the default provider: ${provider} (pass --provider to choose another).`,
-    );
+    console.log(`Using the default provider: ${provider}.`);
   }
 
   if (domain && !providerSupportsReservedDomain(provider)) {
@@ -415,57 +417,78 @@ async function spawnDetachedTunnel(): Promise<void> {
 
 export const tunnel = Object.assign(
   async function tunnel(): Promise<void> {
-  const { assistantName, provider, domain, clearDomain, detach } = parseArgs();
+    const { assistantName, provider, domain, clearDomain, detach } =
+      parseArgs();
 
-  if (detach) {
-    await spawnDetachedTunnel();
-    return;
-  }
+    if (detach) {
+      await spawnDetachedTunnel();
+      return;
+    }
 
-  if (PROVIDER_META[provider].comingSoon) {
-    throw cadetTunnelComingSoonError(provider);
-  }
+    if (PROVIDER_META[provider].comingSoon) {
+      throw cadetTunnelComingSoonError(provider);
+    }
 
-  const { entry, gatewayPort, workspaceDir } =
-    resolveLocalTunnelTarget(assistantName);
+    const { entry, gatewayPort, workspaceDir } =
+      resolveLocalTunnelTarget(assistantName);
 
-  const preserveIngressUrl =
-    provider === "tailscale" && guardTailnetOnlyWebhookIngress(workspaceDir);
+    const preserveIngressUrl =
+      provider === "tailscale" && guardTailnetOnlyWebhookIngress(workspaceDir);
 
-  if (clearDomain) {
-    clearReservedDomain();
-    console.log("Cleared the saved reserved domain.");
-  }
+    if (clearDomain) {
+      clearReservedDomain();
+      console.log("Cleared the saved reserved domain.");
+    }
 
-  let edge: TunnelEdge;
-  try {
-    edge = await ensureTunnelEdge({
-      assistantId: entry.assistantId,
-      workspaceDir,
-      gatewayPort,
+    const nginxVersion = await ensureBinaryInstalled({
+      binary: "nginx",
+      purpose: "the tunnel edge",
+      packages: {
+        brew: ["brew", "install", "nginx"],
+        "apt-get": ["sudo", "apt-get", "install", "-y", "nginx"],
+        dnf: ["sudo", "dnf", "install", "-y", "nginx"],
+        pacman: ["sudo", "pacman", "-S", "--noconfirm", "nginx"],
+        zypper: ["sudo", "zypper", "install", "-y", "nginx"],
+        choco: ["choco", "install", "-y", "nginx"],
+      },
+      manualHint:
+        "See https://nginx.org/en/docs/install.html for how to install, or point NGINX_BIN at an existing binary.",
+      probe: getNginxVersion,
     });
-  } catch (err) {
-    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
-  }
+    if (!nginxVersion) {
+      console.error("Error: nginx is required to run the tunnel edge.");
+      process.exit(1);
+    }
 
-  console.log(
-    `${edge.started ? "Started" : "Reusing"} the nginx edge on 127.0.0.1:${edge.port} ` +
-      `(serves ${formatEdgeMode(edge.includesWebApp)}).`,
-  );
+    let edge: TunnelEdge;
+    try {
+      edge = await ensureTunnelEdge({
+        assistantId: entry.assistantId,
+        workspaceDir,
+        gatewayPort,
+      });
+    } catch (err) {
+      console.error(
+        `Error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      process.exit(1);
+    }
+
+    console.log(
+      `${edge.started ? "Started" : "Reusing"} the nginx edge on 127.0.0.1:${edge.port}.`,
+    );
 
-  const baseTunnelOpts = {
-    port: edge.port,
-    assistantId: entry.assistantId,
-    workspaceDir,
-  };
+    const baseTunnelOpts = {
+      port: edge.port,
+      assistantId: entry.assistantId,
+      workspaceDir,
+    };
 
-  await runProviderTunnel(provider, {
-    ...baseTunnelOpts,
-    ...(domain ? { domain } : {}),
-    ...(preserveIngressUrl ? { preserveIngressUrl } : {}),
-  });
-},
+    await runProviderTunnel(provider, {
+      ...baseTunnelOpts,
+      ...(domain ? { domain } : {}),
+      ...(preserveIngressUrl ? { preserveIngressUrl } : {}),
+    });
+  },
   { description: "Create a tunnel for a locally hosted assistant" },
 );
-

package/src/commands/uninstall.ts

@@ -141,7 +141,7 @@ function selfDelete(): void {
       "Cadet is running from a source checkout — skipping self-removal.",
     );
     console.log(
-      "Remove the installed copy with `bun remove -g mycadet` (or `npm uninstall -g mycadet`).",
+      "Remove the installed copy with `bun remove -g mycadet` or `npm uninstall -g mycadet`.",
     );
     return;
   }
@@ -206,14 +206,14 @@ export const uninstall = Object.assign(
     const existing = loadAllAssistants();
     if (existing.length > 0) {
       console.warn(
-        `\n⚠️  ${existing.length} assistant(s) still exist: ${existing.map((a) => a.assistantId).join(", ")}`,
+        `\n⚠️  ${existing.length} ${existing.length === 1 ? "assistant still exists" : "assistants still exist"}: ${existing.map((a) => a.assistantId).join(", ")}`,
       );
       console.warn(
         "   They will be retired now — their data (and any retired archives) will be permanently deleted by this uninstall.",
       );
       for (const entry of existing) {
         if (entry.cloud === "apple-container" || entry.cloud === "paired") {
-          console.log(`   Skipping '${entry.assistantId}' (${entry.cloud}) — its lifecycle is managed elsewhere.`);
+          console.log(`   Skipping '${entry.assistantId}' on ${entry.cloud} — its lifecycle is managed elsewhere.`);
           continue;
         }
         try {
@@ -239,7 +239,7 @@ export const uninstall = Object.assign(
     } else {
       console.log("It will permanently delete:");
       for (const t of targets) {
-        console.log(`  - ${t.path}  (${t.description})`);
+        console.log(`  - ${t.path}  — ${t.description}`);
       }
     }
     const execBase = basename(execPath);

package/src/commands/upgrade.ts

@@ -19,6 +19,7 @@ import {
   GATEWAY_INTERNAL_PORT,
   ASSISTANT_INTERNAL_PORT,
   dockerResourceNames,
+  pullImage,
   startContainers,
   stopContainers,
 } from "../lib/docker";
@@ -46,7 +47,6 @@ import {
 } from "../lib/backup-ops.js";
 import { emitCliError, categorizeUpgradeError } from "../lib/cli-error.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
-import { exec } from "../lib/step-runner.js";
 import {
   broadcastUpgradeEvent,
   attemptFailedStateRestore,
@@ -118,12 +118,12 @@ function parseArgs(): UpgradeArgs {
       console.log("");
       console.log("Arguments:");
       console.log(
-        "  <name>               Name of the assistant to upgrade (default: active or only assistant)",
+        "  <name>               Name of the assistant to upgrade, defaults to active or only assistant",
       );
       console.log("");
       console.log("Options:");
       console.log(
-        "  --version <version>  Target version to upgrade to (default: CLI version)",
+        "  --version <version>  Target version to upgrade to, defaults to the CLI version",
       );
       console.log(
         "  --latest             Upgrade to the latest stable release, updating the CLI first if needed",
@@ -316,7 +316,7 @@ async function upgradeDocker(
       );
       return;
     }
-    console.log(`🔁 Reinstalling ${versionTag} (--force)...\n`);
+    console.log(`🔁 Reinstalling ${versionTag} with --force...\n`);
   }
 
   console.log("🔍 Resolving image references...");
@@ -406,7 +406,7 @@ async function upgradeDocker(
   try {
     for (const [service, image] of pullImages) {
       console.log(`   Pulling ${service}: ${image}`);
-      await exec("docker", ["pull", image]);
+      await pullImage(image);
     }
   } catch (pullErr) {
     const detail = pullErr instanceof Error ? pullErr.message : String(pullErr);
@@ -453,7 +453,7 @@ async function upgradeDocker(
     // Clean up old pre-upgrade backups, keep last 3
     pruneOldBackups(entry.assistantId, 3);
   } else {
-    console.warn("⚠️  Pre-upgrade backup failed (continuing with upgrade)\n");
+    console.warn("⚠️  Pre-upgrade backup failed, continuing with upgrade\n");
   }
 
   // Persist the backup path so `cadet rollback` can restore the exact backup
@@ -891,7 +891,7 @@ async function upgradeLocal(
       );
       return;
     }
-    console.log(`🔁 Reinstalling ${targetVersion} (--force)...\n`);
+    console.log(`🔁 Reinstalling ${targetVersion} with --force...\n`);
   }
 
   console.log(
@@ -933,7 +933,7 @@ async function upgradeLocal(
     console.log(`   Backup saved: ${backupPath}\n`);
     pruneOldBackups(entry.assistantId, 3);
   } else {
-    console.warn("⚠️  Pre-upgrade backup failed (continuing with upgrade)\n");
+    console.warn("⚠️  Pre-upgrade backup failed, continuing with upgrade\n");
   }
 
   let bootstrapSecret = entry.guardianBootstrapSecret;

package/src/commands/use.ts

@@ -38,7 +38,7 @@ export const use = Object.assign(
           `Active assistant: ${formatAssistantReference(result.entry)}`,
         );
       } else {
-        console.log(`Active assistant: ${active} (not found in lockfile)`);
+        console.log(`Active assistant: ${active} — not found in lockfile`);
       }
     } else {
       console.log("No active assistant set.");

package/src/commands/wake.ts

@@ -58,7 +58,7 @@ export const wake = Object.assign(
     console.log("");
     console.log("Arguments:");
     console.log(
-      "  <name>    Name of the assistant to start (default: active or only local)",
+      "  <name>    Name of the assistant to start, defaults to active or only local",
     );
     console.log("");
     console.log("Options:");
@@ -122,7 +122,7 @@ export const wake = Object.assign(
   // Foreground blocking is a single-assistant concern (--all refuses the
   // flag), and the docker path already warned that foreground is ignored.
   if (foreground && entry.cloud !== "docker") {
-    console.log("Running in foreground (Ctrl+C to stop)...\n");
+    console.log("Running in the foreground, Ctrl+C to stop...\n");
     // Block forever — the daemon is running with inherited stdio so its
     // output streams to this terminal. When the user hits Ctrl+C, SIGINT
     // propagates to the daemon child and both exit.
@@ -213,7 +213,7 @@ async function wakeAssistant(
         .filter(Boolean)
         .join(" and ");
       console.warn(
-        `Warning: ${ignored} ignored for Docker instances (not supported).`,
+        `Warning: ${ignored} ignored for Docker instances.`,
       );
     }
     const res = dockerResourceNames(entry.assistantId);
@@ -364,7 +364,7 @@ async function wakeAssistant(
       daemonMigrationsFailed = daemonState.status === "migration_failed";
       if (watch) {
         console.log(
-          `Assistant running (pid ${daemonState.pid}) — watch mode not available (no source files). Keeping existing process.`,
+          `Assistant running (pid ${daemonState.pid}) — watch mode not available, no source files. Keeping existing process.`,
         );
       } else if (daemonMigrationsFailed) {
         console.log(
@@ -488,7 +488,7 @@ async function wakeAssistant(
       } else {
         if (watch) {
           console.log(
-            `Gateway running (pid ${gatewayState.pid}) — watch mode not available (no source files). Keeping existing process.`,
+            `Gateway running (pid ${gatewayState.pid}) — watch mode not available, no source files. Keeping existing process.`,
           );
         } else {
           console.log(`Gateway already running (pid ${gatewayState.pid}).`);
@@ -569,7 +569,7 @@ async function wakeAssistant(
           await new Promise((r) => setTimeout(r, 2000 * 2 ** (attempt - 1)));
         } else {
           console.warn(
-            `   Guardian token re-provision failed${err instanceof GuardianLeasePermanentError ? " (not retrying — a malformed 200 will not fix itself)" : ` after ${maxAttempts} attempts`}: ${err}`,
+            `   Guardian token re-provision failed${err instanceof GuardianLeasePermanentError ?", not retrying — a malformed 200 will not fix itself" : ` after ${maxAttempts} attempts`}: ${err}`,
           );
           // The user explicitly confirmed this destructive repair — a
           // success exit here would make callers (the web recovery flow)

package/src/index.ts

@@ -14,6 +14,7 @@ import cliPkg from "../package.json";
 import { backup } from "./commands/backup";
 import { clean } from "./commands/clean";
 import { client } from "./commands/client";
+import { completeCadet, completions } from "./commands/completions";
 import { confirm } from "./commands/confirm";
 import { connect } from "./commands/connect";
 import { devices } from "./commands/devices";
@@ -53,6 +54,7 @@ const commands = {
   backup,
   clean,
   client,
+  completions,
   confirm,
   connect,
   debug,
@@ -231,6 +233,19 @@ async function main() {
     process.exit(0);
   }
 
+  // Hidden completion hook: the bash completion script calls
+  // `cadet __complete <words-up-to-cursor>` and filters the printed
+  // candidates against the word under the cursor. Deliberately unlisted in
+  // the command map so it never shows up in help.
+  if (commandName === "__complete") {
+    const candidates = completeCadet(
+      process.argv.slice(3),
+      Object.keys(commands),
+    );
+    console.log(candidates.join("\n"));
+    process.exit(0);
+  }
+
   const command = commands[commandName as CommandName];
 
   if (!command) {

package/src/lib/__tests__/docker.test.ts

@@ -8,6 +8,7 @@ import {
   collectWatchTargets,
   dockerResourceNames,
   ensureDockerDaemonRunning,
+  pullImage,
   resolveAvatarDevicePath,
   resolveDockerHatchMode,
   resolveDockerProviderCredentialSetupAction,
@@ -158,6 +159,38 @@ describe("resolveDockerProviderCredentialSetupAction", () => {
       }),
     ).toBe("skip");
   });
+
+  test("detached hatch with a pre-collected key configures instead of deferring", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "fireworks",
+        guardianAccessToken: "guardian-token",
+        detached: true,
+        precollectedKey: "fw-key-123",
+      }),
+    ).toBe("configure");
+  });
+
+  test("pre-collected key without a guardian token reports missing-token (no silent defer)", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "fireworks",
+        detached: true,
+        precollectedKey: "fw-key-123",
+      }),
+    ).toBe("missing-token");
+  });
+
+  test("an explicitly skipped key still counts as answered — configure runs and reports the gap", () => {
+    expect(
+      resolveDockerProviderCredentialSetupAction({
+        provider: "fireworks",
+        guardianAccessToken: "guardian-token",
+        detached: true,
+        precollectedKey: "",
+      }),
+    ).toBe("configure");
+  });
 });
 
 describe("buildServiceRunArgs — gateway", () => {
@@ -384,25 +417,48 @@ describe("collectWatchTargets", () => {
 });
 
 /**
- * Build a fake `exec` that records calls and fails the probes named in `fail`.
- * Injected into `ensureDockerDaemonRunning` so these cases need no `mock.module`
- * (which is process-global and would leak across the CLI's single-process test
- * run) and no real Docker/Colima subprocesses.
+ * Build a STATEFUL fake `exec` modeling the Docker daemon + Colima interplay:
+ * `docker info` succeeds only while `daemonUp`; a `colima start` heals the
+ * daemon (unless the fake is told to model the zombie state, where Colima's
+ * state file says "already running, ignoring" but the daemon stays dead —
+ * only the stop → start cycle recovers). Injected into
+ * `ensureDockerDaemonRunning` so these cases need no `mock.module` (which is
+ * process-global and would leak across the CLI's single-process test run) and
+ * no real Docker/Colima subprocesses.
  */
-function fakeExec(fail: { dockerInfo?: boolean; colimaStatus?: boolean }) {
+function fakeExec(
+  opts: {
+    /** Daemon already reachable when the test starts. */
+    daemonUpAtStart?: boolean;
+    /** `colima start` exits nonzero instead of healing. */
+    startFails?: boolean;
+    /** First `colima start` is a zombie no-op that does NOT heal the daemon. */
+    zombieFirstStart?: boolean;
+  } = {},
+) {
   const calls: Array<{ cmd: string; args: string[] }> = [];
+  let daemonUp = opts.daemonUpAtStart ?? false;
+  let starts = 0;
   const exec = async (cmd: string, args: string[] = []): Promise<void> => {
     calls.push({ cmd, args });
-    if (cmd === "docker" && args[0] === "info" && fail.dockerInfo) {
-      throw new Error("Cannot connect to the Docker daemon");
+    if (cmd === "docker" && args[0] === "info") {
+      if (!daemonUp) throw new Error("Cannot connect to the Docker daemon");
+      return;
+    }
+    if (cmd === "colima" && args[0] === "start") {
+      starts++;
+      if (opts.startFails) throw new Error("colima start exited 1");
+      if (!opts.zombieFirstStart || starts > 1) daemonUp = true;
+      return;
     }
-    if (cmd === "colima" && args[0] === "status" && fail.colimaStatus) {
-      throw new Error("colima is not running");
+    if (cmd === "colima" && args[0] === "stop") {
+      daemonUp = false;
+      return;
     }
   };
   const ran = (cmd: string, sub: string): boolean =>
     calls.some((c) => c.cmd === cmd && c.args[0] === sub);
-  return { exec: exec as typeof import("../step-runner.js").exec, ran };
+  return { exec, ran };
 }
 
 describe("ensureDockerDaemonRunning", () => {
@@ -410,30 +466,122 @@ describe("ensureDockerDaemonRunning", () => {
   // Colima, because that switches the active `docker context` and points
   // `docker start` at a VM that never held the instance's containers.
   test("reuses an already-reachable daemon (e.g. Docker Desktop) and never touches Colima", async () => {
-    const { exec, ran } = fakeExec({ dockerInfo: false });
+    const { exec, ran } = fakeExec({ daemonUpAtStart: true });
 
     await ensureDockerDaemonRunning(exec);
 
     expect(ran("docker", "info")).toBe(true);
-    expect(ran("colima", "status")).toBe(false);
     expect(ran("colima", "start")).toBe(false);
+    expect(ran("colima", "stop")).toBe(false);
   });
 
-  test("starts Colima only when no daemon is reachable", async () => {
-    const { exec, ran } = fakeExec({ dockerInfo: true, colimaStatus: true });
+  test("starts Colima when no daemon is reachable and confirms the daemon answered", async () => {
+    const { exec, ran } = fakeExec();
 
-    await ensureDockerDaemonRunning(exec);
+    await ensureDockerDaemonRunning(exec, { settleTimeoutMs: 0 });
 
     expect(ran("docker", "info")).toBe(true);
     expect(ran("colima", "start")).toBe(true);
+    expect(ran("colima", "stop")).toBe(false);
   });
 
-  test("does not restart Colima when it is already running", async () => {
-    const { exec, ran } = fakeExec({ dockerInfo: true, colimaStatus: false });
+  // Regression (v0.12.8 release feedback): a zombie Colima — stale state file
+  // saying "already running" while the daemon inside is dead — used to sail
+  // through wake (no `colima status` oracle anymore) and leave every later
+  // docker command dying on the unreachable socket.
+  test("recovers a zombie Colima: start no-ops, daemon stays dead → stop --force → start → daemon up", async () => {
+    const { exec, ran } = fakeExec({ zombieFirstStart: true });
 
-    await ensureDockerDaemonRunning(exec);
+    await ensureDockerDaemonRunning(exec, { settleTimeoutMs: 0 });
 
-    expect(ran("colima", "status")).toBe(true);
-    expect(ran("colima", "start")).toBe(false);
+    expect(ran("colima", "start")).toBe(true);
+    expect(ran("colima", "stop")).toBe(true);
+  });
+
+  test("never deletes the Colima VM — the VM disk holds every image and volume", async () => {
+    const { exec, ran } = fakeExec({ zombieFirstStart: true });
+
+    await ensureDockerDaemonRunning(exec, { settleTimeoutMs: 0 });
+
+    expect(ran("colima", "delete")).toBe(false);
+  });
+
+  test("throws an actionable error when even the restart cannot bring the daemon up", () => {
+    // A start that always exits nonzero: the first failure surfaces its
+    // output, the recovery stop+start runs, and the final wait still finds
+    // no daemon → the helper throws instead of letting hatch proceed.
+    const { exec } = fakeExec({ startFails: true });
+    expect(
+      ensureDockerDaemonRunning(exec, { settleTimeoutMs: 0 }),
+    ).rejects.toThrow(/Failed to restart Colima/);
+  });
+});
+
+describe("pullImage", () => {
+  function fakePull(
+    opts: {
+      failFirstPullWith?: string;
+      failAllPullsWith?: string;
+    } = {},
+  ) {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    let pulls = 0;
+    const exec = async (cmd: string, args: string[] = []): Promise<void> => {
+      calls.push({ cmd, args });
+      if (cmd === "docker" && args[0] === "pull") {
+        pulls++;
+        if (opts.failAllPullsWith) throw new Error(opts.failAllPullsWith);
+        if (opts.failFirstPullWith && pulls === 1) {
+          throw new Error(opts.failFirstPullWith);
+        }
+      }
+      // `docker logout` (and anything else) succeeds silently.
+    };
+    const ran = (sub: string): boolean =>
+      calls.some((c) => c.cmd === "docker" && c.args[0] === sub);
+    return { exec, ran };
+  }
+
+  test("pulls without touching stored credentials on success", async () => {
+    const { exec, ran } = fakePull();
+
+    await pullImage("mycadet/mycadet-assistant:v1", () => {}, exec);
+
+    expect(ran("pull")).toBe(true);
+    expect(ran("logout")).toBe(false);
+  });
+
+  test("clears stale Docker Hub credentials and retries once on an expired-token error", async () => {
+    const { exec, ran } = fakePull({
+      failFirstPullWith:
+        "Error response from daemon: authentication required - personal access token is expired",
+    });
+
+    await pullImage("mycadet/mycadet-assistant:v1", () => {}, exec);
+
+    expect(ran("logout")).toBe(true);
+  });
+
+  test("wraps the failure with actionable copy when the auth retry also fails", () => {
+    const { exec } = fakePull({
+      failAllPullsWith:
+        "Error response from daemon: authentication required - personal access token is expired",
+    });
+
+    expect(
+      pullImage("mycadet/mycadet-assistant:v1", () => {}, exec),
+    ).rejects.toThrow("Failed to pull mycadet/mycadet-assistant:v1");
+  });
+
+  test("rethrows non-auth pull errors raw and never logs out", () => {
+    const { exec, ran } = fakePull({
+      failAllPullsWith:
+        "Cannot connect to the Docker daemon at unix:///var/run/docker.sock",
+    });
+
+    expect(
+      pullImage("mycadet/mycadet-assistant:v1", () => {}, exec),
+    ).rejects.toThrow("Cannot connect to the Docker daemon");
+    expect(ran("logout")).toBe(false);
   });
 });

package/src/lib/__tests__/job-polling.test.ts

@@ -203,7 +203,7 @@ describe("pollJobUntilDone", () => {
       expect(refreshes).toBe(1);
       expect(calls).toBe(2);
       // The 401 branch logs its own distinct warning (not the generic
-      // "polling failed, retrying" one) so operators can distinguish an
+      // "polling failed:" one) so operators can distinguish an
       // auth refresh from a transient-error retry in the output.
       expect(warnSpy).toHaveBeenCalledWith(
         expect.stringContaining("refreshing auth"),