link-cache 0.4.0 → 0.5.0

package/README.md

@@ -4,38 +4,41 @@ Zero-dependency helper CLIs for **cached** link checking with [Lychee][], for
 any static site that builds to a `public/` directory (Docsy, Hugo, and others).
 Two tools:
 
-- **`lychee-norm-cache`** — run lychee over your built `public/` output, keeping
+- **`lychee-norm-cache`**: run lychee over your built `public/` output, keeping
   the committed `link-cache.jsonc` cache and lychee's derived `.lycheecache` in
   sync.
-- **`link-cache`** — inspect and prune the cache: list the oldest entries, prune
-  a count or percentage (optionally scoped by URL regex), or print a summary
-  (status, provenance, ages). (`refcache` is a deprecated alias.)
+- **`link-cache`**: inspect and prune the cache. List the oldest entries, prune
+  a count or percentage (optionally scoped by URL regex; `manual` entries are
+  exempt, and those with an `expires` date retire then), print a summary
+  (result, provenance, ages), or run the staleness guard (`--max-age`).
+  (`refcache` is a deprecated alias.)
 
 With a committed `lychee.toml` and `link-cache.jsonc`, these give a site a
 self-contained, cached link-checking setup: fast reruns, and diffs that reflect
-real changes — link statuses, and check recency for freshly re-verified entries.
+real changes (link statuses, and check recency for freshly re-verified entries).
 
 ## The owned cache: `link-cache.jsonc`
 
-The committed source of truth is `link-cache.jsonc` — a JSONC file,
+The committed source of truth is `link-cache.jsonc`: a JSONC file,
 pretty-printed by construction in Prettier's style (so `prettier --check` passes
 it untouched), one multi-line object per URL, sorted, with `//` comments allowed
 on their own lines. Each comment attaches to the entry below it and survives
-rewrites for as long as the entry's status holds; a status change replaces the
-entry and retires its comments (a stale rationale is worse than none). The
-multi-line shape is deliberate: field-per-line entries keep concurrent updates
-merging cleanly under git's normal 3-way merge.
+re-confirmations and recorded failures (the rationale still explains the URL);
+an entry replaced by a different live HTTP result drops its comments (a stale
+rationale is worse than none). The multi-line shape is deliberate:
+field-per-line entries keep concurrent updates merging cleanly under git's
+normal 3-way merge.
 
 ```jsonc
 {
   "https://example.com/": {
-    "status": 200,
+    "result": 200,
     "when": "2026-08-29T20:06:38Z",
     "via": "lychee",
   },
   // Seeded pending my-org/repo#123; the target lands with that merge.
   "https://example.com/future-page/": {
-    "status": 200,
+    "result": 200,
     "when": "2026-08-29T20:06:38Z",
     "via": "manual",
     "expires": "2026-09-30",
@@ -45,51 +48,109 @@ merging cleanly under git's normal 3-way merge.
 
 Each entry records:
 
-- **`status`** — generalized: positive values are HTTP statuses; `0` is
-  unchecked; negative values are tool-specific errors (`-10` timeout, `-20`
-  network/DNS, `-30` certificate, `-40` generic client error).
-- **`when`** — the moment the status was established, as RFC3339 UTC at whole
+- **`result`**: an HTTP status int (`200`, `206`, …), or a failure word from
+  lychee's own tag vocabulary (`"error"`, `"timeout"`). Only 2xx results serve
+  as lychee cache hits; failure words and non-2xx results live in the owned file
+  only. (0.4.x files spelled this field `status` with negative error codes;
+  they're read compatibly and rewritten to `result` on the first run.)
+- **`when`**: the moment the result was established, as RFC3339 UTC at whole
   seconds (`YYYY-MM-DDTHH:MM:SSZ`), converting exactly to and from lychee's
-  epoch-seconds cache timestamps. The form is strict — no fractional seconds, no
-  offsets — so timestamps are byte-comparable and lexicographically
+  epoch-seconds cache timestamps. The form is strict (no fractional seconds, no
+  offsets), so timestamps are byte-comparable and lexicographically
   chronological.
-- **`via`** — the resolver that set the status: `lychee`, `manual`
+- **`via`**: the resolver that set the result, one of `lychee`, `manual`
   (hand-seeded), or a named specialized resolver (e.g. a browser-grade probe).
-- **`expires`** (optional, `manual` entries) — `YYYY-MM-DD`. Until then the
-  entry is trusted (never re-checked, overriding lychee's `max_cache_age`);
-  after that, it's re-checked live and replaced by the verified result.
+  Key hand-seeded entries by the URL exactly as lychee prints it: lowercase
+  host, no default port, resolved dot segments, and a `/` path on bare hosts
+  (`https://example.com/`, never `https://example.com`). Results merge back by
+  byte-for-byte key comparison, so a non-canonical spelling never matches its
+  re-check.
+- **`expires`** (optional, `manual` entries): `YYYY-MM-DD`. Until then the entry
+  is trusted; after that, a `--check-stale` run re-checks it live and replaces
+  it with the verified result. Seed **2xx results only**: a seed's job is to
+  vouch that a URL is good so it isn't re-checked, and only 2xx results serve as
+  cache hits, so a non-2xx seed is re-checked every run, fails it, and is
+  replaced by the live result. For URLs whose expected status is non-2xx, use
+  `exclude` or `accept` instead.
 
 Lychee's own CSV cache, `.lycheecache`, is **derived**: `lychee-norm-cache`
 projects the owned cache into it before each run and folds lychee's results back
 afterwards. Gitignore `.lycheecache`; commit `link-cache.jsonc`. A re-check that
-changes an entry's status replaces the entry (provenance moves to `lychee`); a
+changes an entry's result replaces the entry (provenance moves to `lychee`); a
 re-confirmation leaves provenance-bearing entries (`manual`, named resolvers)
