foldrun 0.5.0 → 0.6.0

package/README.md

@@ -107,6 +107,7 @@ declared the same way.
 | `foldrun open [page]` | the dashboard for this workspace, in the browser |
 | `foldrun login` | sign this machine in from the browser — no key to copy |
 | `foldrun whoami` | who you are on the platform: account, role, workspaces |
+| `foldrun doctor` | check the path to the platform: node, CLI, account, DNS, a timed `/api/healthz` — exit 1 if any line fails |
 | `foldrun keys ls` | the account's API keys — also `create <label>`, `revoke <id>` |
 
 `foldrun --help` lists every flag.

package/bin/foldrun.mjs

@@ -19,6 +19,7 @@
 //   foldrun open  [page]    the dashboard for this workspace
 //   foldrun login           sign this machine in from the browser
 //   foldrun whoami          who the platform thinks this terminal is
+//   foldrun doctor          what is between this terminal and the platform, checked
 //   foldrun accounts        every account signed in here; `use <name>` switches
 //   foldrun keys  <verb>    ls / create / revoke — the account's API keys
 //
@@ -47,7 +48,7 @@ const HELP = `foldrun — agents are just folders
   foldrun eval [name]       run one eval, or all of them
   foldrun probe <model>     live check: can this model hold a tool loop here?
   foldrun logs [run-id]     recent runs, or one run's full event trail
-  foldrun secrets set NAME  store a secret (prompted, never echoed) — also ls, rm
+  foldrun secrets set NAME  store a secret (prompted, never echoed) — also ls, rm, status
   foldrun connect NAME      OAuth sign-in from the terminal, stored as an auto-refreshing secret
   foldrun deploy [dir]      push a workspace into an installation
   foldrun invoke <flow>     start a flow on a running platform (--to <workspace>)
@@ -58,6 +59,7 @@ Signing in
   foldrun login             sign this machine in from the browser (--token <key> to skip it)
   foldrun logout            forget this machine's key, and revoke it where allowed
   foldrun whoami            who you are on the platform: account, role, workspaces
+  foldrun doctor            check the path to the platform: node, CLI, account, DNS, a timed /api/healthz
   foldrun accounts          every account signed in on this machine, and which one is active
   foldrun use <name>        act as one of them from here on
   foldrun keys ls           the account's API keys — also create <label>, revoke <id>
@@ -67,6 +69,7 @@ Options
   --workspace <dir>         the workspace folder (default: .)
   --from <template>         start from a shipped template, e.g. templates/hello
   --task "<text>"           the instruction for a manual run
+  --test                    run, invoke: a test run — nothing outward, state/ untouched, receipts on the run page
   --follow                  logs: keep tailing a live run (with --url: on the platform)
   --value "<text>"          secrets set: skip the prompt (careful with shell history)
   --file <path>             source put: the local file to send (default: stdin)
@@ -91,6 +94,7 @@ Platform options (deploy, invoke, secrets, logs, keys)
   --data <dir>              the installation's data directory
   --url <url>               a running platform (or FOLDRUN_URL, or where you last signed in)
   --token <key>             API key for --url (or FOLDRUN_TOKEN, or the one from foldrun login)
+  FOLDRUN_TIMEOUT=<s>       seconds one request to the platform may take (default 30)
   --profile <name>          act as one stored account for this command (see foldrun accounts)
   --local                   deploy: into the installation on this machine, even when signed in
   --commit <sha>            deploy: record which commit this is
@@ -111,7 +115,7 @@ if (!command || command === "--help" || command === "-h") {
 // `--value` as the account's argument and stored an empty secret; `--force
 // ./dir` swallowed the directory. A flag followed by another flag is also
 // boolean, so an unlisted switch at least does not eat its neighbour.
-const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local"]);
+const BOOLEAN_FLAGS = new Set(["account", "follow", "force", "oauth2", "wait", "watch", "print", "dry-run", "help", "no-browser", "local", "test"]);
 const flags = {};
 const positional = [];
 for (let i = 0; i < rest.length; i++) {
@@ -162,12 +166,14 @@ if (isDeploy) {
   process.env.FOLDRUN_DATA ??= installationRoot ?? path.join(workspace, ".foldrun");
 }
 
-const { run } = await import(path.join(HERE, "../src/commands.mjs"));
+const { run, explain } = await import(path.join(HERE, "../src/commands.mjs"));
 
 try {
   const code = await run(command, positional, flags, workspace);
   process.exit(code ?? 0);
 } catch (err) {
-  console.error(`\n  ${err instanceof Error ? err.message : String(err)}\n`);
+  // The whole chain, not the top: "fetch failed" is the top, and the
+  // ECONNREFUSED underneath it is the part that says what to do.
+  console.error(`\n  ${explain(err)}\n`);
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "Apache-2.0",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^0.3.0"
+    "@foldrun/core": "^0.4.0"
   },
   "files": [
     "bin",
@@ -20,8 +20,9 @@
   ],
   "scripts": {
     "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
-    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-secrets.test.ts tests/cli-check-library.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts",
-    "release": "node scripts/release.mjs"
+    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-secrets.test.ts tests/cli-check-library.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts",
+    "release": "node scripts/release.mjs",
+    "typecheck": "tsc -p tsconfig.json"
   },
   "repository": {
     "type": "git",
@@ -40,5 +41,10 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "gray-matter": "^4.0.3",
+    "typescript": "^5.9.3"
   }
 }

package/src/commands.mjs

@@ -1,19 +1,25 @@
 // CLI commands. Kept separate from bin/ so the environment is set before the
 // core is imported — single-workspace mode is read at module load.
 
+import dns from "node:dns";
 import fs from "node:fs";
+import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { credentialFor, defaultPlatform, saveCredential, removeCredential, readCredentials, normaliseUrl, profileByName, currentProfile, useProfile, listProfiles } from "./credentials.mjs";
+import { defaultPlatform, saveCredential, removeCredential, readCredentials, normaliseUrl, profileByName, currentProfile, useProfile, listProfiles } from "./credentials.mjs";
 
