jules-orchestrator-kit 0.70.0 → 0.72.0

package/src/config.mjs

@@ -205,7 +205,13 @@ const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
 function coerce(val) {
   if (!val) return "";
-  if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+  if (val.startsWith("'") && val.endsWith("'") && val.length >= 2) {
+    // `''` is how a single-quoted YAML scalar escapes a quote, and it is what
+    // `yamlScalar` emits. Reading the quotes off without undoing the escape
+    // meant the emitter and the parser disagreed about the same file.
+    return val.slice(1, -1).replace(/''/g, "'");
+  }
+  if (val.startsWith('"') && val.endsWith('"') && val.length >= 2) {
     return val.slice(1, -1);
   }
   if (val === "true") return true;
@@ -315,6 +321,86 @@ export function normalizeScope(parsed = {}) {
   };
 }
 
+/**
+ * A YAML scalar quoted only as much as YAML requires.
+ *
+ * The scaffold wrapped every generated string in double quotes, which is valid
+ * YAML and idiomatic nowhere. On a repository that lints its own YAML that is a
+ * hard red on the kit's own files: measured on `unjs/unimport`, following the
+ * README verbatim produced 40 eslint errors — `yaml/quotes` and
+ * `yaml/plain-scalar` — across `.agent/config.yml` and `.agent/jules.yml`, so a
+ * newcomer's very first `agentctl check` failed on output `agentctl init` had
+ * just written, in a repository that was green a minute earlier. Teaching a new
+ * user that the gate is broken is the most expensive thing this tool can do.
+ *
+ * Nothing here is specific to eslint or to that repository. Emitting a plain
+ * scalar where YAML permits one, and single quotes where it does not, is simply
+ * how YAML is written; the linters that check it are agreeing with the spec.
+ *
+ * The quoting test is deliberately conservative — anything that could change
+ * meaning unquoted gets quotes. A glob beginning with a star stays quoted,
+ * because a leading `*` is an alias reference; `pnpm -r test` does not, because
+ * there is nothing in it to misread.
+ */
+const YAML_NEEDS_QUOTES =
+  /^$|^[-?:,[\]{}#&*!|>'"%@`]|^\s|\s$|:\s|\s#|:$|[\n\r\t]|^(?:true|false|yes|no|on|off|null|~)$/i;
+
+export function yamlScalar(value) {
+  const s = value === null || value === undefined ? "" : String(value);
+  if (!YAML_NEEDS_QUOTES.test(s) && !/^[+-]?(?:\d[\d_]*)(?:\.[\d_]*)?(?:[eE][+-]?\d+)?$/.test(s)) return s;
+  return `'${s.replace(/'/g, "''")}'`;
+}
+
+/**
+ * Can a quoted scalar begin at this offset?
+ *
+ * A quote character is only an opening quote where a value may start — after
+ * `key:`, after a `-` list marker, at the head of a flow collection, or at the
+ * start of the line. Anywhere else it is an ordinary apostrophe, and treating
+ * `test: it's fine` as an unterminated string would swallow the rest of it.
+ */
+function opensQuotedScalar(line, i) {
+  return /(?:^\s*|:\s+|-\s+|[[{,]\s*)$/.test(line.slice(0, i));
+}
+
+/**
+ * Strip a trailing `#` comment without cutting into a quoted scalar.
+ *
+ * `rawLine.indexOf("#")` stood here, which is not the YAML rule twice over: a
+ * `#` opens a comment only when it begins the line or follows whitespace, and
+ * never inside quotes. So any configured value containing a hash was silently
+ * truncated on the way in — `test: 'pytest -k "not #slow"'` became
+ * `test: 'pytest -k "not`, and the gate then ran a command the user never
+ * wrote. Silent truncation of a verification command is the worst shape this
+ * file can produce, because every later phase reports on whatever did run.
+ *
+ * It matters more now that `yamlScalar` exists: an emitter and a parser that
+ * disagree about the same file is this project's recurring defect with both
+ * halves in one module.
+ */
+function stripYamlComment(rawLine) {
+  let quote = null;
+  for (let i = 0; i < rawLine.length; i++) {
+    const ch = rawLine[i];
+    if (quote) {
+      if (quote === '"' && ch === "\\") {
+        i++;
+      } else if (ch === quote) {
+        // `''` is an escaped quote inside a single-quoted scalar, not the end.
+        if (quote === "'" && rawLine[i + 1] === "'") i++;
+        else quote = null;
+      }
+      continue;
+    }
+    if ((ch === '"' || ch === "'") && opensQuotedScalar(rawLine, i)) {
+      quote = ch;
+      continue;
+    }
+    if (ch === "#" && (i === 0 || /\s/.test(rawLine[i - 1]))) return rawLine.slice(0, i);
+  }
+  return rawLine;
+}
+
 /**
  * Indent-stack zero-dependency YAML parser with prototype pollution protection.
  */
@@ -331,8 +417,7 @@ export function parseYaml(src) {
   const lines = src.split("\n");
 
   for (let rawLine of lines) {
-    const commentIdx = rawLine.indexOf("#");
-    const line = commentIdx !== -1 ? rawLine.slice(0, commentIdx) : rawLine;
+    const line = stripYamlComment(rawLine);
     const trimmed = line.trim();
     if (!trimmed) continue;
 
@@ -433,9 +518,9 @@ export function detectPackageManager(root = process.cwd(), pkg = {}) {
   return "npm";
 }
 
-import { buildProfileStages, PROFILE_NAMES, PROFILE_DESCRIPTIONS } from "./profiles.mjs";
+import { buildProfileStages, buildDefaultStages, PROFILE_NAMES, PROFILE_DESCRIPTIONS } from "./profiles.mjs";
 
-export { buildProfileStages, PROFILE_NAMES, PROFILE_DESCRIPTIONS };
+export { buildProfileStages, buildDefaultStages, PROFILE_NAMES, PROFILE_DESCRIPTIONS };
 
 import {
   detectPolyglotStack,
@@ -444,6 +529,7 @@ import {
   findSubprojectRoot,
   detectCrossPackageBoundaryViolations,
   detectCircularDependencies,
+  isPlaceholderTestScript,
 } from "./stack-detector.mjs";
 
 export {
@@ -453,8 +539,11 @@ export {
   findSubprojectRoot,
   detectCrossPackageBoundaryViolations,
   detectCircularDependencies,
+  isPlaceholderTestScript,
 };
 
+import { showFromOrigin, detectDefaultBranch } from "./git.mjs";
+
 /**
  * Autodetects verification test/build commands across 24+ polyglot tech stacks.
  */
@@ -703,6 +792,7 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
       // Named so `doctor` can tell an operator that the gate they enabled is
       // running one fewer check than they think, and why.
       profileSkipped: profilePlan?.skipped ?? [],
+      minTests: parsed.verify?.minTests ?? parsed.verify?.min_tests ?? (parsed.minTests ?? parsed.min_tests ?? 1),
       timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 300_000,
     },
     evidence: {
@@ -780,3 +870,342 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
 
   return config;
 }
+
+/**
+ * Verifies that a bootstrap scaffold (introduced in a repository whose base has
+ * no gate configuration yet) does not weaken verification, lower profiles,
+ * bypass tests, disable strict locks, or tamper with security invariants (F06, F08).
+ *
+ * @param {string} root - repository root
+ * @param {object} proposedConfig - parsed .agent/config.yml if present
+ * @param {object} proposedJules - parsed .agent/jules.yml if present
+ * @param {object} autoVerify - autodetected verification commands
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function checkBootstrapPolicyIntegrity(root, proposedConfig = {}, proposedJules = {}, autoVerify = {}) {
+  const pConfig = proposedConfig || {};
+  const pJules = proposedJules || {};
+
+  const testCmd = pConfig.verify?.test ?? pConfig.test_cmd ?? pJules.test_cmd ?? pJules.verify?.test;
+  if (testCmd !== undefined && testCmd !== null) {
+    const str = String(testCmd).trim();
+    if (str && isPlaceholderTestScript(str)) {
+      return {
+        ok: false,
+        error: `Bootstrap policy rejected: verify.test cannot be a placeholder command (${JSON.stringify(str)}) in uncommitted scaffold (F06).`,
+      };
+    }
+    if (!str && autoVerify.test) {
+      return {
+        ok: false,
+        error: `Bootstrap policy rejected: verify.test cannot be empty when repository has detected tests (${autoVerify.test}).`,
+      };
+    }
+  }
+
+  const profile = pConfig.verify?.profile ?? pConfig.profile ?? pJules.verify?.profile ?? pJules.profile;
+  if (profile && String(profile).toLowerCase() === "minimal") {
+    return {
+      ok: false,
+      error: 'Bootstrap policy rejected: verify.profile cannot be lowered to "minimal" in uncommitted scaffold (F06).',
+    };
+  }
+
+  const required = pConfig.verify?.required ?? pJules.verify?.required;
+  if (required === false) {
+    return {
+      ok: false,
+      error: "Bootstrap policy rejected: verify.required cannot be set to false in uncommitted scaffold.",
+    };
+  }
+
+  const strictLock =
+    pConfig.evidence?.strict_test_lock ??
+    pConfig.evidence?.strictTestLock ??
+    pJules.evidence?.strict_test_lock ??
+    pJules.evidence?.strictTestLock;
+  if (strictLock === false) {
+    return {
+      ok: false,
+      error: "Bootstrap policy rejected: evidence.strictTestLock cannot be disabled in uncommitted scaffold.",
+    };
+  }
+
+  const tamperGuard =
+    pConfig.verify?.tamper_guard ??
+    pConfig.verify?.tamperGuard ??
+    pJules.verify?.tamper_guard ??
+    pJules.verify?.tamperGuard;
+  if (tamperGuard === false) {
+    return {
+      ok: false,
+      error: "Bootstrap policy rejected: verify.tamperGuard cannot be disabled in uncommitted scaffold.",
+    };
+  }
+
+  const baseBranch = pConfig.base_branch ?? pConfig.baseBranch ?? pJules.base_branch ?? pJules.baseBranch;
+  if (baseBranch && String(baseBranch).toUpperCase() === "HEAD") {
+    return {
+      ok: false,
+      error: 'Bootstrap policy rejected: base_branch cannot be set to "HEAD" (F08).',
+    };
+  }
+
+  const stages = pConfig.verify?.stages ?? pJules.verify?.stages;
+  if (Array.isArray(stages)) {
+    if (stages.length === 0) {
+      return {
+        ok: false,
+        error: "Bootstrap policy rejected: verify.stages cannot be empty in uncommitted scaffold.",
+      };
+    }
+    const hasTestStage = stages.some(
+      (s) => (s.kind === "test" || s.kind === "unit") && s.cmd && !isPlaceholderTestScript(s.cmd)
+    );
+    if (!hasTestStage && autoVerify.test) {
+      return {
+        ok: false,
+        error: "Bootstrap policy rejected: verify.stages must include a valid test/unit command in uncommitted scaffold.",
+      };
+    }
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Resolves the authoritative security policy and verification plan from the
+ * trusted base commit (or pristine bootstrap baseline), guaranteeing that
+ * untrusted edits in the working tree, staged index, or branch diff under
+ * review cannot weaken verification, disable security guards, or redirect
+ * the trusted base (F06, F07, F08).
+ *
+ * @param {string} root - repository root
+ * @param {string} [baseRef] - explicit base reference (e.g. from CLI --base)
+ * @param {string} [mode="working-tree"] - "working-tree" | "staged" | "committed"
+ * @param {object} [opts={}] - additional options (e.g. allowProtected, config)
+ * @returns {{
+ *   ok: boolean,
+ *   code?: number,
+ *   error?: string,
+ *   base: string,
+ *   scope: { deny: string[], allow: string[], protect: string[] },
+ *   verify: object,
+ *   limits: object,
+ *   evidence: { strictTestLock: boolean },
+ *   isBootstrap: boolean,
+ *   rawConfig: string | null,
+ * }}
+ */
+export function resolveTrustedPolicy(root = process.cwd(), baseRef = null, mode = "working-tree", opts = {}) {
+  // 1. Resolve base branch
+  let base = baseRef || opts.base;
+  if (!base) {
+    if (mode === "committed") {
+      base = detectDefaultBranch(root) || "main";
+    } else {
+      const diskConfig = opts.config || (existsSync(join(root, ".agent/config.yml")) ? loadConfig(root) : null);
+      base = diskConfig?.baseBranch || detectDefaultBranch(root) || "main";
+    }
+  }
+
+  // F08 Guard: In committed mode, base branch can never be HEAD
+  // (Comparing a commit against itself would produce an empty diff and bypass the gate)
+  if (mode === "committed" && (base === "HEAD" || base === "HEAD^0")) {
+    return {
+      ok: false,
+      code: 3,
+      error: 'Cannot evaluate committed diff against base "HEAD": comparing a revision to itself would bypass the safety gate (F08).',
+      base,
+      isBootstrap: false,
+    };
+  }
+
+  let trustedConfigRaw = null;
+  let trustedJulesRaw = null;
+  try {
+    trustedConfigRaw = showFromOrigin(root, base, ".agent/config.yml");
+    trustedJulesRaw = showFromOrigin(root, base, ".agent/jules.yml");
+  } catch (_) {
+    // If base branch cannot be resolved or show fails, let changedFiles report code 1
+  }
+
+  const autoVerify = resolveVerify(root);
+
+  if (trustedConfigRaw || trustedJulesRaw) {
+    const raw = trustedConfigRaw || trustedJulesRaw;
+    let parsed = {};
+    try {
+      if (raw) parsed = parseYaml(raw) || {};
+    } catch (_) {}
+
+    const trustedScope = normalizeScope(parsed);
+    const trustedDiffKb = Number(parsed.limits?.diff_kb || parsed.limits?.diffKb) || 75;
+
+    const rawSetup = parsed.setup_cmd ?? parsed.verify?.setup;
+    const rawTest = parsed.test_cmd ?? parsed.verify?.test;
+    const rawLint = parsed.lint_cmd ?? parsed.verify?.lint;
+    const rawFuzz = parsed.fuzz_cmd ?? parsed.verify?.fuzz;
+    const rawInvariant = parsed.invariant_cmd ?? parsed.verify?.invariant;
+    const rawE2e = parsed.e2e_cmd ?? parsed.verify?.e2e;
+    const rawTeardown = parsed.teardown_cmd ?? parsed.verify?.teardown;
+    const rawBuild = parsed.build_cmd ?? parsed.verify?.build;
+    const rawUnit = parsed.verify?.unit;
+    const verifyTimeoutMs = parsed.verify?.timeoutMs ?? parsed.verify?.timeout_ms ?? 300_000;
+
+    const mergedVerify = {
+      stack: autoVerify.stack || "unknown",
+      setup: rawSetup ?? autoVerify.setup ?? "",
+      lint: rawLint ?? autoVerify.lint ?? "",
+      test: rawTest ?? autoVerify.test,
+      unit: rawUnit ?? rawTest ?? autoVerify.unit ?? autoVerify.test,
+      fuzz: rawFuzz ?? autoVerify.fuzz ?? "",
+      invariant: rawInvariant ?? autoVerify.invariant ?? "",
+      e2e: rawE2e ?? autoVerify.e2e ?? "",
+      teardown: rawTeardown ?? autoVerify.teardown ?? "",
+      build: rawBuild ?? autoVerify.build,
+      policy: parsed.verify?.policy ?? autoVerify.policy,
+      scope: parsed.verify?.scope === "affected" ? "affected" : "global",
+      required: parsed.verify?.required !== undefined ? parsed.verify.required !== false : true,
+      minTests: parsed.verify?.minTests ?? parsed.verify?.min_tests ?? 1,
+      tamperGuard: parsed.verify?.tamperGuard ?? parsed.verify?.tamper_guard ?? true,
+      timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 300_000,
+    };
+
+    const rawProfile = parsed.verify?.profile ?? parsed.profile ?? null;
+    const explicitStages = parsed.verify?.stages ?? null;
+    const profilePlan =
+      !explicitStages && rawProfile
+        ? buildProfileStages(rawProfile, { stack: autoVerify.stack, verify: mergedVerify })
+        : null;
+
+    const stages = explicitStages ?? profilePlan?.stages ?? null;
+
+    return {
+      ok: true,
+      base,
+      scope: trustedScope,
+      verify: {
+        ...mergedVerify,
+        stages,
+        profile: profilePlan?.profile ?? (rawProfile ? String(rawProfile).toLowerCase() : null),
+        profileSkipped: profilePlan?.skipped ?? [],
+      },
+      limits: { diffKb: trustedDiffKb },
+      evidence: {
+        strictTestLock: parsed.evidence?.strict_test_lock ?? parsed.evidence?.strictTestLock ?? true,
+      },
+      isBootstrap: false,
+      rawConfig: raw,
+    };
+  }
+
+  // Bootstrap mode: base has no configuration file
+  // Inspect any proposed scaffold in this change (F06)
+  let proposedConfig = null;
+  let proposedJules = null;
+
+  try {
+    if (mode === "committed") {
+      const c = showFromOrigin(root, "HEAD", ".agent/config.yml");
+      if (c) proposedConfig = parseYaml(c);
+      const j = showFromOrigin(root, "HEAD", ".agent/jules.yml");
+      if (j) proposedJules = parseYaml(j);
+    } else {
+      const configPath = join(root, ".agent/config.yml");
+      if (existsSync(configPath)) proposedConfig = parseYaml(readFileSync(configPath, "utf-8"));
+      const julesPath = join(root, ".agent/jules.yml");
+      if (existsSync(julesPath)) proposedJules = parseYaml(readFileSync(julesPath, "utf-8"));
+    }
+  } catch (_) {}
+
+  const effectiveProposed = proposedConfig || proposedJules || opts.config || null;
+
+  if (proposedConfig || proposedJules) {
+    const integrity = checkBootstrapPolicyIntegrity(root, proposedConfig, proposedJules, autoVerify);
+    if (!integrity.ok) {
+      return {
+        ok: false,
+        code: 3,
+        error: integrity.error,
+        base,
+        scope: normalizeScope({}),
+        verify: {
+          ...autoVerify,
+          stages: null,
+          required: true,
+          tamperGuard: true,
+          minTests: 1,
+          timeoutMs: 300_000,
+        },
+        limits: { diffKb: 75 },
+        evidence: { strictTestLock: true },
+        isBootstrap: true,
+        rawConfig: null,
+      };
+    }
+  }
+
+  const pConfig = effectiveProposed || {};
+  const rawSetup = pConfig.setup_cmd ?? pConfig.verify?.setup;
+  const rawTest = pConfig.test_cmd ?? pConfig.verify?.test;
+  const rawLint = pConfig.lint_cmd ?? pConfig.verify?.lint;
+  const rawFuzz = pConfig.fuzz_cmd ?? pConfig.verify?.fuzz;
+  const rawInvariant = pConfig.invariant_cmd ?? pConfig.verify?.invariant;
+  const rawE2e = pConfig.e2e_cmd ?? pConfig.verify?.e2e;
+  const rawTeardown = pConfig.teardown_cmd ?? pConfig.verify?.teardown;
+  const rawBuild = pConfig.build_cmd ?? pConfig.verify?.build;
+  const rawUnit = pConfig.verify?.unit;
+  const verifyTimeoutMs = pConfig.verify?.timeoutMs ?? pConfig.verify?.timeout_ms ?? 300_000;
+
+  const mergedBootstrapVerify = {
+    stack: autoVerify.stack || "unknown",
+    setup: rawSetup ?? autoVerify.setup ?? "",
+    lint: rawLint ?? autoVerify.lint ?? "",
+    test: rawTest ?? autoVerify.test,
+    unit: rawUnit ?? rawTest ?? autoVerify.unit ?? autoVerify.test,
+    fuzz: rawFuzz ?? autoVerify.fuzz ?? "",
+    invariant: rawInvariant ?? autoVerify.invariant ?? "",
+    e2e: rawE2e ?? autoVerify.e2e ?? "",
+    teardown: rawTeardown ?? autoVerify.teardown ?? "",
+    build: rawBuild ?? autoVerify.build,
+    policy: pConfig.verify?.policy ?? autoVerify.policy,
+    scope: pConfig.verify?.scope === "affected" ? "affected" : "global",
+    required: pConfig.verify?.required !== undefined ? pConfig.verify.required !== false : true,
+    minTests: pConfig.verify?.minTests ?? pConfig.verify?.min_tests ?? 1,
+    tamperGuard: pConfig.verify?.tamperGuard ?? pConfig.verify?.tamper_guard ?? true,
+    timeoutMs: Number.isFinite(Number(verifyTimeoutMs)) ? Number(verifyTimeoutMs) : 300_000,
+  };
+
+  const rawProfile = pConfig.verify?.profile ?? pConfig.profile ?? null;
+  const explicitStages = pConfig.verify?.stages ?? null;
+  const profilePlan =
+    !explicitStages && rawProfile
+      ? buildProfileStages(rawProfile, { stack: autoVerify.stack, verify: mergedBootstrapVerify })
+      : null;
+
+  const stages = explicitStages ?? profilePlan?.stages ?? null;
+  const trustedScope = normalizeScope(pConfig);
+  const trustedLimits = {
+    diffKb: Number(pConfig.limits?.diff_kb || pConfig.limits?.diffKb) || 75,
+  };
+  const trustedEvidence = {
+    strictTestLock: pConfig.evidence?.strict_test_lock ?? pConfig.evidence?.strictTestLock ?? true,
+  };
+
+  return {
+    ok: true,
+    base,
+    scope: trustedScope,
+    verify: {
+      ...mergedBootstrapVerify,
+      stages,
+      profile: profilePlan?.profile ?? (rawProfile ? String(rawProfile).toLowerCase() : null),
+      profileSkipped: profilePlan?.skipped ?? [],
+    },
+    limits: trustedLimits,
+    evidence: trustedEvidence,
+    isBootstrap: true,
+    rawConfig: null,
+  };
+}

package/src/coverage.mjs

@@ -31,6 +31,42 @@ export function isExcludedFromCoverage(filePath = "") {
   return false;
 }
 
+/**
+ * Extensions V8 could have observed. Coverage outside this family is not a
+ * measurement that returned nothing — it is no measurement at all, and a
+ * hard red there is how the gate gets switched off.
+ */
+const V8_OBSERVABLE_EXT = new Set([".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"]);
+
+const isV8Observable = (file) => {
+  const dot = file.lastIndexOf(".");
+  return dot !== -1 && V8_OBSERVABLE_EXT.has(file.slice(dot).toLowerCase());
+};
+
+/**
+ * Lines of source text that are executable on their own — the denominator a
+ * line coverage measure would count. V8's own mapper only emits entries for
+ * lines its function ranges *observed*; a file Node never imported has no
+ * functions at all, so every executable line in it was previously invisible
+ * and a 0/0 diff was reported as a passing 100% (F12). The heuristic stays
+ * deliberately conservative: comments, blank lines, and pure declarations
+ * (imports, exports of names alone) do not count.
+ */
+export function executableLineNumbers(sourceContent = "") {
+  const lines = sourceContent.split("\n");
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*")) continue;
+    if (trimmed.startsWith("import ")) continue;
+    if (/^(?:export\s+)?(?:default\s+)?(?:class|function|const|let|var)\s+[A-Za-z_$][\w$]*\s*$/.test(trimmed)) continue;
+    if (trimmed === "{" || trimmed === "}" || trimmed === "};") continue;
+    out.push(i + 1);
+  }
+  return out;
+}
+
 /**
  * Maps V8 function range offsets to 1-indexed line hit counts.
  * @param {string} sourceContent - Full text of source file
@@ -267,6 +303,11 @@ export function calculateDiffCoverage(coverageByFile, diffStr = "", options = {}
   let totalLines = 0;
   let coveredLines = 0;
   const missedByFile = {};
+  // Files V8 can measure, but for which the test run produced no coverage
+  // data at all — code Node never imported. Distinct from files V8 cannot
+  // observe (Python, Go, …): those are genuinely not measurable here, and
+  // scoring them zero blocks stacks the gate never claimed to cover.
+  const unobservedExecutableFiles = [];
 
   for (const [file, addedLines] of addedLinesMap.entries()) {
     const absPath = resolve(root, file);
@@ -279,11 +320,20 @@ export function calculateDiffCoverage(coverageByFile, diffStr = "", options = {}
       continue;
     }
 
+    const v8Observable = isV8Observable(file);
     const v8Functions = coverageByFile.get(file) || [];
     const lineHits = mapV8RangesToLines(sourceContent, v8Functions);
 
+    // The executable denominator *from the source itself*, independent of
+    // whether V8 happened to map the file. A file that added executable
+    // lines but never appeared in V8's report ran nothing of what was added.
+    const executableSet = new Set(executableLineNumbers(sourceContent));
+    const neverObserved = v8Observable && v8Functions.length === 0 && addedLines.some((n) => executableSet.has(n));
+    if (neverObserved) unobservedExecutableFiles.push(file);
+
     const missed = [];
     for (const lineNo of addedLines) {
+      const isExecutable = executableSet.has(lineNo);
       if (lineHits.has(lineNo)) {
         totalLines++;
         const count = lineHits.get(lineNo);
@@ -292,6 +342,13 @@ export function calculateDiffCoverage(coverageByFile, diffStr = "", options = {}
         } else {
           missed.push(lineNo);
         }
+      } else if (neverObserved && isExecutable) {
+        // V8 could have seen this line, mapped nothing in the file, and the
+        // line is executable: it was not covered. Counting it is what turns
+        // "0/0 scored" for an unimported module into a real miss — the gate
+        // returning exit 0 on code no test ran is F12.
+        totalLines++;
+        missed.push(lineNo);
       }
     }
 
@@ -302,30 +359,45 @@ export function calculateDiffCoverage(coverageByFile, diffStr = "", options = {}
 
   // 100% of nothing is not 100%.
   //
-  // The denominator counts only the added lines V8 actually mapped, and V8
-  // maps nothing outside Node. So a Python diff adding three executable lines
-  // measured zero of them and was reported as `score: 100` — the best possible
-  // number, produced by a measurement that never happened, on 20-odd of the 25
-  // stacks this kit claims to support. `mutation.mjs` had the identical bug and
-  // was fixed in v0.57.0; this is the same shape one module over.
+  // Two very different ways the denominator can be zero:
+  //
+  //   1. There were no executable added lines to measure, or the diff is in
+  //      code V8 cannot observe (Python, Go, …). The measurement is simply
+  //      not applicable here; `ok` stays true because nothing failed to be
+  //      covered — a gate that blocks every non-Node diff gets switched off.
+  //      What changes is the claim: `scored: false` and a reason.
+  //   2. There were executable lines in code V8 *can* observe, and the test
+  //      run mapped none of them — the file was never imported. A passing
+  //      result on that is the same failure as a line counted uncovered:
+  //      the suite certified code it never ran (F12). That is scored zero,
+  //      not scored nothing.
   //
-  // `ok` stays true because nothing failed to be covered, and a gate that
-  // blocks every non-Node diff gets switched off. What changes is the claim:
-  // `scored: false` and a reason, instead of a number nobody measured.
+  // `mutation.mjs` had the original "100% of 0/0" bug in the first family
+  // and was fixed in v0.57.0; this is the second family, one module over.
+  const measuredNothingExecutable = unobservedExecutableFiles.length > 0 && totalLines === 0;
   const scored = totalLines > 0;
   const score = scored ? Math.round((coveredLines / totalLines) * 10000) / 100 : null;
-  const ok = scored ? score >= minCoverage : true;
+  // N/A only when V8 could not have measured the added code (no executable
+  // lines at all, or a stack V8 does not observe). Executable Node code the
+  // test run never reached is a failure, not an N/A.
+  const notApplicable = !scored && !measuredNothingExecutable;
+  const ok = notApplicable ? true : score >= minCoverage;
 
   return {
     ok,
-    score,
+    score: notApplicable ? null : score,
     scored,
-    ...(scored ? {} : { reason: "No added executable lines were measurable — V8 coverage only observes code Node itself ran, so nothing was scored." }),
+    ...(notApplicable
+      ? { reason: "No added executable lines were measurable — V8 coverage only observes code Node itself ran, so nothing was scored." }
+      : {
+          reason: `Added executable code was never executed by the test run (unobserved: ${unobservedExecutableFiles.join(", ")}) — V8 coverage saw no execution of it, so it counts as uncovered.`,
+          unobservedFiles: unobservedExecutableFiles,
+        }),
     minCoverage,
     totalLines,
     coveredLines,
     missedLines: totalLines - coveredLines,
     missedByFile,
-    summary: `Diff Coverage: ${score}% (${coveredLines}/${totalLines} added executable lines covered, min: ${minCoverage}%)`,
+    summary: `Diff Coverage: ${notApplicable ? "null" : score}% (${coveredLines}/${totalLines} added executable lines covered, min: ${minCoverage}%)`,
   };
 }