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

package/src/lib/docker.ts

@@ -27,6 +27,7 @@ import {
   ASSISTANT_INTERNAL_PORT,
   getDefaultPorts,
 } from "./environments/paths.js";
+import { green, yellow } from "./color.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { leaseGuardianToken } from "./guardian-token";
 import { logHatchNextSteps } from "./hatch-next-steps.js";
@@ -40,8 +41,8 @@ import {
 import { resolveOwnImageRefs } from "./cloud-releases.js";
 import { isDevVersion } from "./version-compat.js";
 import {
+  collectProviderApiKey,
   configureHatchProviderApiKey,
-  formatProviderName,
   promptProviderChoice,
   resolveHatchProvider,
   shouldPromptForHatchProvider,
@@ -340,14 +341,96 @@ export function resolveDockerProviderCredentialSetupAction(options: {
   provider: string | null | undefined;
   guardianAccessToken?: string;
   detached: boolean;
+  /**
+   * Key — or an explicit skip ("") — collected from the user right after
+   * they picked the provider. When present (even empty), the user already
+   * answered at the prompt, so detached hatches configure (or report the
+   * missing key) instead of deferring to a second `cadet setup` run.
+   */
+  precollectedKey?: string;
 }): DockerProviderCredentialSetupAction {
   if (options.provider === undefined) return "skip";
   if (options.provider === null) return options.detached ? "skip" : "configure";
-  if (options.detached) return "defer";
+  if (options.detached) {
+    if (options.precollectedKey !== undefined) {
+      return options.guardianAccessToken ? "configure" : "missing-token";
+    }
+    return "defer";
+  }
   if (!options.guardianAccessToken) return "missing-token";
   return "configure";
 }
 
+/** Time to wait for the Docker daemon to answer `docker info` after a Colima start. */
+const COLIMA_SETTLE_TIMEOUT_MS = 15_000;
+
+/** Poll `docker info` until the daemon answers or the timeout elapses. */
+async function waitForDockerDaemon(
+  execFn: typeof exec,
+  timeoutMs: number,
+): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      await execFn("docker", ["info"]);
+      return true;
+    } catch {
+      if (Date.now() >= deadline) return false;
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  }
+}
+
+/**
+ * Start Colima and wait for the Docker daemon to actually answer.
+ *
+ * `colima start` exiting 0 only means Colima's own state file says the VM is
+ * up — that state can be stale (zombie VM after a host sleep or crash), in
+ * which case start is a no-op ("already running, ignoring") while the daemon
+ * inside stays dead. So success is decided by re-probing `docker info`, and a
+ * failed probe triggers the manual-fix cycle: force-stop and start fresh.
+ * Never `colima delete` — the VM disk holds every container image and volume.
+ * `startArgs` carries extra flags (e.g. `--memory`) for a first start; the
+ * wake path starts an existing instance bare.
+ */
+async function startColimaAndAwaitDaemon(
+  execFn: typeof exec,
+  log: (msg: string) => void,
+  opts: { startArgs?: string[]; settleTimeoutMs?: number } = {},
+): Promise<void> {
+  const startArgs = opts.startArgs ?? [];
+  const settleTimeoutMs = opts.settleTimeoutMs ?? COLIMA_SETTLE_TIMEOUT_MS;
+
+  try {
+    await execFn("colima", ["start", ...startArgs]);
+  } catch (err) {
+    // exec captures the child's output and only surfaces it in the error —
+    // print it so a failed start is never silent.
+    log(`⚠️  colima start failed: ${err instanceof Error ? err.message : err}`);
+  }
+
+  if (await waitForDockerDaemon(execFn, settleTimeoutMs)) return;
+
+  log(
+    "🔄 Colima state looks stale — restarting the VM (colima stop --force, then start)...",
+  );
+  await execFn("colima", ["stop", "--force"]).catch(() => {});
+  try {
+    await execFn("colima", ["start", ...startArgs]);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to restart Colima. Please run 'colima stop --force && colima start' manually.\n${message}`,
+    );
+  }
+  if (!(await waitForDockerDaemon(execFn, settleTimeoutMs))) {
+    throw new Error(
+      "Docker daemon is still not reachable after restarting Colima. " +
+        "Check `colima status` and `docker info`, then try again.",
+    );
+  }
+}
+
 /**
  * Checks whether the `docker` CLI and daemon are available on the system.
  * Installs Colima and Docker via direct binary download if missing (no sudo
@@ -418,41 +501,9 @@ async function ensureDockerInstalled(): Promise<void> {
     }
 
     console.log("🚀 Docker daemon not running. Starting Colima...");
-    try {
-      await exec("colima", [
-        "start",
-        "--memory",
-        String(COLIMA_DEFAULT_MEMORY_GIB),
-      ]);
-    } catch {
-      // Colima may fail if a previous VM instance is in a corrupt state.
-      // Attempt to delete the stale instance and retry once.
-      console.log(
-        "⚠️  Colima start failed — attempting to reset stale VM state...",
-      );
-      try {
-        await exec("colima", ["stop", "--force"]).catch(() => {});
-        await exec("colima", ["delete", "--force"]);
-      } catch {
-        // If delete also fails, fall through to the retry which will
-        // produce a clear error message.
-      }
-
-      try {
-        console.log("🔄 Retrying colima start...");
-        await exec("colima", [
-          "start",
-          "--memory",
-          String(COLIMA_DEFAULT_MEMORY_GIB),
-        ]);
-      } catch (retryErr) {
-        const message =
-          retryErr instanceof Error ? retryErr.message : String(retryErr);
-        throw new Error(
-          `Failed to start Colima after resetting stale VM state. Please run 'colima start' manually.\n${message}`,
-        );
-      }
-    }
+    await startColimaAndAwaitDaemon(exec, console.log, {
+      startArgs: ["--memory", String(COLIMA_DEFAULT_MEMORY_GIB)],
+    });
   }
 }
 
@@ -486,6 +537,56 @@ export async function removeContainer(containerName: string): Promise<void> {
   }
 }
 
+/**
+ * Error signatures Docker Hub returns when the host has STALE Docker Hub
+ * credentials: an expired personal access token saved by a past
+ * `docker login` gets attached to the pull, and Hub rejects the request
+ * instead of falling back to anonymous access for a public image.
+ */
+export function isExpiredDockerHubCredentialError(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err);
+  return /personal access token is expired|authentication required|unauthorized/i.test(
+    message,
+  );
+}
+
+/**
+ * Pull an image, retrying once without stale credentials when Docker Hub
+ * rejects the pull with an expired-token/auth error — public pulls need no
+ * login, so `docker logout` (clears the stored Docker Hub credentials the
+ * docker CLI attaches to pulls) costs nothing. Other failures propagate raw;
+ * a still-failing auth retry is rethrown with actionable copy.
+ */
+export async function pullImage(
+  ref: string,
+  log: (msg: string) => void = console.log,
+  execFn: typeof exec = exec,
+): Promise<void> {
+  try {
+    await execFn("docker", ["pull", ref]);
+    return;
+  } catch (err) {
+    if (!isExpiredDockerHubCredentialError(err)) throw err;
+    log(
+      `⚠️  Docker Hub rejected the pull of ${ref} with an expired-credential ` +
+        `error — clearing stale Docker Hub login and retrying (public images ` +
+        `need no credentials)...`,
+    );
+    await execFn("docker", ["logout"]).catch(() => {});
+  }
+  try {
+    await execFn("docker", ["pull", ref]);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Failed to pull ${ref}.\n${message}\n` +
+        `If the Docker daemon is not running, start it, e.g. 'colima start' on macOS. ` +
+        `If the error mentions authentication, run 'docker logout' and check your ` +
+        `Docker Hub credentials — public image pulls need none.`,
+    );
+  }
+}
+
 export async function retireDocker(name: string): Promise<void> {
   console.log(`\u{1F5D1}\ufe0f  Stopping Docker containers for '${name}'...\n`);
 
@@ -846,7 +947,7 @@ export async function recreateDockerContainers(entry: AssistantEntry): Promise<v
   // 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]);
+    await pullImage(image, log);
   }
 
   const gatewayPort = parseGatewayPort(entry.runtimeUrl) ??
