run402 4.38.2 → 4.39.0

package/lib/gitvault.mjs

@@ -39,8 +39,8 @@ export const HELP = `run402 gitvault — your source, encrypted before it leaves
 
 Usage:
   run402 gitvault init     [--project <id>] [--org <org_id>] [--git-remote] [--no-remote]
-  run402 gitvault status   [--project <id>] [--repo <repo_id>] [--refs]
-  run402 gitvault snapshot [--project <id>] [--repo <repo_id>] [--message <text>] [--checkpoint]
+  run402 gitvault status   [--project <id>] [--repo <repo_id>] [--refs] [--human]
+  run402 gitvault snapshot [--project <id>] [--repo <repo_id>] [--message <text>] [--checkpoint] [--dry-run]
   run402 gitvault policy   <required|grandfathered> [--project <id>] [--repo <repo_id>]
                            [--reason <why>]
   run402 gitvault compact  [--project <id>] [--repo <repo_id>]
@@ -83,7 +83,9 @@ Subcommands:
             next release. Once \`gitvault\` was the only publish verb; \`git
             push\` is now the actual publish path (via the remote helper),
             so \`push\` here was renamed to name what it does: one verb per
-            operation.
+            operation. \`--dry-run\` (kychee-com/run402#565) previews it
+            instead: the same real local pipeline, publishing nothing and
+            never allocating.
   compact   Publish a checkpoint covering the canonical refs, every root
             unexpired at the cutoff, and the HEAD target, under a maintenance
             lease so a concurrent cycle cannot race it.
@@ -110,10 +112,25 @@ Options:
                     HEAD target. This is a VERIFICATION (it walks the head
                     chain and advances the local materialized pin), which is
                     why plain \`status\` — an observation — does not do it.
+  --human           status: a five/six-line human summary on stdout instead of
+                    the JSON dump (kychee-com/run402#569; explicit opt-in per
+                    the cli-output-contract). Address, remote; HEAD + ref count
+                    (needs --refs too — otherwise the line names the omission);
+                    generations in decimal; storage bytes/object count (from
+                    this SAME status() call — no extra network read); whether
+                    THIS machine can decrypt, and the policy; standing warnings,
+                    if any, verbatim (a live terminal-loss risk may be the sixth
+                    line). Rejected together with --json. No effect on plain
+                    \`status\`'s own output, which is unchanged.
   --repo <repo_id>  Address the vault directly by id, skipping project lookup
   --message <text>  snapshot: commit message for the synthetic commit a dirty tree
                     produces (a clean tree pushes HEAD itself, no message used)
   --checkpoint      snapshot: force the checkpoint-bearing form regardless of delta size
+  --dry-run         snapshot: a REAL preview (kychee-com/run402#565) — runs the actual
+                    local pipeline (capture, pack building, encryption sizing) and
+                    reports objects, encrypted bytes, refs, and the generation it
+                    would admit as. Publishes NOTHING, and never allocates a vault
+                    that does not exist yet (reports allocation_needed instead).
   --budget <n>      verify: heads to verify in this call. The verified prefix is
                     persisted, so a budget-exceeded run resumes where it stopped
                     instead of restarting.
@@ -159,7 +176,9 @@ Terminal loss (protocol §0):
 Examples:
   run402 gitvault init
   run402 gitvault status --refs
+  run402 gitvault status --human
   run402 gitvault snapshot --message "wip: refactor the parser"
+  run402 gitvault snapshot --dry-run
   run402 gitvault policy grandfathered --reason "migrating CI to a vaulted client"
   run402 gitvault verify --budget 500
   run402 gitvault prune --project prj_1a2b3c
@@ -377,22 +396,146 @@ async function policy(args) {
   }
 }
 
+/**
+ * The vault's address in the form a human would actually type it: named
+ * (`run402::<org-slug>/<name>`) when this checkout's local pin resolved from
+ * one — an id-form pin buys nothing and is never written (see
+ * `gitvault-address.ts`'s own doc comment), so a non-null `s.pinned` always
+ * carries `resolved_from` — else id-form (`run402::<org_id>/<project_id>`),
+ * falling back to whichever of project_id/repo_id is known when the vault
+ * record itself is unavailable.
+ */
+function formatGitvaultAddress(s) {
+  if (s.pinned?.resolved_from) {
+    return `run402::${s.pinned.resolved_from.org_slug}/${s.pinned.resolved_from.repo_name}`;
+  }
+  const orgId = s.vault?.org_id ?? null;
+  const projectId = s.project_id ?? s.vault?.project_id ?? null;
+  if (orgId && projectId) return `run402::${orgId}/${projectId}`;
+  if (projectId) return projectId;
+  if (s.repo_id) return `repo ${s.repo_id}`;
+  return "(unresolved)";
+}
+
+/**
+ * `run402 gitvault status --human` (kychee-com/run402#569) — the five-liner:
+ * "status --refs is an admission-debugging protocol dump; the human question
+ * is five lines — remote URL, branch/HEAD, generation, bytes,
+ * can-this-machine-decrypt." Renders from `s` alone — the SAME status() call
+ * the JSON path already made, so `--human` costs no extra network read.
+ *
+ * Generations render DECIMAL, not the wire's 16-hex-digit form — a hex
+ * generation is a protocol detail, not something a human reads at a glance.
+ *
+ * The HEAD/ref-count line needs the vault's OWN ref map, which `status`
+ * fetches only when `--refs` is ALSO passed (materializing is a verification
+ * that advances local state — `status` alone stays a pure observation, see
+ * that option's own doc comment). Composing `--human --refs` gets the full
+ * line; `--human` alone names the omission rather than guessing from the
+ * local git checkout, which could easily disagree with what the vault holds.
+ *
+ * Warnings — including the progressive terminal-loss risk warning — are
+ * echoed EXACTLY as the SDK reported them (never reworded) and become an
+ * optional sixth line, present only when `s.warnings` is non-empty. Without
+ * `--human`, `run402 gitvault status` is unchanged: it always prints the
+ * FULL terminal-loss statement verbatim on stderr regardless of warnings;
+ * this compact view surfaces it only when it is actually live advice.
+ */
+async function formatGitvaultHuman(s) {
+  const lines = [];
+  const remotePart = s.remote
+    ? ` (remote '${s.remote.name}'${s.remote.matches ? "" : " — points at a DIFFERENT project"})`
+    : " (no local remote)";
+  lines.push(`Address: ${formatGitvaultAddress(s)}${remotePart}`);
+
+  if (!s.vault) {
+    // A normal shape (protocol D183) — no vault allocated for this project
+    // yet. Nothing below this line is knowable, so it is not fabricated.
+    lines.push("Vault: not allocated yet for this project — run 'run402 gitvault init' to allocate one.");
+    if (s.warnings.length > 0) lines.push(`Warnings: ${s.warnings.map((w) => w.message).join(" ")}`);
+    return lines.join("\n");
+  }
+
+  if (s.refs) {
+    const count = Object.keys(s.refs).length;
+    const head = !s.head_target
+      ? "(none yet)"
+      : s.head_target.kind === "symref"
+        ? s.head_target.ref
+        : `detached @ ${s.head_target.oid}`;
+    lines.push(`HEAD: ${head}  (${count} ref${count === 1 ? "" : "s"})`);
+  } else {
+    lines.push("HEAD: (not materialized — pass --refs to see HEAD/ref count)");
+  }
+
+  const { generationToBigInt } = await import("#sdk/node");
+  const decimal = (g) => (g ? generationToBigInt(g).toString() : "none");
+  lines.push(`Generations: authenticated ${decimal(s.pins.highest_authenticated)}, materialized ${decimal(s.pins.highest_materialized)}`);
+
+  // Bytes + object count — pulled from the vault record `status()` ALREADY
+  // fetched (no new network read, per the ask). `objects` is per-object-kind
+  // counts; summed for one number a human can glance at.
+  const storage = s.vault.storage;
+  const objectCount = storage?.objects ? Object.values(storage.objects).reduce((sum, n) => sum + Number(n), 0) : null;
+  lines.push(storage ? `Storage: ${storage.source_bytes} byte(s)${objectCount != null ? ` across ${objectCount} object(s)` : ""}` : "Storage: unknown");
+
+  const decryptPart = !s.keystore.holds_repo_key
+    ? "CANNOT decrypt (no key in this machine's keystore)"
+    : s.keystore.can_sign
+      ? "can decrypt and publish"
+      : "can decrypt (read-only — no signing key)";
+  lines.push(`This machine: ${decryptPart}. Policy: ${s.gitvault_policy ?? "(none)"}`);
+
+  if (s.warnings.length > 0) lines.push(`Warnings: ${s.warnings.map((w) => w.message).join(" ")}`);
+
+  return lines.join("\n");
+}
+
 async function status(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--refs", "--help", "-h"], COMMON_VALUE_FLAGS);
+  assertKnownFlags(a, [...COMMON_VALUE_FLAGS, "--refs", "--human", "--help", "-h"], COMMON_VALUE_FLAGS);
   requirePositionalCount(a, COMMON_VALUE_FLAGS, {
     min: 0, max: 0, command: "run402 gitvault status", missing: "",
   });
+  // kychee-com/run402#569 — an explicit opt-in per the cli-output-contract
+  // (openspec/specs/cli-output-contract/spec.md: raw/human stdout REQUIRES
+  // one), the same shape `run402 up`'s own `--human` already uses. Without
+  // it, behavior is byte-identical to before this flag existed.
+  const human = a.includes("--human");
+  if (human && a.includes("--json")) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--human cannot be combined with --json.",
+      details: { flags: a.filter((arg) => arg === "--human" || arg === "--json") },
+    });
+  }
   const target = await vaultTarget(a);
   if (a.includes("--refs")) target.refs = true;
   try {
     const s = await getSdk().gitvault.status(target);
+    if (human) {
+      // The human view REPLACES the JSON dump — it is the sanctioned
+      // exception the CLI-wide `--json` no-op convention already carves out
+      // for a command's OWN `--human` flag (see argparse.mjs's header
+      // comment). No new network read: everything below is already present
+      // on `s`, the SAME status() call the JSON path made.
+      console.log(await formatGitvaultHuman(s));
+      return;
+    }
     console.log(JSON.stringify(s, null, 2));
     printTerminalLoss(s);
     // Two facts the user otherwise has to leave the CLI for: which vault this
     // checkout is wired to, and what the control plane says is in it.
     if (s.remote) {
-      console.error(`remote '${s.remote.name}': ${s.remote.url}${s.remote.matches ? "" : "  ← points at a DIFFERENT project than this status"}`);
+      // `matches` is a TRI-STATE (kychee-com/run402#562): `false` is a real
+      // mismatch; `null` only means a slug-form remote has not resolved on
+      // this machine yet — that is NOT evidence of anything wrong, so it
+      // gets a neutral note, never the mismatch warning.
+      const suffix =
+        s.remote.matches === false ? "  ← points at a DIFFERENT project than this status"
+        : s.remote.matches === null ? `  (${s.remote.reason})`
+        : "";
+      console.error(`remote '${s.remote.name}': ${s.remote.url}${suffix}`);
     }
     // The id-pinning state (design D6, task 4.5): a slug-form remote pins
     // repo_id in local git state the first time it resolves; id-form pins
@@ -459,10 +602,11 @@ async function detectSlugFormRemote(a, repoDir) {
 async function snapshot(args) {
   const a = normalizeArgv(args);
   const valueFlags = [...COMMON_VALUE_FLAGS, "--message"];
-  assertKnownFlags(a, [...valueFlags, "--checkpoint", "--help", "-h"], valueFlags);
+  assertKnownFlags(a, [...valueFlags, "--checkpoint", "--dry-run", "--help", "-h"], valueFlags);
   requirePositionalCount(a, valueFlags, {
     min: 0, max: 0, command: "run402 gitvault snapshot", missing: "",
   });
+  const dryRun = a.includes("--dry-run");
   const message = flagValue(a, "--message");
   const repoDir = process.cwd();
   const address = await detectSlugFormRemote(a, repoDir);
@@ -472,20 +616,26 @@ async function snapshot(args) {
   // it is skipped there, matching `open()`'s own precedence. Skipped
   // entirely for a slug-form remote (`address` above) — that resolves
   // through the address, not a project_id, and needs no separate org_id.
+  //
+  // Skipped ENTIRELY for --dry-run (kychee-com/run402#565): org resolution
+  // exists only to feed lazy allocation, and a dry run never allocates — the
+  // read would cost a network round-trip for a fact `planPush` never uses.
   const target = address ? { repo_dir: repoDir } : await vaultTarget(a);
-  const orgId = !address && target.project_id ? await resolveOwningOrgId(target.project_id) : null;
+  const orgId = !address && !dryRun && target.project_id ? await resolveOwningOrgId(target.project_id) : null;
   const opts = {
     ...target,
     ...(address ? { address } : {}),
     ...(orgId ? { org_id: orgId } : {}),
     // The gitvault_commit line is progress, not payload: print it the moment
     // the snapshot exists, well before the publication round-trips finish, so
-    // a human watching a slow push sees what is being pushed.
+    // a human watching a slow push sees what is being pushed. Fires for a
+    // dry run too — the capture itself is real, local work.
     onCommitLine: (line) => console.error(line),
     // Fires synchronously, BEFORE the capture/publish that follows — printed
     // here rather than deferred past `push()`'s return so the receipt is
     // never lost if a later step in the SAME push fails after allocation
-    // already landed on the server.
+    // already landed on the server. Never fires for --dry-run: `planPush`
+    // never allocates, so this callback is simply unused there.
     onVaultCreated: async (created) => {
       console.error("");
       console.error(`vault allocated (genesis ${created.genesis_sha256}) — one-shot recovery receipt, keep many copies:`);
@@ -500,6 +650,24 @@ async function snapshot(args) {
   if (message != null) opts.snapshot = { message };
   if (a.includes("--checkpoint")) opts.checkpoint = true;
   try {
+    if (dryRun) {
+      // kychee-com/run402#565: a REAL dry run — the same local pipeline
+      // `push` runs (capture, pack building, encryption sizing), stopping
+      // before the two network mutations. Nothing is published; the JSON
+      // report is the entire contract, so it goes on stdout like every other
+      // gitvault verb's payload.
+      const plan = await getSdk().gitvault.planPush(opts);
+      console.log(JSON.stringify(plan, null, 2));
+      if (plan.allocation_needed) {
+        console.error("dry-run: no vault allocated for this project yet — a real snapshot would allocate one first; object/byte sizing is not knowable until then");
+      } else {
+        console.error(
+          `dry-run: would publish generation ${plan.would_admit_generation} (${plan.would_admit_generation_decimal}, ${plan.form}) — ` +
+          `${plan.object_count} object(s), ${plan.encrypted_bytes} encrypted byte(s) (${plan.raw_bytes} raw)`,
+        );
+      }
+      return;
+    }
     const result = await getSdk().gitvault.push(opts);
     console.log(JSON.stringify(result, null, 2));
     console.error(`published generation ${result.generation} (${result.form})`);

package/lib/update-check.mjs

@@ -124,6 +124,12 @@ export async function refreshUpdateCheck({
   timeoutMs = UPDATE_CHECK_TIMEOUT_MS,
   registry = npmRegistryBase(env),
 } = {}) {
+  // Faithful (kychee-com/run402#561): a failed live check must never ERASE a
+  // previously known-good `latest` — reporting `latest: null` in its place
+  // would be a confident lie ("nothing is known"), not an honest stale
+  // estimate. Read what is already cached BEFORE attempting the network
+  // call, so a failure can fall back to it.
+  const previous = readUpdateCache({ path: cachePath });
   try {
     const latest = await fetchLatestRun402Version({ env, fetchImpl, timeoutMs, registry });
     const record = {
@@ -137,16 +143,24 @@ export async function refreshUpdateCheck({
     writeUpdateCache(record, { path: cachePath });
     return { ok: true, ...record };
   } catch (err) {
+    // `checked_at`/`latest`/`source` are carried forward from the last
+    // SUCCESSFUL check (or absent, for a genuine first-ever attempt) —
+    // `checked_at` therefore means "the last time we actually knew
+    // anything", which is exactly what cache-age labeling needs to report.
+    // `last_attempt_at` records THIS failed attempt separately, so a caller
+    // can tell "stale, never rechecked" apart from "stale, just tried and
+    // failed again".
     const record = {
       current,
-      latest: null,
-      checked_at: new Date().toISOString(),
-      source: "registry",
+      latest: previous?.latest ?? null,
+      checked_at: previous?.checked_at ?? new Date().toISOString(),
+      source: previous?.source ?? "registry",
       registry,
       error: {
         code: errorCode(err),
         message: err instanceof Error ? err.message : String(err),
       },
+      last_attempt_at: new Date().toISOString(),
     };
     writeUpdateCache(record, { path: cachePath });
     return { ok: false, ...record };
@@ -217,6 +231,21 @@ export function createUpdateCheckScheduler({
   };
 }
 
+/** `now - checked_at`, or `null` when there is nothing to measure from. */
+function cacheAgeMs(record, now) {
+  const checked = Date.parse(record?.checked_at ?? "");
+  return Number.isFinite(checked) ? Math.max(0, now - checked) : null;
+}
+
+/** A short, human-readable age for a hint string — hours under two days, days beyond that. */
+function humanAge(ms) {
+  if (ms === null) return "an unknown age";
+  const hours = ms / (60 * 60 * 1000);
+  if (hours < 1) return "under an hour";
+  if (hours < 48) return `${Math.round(hours)}h`;
+  return `${Math.round(hours / 24)}d`;
+}
+
 export async function doctorUpdateCheck({
   refresh = false,
   cwd = process.cwd(),
@@ -246,9 +275,32 @@ export async function doctorUpdateCheck({
   }
 
   let record = readUpdateCache({ path: cachePath });
-  if (refresh) {
-    record = await refreshUpdateCheck({ env, fetchImpl, current, cachePath });
+
+  // A real TTL (24h) that actually causes a refresh (kychee-com/run402#561
+  // — grok saw a THREE-minor-version, four-week-old cached "latest" with
+  // nothing ever having re-checked it). An explicit `--refresh` always
+  // checks live, same as before; now a MISSING or EXPIRED cache also gets
+  // exactly ONE bounded live attempt automatically, so a plain
+  // `run402 doctor` self-heals a stale cache instead of silently reporting
+  // a weeks-old value as if it were current. `refreshUpdateCheck` itself
+  // never erases a previously known-good `latest` on failure (see its own
+  // doc comment), so a failed attempt here degrades gracefully to the LAST
+  // GOOD record — never to a bare unknown when something was already known.
+  const cacheWasFreshAtStart = isCacheFresh(record, { now });
+  const refreshAttempted = refresh || !cacheWasFreshAtStart;
+  let refreshFailed = false;
+  if (refreshAttempted) {
+    const refreshed = await refreshUpdateCheck({ env, fetchImpl, current, cachePath });
+    refreshFailed = !refreshed.ok;
+    record = refreshed;
   }
+  // A refresh (success or failure) just happened at REAL wall-clock time —
+  // `refreshUpdateCheck` has no `now` override, so the instant used to
+  // report freshness/age below is re-derived here rather than reusing a
+  // `now` captured before the refresh ran (which would read the brand-new
+  // record as "in the future" and misreport it as stale). A call that never
+  // triggers a refresh keeps using exactly the `now` it was given.
+  const reportNow = refreshAttempted ? Date.now() : now;
 
   if (!record) {
     return {
@@ -260,26 +312,34 @@ export async function doctorUpdateCheck({
         install_context: install.kind,
         confidence: install.confidence,
         package_manager: install.package_manager,
-        cache: { path: cachePath, fresh: false, source: "none" },
+        cache: { path: cachePath, fresh: false, source: "none", refresh_attempted: refreshAttempted, refresh_failed: refreshFailed },
       },
-      hint: "No cached npm version check yet. Run 'run402 doctor --refresh' to check now.",
+      hint: refreshAttempted
+        ? "No cached npm version check yet, and a live check just failed — try 'run402 doctor --refresh' again, or check network access."
+        : "No cached npm version check yet. Run 'run402 doctor --refresh' to check now.",
     };
   }
 
-  const freshness = isCacheFresh(record, { now });
+  const freshness = isCacheFresh(record, { now: reportNow });
+  const ageMs = cacheAgeMs(record, reportNow);
   const notice = updateNoticeFromRecord(record, {
     cwd,
     env,
     argv,
     execPath,
     current,
-    now,
+    now: reportNow,
     command: ["run402", "doctor"],
     source: record.source ?? "cache",
   });
   const comparison = compareSemver(current, record.latest);
   const stale = notice !== null;
   const status = stale ? "warning" : record.latest && comparison !== null ? "ok" : "unknown";
+  // Faithful: an estimate served from a failed-refresh fallback is labeled
+  // as one, not presented as if it were current.
+  const staleEstimateNote = refreshFailed && ageMs !== null
+    ? ` (from a cached check ${humanAge(ageMs)} old — a live check just failed: ${record.error?.code ?? "network error"})`
+    : "";
   return {
     name: "cli_update",
     status,
@@ -293,15 +353,18 @@ export async function doctorUpdateCheck({
       cache: {
         path: cachePath,
         fresh: freshness,
+        age_ms: ageMs,
         source: record.source ?? "cache",
         error: record.error ?? null,
+        refresh_attempted: refreshAttempted,
+        refresh_failed: refreshFailed,
       },
       ...(stale ? { next_actions: notice.next_actions } : {}),
     },
     ...(stale
-      ? { hint: `A newer run402 CLI is available (${current} -> ${record.latest}).` }
+      ? { hint: `A newer run402 CLI is available (${current} -> ${record.latest})${staleEstimateNote}.` }
       : record.error
-        ? { hint: "Could not check npm for the latest run402 version; other doctor checks still ran." }
+        ? { hint: `Could not check npm for the latest run402 version${staleEstimateNote}; other doctor checks still ran.` }
         : {}),
   };
 }

package/lib/update-check.test.mjs

@@ -421,40 +421,193 @@ describe("CLI update notices and scheduler", () => {
     assert.equal(scheduler.getCompletedLiveNotice().latest, "3.7.16");
   }));
 
-  it("doctor reports stale, unknown, skipped, and refresh states without failing other checks", async () => withTemp(async (dir) => {
+  it("doctor reports a cached warning and skipped state without failing other checks", async () => withTemp(async (dir) => {
     packageJson(dir, { devDependencies: { run402: "3.7.14" } });
     const cachePath = join(dir, "cache.json");
+    const now = Date.parse("2026-07-03T10:30:00.000Z"); // 12min after staleRecord()'s checked_at — inside the 24h TTL
+    // Fixed `now` so this stays a within-TTL read: no live check, no
+    // fetchImpl needed at all for this half of the test.
     writeUpdateCache(staleRecord(), { path: cachePath });
     let check = await doctorUpdateCheck({
       cwd: dir,
       execPath: join(dir, "node_modules", ".bin", "run402"),
       current: "3.7.14",
       cachePath,
+      now,
     });
     assert.equal(check.status, "warning");
     assert.equal(check.value.next_actions[0].mutates_project, true);
 
-    check = await doctorUpdateCheck({ cwd: dir, current: "3.7.14", cachePath: join(dir, "missing.json") });
-    assert.equal(check.status, "unknown");
-
     check = await doctorUpdateCheck({
       cwd: dir,
       current: "3.7.14",
       cachePath,
       env: { RUN402_NO_UPDATE_CHECK: "1" },
+      fetchImpl: async () => { throw new Error("RUN402_NO_UPDATE_CHECK must skip every network attempt"); },
     });
     assert.equal(check.status, "skipped");
-
-    check = await doctorUpdateCheck({
-      cwd: dir,
-      current: "3.7.14",
-      cachePath,
-      refresh: true,
-      fetchImpl: async () => new Response(JSON.stringify({ version: "3.7.14" }), {
-        status: 200,
-        headers: { "content-type": "application/json" },
-      }),
-    });
-    assert.equal(check.status, "ok");
   }));
+
+  // ─── the real TTL, and what happens at every edge of it (kychee-com/run402#561) ──
+  //
+  // THE DEFECT (grok dogfood, 4.38.0 installed): `run402 doctor` reported
+  // the latest CLI as 4.17.5 from a cache dated Aug 1 — three minor versions
+  // and ~4 weeks stale — because NOTHING besides an explicit `--refresh`
+  // ever re-checked it. `UPDATE_CHECK_TTL_MS` was already 24h; the bug was
+  // that a plain `doctor` invocation never consulted it to trigger a
+  // refresh, only to LABEL the cache `fresh: false` in a field nobody read.
+  // Four states, each hermetic (`fetchImpl` is always injected — no real
+  // npm registry call from this file, ever):
+  describe("doctor's cache TTL actually causes a refresh (kychee-com/run402#561)", () => {
+    it("fresh fetch: no cache at all triggers ONE automatic live check, even without --refresh", () => withTemp(async (dir) => {
+      const cachePath = join(dir, "cache.json");
+      let fetchCalls = 0;
+      const check = await doctorUpdateCheck({
+        cwd: dir,
+        current: "3.7.14",
+        cachePath,
+        fetchImpl: async () => {
+          fetchCalls += 1;
+          return new Response(JSON.stringify({ version: "3.7.16" }), { status: 200, headers: { "content-type": "application/json" } });
+        },
+      });
+      assert.equal(fetchCalls, 1, "no cache existed yet — a live check must run automatically, not just on --refresh");
+      assert.equal(check.status, "warning");
+      assert.equal(check.value.latest, "3.7.16");
+      assert.equal(check.value.cache.fresh, true);
+      assert.equal(check.value.cache.refresh_attempted, true);
+      assert.equal(check.value.cache.refresh_failed, false);
+      assert.ok(readUpdateCache({ path: cachePath }), "the fresh result must be persisted for the next call");
+    }));
+
+    it("within-TTL reuse: a cache inside the 24h window is served as-is, with NO live check at all", () => withTemp(async (dir) => {
+      const cachePath = join(dir, "cache.json");
+      const now = Date.parse("2026-08-01T12:00:00.000Z");
+      writeUpdateCache({
+        current: "3.7.14",
+        latest: "3.7.15",
+        checked_at: new Date(now - 60 * 60 * 1000).toISOString(), // 1h old
+        source: "cache",
+        error: null,
+      }, { path: cachePath });
+      let fetchCalls = 0;
+      const check = await doctorUpdateCheck({
+        cwd: dir,
+        current: "3.7.14",
+        cachePath,
+        now,
+        fetchImpl: async () => { fetchCalls += 1; throw new Error("a fresh cache must never trigger a live check"); },
+      });
+      assert.equal(fetchCalls, 0);
+      assert.equal(check.status, "warning");
+      assert.equal(check.value.latest, "3.7.15");
+      assert.equal(check.value.cache.fresh, true);
+      assert.equal(check.value.cache.refresh_attempted, false);
+      assert.equal(check.value.cache.age_ms, 60 * 60 * 1000);
+    }));
+
+    it("expired-refresh: a cache past the 24h TTL is refreshed automatically, and the FRESH value wins", () => withTemp(async (dir) => {
+      const cachePath = join(dir, "cache.json");
+      // Real wall-clock throughout (no fixed `now`): a SUCCESSFUL live check
+      // stamps `checked_at` with the actual current time internally
+      // (`refreshUpdateCheck` has no clock override), so comparing it
+      // against a fixed test `now` from the past would read as stale by
+      // construction — the "30 days old" fixture only needs to predate the
+      // REAL clock, which `Date.now() - 30d` does unconditionally.
+      writeUpdateCache({
+        current: "3.7.14",
+        latest: "3.7.15",
+        checked_at: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(), // 30 days old
+        source: "cache",
+        error: null,
+      }, { path: cachePath });
+      let fetchCalls = 0;
+      const check = await doctorUpdateCheck({
+        cwd: dir,
+        current: "3.7.14",
+        cachePath,
+        fetchImpl: async () => {
+          fetchCalls += 1;
+          return new Response(JSON.stringify({ version: "3.7.20" }), { status: 200, headers: { "content-type": "application/json" } });
+        },
+      });
+      assert.equal(fetchCalls, 1, "an expired cache must trigger exactly one automatic live check");
+      assert.equal(check.value.latest, "3.7.20", "the fresh value wins, not the 30-day-old one");
+      assert.equal(check.value.cache.fresh, true);
+      assert.equal(check.value.cache.refresh_failed, false);
+    }));
+
+    it("offline-stale-labeled: an expired cache whose live refresh FAILS falls back to the last known-good value, clearly labeled with its age", () => withTemp(async (dir) => {
+      const cachePath = join(dir, "cache.json");
+      const now = Date.parse("2026-08-26T12:00:00.000Z"); // grok's own dogfood date
+      writeUpdateCache({
+        current: "3.7.14",
+        latest: "4.17.5", // the exact stale value grok saw
+        checked_at: "2026-08-01T10:18:20.000Z", // ~25 days old
+        source: "cache",
+        error: null,
+      }, { path: cachePath });
+      const check = await doctorUpdateCheck({
+        cwd: dir,
+        current: "3.7.14",
+        cachePath,
+        now,
+        fetchImpl: async () => { throw new Error("offline"); },
+      });
+      // Faithful: the network is down, but the LAST KNOWN value is not thrown away as a bare null.
+      assert.equal(check.value.latest, "4.17.5", "a failed refresh must not erase the last known-good value");
+      assert.equal(check.value.cache.fresh, false, "honestly reported as stale, not silently presented as current");
+      assert.equal(check.value.cache.refresh_attempted, true);
+      assert.equal(check.value.cache.refresh_failed, true);
+      assert.ok(check.value.cache.age_ms >= 24 * 60 * 60 * 1000, "the reported age reflects the ORIGINAL successful check, not the failed attempt just now");
+      assert.equal(check.status, "warning", "a known-newer version is still worth flagging, even from stale data");
+      assert.match(check.hint, /\d+d old/, "the hint must name the estimate's age");
+      assert.match(check.hint, /live check just failed/);
+
+      // The next run inherits this SAME good value — a failed refresh must
+      // never clobber what was already known on disk either.
+      const onDisk = readUpdateCache({ path: cachePath });
+      assert.equal(onDisk.latest, "4.17.5");
+      assert.equal(onDisk.checked_at, "2026-08-01T10:18:20.000Z");
+      assert.ok(onDisk.error, "the failed attempt is still recorded, just not destructively");
+    }));
+
+    it("no cache at all AND the auto-refresh fails: unknown, not a crash — and it says a live check was attempted", () => withTemp(async (dir) => {
+      const check = await doctorUpdateCheck({
+        cwd: dir,
+        current: "3.7.14",
+        cachePath: join(dir, "missing.json"),
+        fetchImpl: async () => { throw new Error("offline"); },
+      });
+      assert.equal(check.status, "unknown");
+      assert.equal(check.value.cache.refresh_attempted, true);
+      assert.equal(check.value.cache.refresh_failed, true);
+    }));
+
+    it("--refresh forces a live check even when the cache is still well within the TTL", () => withTemp(async (dir) => {
+      const cachePath = join(dir, "cache.json");
+      const now = Date.parse("2026-08-01T12:00:00.000Z");
+      writeUpdateCache({
+        current: "3.7.14",
+        latest: "3.7.15",
+        checked_at: new Date(now - 60 * 1000).toISOString(), // 1 minute old — as fresh as it gets
+        source: "cache",
+        error: null,
+      }, { path: cachePath });
+      let fetchCalls = 0;
+      const check = await doctorUpdateCheck({
+        cwd: dir,
+        current: "3.7.14",
+        cachePath,
+        now,
+        refresh: true,
+        fetchImpl: async () => {
+          fetchCalls += 1;
+          return new Response(JSON.stringify({ version: "3.7.21" }), { status: 200, headers: { "content-type": "application/json" } });
+        },
+      });
+      assert.equal(fetchCalls, 1, "--refresh must check live regardless of freshness");
+      assert.equal(check.value.latest, "3.7.21");
+    }));
+  });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "4.38.2",
+  "version": "4.39.0",
   "description": "CLI for Run402 — full-stack backend infrastructure for AI agents: Postgres, auth, storage, serverless functions and atomic deploys. Paid with x402/MPP. Includes $0.03 image generation.",
   "type": "module",
   "bin": {