-untouched, while `lychee`-owned entries refresh their `when` to record recency.
-A URL the run itself reports as failing is recorded as a negative tool-error
-status; an entry that merely goes missing from lychee's CSV is left untouched
+untouched, while a live re-check of a `lychee`-owned entry refreshes its `when`
+to record recency (a default-mode cache hit is not a re-check and leaves `when`
+untouched). A URL the run itself reports as failing is recorded with its failure
+word; an entry that merely goes missing from lychee's CSV is left untouched
 (cache-status excludes, cache aging, and site changes all remove entries from
-healthy runs).
+healthy runs). Failure evidence counts only on a dead-links exit, and new
+failure entries mint for http(s) URLs only; for the rationale, see `mergeBack`'s
+contract in `lib/cache.mjs`.
+
+## Two modes: PR checks vs. cache refresh
+
+`lychee-norm-cache` applies staleness checks only on request:
+
+- **Default (PR checks)**: every cached 2xx result is projected into lychee's
+  CSV with a fresh timestamp, so lychee's `max_cache_age` never triggers and
+  expired manual seeds aren't re-checked. A run verifies only URLs without a
+  cached 2xx result, that is, URLs new to the cache plus recorded failures and
+  non-2xx results (lychee's cache loader accepts success codes only, so those
+  never serve as hits and re-check on every run). Entries still age for real
+  (their `when` timestamps are untouched in the owned file); the default just
+  doesn't act on the age.
+- **`--check-stale` (cache refresh)**: real timestamps are projected and
+  lychee's `max_cache_age` and manual `expires` dates apply, so stale and
+  expired entries are re-verified. Use this mode in a scheduled cache-refresh
+  job. In steady state, `link-cache --prune` and `--check-stale` runs are what
+  drive re-checks.
+
+Because a default run never re-checks cached 2xx results, a stopped refresh job
+lets the cache age silently. Guard against that with the staleness guard:
+
+```sh
+link-cache --max-age 60   # exit 3 when the oldest refreshable entry is >60 days old
+```
+
+Under a healthy `--check-stale` schedule the oldest entries legitimately age up
+to `max_cache_age` plus one refresh interval before their re-check lands, so set
+the threshold **at or above that sum** (a lower threshold fails on healthy
+caches); a prune-driven rotation sizes the threshold to its full prune cycle
+instead. Run the guard where its failure gets seen (the refresh job itself, or
+another scheduled check). The guard ages lychee-owned entries by their check
+time, and expired manual seeds by their `expires` date; unexpired seeds and
+named-resolver entries are exempt (their lifecycle is owned elsewhere). It also
+fails on evidence it can't trust: malformed cache lines, or a future-dated
+timestamp anywhere among the aged entries.
 
 Without a `link-cache.jsonc`, `lychee-norm-cache` falls back to the legacy mode:
-normalize the committed `.lycheecache` in place. To migrate:
+normalize the committed `.lycheecache` in place. To import an existing CSV
+cache:
 
 ```sh
-npm run check:links -- --migrate   # .lycheecache -> link-cache.jsonc
+npm run check:links -- --import   # .lycheecache -> link-cache.jsonc
 ```
 
 then commit `link-cache.jsonc` and gitignore `.lycheecache`. If the CSV cache
 carried a `merge=union` gitattribute, drop it rather than moving it over: union
 merging proved ineffective in practice, and on a multi-line file it can
 interleave entries into invalid JSON. The owned cache merges with git's normal
-3-way merge; on a conflict, resolve either way and rerun the check — the next
-run re-normalizes the file.
+3-way merge; on a conflict, resolve either way and rerun the check; the next run
+re-normalizes the file.
+
+In your `lychee.toml`, prefer URL-scoped mechanisms (`exclude` patterns, or
+manual seeds in the owned cache) for URL-specific problems, and reserve lychee's
+`accept` list for statuses that are acceptable **site-wide**: an accepted status
+is recorded in the committed cache for every URL that returns it. Note that
+`accept` buys no caching: only 2xx results serve as cache hits, so an accepted
+non-2xx URL is re-checked on every run.
 
 ## Exit codes (`lychee-norm-cache`)
 