@@ -912,6 +1013,7 @@ function parseGatewayPort(runtimeUrl: string): number | null {
  */
 export async function ensureDockerDaemonRunning(
   execFn: typeof exec = exec,
+  opts: { settleTimeoutMs?: number } = {},
 ): Promise<void> {
   ensureLocalBinOnPath();
 
@@ -924,12 +1026,10 @@ export async function ensureDockerDaemonRunning(
     // No daemon reachable — fall through to the Colima fallback below.
   }
 
-  try {
-    await execFn("colima", ["status"]);
-  } catch {
-    console.log("🚀 Docker daemon not running. Starting Colima...");
-    await execFn("colima", ["start"]);
-  }
+  // Deliberately no `colima status` probe: it trusts Colima's own state file,
+  // which can be stale (zombie VM) — daemon reachability is the oracle.
+  console.log("🚀 Docker daemon not running. Starting Colima...");
+  await startColimaAndAwaitDaemon(execFn, console.log, opts);
 }
 
 /**
@@ -1234,6 +1334,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
   let provider = setupProviderCredentials
     ? resolveHatchProvider(configValues)
     : undefined;
+  let precollectedApiKey: string | undefined;
 
   if (
     shouldPromptForHatchProvider({
@@ -1246,6 +1347,9 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
     const picked = await promptProviderChoice();
     if (picked) {
       provider = picked;
+      // Collect the key immediately, while the choice is fresh — the
+      // startup logs are quiet now, so nothing separates the two prompts.
+      precollectedApiKey = await collectProviderApiKey(picked);
     }
   }
 
@@ -1427,7 +1531,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
           const MAX_PULL_RETRIES = 3;
           for (let attempt = 1; attempt <= MAX_PULL_RETRIES; attempt++) {
             try {
-              await exec("docker", ["pull", ref]);
+              await pullImage(ref, log);
               break;
             } catch (err) {
               if (attempt === MAX_PULL_RETRIES) throw err;
@@ -1440,7 +1544,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
           }
         }
       }
-      log("✅ Docker images acquired");
+      log(green("✅ Docker images acquired", process.stdout));
     }
 
     const res = dockerResourceNames(instanceName);
@@ -1631,6 +1735,7 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
         provider,
         guardianAccessToken,
         detached: waitDetached,
+        precollectedKey: precollectedApiKey,
       });
 
       if (providerSetupAction === "defer" && provider !== null) {
@@ -1640,23 +1745,22 @@ export async function hatchDocker(params: HatchDockerParams): Promise<void> {
         );
       } else if (providerSetupAction === "missing-token" && provider !== null) {
         log(
-          `⚠️  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.`,
+            process.stdout,
+          ),
         );
       } else if (
         providerSetupAction === "configure" &&
         provider !== undefined
       ) {
-        log(
-          provider === null
-            ? "Checking provider credentials..."
-            : `Checking ${formatProviderName(provider)} credentials...`,
-        );
         await configureHatchProviderApiKey({
           gatewayUrl: runtimeUrl,
           provider,
           bearerToken: guardianAccessToken,
           env: process.env,
+          precollectedKey: precollectedApiKey,
           log,
         });
       }
@@ -1749,25 +1853,12 @@ async function waitForGatewayAndLease(opts: {
   };
 
   if (detached) {
-    log("\n✅ Docker assistant hatched!\n");
-    log("Instance details:");
-    printInstanceDetails(
-      {
-        name: instanceName,
-        runtime: runtimeUrl,
-        container: containerName,
-      },
-      log,
-    );
-    log("");
-    log(`Stop with: cadet retire ${instanceName}`);
-
-    // Lease a guardian token even in detached mode so that `cadet ps`,
-    // `cadet exec`, and other CLI commands can authenticate to the
-    // gateway. Skip the /readyz readiness poll (the caller asked to detach
-    // and not block) but retry the lease itself since the gateway may need
-    // a moment to accept connections after the container starts.
-    const leaseStart = Date.now();
+    // Lease a guardian token BEFORE declaring the assistant hatched so the
+    // banner means `cadet ps`, `cadet exec`, and other CLI commands can
+    // already authenticate. Skip the /readyz readiness poll (the caller
+    // asked to detach and not block) but retry the lease silently since
+    // the gateway may need a moment to accept connections after the
+    // container starts; only a final failure surfaces to the user.
     const leaseDeadline = containersUpAt + DOCKER_READY_TIMEOUT_MS;
     let guardianAccessToken: string | undefined;
     while (Date.now() < leaseDeadline) {
@@ -1778,27 +1869,33 @@ async function waitForGatewayAndLease(opts: {
           bootstrapSecret,
         );
         guardianAccessToken = tokenData.accessToken;
-        const leaseElapsed = ((Date.now() - leaseStart) / 1000).toFixed(1);
-        log(
-          `Guardian token lease: success after ${leaseElapsed}s (principalId=${tokenData.guardianPrincipalId})`,
-        );
         break;
-      } catch (err) {
-        const elapsed = ((Date.now() - leaseStart) / 1000).toFixed(0);
-        const msg = err instanceof Error ? err.message : String(err);
-        log(
-          `Guardian token lease: attempt failed after ${elapsed}s (${msg.split("\n")[0]}), retrying...`,
-        );
+      } catch {
         await new Promise((r) => setTimeout(r, 2000));
       }
     }
     if (!guardianAccessToken) {
       log(
-        `⚠️  Guardian token lease failed after ${DOCKER_READY_TIMEOUT_MS / 1000}s.\n` +
-          `   The assistant is running but CLI commands (cadet ps, cadet exec) will not authenticate.\n` +
-          `   Re-hatch or run \`cadet setup\` to recover.`,
+        yellow(
+          `⚠️  Guardian token lease failed after ${DOCKER_READY_TIMEOUT_MS / 1000}s.\n` +
+            `   The assistant is running but CLI commands (cadet ps, cadet exec) will not authenticate.\n` +
+            `   Re-hatch or run \`cadet setup\` to recover.`,
+          process.stdout,
+        ),
       );
     }
+
+    log(`\n${green("✅ Docker assistant hatched!", process.stdout)}\n`);
+    log("Instance details:");
+    printInstanceDetails(
+      {
+        name: instanceName,
+        runtime: runtimeUrl,
+        container: containerName,
+      },
+      log,
+    );
+    log("");
     return { ready: true, guardianAccessToken };
   }
 
@@ -1879,7 +1976,6 @@ async function waitForGatewayAndLease(opts: {
   // Lease guardian token. The /readyz check confirms both gateway and
   // assistant are reachable. Retry with backoff in case there is a brief
   // window where readiness passes but the guardian endpoint is not yet ready.
-  log(`Guardian token lease: starting for ${instanceName} at ${runtimeUrl}`);
   const leaseStart = Date.now();
   const leaseDeadline = start + DOCKER_READY_TIMEOUT_MS;
   let leaseSuccess = false;
@@ -1893,38 +1989,30 @@ async function waitForGatewayAndLease(opts: {
         instanceName,
         bootstrapSecret,
       );
-      const leaseElapsed = ((Date.now() - leaseStart) / 1000).toFixed(1);
-      log(
-        `Guardian token lease: success after ${leaseElapsed}s (principalId=${tokenData.guardianPrincipalId}, expiresAt=${tokenData.accessTokenExpiresAt})`,
-      );
       guardianAccessToken = tokenData.accessToken;
       leaseSuccess = true;
       break;
     } catch (err) {
       lastLeaseError =
         err instanceof Error ? (err.stack ?? err.message) : String(err);
-      // Log periodically so the user knows we're still trying
-      const elapsed = ((Date.now() - leaseStart) / 1000).toFixed(0);
-      log(
-        `Guardian token lease: attempt failed after ${elapsed}s (${
-          lastLeaseError.split("\n")[0]
-        }), retrying...`,
-      );
     }
     await new Promise((r) => setTimeout(r, 2000));
   }
 
   if (!leaseSuccess) {
     log(
-      `\u26a0\ufe0f  Guardian token lease: FAILED after ${(
-        (Date.now() - leaseStart) /
-        1000
-      ).toFixed(1)}s — ${lastLeaseError ?? "unknown error"}`,
+      yellow(
+        `\u26a0\ufe0f  Guardian token lease: FAILED after ${(
+          (Date.now() - leaseStart) /
+          1000
+        ).toFixed(1)}s — ${lastLeaseError ?? "unknown error"}`,
+        process.stdout,
+      ),
     );
   }
 
   log("");
-  log(`\u2705 Docker containers are up and running!`);
+  log(green(`\u2705 Docker containers are up and running!`, process.stdout));
   log(`   Name: ${instanceName}`);
   log(`   Runtime: ${runtimeUrl}`);
   log("");

package/src/lib/ensure-binary.ts

@@ -0,0 +1,171 @@
+import { spawnSync } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+
+/**
+ * Consolidated missing-dependency flow for interactive commands: probe for a
+ * binary, and when it is absent, offer to install it — naming no commands —
+ * then run the right package manager for the platform and verify. Callers
+ * supply the recipes; everything else (prompt, package-manager discovery,
+ * fallback copy) lives here so every command behaves the same.
+ */
+
+export interface EnsureBinaryOptions {
+  /** The binary as invoked on PATH, e.g. "nginx". */
+  binary: string;
+  /** What the running command needs it for, e.g. "the tunnel edge". */
+  purpose: string;
+  /**
+   * Package-manager name → full install argv (sudo included where needed),
+   * e.g. `{ brew: ["brew", "install", "nginx"] }`. The first entry whose
+   * package manager is available wins. Leave out a platform rather than
+   * guessing at an unreliable package ID — the manual hint covers it.
+   */
+  packages: Record<string, string[]>;
+  /** Shown when the user declines or auto-install fails. */
+  manualHint: string;
+  /** Probe: a version-ish string when the binary is usable, null otherwise. */
+  probe: () => string | null;
+  /** Check that a package manager exists. Default: `<pm> --version` probe. */
+  pmAvailable?: (pm: string) => boolean;
+  /** Run an install argv; true on success. Default: inherit-stdio spawnSync. */
+  runInstall?: (argv: string[]) => boolean;
+  /** Confirm the install. Default: promptLine "[Y/n]" on Enter-as-yes. */
+  confirmInstall?: () => Promise<boolean>;
+  streams?: {
+    input?: NodeJS.ReadStream | Readable;
+    output?: NodeJS.WriteStream | Writable;
+  };
+}
+
+/**
+ * Prompt-then-install a missing binary. Returns the probe result — the
+ * existing version when the binary was already present, the fresh one after a
+ * successful install — or null when the binary is missing and the user
+ * declines, no package manager matches, or the install fails. Non-interactive
+ * callers (no TTY) never hang: they get the manual hint and null.
+ */
+export async function ensureBinaryInstalled(
+  opts: EnsureBinaryOptions,
+): Promise<string | null> {
+  const output = opts.streams?.output ?? process.stdout;
+
+  const existing = opts.probe();
+  if (existing) return existing;
+
+  output.write(
+    `\n${opts.binary} is required for ${opts.purpose}, but it isn't installed.\n`,
+  );
+
+  const confirm = opts.confirmInstall ?? defaultConfirm(opts);
+  let install = false;
+  try {
+    install = await confirm();
+  } catch {
+    install = false;
+  }
+  if (!install) {
+    output.write(`Skipping install. ${opts.manualHint}\n`);
+    return null;
+  }
+
+  const pmAvailable = opts.pmAvailable ?? probePackageManager;
+  const argv = Object.entries(opts.packages).find(([pm]) =>
+    pmAvailable(pm),
+  )?.[1];
+  if (!argv) {
+    output.write(`⚠ No supported package manager found. ${opts.manualHint}\n`);
+    return null;
+  }
+
+  const ok = opts.runInstall ? opts.runInstall(argv) : runInstallArgv(argv);
+  const version = ok ? opts.probe() : null;
+  if (!version) {
+    output.write(
+      `⚠ Couldn't install ${opts.binary} automatically. ${opts.manualHint}\n`,
+    );
+    return null;
+  }
+  output.write(`✅ Installed ${opts.binary} (${version}).\n`);
+  return version;
+}
+
+/** Default confirm: visible prompt, Enter = yes, non-TTY throws. */
+function defaultConfirm(opts: EnsureBinaryOptions): () => Promise<boolean> {
+  return async () => {
+    const input = opts.streams?.input ?? process.stdin;
+    const output = opts.streams?.output ?? process.stdout;
+    // Readable has no isTTY; only a real terminal answers the prompt.
+    if (!("isTTY" in input) || !input.isTTY) {
+      throw new Error("Install confirm requires an interactive terminal.");
+    }
+    const answer = (
+      await readLineText(`Install ${opts.binary} now? [Y/n] `, {
+        input,
+        output,
+      })
+    )
+      .trim()
+      .toLowerCase();
+    return answer === "" || answer === "y" || answer === "yes";
+  };
+}
+
+/** Default installer: blocking spawn with inherited stdio (passwords flow). */
+function runInstallArgv(argv: string[]): boolean {
+  const [command, ...args] = argv;
+  if (!command) return false;
+  const result = spawnSync(command, args, { stdio: "inherit" });
+  return !result.error && result.status === 0;
+}
+
+/** Default package-manager check: the manager answers `--version`. */
+function probePackageManager(pm: string): boolean {
+  const result = spawnSync(pm, ["--version"], {
+    stdio: "ignore",
+    shell: process.platform === "win32",
+    windowsHide: true,
+  });
+  return !result.error && result.status === 0;
+}
+
+/**
+ * Read one visible line from stdin (Enter submits). Shared by the binary
+ * install confirm and the ngrok authtoken paste-in, so both degrade the same
+ * way on a non-interactive terminal (the caller decides what empty means).
+ */
+export async function readLineText(
+  prompt: string,
+  streams: { input?: Readable; output?: Writable } = {},
+): Promise<string> {
+  const input = streams.input ?? process.stdin;
+  const output = streams.output ?? process.stdout;
+
+  output.write(prompt);
+
+  return new Promise((resolve, reject) => {
+    let line = "";
+    const onData = (chunk: Buffer | string): void => {
+      line += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+      const newline = line.indexOf("\n");
+      if (newline !== -1) {
+        done(line.slice(0, newline).replace(/\r$/, ""));
+      }
+    };
+    const cleanup = (): void => {
+      input.removeListener("data", onData);
+      input.removeListener("error", onError);
+      input.pause();
+    };
+    const done = (value: string): void => {
+      cleanup();
+      resolve(value);
+    };
+    const onError = (err: Error): void => {
+      cleanup();
+      reject(err);
+    };
+    input.resume();
+    input.on("data", onData);
+    input.on("error", onError);
+  });
+}

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

@@ -39,9 +39,11 @@ const {
   getConfigDir,
   getConfigDirs,
   getDefaultPorts,
+  getInputHistoryPath,
   getLockfilePath,
   getLockfilePaths,
   getMultiInstanceDir,
+  getSharedStateDir,
 } = await import("../paths.js");
 type EnvironmentDefinition =
   import("@mycadet/environments").EnvironmentDefinition;
@@ -58,7 +60,12 @@ const dev: EnvironmentDefinition = {
   webUrl: "https://dev.mycadet.ai",
 };
 
-const XDG_ENV_VARS = ["XDG_DATA_HOME", "XDG_CONFIG_HOME", "APPDATA"] as const;
+const XDG_ENV_VARS = [
+  "XDG_DATA_HOME",
+  "XDG_CONFIG_HOME",
+  "XDG_STATE_HOME",
+  "APPDATA",
+] as const;
 
 describe("path helpers", () => {
   let savedEnv: Record<string, string | undefined>;
@@ -224,6 +231,25 @@ describe("path helpers", () => {
     });
   });
 
+  describe("getSharedStateDir", () => {
+    test("is not environment-scoped: ~/.local/state/cadet for every env", () => {
+      expect(getSharedStateDir()).toBe(
+        join(TEST_HOME, ".local", "state", "cadet"),
+      );
+    });
+
+    test("respects XDG_STATE_HOME", () => {
+      process.env.XDG_STATE_HOME = "/custom/state";
+      expect(getSharedStateDir()).toBe("/custom/state/cadet");
+    });
+
+    test("holds the shared terminal input history file", () => {
+      expect(getInputHistoryPath()).toBe(
+        join(getSharedStateDir(), "input-history"),
+      );
+    });
+  });
+
   describe("getDefaultPorts", () => {
     test("returns production defaults for production", () => {
       const ports = getDefaultPorts(prod);