duediligence 0.3.0 → 0.4.0

package/bin/hash.mjs

@@ -0,0 +1,111 @@
+// The commitment hash: one sha256 over a spec's hidden suite as the judge
+// uses it, so a graded party can check the suite was fixed before they
+// submitted. bin/prepare.mjs records it in prepared.json, bin/handout.mjs
+// shows it in BRIEF.md and handout.json, bin/judge.mjs recomputes it and
+// refuses on a mismatch, bin/promote.mjs prints it at reveal, and a seal
+// (bin/seal.mjs) carries it in seal.json. bin/commitment.mjs records and
+// checks it per spec; this module only computes it, from a folder or from
+// files in memory, and reads nothing else (no DUEDILIGENCE_HOME, no HOME).
+//
+// What is hashed, from a folder laid out as specs/<slug>/ (or an unpacked
+// seal): a manifest of lines in `sha256sum` format, `<hex>  <path>\n`,
+//   - one per file under tests/private/, every depth, `.DS_Store` skipped,
+//     sorted by the UTF-8 bytes of the path: the hex the sha256 of its
+//     bytes, the path `tests/private/<rel>` with `/` separators;
+//   - then one line for the kept test ids: the hex the sha256 of
+//     JSON.stringify(calibration.kept sorted) (UTF-8), the path
+//     `calibration.kept`;
+//   - only for a spec at a black-box seam, a last line for what the suites
+//     call (toolchain.json `boundary`: the command, or the service's start,
+//     healthcheck and build), since changing it changes what the hidden
+//     suite tests: the hex the sha256 of its JSON with keys sorted at every
+//     level, the path `toolchain.boundary`. A spec without one hashes as
+//     before.
+// hiddenSha256 is the sha256 of the manifest's UTF-8 bytes, lowercase hex.
+// By hand:
+//   (cd specs/<slug> && find tests/private -type f ! -name .DS_Store | LC_ALL=C sort | xargs shasum -a 256
+//    && printf '%s  calibration.kept\n' "$(jq -cj '.kept | sort' calibration.json | shasum -a 256 | cut -c1-64)"
+//    && printf '%s  toolchain.boundary\n' "$(jq -cjS '.boundary' toolchain.json | shasum -a 256 | cut -c1-64)") | shasum -a 256
+// (the last printf only when toolchain.json has a boundary)
+// (jq sorts by code point and JS by UTF-16 unit; the two agree unless an id
+// holds characters beyond the BMP.)
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const sha = (data) => createHash("sha256").update(data).digest("hex");
+const byBytes = (a, b) => Buffer.compare(Buffer.from(a.path), Buffer.from(b.path));
+/** A JSON value with every object's keys sorted, as `jq -S` writes it. */
+const sorted = (value) =>
+  Array.isArray(value)
+    ? value.map(sorted)
+    : value !== null && typeof value === "object"
+      ? Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])]))
+      : value;
+
+/** Every file under `dir`, relative with `/`, sorted; none when it does not exist. */
+function filesUnder(dir) {
+  const out = [];
+  const walk = (at, rel) => {
+    for (const entry of readdirSync(at, { withFileTypes: true })) {
+      const path = rel === "" ? entry.name : `${rel}/${entry.name}`;
+      if (entry.isDirectory()) walk(join(at, entry.name), path);
+      else out.push(path);
+    }
+  };
+  if (existsSync(dir)) walk(dir, "");
+  return out.sort();
+}
+
+/**
+ * The spec as hashed: its hidden files (`tests/private/<rel>` → bytes),
+ * calibration.json and toolchain.json parsed (or undefined), from a folder
+ * or from a file map of the same layout: a Map or object keyed by paths
+ * relative to the spec folder with `/`, each a string (UTF-8) or bytes.
+ */
+function specOf(source) {
+  if (typeof source === "string") {
+    const json = (name) => (existsSync(join(source, name)) ? JSON.parse(readFileSync(join(source, name), "utf8")) : undefined);
+    const hidden = join(source, "tests", "private");
+    return {
+      hidden: filesUnder(hidden).map((rel) => ({ rel, bytes: () => readFileSync(join(hidden, ...rel.split("/"))) })),
+      calibration: json("calibration.json"),
+      toolchain: json("toolchain.json"),
+    };
+  }
+  if (source === null || typeof source !== "object")
+    throw new TypeError("hiddenManifest: pass a spec folder or a file map ({ 'tests/private/<file>': contents, ... })");
+  const entries = source instanceof Map ? [...source.entries()] : Object.entries(source);
+  const text = (value) => (typeof value === "string" ? value : Buffer.from(value).toString("utf8"));
+  const json = (name) => {
+    const found = entries.find(([path]) => path === name);
+    return found === undefined ? undefined : JSON.parse(text(found[1]));
+  };
+  return {
+    hidden: entries
+      .filter(([path]) => path.startsWith("tests/private/"))
+      .map(([path, value]) => ({ rel: path.slice("tests/private/".length), bytes: () => value })),
+    calibration: json("calibration.json"),
+    toolchain: json("toolchain.json"),
+  };
+}
+
+/**
+ * The manifest hiddenSha256 is the hash of (see above), from a spec folder
+ * or a file map. `kept` defaults to calibration.json's.
+ */
+export function hiddenManifest(source, kept) {
+  const spec = specOf(source);
+  const ids = kept ?? spec.calibration?.kept ?? [];
+  const lines = spec.hidden
+    .filter((file) => file.rel.split("/").at(-1) !== ".DS_Store")
+    .map((file) => ({ path: `tests/private/${file.rel}`, hex: sha(file.bytes()) }));
+  lines.sort(byBytes).push({ path: "calibration.kept", hex: sha(JSON.stringify([...ids].sort())) });
+  const boundary = spec.toolchain?.boundary;
+  if (boundary !== undefined) lines.push({ path: "toolchain.boundary", hex: sha(JSON.stringify(sorted(boundary))) });
+  return lines.map((line) => `${line.hex}  ${line.path}\n`).join("");
+}
+
+/** The commitment hash of the hidden suite in a spec folder (specs/<slug>/ or an unpacked seal) or a file map. */
+export const hiddenSha256 = (source, kept) => sha(hiddenManifest(source, kept));