+// NO_COLOR (no-color.org) turns the escapes off — for a log file, a CI
+// job, or a test that wants to match what a person reads. The tests had
+// been setting it all along, to no effect.
+const paint = (code) => (s) => (process.env.NO_COLOR ? String(s) : `\x1b[${code}m${s}\x1b[0m`);
 const c = {
-  dim: (s) => `\x1b[2m${s}\x1b[0m`,
-  bold: (s) => `\x1b[1m${s}\x1b[0m`,
-  green: (s) => `\x1b[32m${s}\x1b[0m`,
-  red: (s) => `\x1b[31m${s}\x1b[0m`,
-  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
-  amber: (s) => `\x1b[33m${s}\x1b[0m`,
+  dim: paint(2),
+  bold: paint(1),
+  green: paint(32),
+  red: paint(31),
+  yellow: paint(33),
+  amber: paint(33),
 };
 
 // The published runtime, not a relative reach into a sibling directory. It was
@@ -323,12 +329,14 @@ async function extract(workspace, flags) {
     // Prove it before deleting anything. parseToolDef is what the runtime
     // uses, so "it loads" here means it loads there.
     const check = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(manifest);
+    if (!check) throw new Error(`${name}: the manifest has no frontmatter — nothing to extract from`);
     const data = Object.fromEntries(
       check[1]
         .split("\n")
-        .map((l) => /^([a-z_-]+):\s*(.*)$/.exec(l))
-        .filter(Boolean)
-        .map((m) => [m[1], m[2]]),
+        .flatMap((l) => {
+          const m = /^([a-z_-]+):\s*(.*)$/.exec(l);
+          return m ? [[m[1], m[2]]] : [];
+        }),
     );
     const def = parseToolDef(data, name, manifest.slice(check[0].length));
     const ok =
@@ -369,7 +377,7 @@ async function platformLibrary(flags) {
   if (!url) return { url: undefined, tools: new Set(), skills: new Set(), warning: null };
   let token;
   try {
-    token = tokenFor(url, flags);
+    token = tokenFor(url, { ...flags, quiet: true });
   } catch {
     return { url, tools: new Set(), skills: new Set(), warning: `${url} is the platform but this machine is not signed in — library tools there cannot be seen` };
   }
@@ -379,7 +387,7 @@ async function platformLibrary(flags) {
       signal: AbortSignal.timeout(8_000),
     });
     if (!res.ok) throw new Error(`/api/library/${kind} → HTTP ${res.status}`);
-    const body = await res.json();
+    const body = /** @type {any} */ (await res.json());
     return new Set((body.entries ?? []).map((e) => e.name).filter(Boolean));
   };
   try {
@@ -556,7 +564,7 @@ async function check(workspace, flags = {}) {
         note("error", `flows/${f.file}`, `[[${s.subflow ? "flow:" : ""}${target}]] does not exist`, s.line);
       }
     }
