@codyswann/lisa 4.45.2 → 4.45.3

package/plugins/lisa-rails-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.45.2",
+  "version": "4.45.3",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/hooks/parity-safety-net.sh

@@ -405,7 +405,12 @@ readonly FOLLOW_MAX_TOTAL_BYTES=524288
 readonly FOLLOW_MAX_FILES=8
 readonly FOLLOW_MAX_DEPTH=3
 
-follow_bases=""
+# Effective working directory established by a literal `cd` in the command, and
+# the flag that says a `cd` happened whose target could NOT be read literally.
+# Empty + 0 means no `cd` has been seen and the session's own cwd governs.
+follow_cwd=""
+follow_cwd_unknown=0
+follow_normalized=""
 follow_paths=$'\n'
 follow_names=""
 follow_count=0
@@ -420,6 +425,10 @@ see is the thing it exists to stop.
 
 - Name the script by a LITERAL path that exists and is readable — \`bash
   ./scripts/x.sh\` rather than \`bash \"\$SCRIPT\"\` — and the guard can classify it.
+- A leading \`cd\` the guard cannot read literally — \`cd \"\$DIR\" && bash x.sh\` —
+  leaves it unable to say WHICH copy of \`x.sh\` would run, and a same-named file
+  in another directory is a different file. Spell the directory out, or give the
+  script its full path.
 - A file past the inspection cap is refused rather than half-scanned, because a
   truncated scan reports a confident ALLOW about text it never read. Split it,
   or run it manually outside the agent.
@@ -550,15 +559,77 @@ follow_split() {
   '
 }
 
-# Record a literal `cd` target as an additional base for resolving a relative
-# executed path, so `cd sub && ./run.sh` resolves the way the shell will.
-follow_add_base() {
-  local d="$1"
+# Collapse `.`, `..` and empty segments so the path a verdict NAMES is the one a
+# reader recognises. Purely lexical, and it cannot move a verdict: every
+# component has already been proven to exist by the `-d` test that follows, and
+# the `-f`/`-r` tests are applied to the collapsed path either way.
+follow_normalize() {
+  local p="$1" out="" seg
+  local IFS=/
+  set -f
+  # The word split is the point: `$p` is being addressed one path segment at a
+  # time, and the glob guard above keeps a literal `*` from expanding.
+  # shellcheck disable=SC2086
+  for seg in $p; do
+    case "$seg" in
+      "" | .) ;;
+      ..) out="${out%/*}" ;;
+      *) out="$out/$seg" ;;
+    esac
+  done
+  set +f
+  follow_normalized="${out:-/}"
+}
+
+# Track the working directory a literal `cd` establishes, so a relative executed
+# path resolves against the directory the command will actually have.
+#
+# This REPLACES the session's own cwd rather than adding to it. It used to be an
+# extra base appended AFTER `$PWD`, so `$PWD` always won and
+# `cd <other-checkout> && bash scripts/x.sh` was classified against the session
+# checkout's same-named copy. That is not a resolution failure — it succeeds,
+# against a real and readable file, and the verdict is reported with full
+# confidence about text nobody was about to run (CodySwannGT/lisa#3933). Two
+# checkouts of one repository differ by exactly the work in flight, which is the
+# entire point of the second one, so the copy that would RUN is the only copy
+# whose verdict means anything. Wrong in both directions, and the expensive
+# direction is silent: the dangerous line sits in the copy that would run and
+# the guard reads the pristine one.
+#
+# A target this hook cannot turn into a literal directory marks the cwd UNKNOWN
+# instead of leaving a stale one in place. `follow_locate` then refuses a
+# relative token rather than guessing, which is the honest-refusal doctrine the
+# rest of this block already follows: a confident scan of the wrong file is
+# strictly worse than saying it could not tell.
+follow_cd() {
+  local d="$1" home="${HOME:-}"
+  # The tilde arms are LITERAL text — the unexpanded spelling the hook was
+  # handed — for the reason follow_locate's arms document.
+  # shellcheck disable=SC2088
+  case "$d" in
+    '~') d="$home" ;;
+    '~/'*) d="$home/${d#'~/'}" ;;
+  esac
+  case "$d" in
+    "" | -* | *'$'* | *'*'* | *'?'* | *'`'* | *'{'* | *'['*)
+      follow_cwd=""
+      follow_cwd_unknown=1
+      return 0
+      ;;
+  esac
   case "$d" in
-    "" | -* | *'$'* | *'*'* | *'?'*) return 0 ;;
+    /*) ;;
+    *) d="${follow_cwd:-$PWD}/$d" ;;
   esac
-  [ -d "$d" ] || return 0
-  follow_bases="$follow_bases"$'\n'"$d"
+  follow_normalize "$d"
+  d="$follow_normalized"
+  if [ -d "$d" ]; then
+    follow_cwd="$d"
+    follow_cwd_unknown=0
+  else
+    follow_cwd=""
+    follow_cwd_unknown=1
+  fi
 }
 
 # Resolve one executed-file operand to a readable regular file, or fail.
@@ -571,6 +642,7 @@ follow_add_base() {
 # this hook cannot evaluate.
 follow_locate() {
   local token="$1" home="${HOME:-}" tmp="${TMPDIR:-/tmp}" proj="${CLAUDE_PROJECT_DIR:-$PWD}" base
+  local cwd="${follow_cwd:-$PWD}"
   follow_located=""
   tmp="${tmp%/}"
   [ -n "$tmp" ] || tmp="/tmp"
@@ -584,8 +656,14 @@ follow_locate() {
     '${TMPDIR}' | '${TMPDIR}'/*) token="$tmp${token#'${TMPDIR}'}" ;;
     '$HOME' | '$HOME'/*) token="$home${token#'$HOME'}" ;;
     '${HOME}' | '${HOME}'/*) token="$home${token#'${HOME}'}" ;;
-    '$PWD' | '$PWD'/*) token="$PWD${token#'$PWD'}" ;;
-    '${PWD}' | '${PWD}'/*) token="$PWD${token#'${PWD}'}" ;;
+    '$PWD' | '$PWD'/*)
+      [ "$follow_cwd_unknown" -eq 0 ] || return 1
+      token="$cwd${token#'$PWD'}"
+      ;;
+    '${PWD}' | '${PWD}'/*)
+      [ "$follow_cwd_unknown" -eq 0 ] || return 1
+      token="$cwd${token#'${PWD}'}"
+      ;;
     '$CLAUDE_PROJECT_DIR' | '$CLAUDE_PROJECT_DIR'/*) token="$proj${token#'$CLAUDE_PROJECT_DIR'}" ;;
     '${CLAUDE_PROJECT_DIR}' | '${CLAUDE_PROJECT_DIR}'/*) token="$proj${token#'${CLAUDE_PROJECT_DIR}'}" ;;
   esac
@@ -597,13 +675,26 @@ follow_locate() {
       return 0
       ;;
   esac
+  # Past this point the token is RELATIVE, so which directory it is resolved
+  # from decides which file the verdict is about.
+  if [ "$follow_cwd_unknown" -eq 1 ]; then
+    return 1
+  fi
+  if [ -n "$follow_cwd" ]; then
+    # A literal `cd` names the directory the shell will be in. It is the only
+    # candidate — falling back to `$PWD` here is what made the guard report
+    # confidently about a same-named file in another checkout.
+    [ -f "$follow_cwd/$token" ] && [ -r "$follow_cwd/$token" ] || return 1
+    follow_located="$follow_cwd/$token"
+    return 0
+  fi
   while IFS= read -r base; do
     [ -n "$base" ] || continue
     if [ -f "$base/$token" ] && [ -r "$base/$token" ]; then
       follow_located="$base/$token"
       return 0
     fi
-  done <<<"$PWD"$'\n'"$proj$follow_bases"
+  done <<<"$PWD"$'\n'"$proj"
   return 1
 }
 
@@ -636,7 +727,15 @@ follow_take() {
   follow_names="$follow_names $path"
   followed_text="$followed_text"$'\n'"$content"
   if [ "$depth" -lt "$FOLLOW_MAX_DEPTH" ]; then
+    # A `cd` inside the followed script governs what THAT script goes on to
+    # execute, and nothing after it in the command that ran the script — the
+    # child inherits this directory but cannot change the parent's. Saving and
+    # restoring is what keeps a nested `cd` from silently re-pointing the rest
+    # of the outer walk.
+    local saved_cwd="$follow_cwd" saved_unknown="$follow_cwd_unknown"
     follow_scan "$content" "$((depth + 1))"
+    follow_cwd="$saved_cwd"
+    follow_cwd_unknown="$saved_unknown"
   fi
 }
 
@@ -861,7 +960,11 @@ follow_scan() {
         cd)
           if [ $((i + 1)) -lt "$n" ]; then
             follow_unwrap "${toks[i + 1]}"
-            follow_add_base "$follow_unwrapped"
+            follow_cd "$follow_unwrapped"
+          else
+            # A bare `cd` is `cd "$HOME"`, and leaving the previous directory in
+            # place would resolve later tokens from a directory the shell left.
+            follow_cd "${HOME:-}"
           fi
           cmd_pos=0
           i=$((i + 1))

package/scripts/check-typecheck-tests.mjs

@@ -27,6 +27,33 @@
  * threshold-ratchet as an `allow-list` family, so *adding* an entry is flagged
  * by a gate somebody already reads.
  *
+ * IT REFUSES TO ANSWER FROM AN UNRESOLVABLE TREE (CodySwannGT/lisa#3913). The
+ * second of those ratchet directions is the destructive one: it names files and
+ * tells a reader to delete their quarantine entries. With an empty
+ * `node_modules` the compiler cannot start, nothing is compiled, no diagnostic
+ * is parsed — and "no diagnostic for this file" is exactly the shape of "this
+ * file was fixed". The gate reported all 370 quarantined files as cleared and
+ * instructed their removal, which is a destructive edit ordered on the strength
+ * of a comparison whose inputs never resolved.
+ *
+ * So there are two ways this refuses instead of reporting, and the second is
+ * the general one:
+ *
+ *   - the compiler is not present at the path this spawns it from; and
+ *   - the compiler signalled failure and produced NOT ONE parseable
+ *     diagnostic, which also covers a broken tsconfig, an OOM and a crash.
+ *
+ * Both exit non-zero with the denial first and NO file list, because a gate
+ * whose only surface is an exit code cannot invent a third one — see
+ * `scripts/lib/dependency-tree.mjs` for why the wording is a contract rather
+ * than a string.
+ *
+ * `--root` EXISTS SO THIS CAN BE POINTED AT A FIXTURE. Deriving the root solely
+ * from `import.meta.url` made the failure above reproducible only by copying
+ * this file somewhere else, and `check-empty-subject-guards.mjs` reads that
+ * token out of this header to decide the gate is probeable at all — without it
+ * this sits in that sweep's declared blind spot.
+ *
  * WHAT IS DELIBERATELY NOT DONE HERE: the declared `lib` is not widened. tsc
  * emits "Try changing the 'lib' compiler option to 'es2023' or later" on the
  * ES2023 array APIs, and taking that suggestion would have erased the
@@ -38,110 +65,240 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import * as path from "node:path";
+import process from "node:process";
 import { fileURLToPath } from "node:url";
 
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-const QUARANTINE = path.join(ROOT, "typecheck-quarantine.json");
-const PROJECT = path.join(ROOT, "tsconfig.tests.json");
+import {
+  cannotMeasure,
+  INSTALL_COMMAND,
+  missingDependencies,
+  ranVacuously,
+} from "./lib/dependency-tree.mjs";
+import { invokedAsScript } from "./lib/invoked-as-script.mjs";
+
+const DEFAULT_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+
+/** The gate's name, as it prints in both the report and the refusal. */
+const GATE = "type-correctness (tests)";
+
+/** Where the compiler is spawned from, relative to the root. */
+const TSC = path.join("node_modules", "typescript", "bin", "tsc");
 
 /** Matches `path/to/file.ts(12,34): error TS1234: message`. */
 const ERROR_LINE = /^(?<file>[^(]+)\((?<line>\d+),\d+\): error (?<code>TS\d+):/;
 
 /**
  * Read the quarantined paths.
- * @returns {{files: string[], reason: string}} The parsed quarantine.
+ * @param {string} root - The directory holding the quarantine.
+ * @returns {{files: string[], reason: string} | null} The parsed quarantine, or
+ *   `null` when it could not be read — an unreadable list is a refusal, not a
+ *   pass, because that file is what makes this gate green.
  */
-function readQuarantine() {
+function readQuarantine(root) {
+  const quarantine = path.join(root, "typecheck-quarantine.json");
   try {
-    const parsed = JSON.parse(readFileSync(QUARANTINE, "utf-8"));
+    const parsed = JSON.parse(readFileSync(quarantine, "utf-8"));
     return { files: parsed.files ?? [], reason: parsed.reason ?? "" };
   } catch (error) {
     console.error(
-      `check-typecheck-tests: cannot read ${path.relative(ROOT, QUARANTINE)} — ${error.message}`
+      `check-typecheck-tests: cannot read ${path.relative(root, quarantine)} — ${error.message}`
     );
     console.error(
       "That file is what makes this gate green, so an unreadable one is a refusal, not a pass."
     );
-    process.exit(1);
+    return null;
   }
 }
 
-const { files: quarantined } = readQuarantine();
-const exempt = new Set(quarantined);
-
-const tsc = spawnSync(
-  process.execPath,
-  [
-    path.join(ROOT, "node_modules", "typescript", "bin", "tsc"),
-    "--noEmit",
-    "-p",
-    PROJECT,
-  ],
-  { cwd: ROOT, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 }
-);
-
-if (tsc.error) {
-  console.error(
-    `check-typecheck-tests: could not run tsc — ${tsc.error.message}`
-  );
-  process.exit(1);
+/**
+ * Parse tsc's output into a per-file error count.
+ * @param {string} output - Combined stdout and stderr.
+ * @returns {Map<string, number>} Errors keyed by forward-slashed path.
+ */
+function parseDiagnostics(output) {
+  /** @type {Map<string, number>} */
+  const errorsByFile = new Map();
+  for (const line of output.split("\n")) {
+    const match = ERROR_LINE.exec(line.trim());
+    if (!match?.groups) continue;
+    const file = match.groups.file.replace(/\\/g, "/");
+    errorsByFile.set(file, (errorsByFile.get(file) ?? 0) + 1);
+  }
+  return errorsByFile;
 }
 
-const lines = `${tsc.stdout ?? ""}\n${tsc.stderr ?? ""}`.split("\n");
-/** @type {Map<string, number>} */
-const errorsByFile = new Map();
-for (const line of lines) {
-  const match = ERROR_LINE.exec(line.trim());
-  if (!match?.groups) continue;
-  const file = match.groups.file.replace(/\\/g, "/");
-  errorsByFile.set(file, (errorsByFile.get(file) ?? 0) + 1);
+/**
+ * The refusal issued when nothing was compiled.
+ *
+ * The denial names the destructive remedy explicitly. "Nothing type-checked" is
+ * the inference a reader draws from an empty diagnostic set, and the gate's own
+ * cleared-entry message is what turns that inference into a deletion — so this
+ * has to deny both, not just the first.
+ *
+ * NO FILE IS NAMED HERE, deliberately. A list of paths is what makes the
+ * destructive message actionable, and a refusal that still printed 370 paths
+ * would be followed exactly as often as the finding it replaces.
+ *
+ * @param {string} because - Why the measurement could not happen.
+ * @param {number} quarantined - How many entries went unexamined.
+ * @param {string} fix - The action that repairs THIS cause. Named per call
+ *   site rather than fixed, because telling someone to install dependencies
+ *   they already have is how a refusal gets dismissed as noise.
+ * @returns {string} The refusal block.
+ */
+function refuseUnmeasurable(because, quarantined, fix) {
+  return cannotMeasure({
+    gate: GATE,
+    denial: `that any of the ${quarantined} quarantined file(s) now type-check`,
+    because,
+    remedy:
+      `${fix} Do NOT edit typecheck-quarantine.json on the strength of ` +
+      `this — no file was compiled, so nothing was established about any ` +
+      `entry in it.`,
+  });
 }
 
-const offenders = [...errorsByFile.keys()]
-  .filter(file => !exempt.has(file))
-  .sort();
-const cleared = quarantined.filter(file => !errorsByFile.has(file)).sort();
+/**
+ * Run the gate.
+ * @param {string} root - Directory to resolve the project and quarantine under.
+ * @returns {number} The process exit code.
+ */
+export function main(root) {
+  const quarantine = readQuarantine(root);
+  if (quarantine === null) return 1;
+  const quarantined = quarantine.files;
+  const exempt = new Set(quarantined);
 
-const totalErrors = [...errorsByFile.values()].reduce((sum, n) => sum + n, 0);
-console.log(
-  `type-correctness (tests): ${errorsByFile.size} file(s) with ${totalErrors} error(s); ` +
-    `${quarantined.length} quarantined.`
-);
+  // PRECONDITION. Checked before the spawn rather than inferred from it: the
+  // spawn SUCCEEDS with an empty `node_modules` — node starts, and it is node
+  // that cannot find the module — so `tsc.error` never fires and the failure
+  // arrives as an empty diagnostic set indistinguishable from a clean run.
+  const missing = missingDependencies(root, [TSC]);
+  if (missing.length > 0) {
+    console.error(
+      refuseUnmeasurable(
+        `the TypeScript compiler is not installed — no file at ${missing[0]}.`,
+        quarantined.length,
+        `Run \`${INSTALL_COMMAND}\`, then re-run this gate.`
+      )
+    );
+    return 1;
+  }
 
-if (offenders.length > 0) {
-  console.error("");
-  console.error(
-    `❌ ${offenders.length} file(s) outside the quarantine have type errors:`
+  const tsc = spawnSync(
+    process.execPath,
+    [
+      path.join(root, TSC),
+      "--noEmit",
+      "-p",
+      path.join(root, "tsconfig.tests.json"),
+    ],
+    { cwd: root, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 }
   );
-  for (const file of offenders) {
-    console.error(`   ${file} (${errorsByFile.get(file)})`);
+
+  if (tsc.error) {
+    console.error(
+      `check-typecheck-tests: could not run tsc — ${tsc.error.message}`
+    );
+    return 1;
   }
-  console.error("");
-  console.error(
-    "Fix them. Do NOT add them to typecheck-quarantine.json — that list"
-  );
-  console.error(
-    "only shrinks, and the threshold-ratchet flags additions to it."
-  );
-}
 
-if (cleared.length > 0) {
-  console.error("");
-  console.error(
-    `❌ ${cleared.length} quarantined file(s) now type-check and must leave the list:`
+  const errorsByFile = parseDiagnostics(
+    `${tsc.stdout ?? ""}\n${tsc.stderr ?? ""}`
   );
-  for (const file of cleared) console.error(`   ${file}`);
-  console.error("");
-  console.error(
-    "Remove them from typecheck-quarantine.json. A list that keeps entries"
+
+  // POSTCONDITION, and the general form of the same defect. The compiler
+  // signalled failure and produced nothing this gate can read, so the
+  // comparison below would run against an empty set — the exact shape of "every
+  // quarantined file is fixed". A ZERO exit with no diagnostics is not this: it
+  // is a clean run, and it reports normally.
+  if (ranVacuously(tsc.status, errorsByFile.size)) {
+    const firstLine = `${tsc.stderr ?? ""}${tsc.stdout ?? ""}`
+      .split("\n")
+      .map(line => line.trim())
+      .find(Boolean);
+    console.error(
+      refuseUnmeasurable(
+        `tsc exited ${tsc.status} without emitting one diagnostic this gate ` +
+          `could parse, so the comparison had no subject.` +
+          `${firstLine ? ` First output line: ${firstLine}` : ""}`,
+        quarantined.length,
+        "Fix the cause named above, then re-run this gate."
+      )
+    );
+    return 1;
+  }
+
+  const offenders = [...errorsByFile.keys()]
+    .filter(file => !exempt.has(file))
+    .sort();
+  const cleared = quarantined.filter(file => !errorsByFile.has(file)).sort();
+
+  const totalErrors = [...errorsByFile.values()].reduce((sum, n) => sum + n, 0);
+  console.log(
+    `${GATE}: ${errorsByFile.size} file(s) with ${totalErrors} error(s); ` +
+      `${quarantined.length} quarantined.`
   );
-  console.error(
-    "after they are fixed would re-authorise them if they ever regressed."
+
+  if (offenders.length > 0) {
+    console.error("");
+    console.error(
+      `❌ ${offenders.length} file(s) outside the quarantine have type errors:`
+    );
+    for (const file of offenders) {
+      console.error(`   ${file} (${errorsByFile.get(file)})`);
+    }
+    console.error("");
+    console.error(
+      "Fix them. Do NOT add them to typecheck-quarantine.json — that list"
+    );
+    console.error(
+      "only shrinks, and the threshold-ratchet flags additions to it."
+    );
+  }
+
+  if (cleared.length > 0) {
+    console.error("");
+    console.error(
+      `❌ ${cleared.length} quarantined file(s) now type-check and must leave the list:`
+    );
+    for (const file of cleared) console.error(`   ${file}`);
+    console.error("");
+    console.error(
+      "Remove them from typecheck-quarantine.json. A list that keeps entries"
+    );
+    console.error(
+      "after they are fixed would re-authorise them if they ever regressed."
+    );
+  }
+
+  if (offenders.length > 0 || cleared.length > 0) return 1;
+
+  console.log(
+    "✅ No type errors outside the quarantine, and no stale quarantine entries."
   );
+  return 0;
 }
 
-if (offenders.length > 0 || cleared.length > 0) process.exit(1);
+/**
+ * Resolve the root from `--root <dir>`, defaulting to the repository.
+ * @param {ReadonlyArray<string>} argv - Arguments after the script name.
+ * @returns {string} The absolute root.
+ */
+export function rootFrom(argv) {
+  const flag = argv.indexOf("--root");
+  if (flag === -1) return DEFAULT_ROOT;
+  const value = argv[flag + 1];
+  if (value === undefined) {
+    console.error("check-typecheck-tests: --root requires a value");
+    process.exit(2);
+  }
+  return path.resolve(value);
+}
 
-console.log(
-  "✅ No type errors outside the quarantine, and no stale quarantine entries."
-);
+if (invokedAsScript(import.meta.url)) {
+  process.exit(main(rootFrom(process.argv.slice(2))));
+}