-- `0` — success.
-- `1` — dead links: the check ran and found failures.
-- `2` — preflight or sanity failure: lychee or `public/` missing, lychee config
-  error, or **zero links checked** (an empty or fully-excluded `public/` is a
+- `0`: success.
+- `1`: dead links (the check ran and found failures).
+- `2`: preflight or sanity failure (lychee or `public/` missing, lychee config
+  error, or **zero links checked**; an empty or fully-excluded `public/` is a
   false-clean, not a pass).
 
 Warn-style wrappers can soften exit 1 (advisory link rot) while still failing
@@ -101,8 +162,9 @@ hard on exit 2 (the check didn't actually run).
 - A `lychee.toml` at your site root (lychee's config and ignore rules).
 - A built site under `public/` (run your site build first).
 - [Node.js][] ≥ 24.
-- Optional: the [`gh`][gh] CLI — `lychee-norm-cache` bridges its token to lychee
-  to raise the github.com rate limit when `GITHUB_TOKEN` isn't already set.
+- Optional: the [`gh`][gh] CLI, whose token `lychee-norm-cache` bridges to
+  lychee to raise the github.com rate limit when `GITHUB_TOKEN` isn't already
+  set.
 
 ## Install
 
@@ -113,14 +175,14 @@ npm install --save-dev link-cache
 Or, to install from GitHub rather than the npm registry:
 
 ```sh
-npm install --save-dev github:chalin/link-cache#semver:^0.4.0
+npm install --save-dev github:chalin/link-cache#semver:^0.5.0
 ```
 
 This puts both bins on your project's `PATH`.
 
 ## Usage
 
-Wire the bins into your `package.json` scripts (bare names — `npm run` puts
+Wire the bins into your `package.json` scripts, using bare names (`npm run` puts
 `node_modules/.bin` on the `PATH`):
 
 ```json
@@ -131,9 +193,11 @@ Wire the bins into your `package.json` scripts (bare names — `npm run` puts
 ```
 
 ```sh
-npm run check:links              # sync caches, run lychee, fold results back
-npm run link-cache -- --summary  # cache stats (count, oldest, status, via, ages)
+npm run check:links              # verify URLs not yet in the cache
+npm run check:links -- --check-stale  # also re-verify stale/expired entries
+npm run link-cache -- --summary  # cache stats (count, oldest, result, via, ages)
 npm run link-cache -- --match 'github\.com' --prune 10  # trim 10 oldest matching
+npm run link-cache -- --max-age 60  # staleness guard (exit 3 when breached)
 ```
 
 > [!WARNING]
@@ -141,13 +205,15 @@ npm run link-cache -- --match 'github\.com' --prune 10  # trim 10 oldest matchin
 > Don't invoke these bins via `npx`: on a stale or missing `node_modules`, `npx`
 > falls back to the public registry and runs **whatever package holds the bin's
 > name there** (the `lychee-norm-cache` name is squatted). Bare bin names in
-> `npm run` scripts resolve locally or fail loudly — they never touch the
+> `npm run` scripts resolve locally or fail loudly; they never touch the
 > registry.
 
 `lychee-norm-cache` runs in the current directory (your site root) and forwards
 any extra arguments to lychee. Run either tool with `--help` for its full
 options, and `lychee --help` for the link-checking flags `lychee-norm-cache`
-forwards (e.g. `--offline`, `--max-cache-age 0`).
+forwards (e.g. `--offline`). To force re-checks, use `--check-stale`; the
+default mode rejects a forwarded `--max-cache-age`, whose file-age check would
+silently defeat the fresh-timestamp projection.
 
 ## Development
 

package/check/index.mjs

@@ -11,13 +11,21 @@
 // or public/ missing, zero links checked, lychee config error).
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import {
+  existsSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import {
   CSV_FILE,
   OWNED_FILE,
+  RESULT_ERROR,
+  RESULT_TIMEOUT,
   mergeBack,
   migrateCsvText,
   parseCsv,
@@ -34,7 +42,7 @@ export const EXIT_OK = 0;
 export const EXIT_DEAD_LINKS = 1;
 export const EXIT_PREFLIGHT = 2;
 
-const USAGE = `Usage: lychee-norm-cache [--migrate] [lychee args...]
+const USAGE = `Usage: lychee-norm-cache [--check-stale] [--import] [lychee args...]
 
 Run lychee over this site's built ./public output. With a committed
 ${OWNED_FILE}, the ${CSV_FILE} handed to lychee is derived from it before the
@@ -42,8 +50,16 @@ run and folded back into it afterwards; otherwise ${CSV_FILE} is normalized in
 place (legacy mode). Bridges a GitHub token from the gh CLI when GITHUB_TOKEN
 isn't set; extra arguments pass through to lychee.
 
-  --migrate    convert an existing ${CSV_FILE} to ${OWNED_FILE} and exit
-  -h, --help   show this help
+By default staleness checks are not applied: cached 2xx results project with
+fresh timestamps, so a run verifies only URLs without a cached 2xx result
+(failure words and non-2xx results never serve as cache hits and re-check on
+every run). With --check-stale, real timestamps project, so lychee's
+max_cache_age and manual expires dates apply and stale entries are re-verified
+(the scheduled cache-refresh job's mode).
+
+  --check-stale  apply staleness checks (re-verify stale and expired entries)
+  --import       convert an existing ${CSV_FILE} to ${OWNED_FILE} and exit
+  -h, --help     show this help
 
 Exit codes: 0 success; 1 dead links; 2 preflight/sanity failure (missing
 lychee or public/, lychee config or usage errors, zero links verified).
@@ -92,10 +108,19 @@ export function publicDirOf(cwd) {
   return publicDir;
 }
 
+// lychee colors its output when CLICOLOR_FORCE is set (even onto the piped
+// stdout we capture, since the spawn env passes process.env through), and SGR
+// codes around the tags defeat the line parsers (captured live from 0.24.2),
+// so failures would vanish silently. Strip before parsing.
+function stripAnsi(s) {
+  return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
 // Check counts from lychee's stdout summary — the human line ("🔍 2 Total …
 // ✅ 1 OK 🚫 0 Errors …") or --format json fields; null when neither is
 // present. A parsed summary is the proof that a check actually completed.
 export function parseSummary(stdout) {
+  stdout = stripAnsi(stdout);
   const m = /(\d+)\s+Total\b[\s\S]*?(\d+)\s+OK\b[\s\S]*?(\d+)\s+Errors?\b/.exec(
     stdout,
   );
@@ -120,20 +145,47 @@ export function mapLycheeExit(code, summary) {
   return EXIT_PREFLIGHT;
 }
 
-// URLs the run itself reported as failing — the human "[ERROR] URL …" lines,
-// or --format json's fail_map. Positive per-URL evidence for the merge-back's
-// failure recording; CSV absence alone proves nothing (cache_exclude_status,
-// max_cache_age, and site changes all remove entries from healthy runs).
+// URLs the run itself reported as failing, mapped to a failure word from
+// lychee's own tag vocabulary ("error" or "timeout"): the human per-URL
+// lines, or --format json's failure maps. Positive per-URL evidence for the
+// merge-back's failure recording (CSV absence alone proves nothing:
+// merge-back rules, lib/cache.mjs).
+//
+// Line shapes (lychee 0.24, verified against live output and Status::
+// code_as_string in its source): failures carry the word tags ERROR or
+// TIMEOUT, or a numeric status tag with a failure remark ("[403] URL … |
+// Rejected status code: 403 Forbidden", "[404] URL | Error (cached)").
+// Numeric tags alone are not failures: -vv prints accepted URLs the same way
+// ("[200] URL (at 1:1)", "[200] URL | OK (cached)"). Word tags are
+// whitelisted, not blacklisted: the others (EXCLUDED; IGNORED, unsupported
+// URLs printed on green runs; UNKNOWN, mail outside lychee's is_error) are
+// non-failures, as are lychee's log-level lines ([INFO], [WARN], …), and a
+// recorded failure becomes a committed cache entry (merge-back rules again),
+// making a false positive costlier than a false negative. For the same reason
+// the URL token must look like a URL: absolute with scheme:// or mailto:
+// (the one scheme://-less form lychee checks).
+const FAILURE_TAGS = new Set(['ERROR', 'TIMEOUT']);
+const URL_SHAPE = /^(\w[\w+.-]*:\/\/|mailto:)/;
 export function parseFailedUrls(stdout) {
-  const failed = new Set();
+  stdout = stripAnsi(stdout);
+  const failed = new Map();
   const trimmed = stdout.trim();
   if (trimmed.startsWith('{')) {
+    // --format json, possibly with a trailing human "Hint:" line after the
+    // document. Failures live in error_map/timeout_map (0.24's shape);
+    // fail_map covers older lychee.
     try {
-      const failMap = JSON.parse(trimmed).fail_map ?? {};
-      for (const failures of Object.values(failMap)) {
-        for (const f of failures) {
-          const url = typeof f.url === 'string' ? f.url : f.url?.url;
-          if (url) failed.add(url);
+      const json = JSON.parse(trimmed.slice(0, trimmed.lastIndexOf('}') + 1));
+      for (const [map, word] of [
+        [json.fail_map, RESULT_ERROR],
+        [json.error_map, RESULT_ERROR],
+        [json.timeout_map, RESULT_TIMEOUT],
+      ]) {
+        for (const failures of Object.values(map ?? {})) {
+          for (const f of failures) {
+            const url = typeof f.url === 'string' ? f.url : f.url?.url;
+            if (url) failed.set(url, word);
+          }
         }
       }
       return failed;
@@ -141,8 +193,24 @@ export function parseFailedUrls(stdout) {
       // fall through to the line scan
     }
   }
-  for (const m of stdout.matchAll(/^\s*\[ERROR\]\s+(\S+)/gm)) {
-    failed.add(m[1]);
+  for (const m of stdout.matchAll(/^\s*\[(\w+)\]\s+(\S+)(.*)$/gm)) {
+    const [, tag, url, rest] = m;
+    if (!URL_SHAPE.test(url)) continue;
+    if (/^\d+$/.test(tag)) {
+      if (
+        /\|\s*(Rejected|Failed|Error \(cached\)|Request timed out)/.test(rest)
+      ) {
+        failed.set(
+          url,
+          /Request timed out/.test(rest) ? RESULT_TIMEOUT : RESULT_ERROR,
+        );
+      }
+    } else if (FAILURE_TAGS.has(tag.toUpperCase())) {
+      failed.set(
+        url,
+        tag.toUpperCase() === 'TIMEOUT' ? RESULT_TIMEOUT : RESULT_ERROR,
+      );
+    }
   }
   return failed;
 }
@@ -163,12 +231,12 @@ function fail(message) {
   return EXIT_PREFLIGHT;
 }
 
-function migrate(cwd) {
+function importCsv(cwd) {
   const csvPath = path.join(cwd, CSV_FILE);
   const ownedPath = path.join(cwd, OWNED_FILE);
   if (existsSync(ownedPath)) return fail(`${OWNED_FILE} already exists.`);
   if (!existsSync(csvPath)) return fail(`${CSV_FILE} not found.`);
-  const { text, count, malformed } = migrateCsvText(
+  const { text, count, malformed, conflicting, unmappable } = migrateCsvText(
     readFileSync(csvPath, 'utf8'),
   );
   // Migration is specified lossless: refuse rather than silently drop.
@@ -177,9 +245,19 @@ function migrate(cwd) {
       `${CSV_FILE} has ${malformed} malformed line(s); fix or remove them, then rerun.`,
     );
   }
+  if (conflicting) {
+    return fail(
+      `${CSV_FILE} has ${conflicting} URL(s) with conflicting duplicate rows; fix or remove them, then rerun.`,
+    );
+  }
+  if (unmappable) {
+    return fail(
+      `${CSV_FILE} has ${unmappable} entr${unmappable === 1 ? 'y' : 'ies'} with an unmappable status or timestamp; fix or remove them, then rerun.`,
+    );
+  }
   writeFileAtomic(ownedPath, text);
   console.log(
-    `Migrated ${count} entries to ${OWNED_FILE}. Commit it and gitignore ${CSV_FILE}.`,
+    `Imported ${count} ${count === 1 ? 'entry' : 'entries'} to ${OWNED_FILE}. Commit it and gitignore ${CSV_FILE}.`,
   );
   return EXIT_OK;
 }
@@ -191,7 +269,11 @@ function main(argv) {
   }
 
   const cwd = process.cwd();
-  if (argv.includes('--migrate')) return migrate(cwd);
+  if (argv.includes('--import')) return importCsv(cwd);
+
+  // Wrapper-owned flag: consumed here, never forwarded to lychee.
+  const checkStale = argv.includes('--check-stale');
+  argv = argv.filter((a) => a !== '--check-stale');
 
   if (!hasLychee()) {
     return fail(`lychee not found. Install: ${INSTALL_HINT}`);
@@ -217,14 +299,28 @@ function main(argv) {
   if (owned && argv.includes('--cache=false')) {
     return fail(`--cache=false is incompatible with ${OWNED_FILE}.`);
   }
+  // A forwarded cache-age flag is either inert (the fresh-timestamp
+  // projection defeats any realistic value) or, near zero, discards the
+  // just-written cache wholesale via lychee's file-age check; either way it
+  // contradicts the flag's intent, and --check-stale is the sanctioned
+  // re-check path.
+  const hasCacheAgeFlag = argv.some(
+    (a) => a === '--max-cache-age' || a.startsWith('--max-cache-age='),
+  );
+  if (owned && !checkStale && hasCacheAgeFlag) {
+    return fail(
+      '--max-cache-age has no effect on cached entries in the default mode; use --check-stale to re-verify stale entries.',
+    );
+  }
   const cacheArgs = hasCacheFlag ? [] : ['--cache'];
 
-  // Derive the CSV lychee will read from the owned cache.
+  // Derive the CSV lychee will read from the owned cache; keep the projected
+  // timestamps so merge-back can tell echoed cache hits from real re-checks.
+  let projectedTs = new Map();
   if (owned) {
-    writeFileAtomic(
-      cachePath,
-      serializeCsv(projectToCsv(owned.entries, { now })),
-    );
+    const projected = projectToCsv(owned.entries, { now, checkStale });
+    projectedTs = new Map(projected.map((e) => [e.url, e.ts]));
+    writeFileAtomic(cachePath, serializeCsv(projected));
   }
 
   const token = resolveToken();
@@ -250,16 +346,26 @@ function main(argv) {
     },
   );
   if (run.stdout) process.stdout.write(run.stdout);
+
+  // A failed or verdict-free run never folds; remove the derived CSV rather
+  // than leave it behind (the projection's fresh timestamps are a lie about
+  // recency once no completed run consumed them).
+  const bail = (message) => {
+    if (owned) rmSync(cachePath, { force: true });
+    return fail(message);
+  };
+
   if (run.error) {
-    return fail(`lychee failed to run: ${run.error.message}`);
+    return bail(`lychee failed to run: ${run.error.message}`);
   }
   const summary = parseSummary(run.stdout ?? '');
   const status = mapLycheeExit(run.status ?? 1, summary);
 
-  // On a preflight failure lychee produced no trustworthy results: leave both
-  // caches untouched (folding would mislabel unprojected entries as failed).
+  // On a preflight failure lychee produced no trustworthy results: leave the
+  // owned cache untouched (folding would mislabel unprojected entries as
+  // failed).
   if (status === EXIT_PREFLIGHT) {
-    return fail('lychee did not complete a check; caches left untouched.');
+    return bail('lychee did not complete a check; owned cache left untouched.');
   }
 
   // A clean run in which nothing got a verdict is a false-clean (empty or
@@ -267,7 +373,7 @@ function main(argv) {
   // unattempted entries as failed, so the check precedes the fold. Cache hits
   // count toward OK in lychee's summary, so a fully-cached run passes.
   if (status === EXIT_OK && summary && summary.ok + summary.errors === 0) {
-    return fail('lychee verified 0 links: empty or fully-excluded public/?');
+    return bail('lychee verified 0 links: empty or fully-excluded public/?');
   }
 
   // Fold the post-run CSV back into the owned cache (also on dead links, so a
@@ -277,10 +383,19 @@ function main(argv) {
     const csvEntries = existsSync(cachePath)
       ? parseCsv(readFileSync(cachePath, 'utf8')).entries
       : [];
-    const failedUrls = parseFailedUrls(run.stdout ?? '');
+    // Failure evidence counts only on a dead-links exit: a green run means
+    // lychee accepted everything it printed (--accept-timeouts runs print
+    // "[TIMEOUT] URL …" lines while exiting 0), so recording those would mint
+    // and churn failure entries on every clean run.
+    const failedUrls =
+      status === EXIT_DEAD_LINKS
+        ? parseFailedUrls(run.stdout ?? '')
+        : new Map();
     writeFileAtomic(
       ownedPath,
-      serializeOwned(mergeBack(owned, csvEntries, { now, failedUrls })),
+      serializeOwned(
+        mergeBack(owned, csvEntries, { now, failedUrls, projectedTs }),
+      ),
     );
     writeFileAtomic(cachePath, sortCacheText(readFileSync(cachePath, 'utf8')));
   } else if (existsSync(cachePath)) {

package/lib/cache.mjs

@@ -10,10 +10,14 @@
 // raw URL byte order (matching LC_ALL=C). Stripping comments and trailing
 // commas yields valid JSON.
 //
-// Entry schema: { "status": INT, "when": RFC3339_UTC, "via": "RESOLVER" }
-// with an optional "expires": "YYYY-MM-DD" (manual entries). Status
-// generalizes HTTP: positive = HTTP status, 0 = unchecked, negative =
-// tool-specific error. `when` is the canonical whole-second UTC form
+// Entry schema: { "result": INT|WORD, "when": RFC3339_UTC, "via": "RESOLVER" }
+// with an optional "expires": "YYYY-MM-DD" (manual entries). `result` is
+// heterogeneous: an HTTP status int (100-999, the only values that project
+// into Lychee's CSV), or a failure word from lychee's own tag vocabulary
+// ("error", "timeout"). Legacy 0.4.x files spell the field "status" with
+// negative tool-error codes; parseOwned accepts that on read and maps it, so
+// caches self-migrate on the first rewrite (read-old-write-new, one version).
+// `when` is the canonical whole-second UTC form
 // (YYYY-MM-DDTHH:MM:SSZ) — no fractional seconds, no offsets — validated
 // strictly: this tool is the file's only writer, so a non-canonical value is
 // a bug to surface, not smooth over (lesson from the htmltest-era
@@ -22,11 +26,18 @@
 export const OWNED_FILE = 'link-cache.jsonc';
 export const CSV_FILE = '.lycheecache';
 
-// Tool-specific error statuses (the htmltest-fork convention).
-export const STATUS_TIMEOUT = -10;
-export const STATUS_NETWORK_ERROR = -20;
-export const STATUS_CERT_ERROR = -30;
-export const STATUS_CLIENT_ERROR = -40;
+// Failure words (lychee's tag vocabulary, lowercased).
+export const RESULT_ERROR = 'error';
+export const RESULT_TIMEOUT = 'timeout';
+const FAILURE_WORDS = new Set([RESULT_ERROR, RESULT_TIMEOUT]);
+
+// Legacy 0.4.x numeric tool-error codes -> failure words (read-side only).
+const LEGACY_STATUS_WORDS = new Map([
+  [-10, RESULT_TIMEOUT],
+  [-20, RESULT_ERROR],
+  [-30, RESULT_ERROR],
+  [-40, RESULT_ERROR],
+]);
 
 const WHEN_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
 
@@ -49,11 +60,16 @@ const byUrlBytes = (a, b) =>
 
 // --- CSV (.lycheecache) ------------------------------------------------------
 
-// Unquote a CSV field: lychee quotes URLs that contain a comma.
+// Unquote a CSV field: lychee quotes URLs that contain a comma or a quote.
+// Null when the quote grammar is violated: an unquoted field may not contain
+// quotes, and a quoted field's interior quotes must be doubled.
 export function csvUnquote(field) {
-  return field.startsWith('"') && field.endsWith('"')
-    ? field.slice(1, -1).replace(/""/g, '"')
-    : field;
+  if (field.startsWith('"') && field.endsWith('"') && field.length >= 2) {
+    const inner = field.slice(1, -1);
+    if (inner.replace(/""/g, '').includes('"')) return null;
+    return inner.replace(/""/g, '"');
+  }
+  return field.includes('"') ? null : field;
 }
 
 export function csvQuote(url) {
@@ -62,7 +78,8 @@ export function csvQuote(url) {
 
 // Parse one URL,STATUS,TIMESTAMP line; null when malformed. Lexically strict:
 // STATUS and TIMESTAMP must be non-empty digit runs (`Number('')` is 0, which
-// would silently coin status-0/epoch-0 entries from truncated lines).
+// would silently coin status-0/epoch-0 entries from truncated lines), and the
+// URL field must satisfy the CSV quote grammar (csvUnquote).
 export function parseCsvLine(raw) {
   const lastComma = raw.lastIndexOf(',');
   if (lastComma < 0) return null;
@@ -73,12 +90,15 @@ export function parseCsvLine(raw) {
   const statusField = head.slice(statusComma + 1).trim();
   if (!/^\d+$/.test(tsField) || !/^-?\d+$/.test(statusField)) return null;
   const url = csvUnquote(head.slice(0, statusComma));
-  if (url === '') return null;
+  if (url === null || url === '') return null;
   return { url, status: Number(statusField), ts: Number(tsField) };
 }
 
 // Parse a whole CSV cache; malformed lines are counted, duplicates keep the
-// newest timestamp.
+// newest timestamp. Ambiguity is order-independent: a newer row resolves an
+// older equal-ts status conflict, and only ties among the final (newest)
+// winners count as conflicting: both such rows are dropped so a one-shot
+// consumer (import) can refuse.
 export function parseCsv(text) {
   const byUrl = new Map();
   let malformed = 0;
@@ -90,9 +110,22 @@ export function parseCsv(text) {
       continue;
     }
     const prior = byUrl.get(entry.url);
-    if (!prior || entry.ts >= prior.ts) byUrl.set(entry.url, entry);
+    if (!prior || entry.ts > prior.entry.ts) {
+      byUrl.set(entry.url, { entry, conflicted: false });
+    } else if (
+      entry.ts === prior.entry.ts &&
+      entry.status !== prior.entry.status
+    ) {
+      prior.conflicted = true;
+    }
+  }
+  const entries = [];
+  let conflicting = 0;
+  for (const { entry, conflicted } of byUrl.values()) {
+    if (conflicted) conflicting += 1;
+    else entries.push(entry);
   }
-  return { entries: [...byUrl.values()].sort(byUrlBytes), malformed };
+  return { entries: entries.sort(byUrlBytes), malformed, conflicting };
 }
 
 export function serializeCsv(entries) {
@@ -128,7 +161,7 @@ function stripTrailingCommas(lines) {
   return out;
 }
 
-const ENTRY_FIELDS = new Set(['status', 'when', 'via', 'expires']);
+const ENTRY_FIELDS = new Set(['result', 'when', 'via', 'expires']);
 
 // A calendar-real YYYY-MM-DD (round-trip check rejects e.g. Feb 30).
 function isCanonicalDate(s) {
@@ -137,26 +170,43 @@ function isCanonicalDate(s) {
   return Number.isFinite(t) && new Date(t).toISOString().slice(0, 10) === s;
 }
 
-// Rejects unknown fields (a rewrite would silently drop them) and restricts
-// `expires` to manual entries — resolvers set statuses, owners set trust
-// windows. Relax the via restriction if a named resolver ever needs expiry.
-// Statuses live in one of three domains: HTTP (100-999, the only ones that
-// project into Lychee's CSV — Lychee rejects codes outside that range at
-// load, which would wedge the run), 0 (unchecked), negative (tool errors).
-function isValidStatus(s) {
-  return Number.isInteger(s) && (s < 0 || s === 0 || (s >= 100 && s <= 999));
+// A result is an HTTP status (100-999, the only values that project into
+// Lychee's CSV, which rejects codes outside that range at load) or a known
+// failure word.
+function isValidResult(r) {
+  return typeof r === 'string'
+    ? FAILURE_WORDS.has(r)
+    : Number.isInteger(r) && r >= 100 && r <= 999;
 }
 
+// A legacy `status` field is accepted on read and mapped to `result` (never
+// both): the 0.4.x negative codes become failure words; status 0 (unchecked,
+// never tool-written) has no successor by design and fails validation as
+// malformed.
+function migrateLegacyStatus(v) {
+  if (!('status' in v) || 'result' in v) return v;
+  const { status, ...rest } = v;
+  const result =
+    Number.isInteger(status) && status < 0
+      ? LEGACY_STATUS_WORDS.get(status)
+      : status;
+  return isValidResult(result) ? { ...rest, result } : v;
+}
+
+// Rejects unknown fields (a rewrite would silently drop them) and restricts
+// `expires` to manual entries: resolvers set results, owners set trust
+// windows. Relax the via restriction if a named resolver ever needs expiry.
 function validateEntry(url, v) {
   return (
     v !== null &&
     typeof v === 'object' &&
     Object.keys(v).every((k) => ENTRY_FIELDS.has(k)) &&
-    isValidStatus(v.status) &&
+    isValidResult(v.result) &&
     typeof v.when === 'string' &&
     Number.isFinite(whenToTs(v.when)) &&
     whenToTs(v.when) >= 0 && // pre-epoch would project a negative CSV ts
     typeof v.via === 'string' &&
+    v.via !== '' &&
     (v.expires === undefined ||
       (v.via === 'manual' && isCanonicalDate(v.expires)))
   );
@@ -217,13 +267,14 @@ export function parseOwned(text) {
   }
 
   const entries = [];
-  for (const [url, v] of Object.entries(obj)) {
+  for (const [url, raw] of Object.entries(obj)) {
+    const v = migrateLegacyStatus(raw);
     if (!validateEntry(url, v)) {
       throw new Error(`${OWNED_FILE}: malformed entry for ${url}`);
     }
     entries.push({
       url,
-      status: v.status,
+      result: v.result,
       ts: whenToTs(v.when), // epoch internally; `when` re-derives on write
       via: v.via,
       expires: v.expires,
@@ -236,9 +287,9 @@ export function parseOwned(text) {
 // Canonical serialization = Prettier's jsonc style (2-space indent, one field
 // per line, trailing commas, always multi-line), so the output is
 // prettier-idempotent by construction.
-export function serializeEntry({ url, status, ts, via, expires }) {
+export function serializeEntry({ url, result, ts, via, expires }) {
   const fields = [
-    `    "status": ${status},`,
+    `    "result": ${JSON.stringify(result)},`,
     `    "when": ${JSON.stringify(tsToWhen(ts))},`,
     `    "via": ${JSON.stringify(via)},`,
   ];
@@ -263,40 +314,68 @@ export function serializeOwned({ entries, trailing = [] }) {
 
 const dateToTs = (isoDate) => Date.parse(`${isoDate}T23:59:59Z`) / 1000;
 
-// Project the owned entries into Lychee's CSV. Only positive (HTTP) statuses
-// project — Lychee never persists errors, and would re-drop the rest. An
-// unexpired entry with `expires` projects with a fresh timestamp so it
-// outlives Lychee's max_cache_age until its own expiry; once expired it is
-// omitted, forcing a live re-check.
-export function projectToCsv(entries, { now = Date.now() / 1000 } = {}) {
+// Project the owned entries into Lychee's CSV. Only 2xx results project:
+// Lychee's cache loader accepts success codes only (verified against 0.24.2,
+// which drops a non-2xx row at load and re-checks the URL live), and it never
+// persists errors, so recorded failures and non-2xx results re-check on every
+// run. By default every projected entry carries a fresh timestamp (staleness
+// checks not applied): lychee's max_cache_age never triggers and expired
+// seeds are not re-checked, so a run verifies only URLs without a cached 2xx
+// result. With `checkStale`, real timestamps project so max_cache_age
+// applies, and manual `expires` governs its entry: unexpired seeds still
+// project fresh (the expiry date, not max_cache_age, owns a seed's lifecycle)
+// while expired ones are omitted, forcing a live re-check.
+export function projectToCsv(
+  entries,
+  { now = Date.now() / 1000, checkStale = false } = {},
+) {
+  const fresh = Math.floor(now);
   const projected = [];
   for (const e of entries) {
-    if (e.status <= 0) continue;
+    if (typeof e.result !== 'number' || e.result < 200 || e.result > 299) {
+      continue;
+    }
+    if (!checkStale) {
+      projected.push({ url: e.url, status: e.result, ts: fresh });
+      continue;
+    }
     if (e.expires !== undefined) {
       const cutoff = dateToTs(e.expires);
       if (!Number.isFinite(cutoff) || now > cutoff) continue;
-      projected.push({ url: e.url, status: e.status, ts: Math.floor(now) });
+      projected.push({ url: e.url, status: e.result, ts: fresh });
       continue;
     }
-    projected.push({ url: e.url, status: e.status, ts: e.ts });
+    projected.push({ url: e.url, status: e.result, ts: e.ts });
   }
   return projected;
 }
 
 // --- lens: CSV -> owned merge-back ------------------------------------------
 
-// Fold a post-run CSV back into the owned entries. Rules (owner, 08-31;
-// absence-inference dropped 08-31 adversarial round):
+// Fold a post-run CSV back into the owned entries. Rules:
 //   - new URL: added with via "lychee";
-//   - status changed: the whole entry is replaced (via "lychee", fresh fields,
+//   - result changed: the whole entry is replaced (via "lychee", fresh fields,
 //     comments dropped — a stale rationale is worse than none);
-//   - status equal: provenance-bearing entries (via != "lychee") stay
+//   - result equal: provenance-bearing entries (via != "lychee") stay
 //     untouched — a re-confirmation; "lychee" entries adopt the fresh ts;
-//   - expired `expires` entry present in the CSV: replaced wholesale (the seed
+//   - CSV row that merely echoes the projection (same result, the exact ts we
+//     projected, per `projectedTs`): the entry is untouched. Under the default
+//     fresh-ts projection a cache hit echoes the projected row byte-exactly
+//     (verified against lychee 0.24.2); adopting it would freshen `when` on
+//     every run, erasing the real ages the staleness guard reads, and would
+//     let the `expired` branch overwrite seeds no live check ever touched;
+//   - expired `expires` entry re-checked live: replaced wholesale (the seed
 //     served its purpose);
-//   - URL in `failedUrls` (positive evidence from the run's own error report):
-//     recorded as STATUS_CLIENT_ERROR under via "lychee", keeping the entry's
-//     comments (the rationale still explains the URL);
+//   - URL in `failedUrls` (positive evidence from the run's own error report,
+//     a Map of URL -> failure word): recorded under via "lychee" with that
+//     word as its result: for existing entries (keeping their comments: the
+//     rationale still explains the URL) whatever their scheme, and for URLs
+//     new to the cache when http(s), beating a residual CSV row for the same
+//     URL. Minting is http(s)-only because a failure word never projects, so
+//     it heals only via a later CSV success row, which never comes for
+//     file:// or mailto: (lychee persists only http(s) rows); file:// keys
+//     also embed machine-specific absolute paths. Those failures already fail
+//     the run via the exit code;
 //   - entry missing from the CSV without failure evidence: untouched. CSV
 //     absence is ambiguous — cache_exclude_status, max_cache_age expiry, and
 //     URLs no longer in the site all remove entries from healthy runs — so it
@@ -304,11 +383,30 @@ export function projectToCsv(entries, { now = Date.now() / 1000 } = {}) {
 export function mergeBack(
   owned,
   csvEntries,
-  { now = Date.now() / 1000, failedUrls = new Set() } = {},
+  {
+    now = Date.now() / 1000,
+    failedUrls = new Map(),
+    projectedTs = new Map(),
+  } = {},
 ) {
   const csvByUrl = new Map(csvEntries.map((e) => [e.url, e]));
+  const failed = new Map(failedUrls);
   const merged = [];
 
+  const failureEntry = (url, word, comments = []) => ({
+    url,
+    result: word,
+    ts: Math.floor(now),
+    via: 'lychee',
+    comments,
+  });
+
+  const takeFailure = (url) => {
+    const word = failed.get(url);
+    failed.delete(url);
+    return word;
+  };
+
   for (const entry of owned.entries) {
     const csv = csvByUrl.get(entry.url);
     csvByUrl.delete(entry.url);
@@ -318,14 +416,10 @@ export function mergeBack(
       (!Number.isFinite(dateToTs(entry.expires)) ||
         now > dateToTs(entry.expires));
 
-    if (failedUrls.has(entry.url)) {
-      merged.push({
-        url: entry.url,
-        status: STATUS_CLIENT_ERROR,
-        ts: Math.floor(now),
-        via: 'lychee',
-        comments: entry.comments ?? [],
-      });
+    if (failed.has(entry.url)) {
+      merged.push(
+        failureEntry(entry.url, takeFailure(entry.url), entry.comments ?? []),
+      );
       continue;
     }
 
@@ -334,10 +428,14 @@ export function mergeBack(
       continue;
     }
 
-    if (expired || csv.status !== entry.status) {
+    const echoed =
+      csv.status === entry.result && csv.ts === projectedTs.get(entry.url);
+    if (echoed) {
+      merged.push(entry); // a cache hit of our own projection: no new fact
+    } else if (expired || csv.status !== entry.result) {
       merged.push({
         url: entry.url,
-        status: csv.status,
+        result: csv.status,
         ts: csv.ts,
         via: 'lychee',
         comments: [],
@@ -350,7 +448,22 @@ export function mergeBack(
   }
 
   for (const csv of csvByUrl.values()) {
-    merged.push({ ...csv, via: 'lychee', comments: [] });
+    if (failed.has(csv.url)) {
+      merged.push(failureEntry(csv.url, takeFailure(csv.url)));
+      continue;
+    }
+    merged.push({
+      url: csv.url,
+      result: csv.status,
+      ts: csv.ts,
+      via: 'lychee',
+      comments: [],
+    });
+  }
+
+  // Unmatched failures: http(s)-only minting, per the rules above.
+  for (const [url, word] of failed) {
+    if (/^https?:\/\//.test(url)) merged.push(failureEntry(url, word));
   }
 
   return { entries: merged.sort(byUrlBytes), trailing: owned.trailing };
@@ -359,11 +472,28 @@ export function mergeBack(
 // --- migration ---------------------------------------------------------------
 
 // One-shot .lycheecache -> link-cache.jsonc: every entry becomes via "lychee".
+// Legacy negative codes (htmltest-era refcache CSVs) map to failure words;
+// statuses with no result equivalent and timestamps outside the canonical
+// `when` range are counted as unmappable, never written (the parser would
+// reject the output: a false-clean import). Ambiguous duplicate rows surface
+// via `conflicting` (parseCsv).
 export function migrateCsvText(csvText) {
-  const { entries, malformed } = parseCsv(csvText);
-  const owned = {
-    entries: entries.map((e) => ({ ...e, via: 'lychee', comments: [] })),
-    trailing: [],
+  const { entries, malformed, conflicting } = parseCsv(csvText);
+  const migrated = [];
+  let unmappable = 0;
+  for (const { url, status, ts } of entries) {
+    const result = status < 0 ? LEGACY_STATUS_WORDS.get(status) : status;
+    if (!isValidResult(result) || Number.isNaN(whenToTs(tsToWhen(ts)))) {
+      unmappable += 1;
+      continue;
+    }
+    migrated.push({ url, result, ts, via: 'lychee', comments: [] });
+  }
+  return {
+    text: serializeOwned({ entries: migrated, trailing: [] }),
+    count: migrated.length,
+    malformed,
+    conflicting,
+    unmappable,
   };
-  return { text: serializeOwned(owned), count: entries.length, malformed };
 }

package/link-cache/index.mjs

@@ -13,6 +13,7 @@ import { fileURLToPath } from 'node:url';
 import {
   CSV_FILE,
   OWNED_FILE,
+  csvUnquote,
   parseOwned,
   serializeOwned,
 } from '../lib/cache.mjs';
@@ -23,17 +24,24 @@ const BUCKET_COUNT = 5;
 
 // --- parsing ---------------------------------------------------------------
 
+// Parse one URL,STATUS,TIMESTAMP line; null when malformed. Lexically strict:
+// junk rows must count as malformed (the staleness guard fails on them)
+// rather than pass as entries. Quote-grammar validation delegates to lib's
+// csvUnquote; the URL keeps its raw (possibly quoted) spelling because prune
+// rewrites lines byte-for-byte.
 function parseLine(raw) {
   const lastComma = raw.lastIndexOf(',');
   if (lastComma < 0) return null;
-  const ts = Number(raw.slice(lastComma + 1));
+  const tsField = raw.slice(lastComma + 1);
   const head = raw.slice(0, lastComma);
   const statusComma = head.lastIndexOf(',');
   if (statusComma < 0) return null;
   const status = head.slice(statusComma + 1).trim();
-  const url = head.slice(0, statusComma);
-  if (!Number.isInteger(ts) || status === '') return null;
-  return { url, status, ts };
+  const urlField = head.slice(0, statusComma);
+  if (!/^\d+$/.test(tsField) || !/^-?\d+$/.test(status)) return null;
+  const unquoted = csvUnquote(urlField);
+  if (unquoted === null || unquoted === '') return null;
+  return { url: urlField, status, ts: Number(tsField) };
 }
 
 // Parse a whole CSV cache, keeping the original lines (so a prune can rewrite
@@ -60,7 +68,7 @@ export function parseOwnedCache(text) {
   const owned = parseOwned(text);
   const entries = owned.entries.map((e, index) => ({
     url: e.url,
-    status: String(e.status),
+    status: String(e.result),
     ts: e.ts,
     via: e.via,
     index,
@@ -197,7 +205,7 @@ export function formatStats(stats, { now = Date.now() / 1000, path } = {}) {
     );
   }
 
-  lines.push('  Status:');
+  lines.push('  Result:');
   for (const [status, n] of stats.byStatus) {
     lines.push(`    ${status.padEnd(5)} ${n}`);
   }
@@ -224,8 +232,8 @@ export function formatStats(stats, { now = Date.now() / 1000, path } = {}) {
 // --- ordered execution -----------------------------------------------------
 
 // Run the parsed ops in order over the evolving cache, optionally scoped to
-// URLs matching `match`. Pure: returns the text to print and the text to write
-// (null when nothing was pruned); no I/O.
+// URLs matching `match`. Pure: returns the text to print and the text to
+// write (null when nothing was pruned); no I/O.
 export function runOps(
   parsed,
   ops,
@@ -233,6 +241,7 @@ export function runOps(
 ) {
   const removed = new Set();
   let pruned = 0;
+  let guardFailed = false;
   const out = [];
   // Match against the unquoted URL: legacy-CSV entries carry the raw
   // (possibly CSV-quoted) field, which would defeat anchored regexes.
@@ -244,13 +253,74 @@ export function runOps(
     if (op.kind === 'list') {
       out.push(formatList(current(), Number(op.value), { now }));
     } else if (op.kind === 'prune') {
-      const cur = current();
+      // Manual entries are exempt: pruning schedules re-checks for
+      // lychee-verified entries, while a manual entry's lifecycle is owned by
+      // its author and its `expires` date — and under prune-refresh rotation
+      // re-confirmed seeds keep their original timestamp, so they'd otherwise
+      // age to the front and get evicted mid-lifecycle.
+      const cur = current().filter((e) => e.via !== 'manual');
       const k = resolvePruneCount(op.value, cur.length);
       for (const victim of selectOldest(cur, k)) removed.add(victim.index);
       pruned += k;
       out.push(
         `Pruned ${k} oldest ${k === 1 ? 'entry' : 'entries'} (${cur.length} → ${cur.length - k}).`,
       );
+    } else if (op.kind === 'max-age') {
+      // Staleness guard: with staleness checks off by default in
+      // lychee-norm-cache, a dead refresh job rots the cache silently; an
+      // entry aging past the threshold is the signal. Refreshable entries are
+      // the lychee-owned ones (via-less legacy CSV entries included), aged by
+      // their check time, plus expired manual seeds, aged from their expiry
+      // date (a live refresh job replaces them within a rotation). Unexpired
+      // and no-expires seeds and named-resolver entries are exempt: their
+      // timestamps never refresh on re-confirmation, so their age says
+      // nothing about the refresh job.
+      const limit = Number(op.value);
+      if (parsed.malformed > 0) {
+        guardFailed = true;
+        out.push(
+          `Staleness guard: ${parsed.malformed} malformed line(s); the cache's age cannot be trusted.`,
+        );
+      } else {
+        const candidates = [];
+        for (const e of current()) {
+          if (e.via === undefined || e.via === 'lychee') {
+            candidates.push({ url: e.url, ts: e.ts });
+          } else if (e.via === 'manual' && e.src?.expires !== undefined) {
+            const cutoff = Date.parse(`${e.src.expires}T23:59:59Z`) / 1000;
+            if (now > cutoff) candidates.push({ url: e.url, ts: cutoff });
+          }
+        }
+        // Corrupt evidence anywhere in the candidate set poisons the verdict:
+        // a single oldest-entry probe would let any past entry mask a
+        // future-dated one.
+        const future = candidates.find((c) => c.ts > now);
+        const oldest = candidates.sort((a, b) => a.ts - b.ts)[0];
+        if (future) {
+          guardFailed = true;
+          out.push(
+            `Staleness guard: future-dated timestamp on ${displayUrl(future.url)}; the cache's age cannot be trusted.`,
+          );
+        } else if (!oldest) {
+          out.push('Staleness guard: no refreshable entries; nothing to age.');
+        } else {
+          const ageDays = Math.floor((now - oldest.ts) / DAY);
+          if (now - oldest.ts > limit * DAY) {
+            guardFailed = true;
+            out.push(
+              `Staleness guard: oldest refreshable entry is ${ageDays}d old, ` +
+                `exceeds --max-age ${limit}d:\n  ${displayUrl(oldest.url)}\n` +
+                'Is the cache-refresh job running? If the URL has left the ' +
+                'site, its entry never re-checks: prune it (--match URL --prune 1).',
+            );
+          } else {
+            out.push(
+              `Staleness guard: oldest refreshable entry is ${ageDays}d old ` +
+                `(within --max-age ${limit}d).`,
+            );
+          }
+        }
+      }
     } else if (op.kind === 'summary') {
       const stats = computeStats(current(), {
         now,
@@ -278,7 +348,7 @@ export function runOps(
       writeText = parsed.lines.filter((_, i) => !removed.has(i)).join('\n');
     }
   }
-  return { output: out.join('\n\n'), writeText, pruned };
+  return { output: out.join('\n\n'), writeText, pruned, guardFailed };
 }
 
 // --- CLI -------------------------------------------------------------------
@@ -290,6 +360,7 @@ const FLAGS = new Map([
   ['--match', 'match'],
   ['-p', 'prune'],
   ['--prune', 'prune'],
+  ['--max-age', 'max-age'],
   ['-s', 'summary'],
   ['--summary', 'summary'],
 ]);
@@ -331,6 +402,9 @@ export function parseArgs(argv) {
       if (kind === 'prune' && !/^\d+%?$/.test(value)) {
         throw new Error(`--prune needs NUM or NUM%, got: ${value}`);
       }
+      if (kind === 'max-age' && !/^\d+$/.test(value)) {
+        throw new Error(`--max-age needs a day count, got: ${value}`);
+      }
       ops.push({ kind, value });
       continue;
     }
@@ -339,6 +413,12 @@ export function parseArgs(argv) {
     path = a;
   }
 
+  // Scoping the staleness backstop to a URL subset would silently blind it
+  // to unmatched rot; refuse rather than pick a winner.
+  if (match && ops.some((op) => op.kind === 'max-age')) {
+    throw new Error('--max-age cannot be combined with --match');
+  }
+
   return { ops, path, match, help };
 }
 
@@ -350,12 +430,21 @@ the evolving cache, so \`-l 5 -p 5\` lists the 5 oldest about to be pruned,
 while \`-p 5 -l 5\` lists the next 5 after pruning.
 
   -l, --list NUM        list the NUM oldest entries
-  -m, --match REGEX     scope all operations to URLs matching REGEX
-  -p, --prune NUM[%]    drop the NUM (or NUM%) oldest entries, then rewrite
-  -s, --summary         print a summary (counts, ages, status, via, histogram)
+  -m, --match REGEX     scope all operations except --max-age to URLs matching
+                        REGEX (the guard refuses the combination)
+      --max-age DAYS    staleness guard: fail (exit 3) when the oldest
+                        refreshable entry is older than DAYS days
+  -p, --prune NUM[%]    drop the NUM (or NUM%) oldest non-manual entries, then
+                        rewrite (manual entries retire via their expires date)
+  -s, --summary         print a summary (counts, ages, result, via, histogram)
   -h, --help            show this help
 
-With no options, prints the summary. A flag may not be repeated.`;
+With no options, prints the summary. A flag may not be repeated. A --match
+scope shields out-of-scope entries from the operations, never from a prune's
+rewrite: they always survive intact.
+
+Exit codes: 0 success; 1 unreadable or malformed cache file; 2 usage error;
+3 staleness-guard breach.`;
 
 export function main(argv) {
   let args;
@@ -392,7 +481,7 @@ export function main(argv) {
 
   const now = Date.now() / 1000;
   const ops = args.ops.length ? args.ops : [{ kind: 'summary' }];
-  const { output, writeText } = runOps(parsed, ops, {
+  const { output, writeText, guardFailed } = runOps(parsed, ops, {
     now,
     path,
     match: args.match,
@@ -400,6 +489,7 @@ export function main(argv) {
 
   if (output) console.log(output);
   if (writeText !== null) writeFileAtomic(path, writeText);
+  if (guardFailed) process.exit(3);
 }
 
 // Real-path compare, not `file://${argv[1]}`: npm links bins as symlinks, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "link-cache",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Zero-dependency helper CLIs for cached Lychee link-checking around an owned JSONC cache (link-cache.jsonc) with provenance: lychee-norm-cache (run + sync caches) and link-cache (inspect/prune).",
   "keywords": [
     "lychee",