-    for (const w of lintFlow(f, { agents: [...agentNames] })) note("warn", `flows/${f.file}`, w.message, w.line);
+    for (const w of lintFlow(f, { agents: [...agentNames] })) note(w.level ?? "warn", `flows/${f.file}`, w.message, w.line);
   }
 
   for (const e of evals) {
@@ -711,6 +719,11 @@ async function runTarget(target, flags) {
   const name = target.replace(/^flow:/, "");
   const asFlow = target.startsWith("flow:") || !listAgents(T, P).some((a) => a.name === name);
 
+  // --test: a test run. Locally there is no egress proxy, so what holds is
+  // the runner's own half of it — send-capable secrets are withheld from
+  // scripts, FOLDRUN_TEST_MODE=1 is set, and state/ and storage/ writes
+  // are moved under runs/<id>/test-writes/ after each step.
+  const opts = flags.test === true ? { test: true } : {};
   let run;
   if (asFlow) {
     const flow = loadFlow(T, P, name);
@@ -720,12 +733,12 @@ async function runTarget(target, flags) {
           i === 0 ? { ...s, instruction: `${s.instruction}\n\n<run_task>\n${flags.task}\n</run_task>` } : s,
         )
       : flow.steps;
-    run = startFlowRun(T, P, steps, flow.name, flow.model);
+    run = startFlowRun(T, P, steps, flow.name, flow.model, [], null, null, opts);
   } else {
-    run = startFlowRun(T, P, [{ agent: name, instruction: flags.task ?? "", group: 1, optional: false }], `cli:${name}`);
+    run = startFlowRun(T, P, [{ agent: name, instruction: flags.task ?? "", group: 1, optional: false }], `cli:${name}`, null, [], null, null, opts);
   }
 
-  console.log(`\n  ${c.bold(run.flow)}  ${c.dim(run.id)}\n`);
+  console.log(`\n  ${c.bold(run.flow)}  ${c.dim(run.id)}${run.test ? `  ${c.amber("TEST")}` : ""}\n`);
   const seen = new Map();
   for (;;) {
     const current = readRun(T, P, run.id);
@@ -896,7 +909,7 @@ async function deployOverHttp(url, workspace, files, flags) {
   try {
     res = await fetch(endpoint, {
       method: "POST",
-      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": USER_AGENT },
       body: JSON.stringify({
         files,
         commit: flags.commit ?? null,
@@ -908,7 +921,7 @@ async function deployOverHttp(url, workspace, files, flags) {
     throw new Error(`could not reach ${url} — ${err instanceof Error ? err.message : String(err)}`);
   }
 
-  const body = await res.json().catch(() => ({}));
+  const body = /** @type {any} */ (await res.json().catch(() => ({})));
   if (res.status === 401) throw new Error(`${body.error ?? "unauthorized"} — run \`foldrun login\` again, or check FOLDRUN_TOKEN`);
   // 422 is a refusal the caller has to read, not a transport failure: the
   // issues are in the body and reported like any other refused deploy.
@@ -941,6 +954,7 @@ async function deploy(source, flags) {
   // which is what a laptop or a CI job does. Without one, or with --local,
   // it is written straight into the installation on this machine.
   const url = flags.local === true ? undefined : remoteUrl(flags);
+  /** @type {any} */
   const plan = url
     ? await deployOverHttp(url, workspace, files, flags)
     : flags["dry-run"]
@@ -1064,8 +1078,17 @@ function promptVisible(question) {
 // should not shadow the credentials file with nothing.
 const env = (name) => process.env[name] || undefined;
 
-/** The profile a command acts as: --profile by name, else the one whose URL
- *  was asked for, else the current one. */
+/**
+ * The profile a command acts as. In order: --profile by name; else, when a
+ * URL is named (--url, FOLDRUN_URL), the current profile if it is on that
+ * URL, else the one profile there, else a refusal that lists them; else the
+ * current profile.
+ *
+ * It was "the newest login on that URL", which meant `foldrun whoami --url
+ * https://dev.foldrun.io` acted as a different account from the bare
+ * `foldrun whoami` on a machine with two customers on one platform — the
+ * same command, two accounts, and nothing on screen to say so.
+ */
 function chosenProfile(flags) {
   if (typeof flags.profile === "string") {
     const p = profileByName(flags.profile);
@@ -1075,9 +1098,52 @@ function chosenProfile(flags) {
     }
     return p;
   }
-  const url = flags.url ?? env("FOLDRUN_URL");
-  if (url) return credentialFor(url);
-  return currentProfile();
+  const current = currentProfile();
+  const url = typeof flags.url === "string" ? flags.url : env("FOLDRUN_URL");
+  if (!url) return current;
+  let key;
+  try {
+    key = normaliseUrl(url);
+  } catch {
+    return null;
+  }
+  if (current && normaliseUrl(current.url) === key) return current;
+  const here = listProfiles().filter((p) => normaliseUrl(p.url) === key);
+  if (here.length <= 1) return here[0] ?? null;
+  throw new Error(
+    `${here.length} accounts are signed in to ${key} (${here.map((p) => p.name).join(", ")}) and none of them is the current one — say which: --profile <name> for this command, or \`foldrun use <name>\``,
+  );
+}
+
+/**
+ * Which account this command is acting as, said once, dim, on stderr —
+ * stderr so `foldrun source cat … > file` stays a file. The same shape as
+ * a row of `foldrun accounts`, so the two read as one thing.
+ */
+let announced = false;
+function announce(url, flags) {
+  if (announced || flags.quiet === true) return;
+  announced = true;
+  const line = actingAs(url, flags);
+  if (line) console.error(`  ${c.dim(line)}`);
+}
+
+/** "acting as <name>  <account> · <role> · <email> · <url>", or the --token / FOLDRUN_TOKEN form. */
+function actingAs(url, flags) {
+  if (typeof flags.token === "string") return `acting with --token · ${url}`;
+  if (env("FOLDRUN_TOKEN")) return `acting with FOLDRUN_TOKEN · ${url}`;
+  const p = chosenProfile(flags);
+  return p ? `acting as ${p.name}  ${p.account} · ${p.role ?? "?"} · ${p.email ?? "api key"} · ${p.url}` : null;
+}
+
+/**
+ * What to add to a 401/403: which credential was refused. Without it a
+ * `logs --url` that fails on a machine with three accounts says
+ * "forbidden" and leaves the reader to guess which key was sent.
+ */
+function refusedHint(url, flags) {
+  const who = actingAs(url, flags);
+  return who ? ` — ${who}; \`foldrun accounts\` lists the others, --profile <name> picks one` : " — `foldrun login` signs this machine in";
 }
 
 const remoteUrl = (flags) =>
@@ -1089,23 +1155,146 @@ const NOT_SIGNED_IN = "not signed in — run `foldrun login`, or set FOLDRUN_TOK
 function tokenFor(url, flags) {
   // --token and the environment win, always: a CI job with a key in the
   // environment must never read a file, whatever is stored in it.
-  const token = flags.token ?? env("FOLDRUN_TOKEN") ?? chosenProfile(flags)?.token ?? credentialFor(url)?.token;
+  const token = flags.token ?? env("FOLDRUN_TOKEN") ?? chosenProfile(flags)?.token;
   if (!token) throw new Error(NOT_SIGNED_IN);
+  announce(url, flags);
   return token;
 }
 
+// ---------------------------------------------------------------- the HTTP client
+
+/** This CLI's version, so a platform's logs can tell which CLI called. */
+const CLI_VERSION = (() => {
+  try {
+    return String(JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0");
+  } catch {
+    return "0";
+  }
+})();
+const USER_AGENT = `foldrun-cli/${CLI_VERSION}`;
+
+/** How long one request may take, in seconds: FOLDRUN_TIMEOUT, else 30. */
+function timeoutSeconds() {
+  const n = Number(env("FOLDRUN_TIMEOUT"));
+  return Number.isFinite(n) && n > 0 ? n : 30;
+}
+
+/**
+ * Every message on the way down, joined. "fetch failed" on its own says
+ * nothing; the ECONNREFUSED / ENOTFOUND / connect timeout that explains it
+ * sits in err.cause, where undici puts it and where nothing printed from —
+ * so `foldrun whoami` against a stopped box said "fetch failed" and no more.
+ * @param {unknown} err
+ */
+export function explain(err) {
+  const parts = [];
+  const seen = new Set();
+  for (let e = /** @type {any} */ (err); e != null && !seen.has(e); e = e.cause) {
+    seen.add(e);
+    // undici tries every address and hands back an AggregateError with an
+    // empty message; the first member is the one worth reading.
+    if (e instanceof AggregateError && !e.message && e.errors?.length) {
+      parts.push(explain(e.errors[0]));
+      continue;
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    const code = typeof e.code === "string" && !msg.includes(e.code) ? ` (${e.code})` : "";
+    parts.push(`${msg}${code}`);
+  }
+  return parts.join(": ");
+}
+
+/** A failed call: the status and whatever the platform said, kept on the error. */
+export class HttpError extends Error {
+  /** @param {string} message @param {number} status @param {any} body */
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+const RETRY_STATUS = new Set([429, 502, 503, 504]);
+
+/** Retry-After as milliseconds — seconds or an HTTP date — else one second, never past the timeout. */
+function retryAfterMs(res, seconds) {
+  const h = res.headers.get("retry-after");
+  let ms = 1000;
+  if (h && /^\d+$/.test(h.trim())) ms = Number(h) * 1000;
+  else if (h && !Number.isNaN(Date.parse(h))) ms = Date.parse(h) - Date.now();
+  return Math.min(Math.max(ms, 0), seconds * 1000);
+}
+
+/**
+ * One request to a platform: the auth header, a User-Agent, and a clock.
+ *
+ * Without the clock a box that accepts the TCP connection and never answers
+ * held the terminal for as long as the kernel allowed. A GET that meets a
+ * 429/502/503/504 is asked once more, after Retry-After when the server
+ * names one — a rolling deploy or a rate limit deserves the nudge. Nothing
+ * else is retried: a second POST could be a second run.
+ * @param {string} url @param {string} apiPath @param {RequestInit} [init]
+ * @param {{ token?: string }} [opts]
+ */
+async function remoteFetch(url, apiPath, init = {}, { token } = {}) {
+  const target = new URL(apiPath, url);
+  const method = (init.method ?? "GET").toUpperCase();
+  const headers = {
+    "user-agent": USER_AGENT,
+    ...(token ? { authorization: `Bearer ${token}` } : {}),
+    ...(init.headers ?? {}),
+  };
+  const seconds = timeoutSeconds();
+  const attempt = async () => {
+    try {
+      return await fetch(target, { ...init, headers, signal: AbortSignal.timeout(seconds * 1000) });
+    } catch (err) {
+      const name = /** @type {any} */ (err)?.name;
+      if (name === "TimeoutError" || name === "AbortError") {
+        throw new Error(`${target.host} did not answer ${method} ${target.pathname} within ${seconds}s — FOLDRUN_TIMEOUT=<seconds> allows longer`);
+      }
+      throw new Error(`could not reach ${target.origin}`, { cause: err });
+    }
+  };
+  let res = await attempt();
+  if (method === "GET" && RETRY_STATUS.has(res.status)) {
+    await sleep(retryAfterMs(res, seconds));
+    res = await attempt();
+  }
+  return res;
+}
+
+/**
+ * A call to the platform's API, as JSON. A body that is not JSON is not the
+ * platform talking — a Cloudflare challenge, a proxy's error page, a tunnel
+ * that is down — and used to be read as {} and reported as a bare "HTTP
+ * 403". Now the status, the content-type and the first line say so.
+ * @param {string} url @param {Record<string, any>} flags @param {string} apiPath @param {RequestInit} [init]
+ * @returns {Promise<any>}
+ */
 async function remoteCall(url, flags, apiPath, init = {}) {
   const token = tokenFor(url, flags);
-  const res = await fetch(new URL(apiPath, url), {
-    ...init,
-    headers: {
-      authorization: `Bearer ${token}`,
-      "content-type": "application/json",
-      ...(init.headers ?? {}),
-    },
-  });
-  const body = await res.json().catch(() => ({}));
-  if (!res.ok) throw new Error(body.error ?? `${apiPath} → HTTP ${res.status}`);
+  const res = await remoteFetch(url, apiPath, { ...init, headers: { "content-type": "application/json", ...(init.headers ?? {}) } }, { token });
+  const text = await res.text();
+  let body;
+  try {
+    body = text.trim() ? JSON.parse(text) : {};
+  } catch {
+    if (res.ok) return {};
+    const type = (res.headers.get("content-type") ?? "unknown type").split(";")[0].trim();
+    const title = text.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1]?.trim();
+    const line = title || text.split("\n").map((l) => l.trim()).find(Boolean) || "";
+    throw new HttpError(`${apiPath} → HTTP ${res.status} (${type})${line ? `: ${line.slice(0, 160)}` : ""} — not the platform's answer; is ${new URL(url).host} the right address, and is it up?`, res.status, {});
+  }
+  if (!res.ok) {
+    // The body is the useful half of a failure and throwing it away is how a
+    // failed RUN comes to look like a broken PLATFORM. `?wait=true` answers a
+    // run that failed with 500 and a full record of why — status, steps, the
+    // agent's last words — and a caller that prints only "HTTP 500" sends the
+    // reader hunting for an outage that never happened.
+    const hint = res.status === 401 || res.status === 403 ? refusedHint(url, flags) : "";
+    throw new HttpError(`${body.error ?? `${apiPath} → HTTP ${res.status}`}${hint}`, res.status, body);
+  }
   return body;
 }
 
@@ -1128,49 +1317,125 @@ function finishLine(run) {
   return ok ? 0 : run.status === "awaiting-approval" ? 2 : 1;
 }
 
+/** A run that has not finished: the stream is worth following. */
+const isLive = (run) => run.status === "queued" || run.status === "running" || run.status === "awaiting-approval";
+
+/** How long a run stream may stay silent before it is reconnected: four request timeouts, 120 s by default. */
+const streamIdleSeconds = () => timeoutSeconds() * 4;
+
+/** The stream said nothing for this long. Not a failure yet; a reason to reconnect. */
+class StreamIdle extends Error {
+  /** @param {number} seconds */
+  constructor(seconds) {
+    super(`the run stream went quiet for ${seconds}s`);
+    this.seconds = seconds;
+  }
+}
+
+/**
+ * One connection to a run's stream, printed as frames land. Resolves with
+ * the finished run on `done`, with the last run seen if the server ends it
+ * first, and throws StreamIdle when nothing arrives for streamIdleSeconds.
+ */
+async function streamOnce(url, flags, ws, runId, seen) {
+  const token = tokenFor(url, flags);
+  const idle = streamIdleSeconds();
+  const target = new URL(`/api/workspaces/${ws}/runs/${runId}/stream`, url);
+  const ctrl = new AbortController();
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  const arm = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => ctrl.abort(new StreamIdle(idle)), idle * 1000);
+  };
+  arm();
+  try {
+    let res;
+    try {
+      res = await fetch(target, {
+        headers: { authorization: `Bearer ${token}`, accept: "text/event-stream", "user-agent": USER_AGENT },
+        signal: ctrl.signal,
+      });
+    } catch (err) {
+      if (ctrl.signal.aborted) throw ctrl.signal.reason;
+      throw new Error(`could not reach ${target.origin}`, { cause: err });
+    }
+    if (!res.ok || !res.body) {
+      const hint = res.status === 401 || res.status === 403 ? refusedHint(url, flags) : "";
+      throw new HttpError(`stream → HTTP ${res.status}${hint}`, res.status, {});
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let last = null;
+    for (;;) {
+      let chunk;
+      try {
+        chunk = await reader.read();
+      } catch (err) {
+        if (ctrl.signal.aborted) throw ctrl.signal.reason;
+        throw err;
+      }
+      if (chunk.done) break;
+      arm();
+      buffer += decoder.decode(chunk.value, { stream: true });
+      let cut;
+      while ((cut = buffer.indexOf("\n\n")) !== -1) {
+        const frame = buffer.slice(0, cut);
+        buffer = buffer.slice(cut + 2);
+        const event = frame.match(/^event: (.*)$/m)?.[1];
+        const data = frame.match(/^data: (.*)$/m)?.[1];
+        if (!event || !data) continue;
+        if (event === "run") {
+          try {
+            last = JSON.parse(data);
+            printNew(last, seen);
+          } catch {
+            // a partial frame; the next one supersedes it
+          }
+        } else if (event === "done") {
+          try {
+            await reader.cancel();
+          } catch {
+            // the server ended it first
+          }
+          return last;
+        }
+      }
+    }
+    return last;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 /**
  * Follow a run on a platform: the same server-sent events the dashboard's
  * run page reads, printed as they land. Resolves with the finished run.
+ *
+ * A stream that goes quiet is reconnected, up to three times, as long as
+ * the run is still live — every `run` frame carries the whole run, so a
+ * fresh connection IS the resume; `seen` keeps the lines already printed
+ * from printing twice. It used to block `invoke --watch` and `logs
+ * --follow` for as long as a stalled tunnel cared to keep the socket.
  */
 async function followRemote(url, flags, ws, runId, seen = new Map()) {
-  const token = tokenFor(url, flags);
-  const res = await fetch(new URL(`/api/workspaces/${ws}/runs/${runId}/stream`, url), {
-    headers: { authorization: `Bearer ${token}`, accept: "text/event-stream" },
-  });
-  if (!res.ok || !res.body) throw new Error(`stream → HTTP ${res.status}`);
-  const reader = res.body.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
-  let last = null;
-  for (;;) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-    let cut;
-    while ((cut = buffer.indexOf("\n\n")) !== -1) {
-      const frame = buffer.slice(0, cut);
-      buffer = buffer.slice(cut + 2);
-      const event = frame.match(/^event: (.*)$/m)?.[1];
-      const data = frame.match(/^data: (.*)$/m)?.[1];
-      if (!event || !data) continue;
-      if (event === "run") {
-        try {
-          last = JSON.parse(data);
-          printNew(last, seen);
-        } catch {
-          // a partial frame; the next one supersedes it
-        }
-      } else if (event === "done") {
-        try {
-          await reader.cancel();
-        } catch {
-          // the server ended it first
-        }
-        return last;
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await streamOnce(url, flags, ws, runId, seen);
+    } catch (err) {
+      if (!(err instanceof StreamIdle)) throw err;
+      const run = await remoteCall(url, flags, `/api/workspaces/${ws}/runs/${runId}`);
+      printNew(run, seen);
+      if (!isLive(run)) return run;
+      if (attempt >= 3) {
+        throw new Error(
+          `${err.message} three times while ${runId} is still ${run.status} — \`foldrun logs ${runId} --to ${ws} --follow\` picks it up again, or ${url}/dashboard/${ws}/runs?run=${runId}`,
+        );
       }
+      console.error(`  ${c.dim(`… ${err.message}; reconnecting (${attempt}/3)`)}`);
     }
   }
-  return last;
 }
 
 /**
@@ -1237,6 +1502,32 @@ async function secretsCmd(positional, flags) {
     return 0;
   }
 
+  if (verb === "status") {
+    // OAuth grants only: which still refresh, which are failing or about to
+    // expire, and whether a no-prompt reconnect exists for each.
+    if (!url) throw new Error("secrets status reads the platform's connection health — sign in first (foldrun login)");
+    const { connections } = await remoteCall(url, flags, "/api/oauth/connections");
+    if (!connections.length) {
+      console.log(`\n  ${c.dim("no OAuth connections")}\n`);
+      return 0;
+    }
+    console.log();
+    for (const s of connections) {
+      const where = s.workspace ? `workspace ${s.workspace}` : "account";
+      const state =
+        s.status === "ok" ? c.green(`ok${s.daysLeft !== null ? ` · ${s.daysLeft} days left` : ""}`)
+        : s.status === "expiring" ? c.amber(`expires in ${s.daysLeft} days`)
+        : s.status === "no-client" ? c.dim("ok · no saved client (reconnect will ask for it once)")
+        : c.red(`${s.status}${s.lastError ? ` — ${s.lastError}` : ""}`);
+      console.log(`  ${c.bold(s.name)}  ${c.dim(where)}  ${state}`);
+      if (s.status !== "ok" && s.status !== "no-client") {
+        console.log(`    ${c.dim(`reconnect: foldrun connect ${s.name}${s.workspace ? ` --to ${s.workspace}` : ""}   or ${s.reconnectUrl}`)}`);
+      }
+    }
+    console.log();
+    return 0;
+  }
+
   if (!name) throw new Error(`which secret? try \`foldrun secrets ${verb} NAME\``);
 
   if (verb === "set") {
@@ -1387,8 +1678,7 @@ async function remoteLogs(url, positional, flags) {
   console.log(`\n  ${c.bold(run.flow)}  ${c.dim(run.id)}  ${c.dim(run.status)}\n`);
   const seen = new Map();
   printNew(run, seen);
-  const live = run.status === "queued" || run.status === "running" || run.status === "awaiting-approval";
-  if (flags.follow === true && live) run = (await followRemote(url, flags, ws, runId, seen)) ?? run;
+  if (flags.follow === true && isLive(run)) run = (await followRemote(url, flags, ws, runId, seen)) ?? run;
   return finishLine(run);
 }
 
@@ -1409,18 +1699,59 @@ async function invoke(target, flags) {
   const ws = flags.to;
   if (!ws) throw new Error("which workspace is it in? pass --to <workspace>");
 
-  const wait = flags.wait === true ? "?wait=true" : "";
+  // --wait asks in short pieces, not one long request: whatever sits in
+  // front of the platform cuts a request that stays silent too long
+  // (Cloudflare at 100 s, an ALB at 60 s), and a flow can run for many
+  // minutes. The server answers 202 { timedOut: true } when a piece runs out
+  // and the same question is asked again of the run itself. The 524 that
+  // used to land here after 100 s while the run carried on was the trigger.
+  const WAIT_PIECE_S = 25;
+  const wait = flags.wait === true ? `?wait=true&timeout=${WAIT_PIECE_S}` : "";
+  // A waited run that FAILS is answered with 500 and a full record (see
+  // server/wait.ts). That is not an error in the call, it is the answer to
+  // it, so it is reported as a failed run rather than thrown as a transport
+  // fault — the difference between "your flow failed" and "the platform is
+  // down", which is the first thing anyone reading this needs to know.
+  const reportFailedRun = (body, ws) => {
+    if (body?.result) console.log(`\n${body.result}\n`);
+    for (const st of body?.steps ?? []) {
+      const mark = st.status === "completed" ? c.green("✓") : st.status === "skipped" ? c.dim("–") : c.red("✗");
+      console.log(`  ${mark} ${c.dim(st.agent ?? "?")}  ${st.status}${st.skipReason ? c.dim(` (${st.skipReason})`) : ""}`);
+    }
+    console.log(
+      `\n  ${c.red("✗")} ${body?.status ?? "failed"}${body?.costUsd != null ? ` · $${Number(body.costUsd).toFixed(4)}` : ""}` +
+        `${body?.runId ? c.dim(` — foldrun logs ${body.runId} --to ${ws}`) : ""}\n`,
+    );
+    return 1;
+  };
   // --from N starts at step N of the flow as its file numbers them; the
   // earlier steps are recorded as skipped. Mutually exclusive with --task
   // server-side (the task goes to step 1, which --from skips).
   const from = flags.from !== undefined ? Number(flags.from) : undefined;
-  const body = await remoteCall(url, flags, `/api/workspaces/${ws}/flows/${target}/run${wait}`, {
-    method: "POST",
-    body: JSON.stringify({
-      task: typeof flags.task === "string" ? flags.task : "",
-      ...(from !== undefined ? { from } : {}),
-    }),
-  });
+  let body;
+  try {
+    body = await remoteCall(url, flags, `/api/workspaces/${ws}/flows/${target}/run${wait}`, {
+      method: "POST",
+      body: JSON.stringify({
+        task: typeof flags.task === "string" ? flags.task : "",
+        ...(from !== undefined ? { from } : {}),
+        // --test: the platform marks the run a test run — sends refused or
+        // sunk at the proxy, send-capable secrets withheld, state/ kept.
+        ...(flags.test === true ? { test: true } : {}),
+      }),
+    });
+  } catch (err) {
+    if (flags.wait === true && err?.body?.runId && err.body.status) return reportFailedRun(err.body, ws);
+    throw err;
+  }
+  while (flags.wait === true && body?.timedOut === true && body.runId) {
+    try {
+      body = await remoteCall(url, flags, `/api/workspaces/${ws}/runs/${body.runId}${wait}`);
+    } catch (err) {
+      if (err?.body?.runId && err.body.status) return reportFailedRun(err.body, ws);
+      throw err;
+    }
+  }
 
   if (flags.watch === true && body.runId) {
     // Queued, then followed: the trace lands here line by line, the way the
@@ -1434,14 +1765,16 @@ async function invoke(target, flags) {
     return finishLine(run);
   }
   if (!flags.wait) {
-    console.log(`\n  ${c.green("✓")} queued ${c.bold(body.runId)} — ${c.dim(`foldrun logs ${body.runId} --to ${ws} --follow, or ${url}/dashboard/${ws}/runs?run=${body.runId}`)}\n`);
+    console.log(`\n  ${c.green("✓")} queued ${c.bold(body.runId)}${body.test ? ` ${c.amber("TEST")}` : ""} — ${c.dim(`foldrun logs ${body.runId} --to ${ws} --follow, or ${url}/dashboard/${ws}/runs?run=${body.runId}`)}\n`);
     return 0;
   }
   const run = body.run ?? body;
-  const ok = (run.status ?? body.status) === "completed";
+  const status = run.status ?? body.status ?? "finished";
+  const ok = status === "completed";
   if (body.result) console.log(`\n${body.result}\n`);
-  console.log(`  ${ok ? c.green("✓") : c.red("✗")} ${run.status ?? body.status ?? "finished"}${body.costUsd != null ? ` · $${Number(body.costUsd).toFixed(4)}` : ""}\n`);
-  return ok ? 0 : 1;
+  const mark = ok ? c.green("✓") : status === "awaiting-approval" ? c.amber("⏸") : c.red("✗");
+  console.log(`  ${mark} ${status}${body.costUsd != null ? ` · $${Number(body.costUsd).toFixed(4)}` : ""}${status === "awaiting-approval" ? c.dim(` — ${url}/dashboard/${ws}/runs?run=${body.runId}`) : ""}\n`);
+  return ok ? 0 : status === "awaiting-approval" ? 2 : 1;
 }
 
 // ---------------------------------------------------------------- connect
@@ -1470,7 +1803,7 @@ const CONNECT_PORT = 8642;
  */
 async function connect(positional, flags) {
   const name = positional[0];
-  if (!name) throw new Error("usage: foldrun connect NAME --provider <google|github|microsoft|linkedin> [--workspace <name>]");
+  if (!name) throw new Error("usage: foldrun connect NAME [--provider <google|github|microsoft|linkedin>] [--workspace <name>] [--new-client]");
   if (!/^[A-Z][A-Z0-9_]*$/.test(name)) throw new Error(`secret name "${name}" must be UPPER_SNAKE_CASE`);
   const { OAUTH_PRESETS } = await core();
 
@@ -1481,10 +1814,6 @@ async function connect(positional, flags) {
   }
   const authorizeUrl = flags["authorize-url"] ?? preset?.authorize_url;
   const tokenUrl = flags["token-url"] ?? preset?.token_url;
-  if (!authorizeUrl || !tokenUrl) throw new Error("--provider, or both --authorize-url and --token-url");
-  if (!/^https:\/\//.test(tokenUrl) && !/^http:\/\/(127\.0\.0\.1|localhost)[:/]/.test(tokenUrl)) {
-    throw new Error("token URL must be https — a refresh token over http is a leaked one");
-  }
 
   // Where the result goes: the platform when one is named or signed in,
   // this machine's vault otherwise. Decided before the browser opens, so a
@@ -1493,6 +1822,49 @@ async function connect(positional, flags) {
   const token = url ? tokenFor(url, flags) : null;
   const workspaceName = flags.to ?? (flags.workspace ? path.basename(path.resolve(flags.workspace)) : undefined);
 
+  // Reconnecting: the platform already holds the client this secret (or this
+  // provider) was connected with, so run its consent flow — no client id, no
+  // secret, nothing typed. The redirect is the platform's own callback, which
+  // rewrites the same secret at the same scope; we wait for it to land.
+  if (url && !flags["client-id"] && !env("OAUTH_CLIENT_ID") && flags["new-client"] !== true) {
+    let started = null;
+    try {
+      started = await remoteCall(url, flags, "/api/oauth/reconnect", {
+        method: "POST",
+        body: JSON.stringify({ secret: name, workspace: workspaceName, provider: providerName }),
+      });
+    } catch (err) {
+      if (err.status !== 404) throw err;
+    }
+    if (started?.url) {
+      const before = (await remoteCall(url, flags, "/api/oauth/connections")).connections
+        .find((s) => s.name === name && (s.workspace ?? undefined) === workspaceName)?.connectedAt ?? null;
+      console.log(`\n  Reusing the saved ${c.bold(started.client)} client — nothing to type.`);
+      console.log(`  ${c.dim(`consent returns to ${started.redirectUri} (it must be registered on the app)`)}`);
+      const opened = flags["no-browser"] === true ? false : await openInBrowser(started.url);
+      console.log(opened
+        ? `  Opened your browser. Approve as the account that owns the ${providerName ?? started.client} resource.\n`
+        : `  Open this address in your browser:\n\n    ${started.url}\n`);
+      console.log(`  ${c.dim("Waiting for the platform to store it…")}`);
+      const deadline = Date.now() + 10 * 60 * 1000;
+      while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 3000));
+        const row = (await remoteCall(url, flags, "/api/oauth/connections")).connections
+          .find((s) => s.name === name && (s.workspace ?? undefined) === workspaceName);
+        if (row?.connectedAt && row.connectedAt !== before) {
+          console.log(`\n  ${c.green("✓")} ${name} reconnected on ${url}${workspaceName ? ` · ${workspaceName}` : " · account"}\n`);
+          return 0;
+        }
+      }
+      throw new Error("no consent arrived within 10 minutes — run it again, or pass --new-client to enter a client id and secret");
+    }
+  }
+
+  if (!authorizeUrl || !tokenUrl) throw new Error("--provider, or both --authorize-url and --token-url");
+  if (!/^https:\/\//.test(tokenUrl) && !/^http:\/\/(127\.0\.0\.1|localhost)[:/]/.test(tokenUrl)) {
+    throw new Error("token URL must be https — a refresh token over http is a leaked one");
+  }
+
   const clientId = flags["client-id"] ?? env("OAUTH_CLIENT_ID") ?? (await promptVisible("  client_id: "));
   const clientSecret = flags["client-secret"] ?? env("OAUTH_CLIENT_SECRET") ?? (await promptHidden("  client_secret: "));
   if (!clientId || !clientSecret) throw new Error("client_id and client_secret are required");
@@ -1537,7 +1909,7 @@ async function connect(positional, flags) {
       server.close();
       resolve(u.searchParams.get("code"));
     });
-    server.on("error", (e) => reject(e.code === "EADDRINUSE"
+    server.on("error", (/** @type {any} */ e) => reject(e.code === "EADDRINUSE"
       ? new Error(`port ${port} is in use — pass --port <n> and register http://localhost:<n>/callback on the app`)
       : e));
     server.listen(port, "127.0.0.1", async () => {
@@ -1555,14 +1927,15 @@ async function connect(positional, flags) {
     headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
     body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId, client_secret: clientSecret }).toString(),
   });
-  const payload = await exchange.json().catch(() => ({}));
+  const payload = /** @type {any} */ (await exchange.json().catch(() => ({})));
   if (!exchange.ok || (!payload.refresh_token && !payload.access_token)) {
     throw new Error(`token exchange failed (${exchange.status}): ${payload.error_description ?? payload.error ?? "no token in the reply"}`);
   }
 
   // Store: the refresh recipe when there is one, the bare token otherwise.
+  /** @type {any} */
   const body = payload.refresh_token
-    ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, client_secret: clientSecret, refresh_token: payload.refresh_token }, workspace: workspaceName }
+    ? { name, oauth2: { token_url: tokenUrl, client_id: clientId, client_secret: clientSecret, refresh_token: payload.refresh_token }, workspace: workspaceName, scopes, ...(payload.refresh_token_expires_in ? { refresh_token_expires_in: payload.refresh_token_expires_in } : {}) }
     : { name, value: payload.access_token, workspace: workspaceName };
   if (url) {
     // The same PUT `secrets set` makes. A store that fails here has spent the
@@ -1625,16 +1998,17 @@ async function login(flags) {
   if (typeof flags.token === "string") {
     // Verify before storing: a wrong key stored is a wrong key on every
     // later command, each failing one step further from the cause.
-    const me = await remoteCall(url, { token: flags.token }, "/api/me");
+    const me = await remoteCall(url, { token: flags.token, quiet: true }, "/api/me");
     const name = saveCredential(url, { token: flags.token, email: me.actor.email ?? null, account: me.account, role: me.role }, { name: typeof flags.profile === "string" ? flags.profile : undefined });
     console.log(`\n  ${c.green("✓")} signed in to ${c.bold(url)} as ${me.actor.email ?? me.actor.label ?? "an API key"} ${c.dim(`(${me.account}, ${me.role})`)}`);
     console.log(`  ${c.dim(`stored as the account "${name}" — \`foldrun accounts\` lists them, \`foldrun use ${name}\` switches`)}\n`);
     return 0;
   }
 
+  /** @type {any} */
   let start;
   try {
-    const res = await fetch(new URL("/api/cli/login", url), {
+    const res = await remoteFetch(url, "/api/cli/login", {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ hostname: os.hostname() }),
@@ -1654,9 +2028,12 @@ async function login(flags) {
   const deadline = Date.parse(start.expiresAt) || Date.now() + 10 * 60 * 1000;
   while (Date.now() < deadline) {
     await sleep(interval);
+    /** @type {any} */
     let poll;
     try {
-      const res = await fetch(new URL(`/api/cli/login/${start.id}`, url));
+      // Through the shared client: a poll that hangs used to hang the
+      // sign-in; now it is cut at FOLDRUN_TIMEOUT and asked again.
+      const res = await remoteFetch(url, `/api/cli/login/${start.id}`);
       poll = await res.json().catch(() => ({}));
     } catch {
       continue; // a blip; the next poll asks again
@@ -1697,9 +2074,9 @@ async function logout(flags) {
   let revoked = false;
   if (entry.minted) {
     try {
-      const me = await remoteCall(url, { token: entry.token }, "/api/me");
+      const me = await remoteCall(url, { token: entry.token, quiet: true }, "/api/me");
       if (me.actor?.kind === "key" && me.actor.id) {
-        await remoteCall(url, { token: entry.token }, "/api/keys", { method: "DELETE", body: JSON.stringify({ id: me.actor.id }) });
+        await remoteCall(url, { token: entry.token, quiet: true }, "/api/keys", { method: "DELETE", body: JSON.stringify({ id: me.actor.id }) });
         revoked = true;
       }
     } catch {
@@ -1733,6 +2110,102 @@ async function whoami(flags) {
   return 0;
 }
 
+/**
+ * `foldrun doctor [--url]` — one line per thing that can be wrong between
+ * this terminal and a platform, ✓ or ✗, in the order a person would check
+ * them by hand: node, this CLI, its runtime, the environment, the account
+ * a command would act as, the name, and a timed request through the same
+ * client every other command uses. Exit 1 if any line is ✗.
+ *
+ * It exists because "fetch failed" was the whole diagnosis, and the fix
+ * was in a different place each time: a tunnel, a stale profile, a proxy
+ * variable, a box that was down.
+ */
+async function doctor(flags) {
+  const results = [];
+  const line = (ok, label, detail) => {
+    results.push(ok);
+    console.log(`  ${ok ? c.green("✓") : c.red("✗")} ${label.padEnd(9)} ${detail}`);
+  };
+  console.log();
+
+  const major = Number(process.versions.node.split(".")[0]);
+  line(major >= 22, "node", `${process.version}${major >= 22 ? "" : " — foldrun needs 22 or newer"}  ${c.dim(process.execPath)}`);
+  line(true, "cli", `foldrun ${CLI_VERSION}  ${c.dim(fileURLToPath(new URL("..", import.meta.url)))}`);
+  try {
+    const root = coreRoot();
+    const version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+    line(true, "core", `@foldrun/core ${version}  ${c.dim(root)}`);
+  } catch (err) {
+    line(false, "core", `@foldrun/core cannot be resolved — ${explain(err)}`);
+  }
+  // Set or unset, never the value: two of these are a key and a proxy URL
+  // that may carry one.
+  line(true, "env", ["FOLDRUN_URL", "FOLDRUN_TOKEN", "FOLDRUN_TIMEOUT", "HTTPS_PROXY"].map((v) => (env(v) ? `${v} set` : c.dim(`${v} unset`))).join(" · "));
+
+  let url;
+  let token;
+  try {
+    url = remoteUrl(flags);
+    if (typeof flags.token === "string" || env("FOLDRUN_TOKEN")) {
+      token = flags.token ?? env("FOLDRUN_TOKEN");
+      line(true, "account", `${typeof flags.token === "string" ? "--token" : "FOLDRUN_TOKEN"} ${token.slice(0, 8)}…  ${c.dim(url ?? "no platform")}`);
+    } else {
+      const p = chosenProfile(flags);
+      if (p) {
+        token = p.token;
+        line(true, "account", `${p.name}  ${p.account} · ${p.role ?? "?"} · ${p.email ?? "api key"} · key ${String(p.token).slice(0, 8)}…  ${c.dim(p.url)}`);
+      } else {
+        line(false, "account", url ? `no account stored for ${url} — \`foldrun login --url ${url}\`, or --token` : "not signed in — `foldrun login`, or --url with --token");
+      }
+    }
+  } catch (err) {
+    line(false, "account", explain(err));
+  }
+
+  if (!url) {
+    line(false, "dns", "no platform — pass --url, or sign in");
+    line(false, "healthz", "no platform — pass --url, or sign in");
+  } else {
+    const host = new URL(url).hostname;
+    if (net.isIP(host)) line(true, "dns", `${host} is an address, nothing to resolve`);
+    else {
+      const [a, aaaa] = await Promise.allSettled([dns.promises.resolve4(host), dns.promises.resolve6(host)]);
+      const list = (r) => (r.status === "fulfilled" ? r.value.join(", ") : "none");
+      if (a.status === "fulfilled" || aaaa.status === "fulfilled") line(true, "dns", `${host} → A ${list(a)} · AAAA ${list(aaaa)}`);
+      else {
+        // Not in DNS; /etc/hosts still counts, and is where a dev box lives.
+        try {
+          const found = await dns.promises.lookup(host, { all: true });
+          line(true, "dns", `${host} → ${found.map((f) => f.address).join(", ")} ${c.dim("(hosts file, not DNS)")}`);
+        } catch (err) {
+          line(false, "dns", `${host} — ${explain(a.status === "rejected" ? a.reason : err)}`);
+        }
+      }
+    }
+    const t0 = performance.now();
+    const took = () => `${Math.round(performance.now() - t0)} ms`;
+    try {
+      const res = await remoteFetch(url, "/api/healthz", {}, { token });
+      const text = await res.text();
+      let body = {};
+      try {
+        body = JSON.parse(text);
+      } catch {
+        // not JSON; the first line is shown below
+      }
+      const fields = ["version", "role"].filter((k) => body[k] != null).map((k) => `${k} ${body[k]}`).join(" · ");
+      const firstLine = text.split("\n").map((l) => l.trim()).find(Boolean) ?? "";
+      line(res.ok, "healthz", `GET /api/healthz ${res.status} in ${took()}${fields ? ` · ${fields}` : ""}${res.ok ? "" : ` — ${(res.headers.get("content-type") ?? "?").split(";")[0]}: ${firstLine.slice(0, 120)}`}`);
+    } catch (err) {
+      line(false, "healthz", `${explain(err)} ${c.dim(`(${took()})`)}`);
+    }
+  }
+
+  console.log();
+  return results.every(Boolean) ? 0 : 1;
+}
+
 /**
  * `foldrun keys ls|create|revoke` — the account's API keys, from the terminal.
  *
@@ -1902,6 +2375,8 @@ export async function run(command, positional, flags, workspace) {
       return logout(flags);
     case "whoami":
       return whoami(flags);
+    case "doctor":
+      return doctor(flags);
     case "keys":
       return keysCmd(positional, flags);
     case "accounts":

package/src/credentials.mjs

@@ -99,6 +99,9 @@ function write(current, profiles) {
  * Remember a signed-in account. A second login to the same URL for the same
  * ACCOUNT replaces that profile rather than making a near-duplicate; a
  * different account on the same URL is a new one.
+ * @param {string} url
+ * @param {Record<string, any>} entry
+ * @param {{ makeDefault?: boolean, name?: string }} [opts]
  */
 export function saveCredential(url, entry, { makeDefault = true, name } = {}) {
   const key = normaliseUrl(url);