clearotron 0.2.0 → 0.2.1

package/scripts/report-screenshot.mjs

@@ -19,6 +19,7 @@
 // receives, so it loads the brand webfonts the client's browser loads. Two scripts, two intents; do not
 // "fix" either to match the other.
 import { spawn } from "node:child_process";
+import { assertPageLoaded, cjkCharsIn, cjkVerdict, fontsCovering } from "./headless-page.mjs";   // tracker issue 227 — did chrome open the report, or its own error page?
 import { mkdtempSync, writeFileSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, dirname, resolve } from "node:path";
@@ -29,6 +30,9 @@ const OUT = resolve(process.argv[3] ?? join(ROOT, "docs", "assets", "example-rep
 const WIDTH = 1280, HEIGHT = 1040;
 // The frame starts here rather than at the top of the document — see the scroll block below.
 const ANCHOR = process.argv.includes("--anchor") ? process.argv[process.argv.indexOf("--anchor") + 1] : "h1";
+// WHAT ONLY A REPORT CARRIES. `h1` is the ANCHOR — where to start the frame — and it is on every HTML
+// page including Chrome's error interstitial, so it cannot also be the proof that this IS a report.
+const MARKER = process.argv.includes("--marker") ? process.argv[process.argv.indexOf("--marker") + 1] : "[data-run-id]";
 
 const src = process.argv[2];
 if (!src) { console.error("usage: node scripts/report-screenshot.mjs <report.html> [out.png]"); process.exit(2); }
@@ -69,6 +73,34 @@ const sessionId = sess.sessionId;
 const cmd = (method, params = {}) => new Promise((r) => { const n = ++id; pending.set(n, r); ws.send(JSON.stringify({ id: n, sessionId, method, params })); });
 
 await cmd("Page.enable");
+
+// ── IS THIS THE REPORT, OR CHROME'S OWN ERROR PAGE? (tracker issue 227) ──────────────────────────────
+//
+// Chrome is launched with the file URL as an ARGUMENT, so there is no navigation response to check and
+// nothing here ever asked. When the file could not be read, Chrome showed `ERR_ACCESS_DENIED` — a page
+// with an `<h1>` — the anchor below resolved against it, the clip was taken, and this exited 0 having
+// written 38 KB of grey error page over the README's example frame. The successful run and the failed
+// one differed in the log by an anchor offset and a font count, neither of which was asserted on.
+//
+// `existsSync` above does not cover it: a file that EXISTS and cannot be READ passes that check and
+// fails in Chrome. So does a file that is readable and is not a report.
+//
+// THE MARKER IS THE RUN ID, not a tag. `h1` is what the error page has; `[data-run-id]` is what only a
+// rendered report has, and naming it in the log is what makes the success line say what it certified
+// rather than "an h1 was found".
+const evaluate = async (expression) => {
+  const r = await cmd("Runtime.evaluate", { expression, returnByValue: true });
+  return r?.result?.result?.value;
+};
+const loaded = await assertPageLoaded(evaluate, {
+  expected: `file://${page}`,
+  marker: `document.querySelector(${JSON.stringify(MARKER)})`,
+  markerName: `a report element (${MARKER})`,
+  what: "report-screenshot",
+});
+if (!loaded.ok) { chrome.kill(); process.exit(1); }
+const runId = await evaluate(`(document.querySelector(${JSON.stringify(MARKER)})?.getAttribute("data-run-id") ?? "")`);
+
 // The fonts are the point of allowing the network at all, so wait for them rather than for a fixed
 // sleep: a timer long enough on this box is a timer too short on a slower one, and the failure is a
 // screenshot in the wrong typeface that nobody notices until it is in the README.
@@ -91,11 +123,39 @@ if (typeof top !== "number") {
   console.error(`report-screenshot: no element matched ${JSON.stringify(ANCHOR)} — nothing to anchor the frame to.`);
   chrome.kill(); process.exit(1);
 }
+// ── CAN THIS BOX DRAW WHAT THE PAGE SAYS? (tracker issue 227) ───────────────────────────────────────
+//
+// The default demo product's report carries the mark's native-script renderings — ベンクリ, ベンコリ,
+// ヴェンコリ — and they are load-bearing: the verdict sentence reads "A live Japanese class 9
+// registration reading ベンクリ covers measuring and testing instruments". With no CJK-capable font
+// those render as empty boxes, twice in the captured frame, and nothing said so.
+//
+// The wait for `document.fonts.ready` above was written against exactly this class — "the failure is a
+// screenshot in the wrong typeface that nobody notices until it is in the README" — and solved the
+// TYPEFACE half. This is the WRITING-SYSTEM half, in the same script.
+//
+// REFUSES rather than warns. This writes an image that goes into the README by hand; a warning on a
+// terminal nobody is reading when the file is already written is the shape that produced the defect
+// above it. `--allow-tofu` is there for a reader who genuinely wants the frame anyway and has been told
+// what is in it.
+const pageText = await evaluate("document.body ? document.body.innerText : ''");
+const cjkChars = cjkCharsIn(pageText);
+const glyphs = cjkVerdict({ cjkChars, covering: fontsCovering("ja"),
+  sample: (String(pageText).match(/[\u3040-\u30ff\u4e00-\u9fff]{2,8}/u) ?? [])[0] ?? "" });
+if (!glyphs.ok && !process.argv.includes("--allow-tofu")) {
+  console.error(`report-screenshot: ${glyphs.why}`);
+  console.error("  Pass --allow-tofu to capture it anyway, knowing the frame is missing those glyphs.");
+  chrome.kill(); process.exit(1);
+}
+if (!glyphs.ok) console.error(`report-screenshot: WARNING — ${glyphs.why} Capturing anyway (--allow-tofu).`);
+
 const y = Math.max(top - 56, 0);   // a little air above the title, so the page does not read as cropped
 const shot = await cmd("Page.captureScreenshot", { format: "png", captureBeyondViewport: true,
   clip: { x: 0, y, width: WIDTH, height: HEIGHT, scale: 1 } });
 if (!shot?.result?.data) { console.error(`report-screenshot: chrome returned no image. ${JSON.stringify(shot).slice(0, 300)}`); chrome.kill(); process.exit(1); }
 writeFileSync(OUT, Buffer.from(shot.result.data, "base64"));
-const loaded = await cmd("Runtime.evaluate", { expression: "document.fonts.size + ':' + [...document.fonts].filter(f=>f.status==='loaded').length", returnByValue: true });
+const fonts = await cmd("Runtime.evaluate", { expression: "document.fonts.size + ':' + [...document.fonts].filter(f=>f.status==='loaded').length", returnByValue: true });
 chrome.kill();
-console.log(`report-screenshot: wrote ${OUT} (${WIDTH}x${HEIGHT}, anchor ${JSON.stringify(ANCHOR)} at y=${Math.round(y)}, fonts ${loaded?.result?.result?.value ?? "?"})`);
+// NAMES WHAT IT CERTIFIED. "an h1 was found" is true of the error page this used to photograph; the
+// run id is read out of the document and is the thing a reader can check against the report they meant.
+console.log(`report-screenshot: wrote ${OUT} of run ${runId || "(no run id in the page)"} (${WIDTH}x${HEIGHT}, anchor ${JSON.stringify(ANCHOR)} at y=${Math.round(y)}, fonts ${fonts?.result?.result?.value ?? "?"}, ${glyphs.kind})`);

package/scripts/revisit-render-check.mjs

@@ -59,6 +59,7 @@
 // MUST NOT run as a user with a virtual-memory ulimit (`ulimit -v`) — Chrome dumps core under one. Run it
 // as a user with `ulimit -v unlimited`. The dbus/UPower errors Chrome prints on a headless box are noise.
 
+import { navigateOrRefuse } from './headless-page.mjs'   // tracker issue 227 — Page.navigate returns an errorText, and nothing read it
 import { createServer } from 'node:http'
 import { readFileSync, existsSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs'
 import { join, extname, dirname } from 'node:path'
@@ -284,7 +285,7 @@ const record = {}
 
 // The shell, once. Everything after this is client-side.
 epoch = 'boot'
-await cmd('Page.navigate', { url: `${origin}/portal/home` })
+await navigateOrRefuse(cmd, `${origin}/portal/home`, { what: 'revisit-render-check' })
 if (!(await settle())) say(false, 'the shell never went quiet within 12s — it is still requesting')
 const bootPath = await where()
 say(bootPath === '/portal/home', `the shell loaded on /portal/home (got ${bootPath})`)
@@ -375,7 +376,7 @@ await twice('clearances', () => clickNav('Clearances'), '/portal/clearances')
 // URL and the SECOND is the Back button, which is the revisit a reader actually performs and the one that
 // runs AppShell's popstate listener rather than its click funnel.
 epoch = 'result:1'
-await cmd('Page.navigate', { url: `${origin}/portal/result/${RUN_ID}` })
+await navigateOrRefuse(cmd, `${origin}/portal/result/${RUN_ID}`, { what: 'revisit-render-check' })
 const rq1 = await settle()
 const rp1 = await where()
 const rt1 = await screenText()

package/scripts/score.mjs

@@ -646,6 +646,20 @@ function print(id, ref, run, s, delta, refPath) {
     for (const c of B.collisions)
       console.log(`    · ${c.owner}: reference "${c.entry}" is ${c.bucket}, surfaced "${c.noise}" is noise`);
   }
+  // ── SAME PROPRIETOR, DIFFERENT MARKS — REPORTED, NEVER SUPPRESSING (tracker issue 249) ───────────
+  //
+  // These used to print under the line above, which tells the reader not to read the recall numbers.
+  // One large filer anywhere in a matter therefore suppressed a whole run's measurement, and did: R2's
+  // real 88% → 63% recall movement went unquoted on the regression issue because `Novartis AG` held one
+  // withheld reference mark and one surfaced non-reference mark. Those two rows are both true.
+  //
+  // Kept visible because a reader may still want the pairing, and deliberately WITHOUT a verdict: this
+  // is an observation about the matter, not a fault in the scorer.
+  if (B.ownerEchoes?.length) {
+    console.log(`\n  same-proprietor rows (${B.ownerEchoes.length}) — NOT a collision, and the recall numbers above stand:`);
+    for (const c of B.ownerEchoes)
+      console.log(`    · ${c.owner}: reference "${c.entry}" is ${c.bucket}, surfaced "${c.noise}" is noise (different marks)`);
+  }
 
   for (const [name, label] of [["withheld", "WITHHELD — in this run's own records, absent from its findings"],
                                ["lost", "LOST — never retrieved"],

package/shared/access-audience.mjs

@@ -71,3 +71,218 @@ export function audienceLabel(aud) {
   if (!list.length) return "(none)";
   return list.map((a) => `${String(a).slice(0, 8)}…`).join(",");
 }
+
+// ── THE AUDIENCE THE EDGE ISSUES, AS OPPOSED TO THE ONE THIS INSTALL EXPECTS (tracker issue 241) ───
+//
+// Everything above reads LOCAL configuration. What follows reads the EDGE, so `doctor` can compare the
+// two — the half of the recreation trap with no symptom of its own. Deleting and recreating a
+// Cloudflare Access application changes the audience; the existing warning fires on the CHALLENGE being
+// wrong, so on a box where somebody recreated the application and then fixed the sign-in, every layer
+// reads healthy and the stale audience stays invisible until a real request is rejected.
+//
+// ── WHERE THE AUDIENCE IS, AND WHERE IT IS NOT ───────────────────────────────────────────────────
+//
+// Access does not publish it in RFC 8414 discovery metadata. Two investigations looked there, correctly
+// found nothing, and one concluded the route did not exist. It is in the REDIRECT handed to an
+// unauthenticated caller: the login URL carries a `kid` parameter and a `meta` JWT naming the same value.
+//
+// ── THIS DECODES; IT DOES NOT VERIFY, AND THAT IS DELIBERATE ─────────────────────────────────────
+//
+// The meta token is public routing information served to a caller with no credential — its own
+// `auth_status` reads `NONE`. It is not a bearer token and nothing here trusts it: the only thing taken
+// from it is a string, which is then compared against local configuration. Verifying it would mean
+// dragging in the credential path and `jose` with it — which this file's header explains at length that
+// it must not do — to authenticate a document that authenticates nobody, and would invite a later
+// reader to believe a valid signature here meant a request was authorised. It does not.
+//
+// ── AND THE READ IS CROSS-CHECKED AGAINST ITSELF ─────────────────────────────────────────────────
+//
+// The same value arrives two independent ways in one response: the `kid` parameter and the token's own
+// `aud`. Using one when two are there throws away the only free integrity check on the read, and it is
+// the check that would catch this code keying on a field Cloudflare later moves. When they disagree
+// this reports the disagreement rather than picking a winner.
+/** The path that says a hostname is Access-fronted. */
+export const ACCESS_LOGIN_PATH = "/cdn-cgi/access/login/";
+
+/** Base64url → utf8, with no exception escaping to the caller as a silent empty string. */
+function decodeSegment(seg) {
+  const raw = Buffer.from(String(seg), "base64url").toString("utf8");
+  if (!raw) throw new Error("the segment decoded to nothing");
+  return raw;
+}
+
+/**
+ * The audience, read out of the location an unauthenticated request was redirected to.
+ *
+ * `kind` is the whole answer and every branch has one, because the failures here are NOT
+ * interchangeable and the caller must be able to tell them apart:
+ *
+ *   unreachable      the edge could not be asked. A could-not-look, never agreement.
+ *   not-fronted      the hostname answered without an Access challenge. Its own verdict, and the
+ *                    single most important one: this check must not be able to SUCCEED by failing to
+ *                    find an edge, which is the exact shape of the defect it exists to catch.
+ *   unreadable       there is a challenge, and the audience could not be read out of it. Also a
+ *                    could-not-look — the shape may have moved, and a moved shape is not agreement.
+ *   disagree         `kid` and the token's `aud` name different audiences.
+ *   read             one audience, agreed by both sources.
+ */
+// The marker an Access-fronted API path puts in `WWW-Authenticate`. Keyed on the RESOURCE-METADATA path
+// rather than on "Bearer", which any OAuth resource anywhere would send — this names Cloudflare Access
+// specifically, and it is the string the real door returns.
+const ACCESS_RESOURCE_RE = /cloudflare-access-protected-resource/i;
+
+export function readAudience({ location = "", status = null, error = null, wwwAuthenticate = "", viaEdge = false } = {}) {
+  if (error) return { kind: "unreachable", why: String(error?.message ?? error).slice(0, 200) };
+  // ── THREE DOORS, NOT ONE (tracker issue 251) ────────────────────────────────────────────────────
+  //
+  // This returned `not-fronted` for every response with no redirect, and measured against production's
+  // four configured hostnames that one label covered three materially different states:
+  //
+  //   trademark.cordillera.ch        302  redirect present  → audience read, kid agrees
+  //   mcp.cordillera.ch/mcp          401  no redirect       → not-fronted   ← FALSE, it IS fronted
+  //   clients-mcp.cordillera.ch/mcp  401  no redirect       → not-fronted   ← FALSE, it IS fronted
+  //   agent-mcp.cordillera.ch/mcp    502  no redirect       → not-fronted   ← an origin fault
+  //
+  // None of these was a false pass — every one returned ok:false, which is the property that matters
+  // most and is untouched. It was a WRONG DIAGNOSIS on a safe failure, and the cost is a reader's hour
+  // spent hunting an Access application that exists and is working.
+  if (!location) {
+    // FRONTED, API PATH. Managed OAuth on an MCP path answers RFC 9728 style instead of redirecting a
+    // browser: a 401 whose `WWW-Authenticate` names a Cloudflare Access protected-resource document.
+    // Measured on the real door — that document resolves 200, says `protected: true`, and carries NO
+    // audience. So this is a stated could-not-look about the audience ON A DOOR THAT IS CONFIRMED
+    // PRESENT, which is neither a pass nor "no door".
+    if (ACCESS_RESOURCE_RE.test(String(wwwAuthenticate ?? ""))) {
+      return { kind: "fronted-api",
+        why: `the hostname answered ${status ?? "401"} as an OAuth-protected resource, naming a Cloudflare `
+          + "Access protected-resource document — it is fronted, and this route carries no audience to read" };
+    }
+    // THE EDGE ANSWERED AND THE ORIGIN DID NOT. A 5xx carrying `cf-ray` is Cloudflare reporting that it
+    // reached the door and the thing behind it did not answer. Calling that "nothing is fronting this
+    // hostname" is exactly backwards.
+    if (viaEdge && Number(status) >= 500) {
+      return { kind: "origin-failed",
+        why: `the edge answered ${status} for this hostname — Cloudflare reached the door and the origin `
+          + "behind it did not answer, so the audience could not be asked for" };
+    }
+    return { kind: "not-fronted", why: `the hostname answered ${status ?? "with no redirect"} and sent no Access challenge` };
+  }
+  let url;
+  try { url = new URL(location); } catch {
+    return { kind: "unreadable", why: `the redirect target is not a URL: ${String(location).slice(0, 120)}` };
+  }
+  if (!url.pathname.includes(ACCESS_LOGIN_PATH)) {
+    return { kind: "not-fronted", why: `the redirect goes to ${url.origin}${url.pathname}, which is not an Access login` };
+  }
+  const kid = url.searchParams.get("kid") || "";
+  const token = url.searchParams.get("meta") || "";
+  if (!token) return { kind: "unreadable", why: "the Access login carries no `meta` token", kid };
+  const parts = token.split(".");
+  if (parts.length < 2) return { kind: "unreadable", why: "the `meta` token is not a JWT", kid };
+  let payload;
+  try { payload = JSON.parse(decodeSegment(parts[1])); } catch (e) {
+    return { kind: "unreadable", why: `the \`meta\` token's payload could not be read (${String(e?.message ?? e).slice(0, 80)})`, kid };
+  }
+  const aud = typeof payload?.aud === "string" ? payload.aud : "";
+  if (!aud) return { kind: "unreadable", why: "the `meta` token's payload names no `aud`", kid };
+  // BOTH SOURCES, OR NEITHER IS TRUSTED. A `kid` that is absent is itself a change in the shape.
+  if (!kid) return { kind: "unreadable", why: "the Access login carries no `kid` to cross-check the token against", aud };
+  if (kid !== aud) {
+    return { kind: "disagree", aud, kid, hostname: payload?.hostname ?? "", why: "the two sources name different audiences" };
+  }
+  return { kind: "read", aud, kid, hostname: payload?.hostname ?? "" };
+}
+
+/**
+ * What to tell the reader, given what was configured and what the edge said.
+ *
+ * NOTHING HERE RETURNS "fine" FOR A QUESTION IT COULD NOT ASK. Each unhappy kind carries its own
+ * sentence naming what was not established, because "no problem reported" and "no problem" are the two
+ * things this whole check exists to keep apart.
+ */
+export function audienceVerdict({ configured = "", read = {} } = {}) {
+  // MEMBERSHIP, NOT EQUALITY, and this file already learned that once. A deployment runs one Access
+  // application PER AUDIENCE and `CLEAROTRON_OIDC_AUDIENCE` may name several; the edge issues ONE for
+  // the hostname being asked. `===` against a configured list reports every correct multi-application
+  // deployment as a mismatch — the same mistake `audienceIncludes` above exists to have stopped making.
+  const cfg = accessAudience(configured);
+  const cfgList = Array.isArray(cfg) ? cfg : (cfg ? [cfg] : []);
+  switch (read.kind) {
+    case "unreachable":
+      return { kind: "could-not-look", ok: false,
+        message: `the edge could not be reached, so the audience it issues is unknown (${read.why}). `
+          + "This is a failure to look, not agreement." };
+    case "not-fronted":
+      return { kind: "not-fronted", ok: false,
+        message: `nothing is fronting this hostname with Access — ${read.why}. A door that is not there `
+          + "cannot be the one this install is configured for, so this is a finding rather than a pass." };
+    // NEITHER A PASS NOR "NO DOOR". The door is confirmed present and the audience is not readable by
+    // this route — that is a stated could-not-look, and it must not read as either of the two things it
+    // is not. Whether an API path's audience is reachable at all is open; nothing in the
+    // protected-resource document carries it.
+    case "fronted-api":
+      return { kind: "fronted-api", ok: false,
+        message: `this hostname IS fronted by Access — ${read.why}. The audience could not be compared, `
+          + "which is a could-not-look about the audience and not a finding about the door." };
+    case "origin-failed":
+      return { kind: "could-not-look", ok: false,
+        message: `the edge is up and the origin behind it is not — ${read.why}. Nothing here says anything `
+          + "about the audience; it says the service is down." };
+    case "unreadable":
+      return { kind: "could-not-look", ok: false,
+        message: `the Access challenge is there but its audience could not be read (${read.why}). `
+          + "The shape may have moved; a shape that moved is not agreement." };
+    case "disagree":
+      return { kind: "sources-disagree", ok: false,
+        message: `the edge's own two answers disagree: the login's \`kid\` says ${read.kid} and the `
+          + `\`meta\` token says ${read.aud}. Neither is trustworthy on its own, so nothing is compared.` };
+    case "read": {
+      if (!cfgList.length) {
+        return { kind: "not-configured", ok: false,
+          message: `the edge issues ${read.aud} for this hostname, and CLEAROTRON_OIDC_AUDIENCE is unset, `
+            + "so every request it fronts is checked against nothing." };
+      }
+      if (!audienceIncludes(cfg, read.aud)) {
+        // BOTH VALUES, NEVER "audience mismatch". A reader who is told only that two things differ has
+        // to go and find both of them, and the whole point of asking the edge was to hand them over.
+        return { kind: "mismatch", ok: false,
+          message: `the audience does not match. This install is configured with ${cfgList.join(", ")}, and the edge `
+            + `issues ${read.aud} for ${read.hostname || "this hostname"}. Requests will be rejected `
+            + "until they agree — recreating an Access application changes the audience." };
+      }
+      return { kind: "agree", ok: true,
+        message: `the audience matches the one the edge issues for ${read.hostname || "this hostname"} (${read.aud})` };
+    }
+    default:
+      return { kind: "could-not-look", ok: false,
+        message: `the audience check returned no verdict it knows (${JSON.stringify(read.kind)}), which is `
+          + "a fault in this check rather than a finding about the door." };
+  }
+}
+
+/**
+ * One unauthenticated request, with a bound on how long it may take.
+ *
+ * `redirect: "manual"` because the REDIRECT is the answer — following it fetches Cloudflare's login page
+ * and throws away the only thing being read. Failure is returned rather than thrown: the caller's job is
+ * to say "could not look", and an exception here would reach `doctor` as a crash instead.
+ */
+export async function probeAudience({ url, fetchImpl = fetch, timeoutMs = 5000, signalFor = null } = {}) {
+  if (!url) return { error: new Error("no hostname is configured to ask") };
+  const ac = signalFor ? null : new AbortController();
+  const t = ac ? setTimeout(() => ac.abort(new Error(`no answer within ${timeoutMs}ms`)), timeoutMs) : null;
+  try {
+    const res = await fetchImpl(url, { redirect: "manual", signal: signalFor ?? ac.signal });
+    // TWO MORE HEADERS, AND THEY ARE THE WHOLE OF tracker issue 251. Without them every non-redirecting
+    // answer collapses to "no redirect", and three different doors read as one. `www-authenticate` is
+    // how an Access-fronted API path announces itself; `cf-ray` is how a 5xx says the EDGE answered and
+    // the origin behind it did not. Both are on the response already — nothing extra is fetched.
+    return { status: res.status, location: res.headers?.get?.("location") ?? "",
+      wwwAuthenticate: res.headers?.get?.("www-authenticate") ?? "",
+      viaEdge: Boolean(res.headers?.get?.("cf-ray")) };
+  } catch (e) {
+    return { error: e };
+  } finally {
+    if (t) clearTimeout(t);
+  }
+}

package/shared/tracked-files.mjs

@@ -114,5 +114,36 @@ export function grepTrackedFiles(guard, { root, args }) {
   return files;
 }
 
+/**
+ * The tracked corpus WITH ITS INDEX MODES, or null when this tree has no checkout to read it from.
+ *
+ * WHY THIS IS HERE RATHER THAN LEFT TO ITS ONE CALLER (tracker issue 235). The executable-bits guard
+ * needs `ls-files -s`, which carries the mode, and `trackedFiles` above deliberately returns paths
+ * only. So that guard called the helper for its skip contract and then spawned git a SECOND time,
+ * raw, for the modes — correct, because the raw call sits behind the helper's null check, but
+ * indistinguishable from an unguarded one to any reader or check looking at the call sites.
+ *
+ * The invariant is "corpus enumeration degrades to a stated skip", and `-s` is corpus enumeration.
+ * Extending the helper keeps that true by construction instead of by the ordering of two calls.
+ *
+ * @returns {Map<string,string>|null} path -> index mode ("100644", "100755", …) — null means SKIP
+ */
+export function trackedIndexModes(guard, { root }) {
+  const r = run(root, ["ls-files", "-s"]);
+  if (r.status !== 0) {
+    say(`${GUARD_SKIPPED_MARKER} ${guard} — ${reasonFrom(r)}; ${NO_CORPUS_REMEDY}`);
+    return null;
+  }
+  const out = new Map();
+  for (const line of r.stdout.split("\n")) {
+    if (!line.trim()) continue;
+    // `<mode> <object> <stage>\t<path>` — the tab is the only safe separator, a path may contain spaces.
+    const [meta, path] = line.split("\t");
+    if (path) out.set(path, meta.split(" ")[0]);
+  }
+  say(`${GUARD_OK_MARKER} — ${guard}: ${out.size} tracked file(s) with modes`);
+  return out;
+}
+
 /** The one-line reason a guard hands to `t.skip()`, so the TAP line says it too. */
 export const skipReason = (guard) => `${guard}: not a git checkout — ${NO_CORPUS_REMEDY}`;