package/bin/judge.mjs

@@ -53,6 +53,7 @@
 import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { judgement } from "./rules.mjs";
 import { unseal } from "./seal.mjs";
 
 const sealed = openSeal(process.argv.slice(2));
@@ -62,21 +63,16 @@ const {
   args,
   audit,
   checkoutChanges,
-  count,
   discard,
   judge,
   newestTranscript,
   pathsOf,
   promotedOf,
   readJson,
-  regressionsOf,
-  scenarioOf,
   scopeOf,
   sha256,
   specDir,
-  testsOf,
   toolchainOf,
-  verdict,
   workdir,
   writeJson,
   writeSnapshot,
@@ -128,23 +124,17 @@ if (!entries.some((path) => existsSync(join(src, path)))) {
 }
 
 const judged = judge(slug, realpathSync(src));
-const publicCount = count(judged.public, calibration.publicIds);
-const hiddenCount = count(judged.hidden, calibration.kept);
-const reported = new Map(testsOf(judged.hidden).map((test) => [test.id, test]));
-const failures = calibration.kept
-  .filter((id) => reported.get(id)?.ok !== true)
-  .map((id) => ({ id, message: reported.get(id)?.error?.message ?? "did not run" }));
-const result = verdict({ publicCount, hiddenCount });
+// The rule itself: rules.mjs `judgement`, which bin/api.mjs exports as `verdict`.
+const outcome = judgement({ public: judged.public, hidden: judged.hidden, publicIds: calibration.publicIds, kept: calibration.kept });
+const { verdict: result, public: publicCount, hidden: hiddenCount, failures, failedScenarios: scenarios } = outcome;
 
 console.log(`${slug}: ${result}. Public ${publicCount.passed}/${publicCount.total}, hidden ${hiddenCount.passed}/${hiddenCount.total}.`);
 console.log(hashLine());
 const imported = readJson(join(specDir(slug), "imported.json"), null);
 if (imported !== null) console.log(`Imported from ${imported.from}: not held out (bin/import-archive.mjs).`);
 compileReport(judged);
-const scenarios = [...new Set(failures.map((item) => scenarioOf(item.id)).filter(Boolean))].sort();
 if (scenarios.length > 0) console.log(`Failing scenarios: ${scenarios.join(", ")}`);
-if (result === "incomplete")
-  for (const test of testsOf(judged.public).filter((item) => !item.ok)) console.log(`public: ${test.id}`);
+if (result === "incomplete") for (const id of outcome.publicFailing) console.log(`public: ${id}`);
 if (options.detail === true)
   for (const item of failures) console.log(`hidden: ${item.id}\n  ${item.message.split("\n")[0]}`);
 writeRecord({
@@ -170,7 +160,18 @@ function judgeRepo() {
   const found = checkoutChanges(chain, checkout, ref);
   const scope = scopeOf(chain, found.items, found.read);
   const strict = options["strict-scope"] === true;
-  const refused = [...scope.refused, ...(strict ? scope.outsideScope : [])];
+  // The rule (rules.mjs `judgement`) twice: on the scope alone, which says
+  // whether the tree is judged at all, then on the suites' results.
+  const facts = {
+    publicIds: calibration.publicIds,
+    kept: calibration.kept,
+    baseline,
+    refused: scope.refused,
+    changed: [...scope.allowed, ...scope.outsideScope],
+    allowedPaths: chain.allowedPaths ?? [],
+    strictScope: strict,
+  };
+  const { refused } = judgement(facts);
   const snapshot = workdir(`${slug}-snapshot`);
   let judged;
   try {
@@ -179,14 +180,8 @@ function judgeRepo() {
   } finally {
     discard(snapshot);
   }
-  const publicCount = judged === null ? { passed: 0, total: calibration.publicIds.length } : count(judged.public, calibration.publicIds);
-  const hiddenCount = judged === null ? { passed: 0, total: calibration.kept.length } : count(judged.hidden, calibration.kept);
-  const regressions = judged === null ? [] : regressionsOf(baseline, judged.existing);
-  const reported = new Map(judged === null ? [] : testsOf(judged.hidden).map((test) => [test.id, test]));
-  const failures = judged === null ? [] : calibration.kept
-    .filter((id) => reported.get(id)?.ok !== true)
-    .map((id) => ({ id, message: reported.get(id)?.error?.message ?? "did not run" }));
-  const result = verdict({ refused, publicCount, hiddenCount, regressions });
+  const outcome = judgement(judged === null ? facts : { ...facts, public: judged.public, hidden: judged.hidden, existing: judged.existing });
+  const { verdict: result, public: publicCount, hidden: hiddenCount, regressions, failures, failedScenarios: scenarios } = outcome;
   const handout = readJson(join(RUNS, slug, "handout", "handout.json"), null);
   let peeks = null;
   if (options.audit !== undefined) {
@@ -195,17 +190,15 @@ function judgeRepo() {
   }
 
   const where = ref === undefined ? `${found.root} (working tree)` : `${found.root} at ${ref}`;
-  console.log(`${slug}: ${result}. Public ${publicCount.passed}/${publicCount.total}, hidden ${hiddenCount.passed}/${hiddenCount.total}, existing ${judged === null ? "-" : `${count(judged.existing, baseline.passing).passed}/${baseline.passing.length}`}; ${where}.`);
+  console.log(`${slug}: ${result}. Public ${publicCount.passed}/${publicCount.total}, hidden ${hiddenCount.passed}/${hiddenCount.total}, existing ${judged === null ? "-" : `${outcome.existing.passed}/${baseline.passing.length}`}; ${where}.`);
   console.log(hashLine());
   if (refused.length > 0) console.log(`Refused:\n${pathsOf(refused).map((line) => `- ${line}`).join("\n")}`);
   if (judged !== null) compileReport(judged);
   if (regressions.length > 0) console.log(`Regressions (passed on base plus stub, fail now):\n${regressions.map((id) => `- ${id}`).join("\n")}`);
   if (!strict && scope.outsideScope.length > 0) console.log(`Outside the allowed paths:\n${pathsOf(scope.outsideScope).map((line) => `- ${line}`).join("\n")}`);
   if (scope.ownTests.length > 0) console.log(`Own tests (not judged): ${scope.ownTests.map((item) => item.path).join(", ")}`);
-  const scenarios = [...new Set(failures.map((item) => scenarioOf(item.id)).filter(Boolean))].sort();
   if (scenarios.length > 0) console.log(`Failing scenarios: ${scenarios.join(", ")}`);
-  if (result === "incomplete")
-    for (const test of testsOf(judged.public).filter((item) => !item.ok)) console.log(`public: ${test.id}`);
+  if (result === "incomplete") for (const id of outcome.publicFailing) console.log(`public: ${id}`);
   if (options.detail === true)
     for (const item of failures) console.log(`hidden: ${item.id}\n  ${item.message.split("\n")[0]}`);
   if (peeks !== null)
@@ -215,7 +208,7 @@ function judgeRepo() {
         : `Audit of ${peeks.transcript}${peeks.since ? ` since the handout (${peeks.since})` : ""}: ${peeks.attempts.length === 0 ? "no attempt to open the hidden suite" : `${peeks.attempts.length} attempt(s):\n${peeks.attempts.map((item) => `- ${item.at ?? ""} ${item.tool}: ${item.match}: ${item.input}`).join("\n")}`}`,
     );
 
-  const existingCount = judged === null ? null : count(judged.existing, baseline.passing);
+  const existingCount = judged === null ? null : outcome.existing;
   writeRecord({
     slug,
     verdict: result,

package/bin/lib.mjs

@@ -52,6 +52,10 @@ import {
   which,
 } from "./platform.mjs";
 import { withBins } from "./runners/shared.mjs";
+import { allowedIn, count, regressionsOf, scenarioOf, testsOf, verdict } from "./rules.mjs";
+
+// The suite-result rules live in bin/rules.mjs (pure, shared with bin/api.mjs).
+export { count, regressionsOf, scenarioOf, testsOf, verdict };
 
 /**
  * The package: bin/, prompts/, template/ and the bundled example spec. It
@@ -1296,12 +1300,6 @@ export function runSuite(dir, suite, chain = toolchainIn(dir)) {
   }
 }
 
-/** Each test of a suite result, named `file :: test`. */
-export const testsOf = (result) =>
-  result.files.flatMap((file) =>
-    file.tests.map((test) => ({ ...test, id: `${file.file} :: ${test.name}` })),
-  );
-
 /**
  * A `src/` judged as grading judges it: copied onto a fresh template with
  * the public suite, then onto another with the hidden suite, so code that
@@ -1351,41 +1349,7 @@ export function baselineOf(result, stage) {
   };
 }
 /** Whether a repository path is one the implementer may change: in a folder of `allowedPaths` (ending in `/`) or one of its files. */
-export const allowedPath = (chain, path) =>
-  (chain.allowedPaths ?? []).some((allowed) => (allowed.endsWith("/") ? path.startsWith(allowed) : path === allowed));
-/** Tests the baseline passed that `result` (the existing suite after a change) does not. */
-export function regressionsOf(baseline, result) {
-  const ok = new Set(testsOf(result).filter((test) => test.ok).map((test) => test.id));
-  return baseline.passing.filter((id) => !ok.has(id));
-}
-
-/** How many of `ids` passed in a suite result; a test that never reported failed. */
-export function count(result, ids) {
-  const ok = new Set(testsOf(result).filter((test) => test.ok && !test.skipped).map((test) => test.id));
-  return { passed: ids.filter((id) => ok.has(id)).length, total: ids.length };
-}
-
-/**
- * The spec scenario a test is keyed to, from the `[kind-n]` its name starts
- * with (prompts/public-tests.md, prompts/hidden-tests.md), or null.
- */
-export const scenarioOf = (id) =>
-  /^\[([a-z]+-\d+)\] /.exec(id.split(" :: ").at(-1))?.[1] ?? null;
-
-/**
- * The verdict: `refused` when the submission changed anything outside what
- * the agent may write, `incomplete` when a public test fails, `regressed`
- * when a test of the repository's existing suite that passed before the
- * change fails after it (never on the bundled template, which has no
- * existing suite), `passed` when every kept hidden test passes too,
- * `overfit` when one does not.
- */
-export function verdict({ refused = [], publicCount, hiddenCount, regressions = [] }) {
-  if (refused.length > 0) return "refused";
-  if (publicCount.passed !== publicCount.total) return "incomplete";
-  if (regressions.length > 0) return "regressed";
-  return hiddenCount.total > 0 && hiddenCount.passed === hiddenCount.total ? "passed" : "overfit";
-}
+export const allowedPath = (chain, path) => allowedIn(chain.allowedPaths, path);
 
 /**
  * The claude CLI, or null: CLAUDE_BIN, claude on PATH, the newest VS Code

package/bin/login.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// `duediligence login`: see account.mjs.
+import { readFileSync } from "node:fs";
+import { run } from "./account.mjs";
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+process.exitCode = await run("login", process.argv.slice(2), { client: "duediligence", version });

package/bin/logout.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// `duediligence logout`: see account.mjs.
+import { readFileSync } from "node:fs";
+import { run } from "./account.mjs";
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+process.exitCode = await run("logout", process.argv.slice(2), { client: "duediligence", version });

package/bin/platform-client.mjs

@@ -0,0 +1,175 @@
+// The hosted platform (sandbox-factory, platform.lunox.work) as this CLI
+// talks to it: the base URL, the shared credentials file, and one request
+// function on `fetch`, so duediligence keeps no runtime dependency. Nothing
+// here runs unless a platform command (`login`, `whoami`, `logout`) is
+// called; every other command stays local. Not named platform.mjs, which is
+// the host-OS layer.
+//
+// Credentials: `~/.lunox/credentials` (LUNOX_CREDENTIALS moves it), JSON,
+// mode 600 in a 700 folder, written whole through a rename. carveout shares
+// the file, so each CLI keeps its own entry under the platform's URL:
+//
+//   { "https://platform.lunox.work": {
+//       "duediligence": { token, organizationId, organizationHandle, client, createdAt, expiresAt },
+//       "carveout": { ... } } }
+//
+// A token is minted for one client with that client's scopes, so the two
+// CLIs never share one; writing an entry keeps every other.
+
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_PLATFORM = "https://platform.lunox.work";
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+export class PlatformError extends Error {
+  constructor(message, { status, code } = {}) {
+    super(message);
+    this.name = "PlatformError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/** `--platform`, else LUNOX_PLATFORM_URL, else production; no trailing slash. HTTPS, or plain HTTP to this machine only. */
+export function platformUrl(given, env = process.env) {
+  const raw = given ?? env.LUNOX_PLATFORM_URL ?? DEFAULT_PLATFORM;
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new PlatformError(`${raw} is not a URL.`);
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && LOOPBACK.has(url.hostname))) {
+    throw new PlatformError(`${raw}: the platform must be https:// (plain http only on localhost).`);
+  }
+  url.search = "";
+  url.hash = "";
+  return url.href.replace(/\/+$/, "");
+}
+
+export function credentialsPath(env = process.env) {
+  return env.LUNOX_CREDENTIALS ?? join(homedir(), ".lunox", "credentials");
+}
+
+/** The whole file, `{}` when there is none. A file that is not a JSON object is refused, never overwritten. */
+export function readCredentials(path) {
+  if (!existsSync(path)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new PlatformError(`${path} is not valid JSON (${error.message}); fix or remove it.`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new PlatformError(`${path} does not hold a JSON object; fix or remove it.`);
+  }
+  return parsed;
+}
+
+/** Writes the file whole: a 600 temp file beside it, renamed over it. Removes it when nothing is left. */
+export function writeCredentials(path, all) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+  }
+  if (Object.keys(all).length === 0) {
+    rmSync(path, { force: true });
+    return;
+  }
+  const temp = join(dir, `.credentials-${process.pid}-${randomBytes(6).toString("hex")}.tmp`);
+  try {
+    writeFileSync(temp, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    chmodSync(temp, 0o600);
+    renameSync(temp, path);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw error;
+  }
+}
+
+/** This client's entry for a platform, or undefined. */
+export function credentialFor(path, base, client) {
+  const entry = readCredentials(path)[base]?.[client];
+  return entry && typeof entry.token === "string" ? entry : undefined;
+}
+
+/** Sets (or, with `entry` undefined, removes) this client's entry, keeping every other. */
+export function saveCredential(path, base, client, entry) {
+  const all = readCredentials(path);
+  const forBase = { ...(all[base] ?? {}) };
+  if (entry === undefined) delete forBase[client];
+  else forBase[client] = entry;
+  if (Object.keys(forBase).length === 0) delete all[base];
+  else all[base] = forBase;
+  writeCredentials(path, all);
+}
+
+/** The minimum version a 426 names, wherever the body puts it. */
+function minimumOf(body) {
+  const named = body?.minimumVersion ?? body?.minimum_version ?? body?.minimum;
+  if (typeof named === "string") return named;
+  return /\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/.exec(body?.error ?? "")?.[0];
+}
+
+/**
+ * One call to the platform's API. Sends the token as a bearer, the client
+ * and its version as `User-Agent` and `Lunox-Client-Version`
+ * (`<client>/<version>`), and JSON. Answers the parsed body; throws a
+ * PlatformError whose message says what to do: 401 → sign in again, 426 →
+ * upgrade, otherwise the API's own `{ error, code }`. `session` marks the
+ * token as a device sign-in's session rather than a saved API token.
+ */
+export async function request({ base, token, session = false, method = "GET", path, body, client, version, fetchImpl = fetch }) {
+  const headers = {
+    Accept: "application/json",
+    "User-Agent": `${client}/${version}`,
+    "Lunox-Client-Version": `${client}/${version}`,
+  };
+  if (token !== undefined) headers.Authorization = `Bearer ${token}`;
+  if (body !== undefined) headers["Content-Type"] = "application/json";
+  let response;
+  try {
+    response = await fetchImpl(`${base}${path}`, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      redirect: "error",
+      signal: AbortSignal.timeout(30_000),
+    });
+  } catch (error) {
+    throw new PlatformError(`Could not reach ${base}: ${error.cause?.message ?? error.message}`);
+  }
+  const text = await response.text();
+  let parsed;
+  try {
+    parsed = text === "" ? undefined : JSON.parse(text);
+  } catch {
+    parsed = undefined;
+  }
+  if (response.ok) return parsed ?? {};
+  const status = response.status;
+  const code = typeof parsed?.code === "string" ? parsed.code : typeof parsed?.error === "string" && !parsed.error.includes(" ") ? parsed.error : undefined;
+  if (status === 426) {
+    const minimum = minimumOf(parsed);
+    throw new PlatformError(
+      `${base} needs a newer ${client}${minimum ? `: upgrade to at least ${minimum}` : ""} (this is ${version}). npm i -g ${client}@latest`,
+      { status, code },
+    );
+  }
+  if (status === 401 && token !== undefined) {
+    const what = session ? "The browser sign-in" : "The saved sign-in";
+    throw new PlatformError(`${what} for ${base} is no longer valid (expired or revoked). Run \`${client} login\` again.`, {
+      status,
+      code,
+    });
+  }
+  const said = parsed?.error_description ?? parsed?.error ?? parsed?.message;
+  throw new PlatformError(
+    typeof said === "string" ? `${said}${code && code !== said ? ` (${code})` : ""}` : `${method} ${path}: HTTP ${status}`,
+    { status, code },
+  );
+}