@boyingliu01/xp-gate 0.30.2 → 0.30.4

package/lib/__tests__/hook-health.test.js

@@ -0,0 +1,85 @@
+/**
+ * @test REQ-546 hook health: line endings and bash parseability
+ * @intent Verify doctor can tell a hook that merely EXISTS from a hook git can
+ *         actually run. #546: a pre-commit rewritten with CRLF line endings
+ *         failed every commit while `xp-gate doctor` reported it healthy,
+ *         because the check only asked whether the file was there.
+ * @covers AC-05, AC-08
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const { inspectHookFile } = require('../hook-health');
+
+let TMP_DIR;
+
+beforeAll(() => {
+  TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'hook-health-'));
+});
+
+afterAll(() => {
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+function write(name, content) {
+  const p = path.join(TMP_DIR, name);
+  fs.writeFileSync(p, content);
+  return p;
+}
+
+describe('inspectHookFile', () => {
+  test('a healthy LF hook reports ok', () => {
+    const p = write('good.sh', '#!/bin/bash\nfoo() {\n  echo hi\n}\nfoo\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(true);
+    expect(r.crlfLines).toBe(0);
+    expect(r.problems).toEqual([]);
+  });
+
+  test('an all-CRLF hook is reported with a CRLF count', () => {
+    const p = write('crlf.sh', '#!/bin/bash\r\nfoo() {\r\n  echo hi\r\n}\r\nfoo\r\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(false);
+    expect(r.crlfLines).toBe(5);
+    expect(r.problems.join(' ')).toMatch(/CRLF/);
+  });
+
+  test('a single stray CRLF is enough to fail', () => {
+    // One bad line is all bash needs to choke on, and it is the case an
+    // "is the file mostly fine" heuristic would wave through.
+    const p = write('one.sh', '#!/bin/bash\necho one\necho two\r\necho three\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(false);
+    expect(r.crlfLines).toBe(1);
+  });
+
+  test('CRLF in the middle of a multi-line construct is flagged', () => {
+    // The exact shape from #546: the \r lands inside a construct bash is
+    // mid-way through parsing, so the reported line number drifts far from
+    // the real cause.
+    const p = write('mid.sh', 'case "$x" in\r\n  a) echo a ;;\r\nesac\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(false);
+    expect(r.crlfLines).toBe(2);
+  });
+
+  test('a syntax error with clean line endings is reported as unparseable', () => {
+    const p = write('bad.sh', '#!/bin/bash\nif [ 1 -eq 1 ]; then\n  echo x\n');
+    const r = inspectHookFile(p);
+    expect(r.ok).toBe(false);
+    expect(r.problems.join(' ')).toMatch(/not parseable|syntax/i);
+  });
+
+  test('a binary-looking file does not crash the inspector', () => {
+    const p = path.join(TMP_DIR, 'bin.sh');
+    fs.writeFileSync(p, Buffer.from([0x00, 0xff, 0xfe, 0x0a]));
+    expect(() => inspectHookFile(p)).not.toThrow();
+  });
+
+  test('a missing file reports missing rather than throwing', () => {
+    const r = inspectHookFile(path.join(TMP_DIR, 'nope.sh'));
+    expect(r.ok).toBe(false);
+    expect(r.problems.join(' ')).toMatch(/missing/i);
+  });
+});

package/lib/coverage-total.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# Gate 5's Python coverage parsing and threshold verdict (#523).
+#
+# Sourced by githooks/pre-commit; kept in its own file so the contract is
+# unit-testable without executing the hook
+# (githooks/__tests__/issue-523-python-coverage-parse.test.bats).
+#
+# The defect this file exists for: `coverage report --format=total` prints a
+# BARE number ("97"), but the hook piped it through `grep -o '[0-9]*%'` — a
+# pattern that requires a literal percent sign — so COVERAGE_PERCENT was always
+# empty and the 80% threshold branch never executed. The gate answered "Could
+# not determine" forever: a silent no-op, not a verdict.
+
+# Parse the raw output of `coverage report --format=total` (stdin) and echo the
+# integer total percentage — or nothing when the input carries no number.
+#
+# coverage.py 7.x --format=total prints a bare number; other tools (and older
+# forms) append a percent sign. Only a line that IS a bare number (optionally
+# %-suffixed) is accepted — a line that merely CONTAINS a number ("WARNING: 2
+# files skipped") must not be mistaken for the total, so the whole line is
+# matched, not the first token. A decimal part is truncated (floor — the
+# conservative direction for a threshold gate, the same convention as the Java
+# path's ${VAR%.*}). Inputs without any bare-number line (empty, "No data to
+# report.", warnings) produce NO output so the caller takes its
+# cannot-determine path: a wrong number is worse than none.
+parse_coverage_total() {
+  awk '
+    {
+      line = $0
+      sub(/%$/, "", line)
+      gsub(/^[ \t]+|[ \t]+$/, "", line)
+      if (line ~ /^[0-9]+(\.[0-9]+)?$/) {
+        sub(/\.[0-9]+$/, "", line)
+        print line
+        exit
+      }
+    }
+  '
+}
+
+# Gate 5 Stage 2 Python coverage enforcement — the hook's python case body,
+# extracted so the mock-PATH test exercises the real control flow. Echoes the
+# verdict lines and returns 1 on BLOCK (the caller turns that into `exit 1`).
+#
+# COVERAGE_PERCENT is deliberately NOT declared local: the hook's quality
+# report reads it after the Stage-2 loop (last writer wins across languages),
+# exactly as the inline branch did.
+enforce_python_coverage() {
+  # Critical-1 (#399): when the test run was skipped (PY_STRATEGY=skip, set in
+  # pre-commit before this Stage-2 function), refuse to consume a stale
+  # .coverage left by an earlier subset run — its low % is meaningless for a
+  # commit that changed no Python and must not BLOCK a docs-only change. This
+  # mirrors the TS branch's TESTS_SKIPPED guard.
+  if [ "${PY_TEST_SKIPPED:-false}" = "true" ]; then
+    echo "ℹ️  Test run was skipped — skipping Python coverage check."
+    return 0
+  fi
+
+  if ! command -v coverage &> /dev/null; then
+    echo "⚠️  coverage.py not available, cannot enforce Python coverage threshold."
+    return 0
+  fi
+
+  COVERAGE_PERCENT=""
+  if [ -f ".coverage" ]; then
+    COVERAGE_PERCENT=$(coverage report --format=total 2>/dev/null | parse_coverage_total) || true
+  fi
+  if [ -z "$COVERAGE_PERCENT" ] && [ -f "coverage/.coverage" ]; then
+    COVERAGE_PERCENT=$(coverage report --format=total -i coverage 2>/dev/null | parse_coverage_total) || true
+  fi
+
+  if [ -n "$COVERAGE_PERCENT" ]; then
+    if [ "$COVERAGE_PERCENT" -lt "${COVERAGE_THRESHOLD:-80}" ]; then
+      # #399: a subset run (smart test selection) measures only the tested
+      # files, so its global total is meaningless as a verdict — the full
+      # suite may well be >=80% even when the subset is not. Warn exactly as
+      # the TypeScript branch does (#286) instead of blocking. Full runs keep
+      # the hard BLOCK below.
+      if [ "${PARTIAL_TEST_RUN:-false}" = "true" ]; then
+        echo "⚠️  Partial coverage ${COVERAGE_PERCENT}% (subset test run, not full suite)."
+        echo "    Run the full suite for a real Python coverage check."
+        return 0
+      fi
+      echo "❌ BLOCKED - Python coverage ${COVERAGE_PERCENT}% below 80% threshold"
+      return 1
+    fi
+    echo "Python coverage: ${COVERAGE_PERCENT}% ✅ (≥ 80%)"
+  else
+    echo "⚠️  Could not determine Python coverage percentage. Ensure pytest-cov or coverage.py data exists."
+  fi
+  return 0
+}

package/lib/doctor.js

@@ -18,6 +18,14 @@ const { GATE_CLI_TOOLS, checkCliTool, getToolInstallCmd, checkBash } = require('
 // #505: the single source of truth for module resolution order. The hook reads a
 // generated shell projection of this same module.
 const { RESOLUTION_ORDER } = require('./hook-module-resolution.js');
+const { inspectHookFile } = require('./hook-health.js');
+
+/**
+ * Files above this size get a `bash -n` probe in addition to the CRLF scan.
+ * Real xp-gate hooks are 40 KB (pre-push) to 190 KB (pre-commit); test fixtures
+ * and stubs are a few hundred bytes. 4 KB separates them comfortably.
+ */
+const PARSE_CHECK_MIN_BYTES = 4096;
 const {
   diagnoseTuiRegistration, diagnoseInstalledSkills,
   fixTuiRegistration, ensureTuiRegistration, readTuiJson,
@@ -1256,10 +1264,46 @@ function checkSingleHook(hooksDir, name, signature, label, checks) {
     checks.push({ name: `${label}: ${name}`, status: 'FAIL', detail: 'Missing or not xp-gate' });
     return 1;
   }
+  // Existence and signature are not enough (#546): a hook rewritten with CRLF
+  // line endings, or truncated mid-write, satisfies both and still cannot run.
+  // Reporting it as healthy is worse than reporting nothing, because the
+  // operator stops looking.
+  //
+  // The CRLF scan is pure and cheap; the `bash -n` probe spawns a process, so it
+  // is skipped for files under the size floor below — test fixtures and stub
+  // hooks are not the things that break here, and spawning bash per stub made
+  // doctor slower than its own test timeout.
+  const health = inspectHookFile(hookPath, { parseCheck: shouldParseCheck(hookPath) });
+  if (!health.ok) {
+    checks.push({
+      name: `${label}: ${name}`,
+      status: 'FAIL',
+      detail: health.problems.join('; '),
+    });
+    return 1;
+  }
   checks.push({ name: `${label}: ${name}`, status: 'PASS', detail: hookPath });
   return 0;
 }
 
+/**
+ * Should the `bash -n` probe run for this hook?
+ *
+ * Measured on a real install: a 190 KB pre-commit takes ~90 ms to parse, but a
+ * dozen stubs in a test fixture still add up to seconds of process spawns. The
+ * CRLF scan catches the #546 failure without spawning anything, so the probe is
+ * reserved for files large enough to be a real hook.
+ * @param {string} hookPath - Hook path
+ * @returns {boolean} Whether to run the parse check
+ */
+function shouldParseCheck(hookPath) {
+  try {
+    return fs.statSync(hookPath).size > PARSE_CHECK_MIN_BYTES;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Expected gate scripts that should be present in the adapters directory.
  * gate-5.sh and gate-6.sh are inline in pre-commit, so they are NOT expected here.

package/lib/hook-health.js

@@ -0,0 +1,121 @@
+/**
+ * Hook file health inspection (#546).
+ *
+ * `xp-gate doctor` used to answer one question about an installed hook: does the
+ * file exist and does it carry the xp-gate signature. A hook can satisfy both
+ * and still be unrunnable — #546 was a pre-commit that had been rewritten with
+ * CRLF line endings, which fails every commit while doctor reported ✓.
+ *
+ * Two independent failure modes are checked here:
+ *   - CRLF line endings: git runs hooks through bash, and a stray \r makes the
+ *     parser choke at a line number far from the real cause (the reported line
+ *     is wherever the multi-line construct that swallowed the \r began).
+ *   - Unparseable syntax: a truncated or mangled write leaves a hook that
+ *     exists but cannot run.
+ *
+ * Both are reported per file rather than as a single boolean, because the
+ * operator needs to know which one happened: CRLF has a mechanical fix, a
+ * syntax error does not.
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/**
+ * Locate a bash binary without assuming it is on PATH under that exact name.
+ * @returns {string|null} Path or bare command name, null when none found
+ */
+function findBash() {
+  const candidates = ['bash'];
+  if (process.platform === 'win32') {
+    // Git for Windows ships bash outside PATH far more often than inside it.
+    const pf = process.env.ProgramFiles || 'C:\\Program Files';
+    const pf86 = process.env['ProgramFiles(x86)'] || 'C:\\Program Files (x86)';
+    const local = process.env.LOCALAPPDATA;
+    if (local) candidates.push(path.join(local, 'Programs', 'Git', 'bin', 'bash.exe'));
+    candidates.push(path.join(pf, 'Git', 'bin', 'bash.exe'));
+    candidates.push(path.join(pf86, 'Git', 'bin', 'bash.exe'));
+    candidates.push(path.join(pf, 'Git', 'usr', 'bin', 'bash.exe'));
+  }
+  for (const c of candidates) {
+    if (path.isAbsolute(c)) {
+      if (fs.existsSync(c)) return c;
+      continue;
+    }
+    const probe = spawnSync(c, ['--version'], { encoding: 'utf8', timeout: 10000 });
+    if (!probe.error && probe.status === 0) return c;
+  }
+  return null;
+}
+
+/**
+ * Count lines that end with CRLF.
+ * @param {string} text - File content
+ * @returns {number} Number of CRLF-terminated lines
+ */
+function countCrlfLines(text) {
+  const matches = text.match(/\r\n/g);
+  return matches ? matches.length : 0;
+}
+
+/**
+ * Ask bash whether it can parse the file (`bash -n`).
+ * @param {string} filePath - Hook to check
+ * @param {string} bashBin - Resolved bash binary
+ * @returns {{checked: boolean, ok: boolean, detail: string}} Parse verdict
+ */
+function checkParseable(filePath, bashBin) {
+  if (!bashBin) return { checked: false, ok: true, detail: 'bash not found; parse check skipped' };
+  const res = spawnSync(bashBin, ['-n', filePath], { encoding: 'utf8', timeout: 30000 });
+  if (res.error) return { checked: false, ok: true, detail: `bash -n could not run: ${res.error.message}` };
+  if (res.status === 0) return { checked: true, ok: true, detail: 'parses' };
+  // bash reports the first syntax error it hits. Under CRLF that line number is
+  // unreliable, which is exactly why the CRLF count is reported alongside.
+  const firstLine = String(res.stderr || '').split('\n').find(l => l.trim()) || `exit ${res.status}`;
+  return { checked: true, ok: false, detail: firstLine.trim() };
+}
+
+/**
+ * Inspect one hook file for the conditions that make git unable to run it.
+ * @param {string} filePath - Hook path
+ * @param {{bashBin?: string|null, parseCheck?: boolean}} [options] - Overrides
+ * @returns {{ok: boolean, crlfLines: number, parseable: boolean, problems: string[]}}
+ */
+function inspectHookFile(filePath, options = {}) {
+  const problems = [];
+
+  if (!fs.existsSync(filePath)) {
+    return { ok: false, crlfLines: 0, parseable: false, problems: [`hook file is missing: ${filePath}`] };
+  }
+
+  let text = '';
+  try {
+    text = fs.readFileSync(filePath, 'latin1');
+  } catch (err) {
+    return { ok: false, crlfLines: 0, parseable: false, problems: [`hook file is unreadable: ${err.message}`] };
+  }
+
+  const crlfLines = countCrlfLines(text);
+  if (crlfLines > 0) {
+    problems.push(
+      `hook has CRLF line endings (${crlfLines} line(s)) — bash will fail to parse it; ` +
+        'run `tr -d "\\r" < hook > hook.fixed && mv hook.fixed hook`'
+    );
+  }
+
+  // A CRLF hit already answers the question this probe exists to answer, and
+  // the probe is the expensive half. Callers can also opt out for stubs.
+  if (crlfLines > 0 || options.parseCheck === false) {
+    return { ok: problems.length === 0, crlfLines, parseable: crlfLines === 0, problems };
+  }
+
+  const bashBin = options.bashBin !== undefined ? options.bashBin : findBash();
+  const parsed = checkParseable(filePath, bashBin);
+  if (!parsed.ok) {
+    problems.push(`hook is not parseable by bash: ${parsed.detail}`);
+  }
+
+  return { ok: problems.length === 0, crlfLines, parseable: parsed.ok, problems };
+}
+
+module.exports = { inspectHookFile, findBash, countCrlfLines };

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-10-20T12:36:08.136Z",
+  "checked_at": "2026-10-20T23:31:25.547Z",
   "source": "network"
 }

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
 **Generated:** 2026-10-20
-**Commit:** 9fab5b3b
+**Commit:** 54318594
 **Branch:** main
-**Version:** 0.30.2.0
+**Version:** 0.30.4.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
 **Generated:** 2026-10-20
-**Commit:** 9fab5b3b
+**Commit:** 54318594
 **Branch:** main
-**Version:** 0.30.2.0
+**Version:** 0.30.4.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/mutation/__tests__/gate-m-survivors.test.ts

@@ -0,0 +1,133 @@
+/**
+ * @test #544 - Gate M survivor detail for retro
+ * @intent Verify Gate M reports per-file mutant outcome counts, not just a
+ *         score. #544: the pre-push journal carried
+ *         {skip_reason, duration_ms, mutation_score} and nothing else, so
+ *         `xp-gate retro` could not answer "which module has the most surviving
+ *         mutants". The data was never missing at the source: Stryker's JSON
+ *         reporter emits files[].nrOfSurvivedMutants, and stryker-types.ts
+ *         already declares it. The counts were dropped on the way through, then
+ *         buildMutationScores hardcoded {mutants: 0, killed: 0, survived: 0}.
+ *         Three zeros written next to a real score read as "measured: no
+ *         survivors" -- the same class of false success this project keeps
+ *         fixing, so unknown must stay absent, never zero.
+ * @covers REQ-MUT-001 AC-001
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  summarizeSurvivors,
+  type StrykerReportLike,
+  type SurvivorSummary,
+} from '../gate-m';
+
+/** A report shaped like Stryker's JSON output. */
+function report(files: Record<string, [number, number, number]>): StrykerReportLike {
+  const entries = Object.entries(files);
+  const totalMutants = entries.reduce((a, [, v]) => a + v[0], 0);
+  const totalKilled = entries.reduce((a, [, v]) => a + v[1], 0);
+  const totalSurvived = entries.reduce((a, [, v]) => a + v[2], 0);
+  return {
+    mutationScore: totalMutants > 0 ? parseFloat(((totalKilled / totalMutants) * 100).toFixed(1)) : 100,
+    nrOfMutants: totalMutants,
+    nrOfKilledMutants: totalKilled,
+    nrOfSurvivedMutants: totalSurvived,
+    files: Object.fromEntries(
+      entries.map(([k, [m, kd, sv]]) => [k, {
+        mutationScore: m > 0 ? parseFloat(((kd / m) * 100).toFixed(1)) : 100,
+        nrOfMutants: m,
+        nrOfKilledMutants: kd,
+        nrOfSurvivedMutants: sv,
+      }])
+    ),
+  };
+}
+
+/** Narrow to a non-null summary, failing the test with a clear message. */
+function expectSummary(s: SurvivorSummary | null): SurvivorSummary {
+  expect(s).not.toBeNull();
+  if (s === null) throw new Error('expected a survivor summary, got null');
+  return s;
+}
+
+describe('AC-544: Gate M survivor detail', () => {
+  it('reports per-file survived counts from the Stryker report', () => {
+    const summary = expectSummary(summarizeSurvivors(report({
+      'src/mutation/gate-m.ts': [20, 8, 12],
+      'src/principles/analyzer.ts': [10, 3, 7],
+    })));
+
+    expect(summary.survivedByFile).toEqual({
+      'src/mutation/gate-m.ts': 12,
+      'src/principles/analyzer.ts': 7,
+    });
+  });
+
+  it('totals killed, survived and mutants', () => {
+    const summary = expectSummary(summarizeSurvivors(report({
+      'a.ts': [20, 8, 12],
+      'b.ts': [10, 3, 7],
+    })));
+
+    expect(summary.mutants).toBe(30);
+    expect(summary.killed).toBe(11);
+    expect(summary.survived).toBe(19);
+  });
+
+  it('orders survivedByFile worst-first so retro can take the top N', () => {
+    const summary = expectSummary(summarizeSurvivors(report({
+      'small.ts': [10, 9, 1],
+      'worst.ts': [10, 0, 10],
+      'middle.ts': [10, 5, 5],
+    })));
+
+    expect(Object.keys(summary.survivedByFile)).toEqual(['worst.ts', 'middle.ts', 'small.ts']);
+  });
+
+  it('caps the per-file map so one huge repo cannot bloat the journal', () => {
+    const many: Record<string, [number, number, number]> = {};
+    // Every file must have at least one survivor, otherwise this asserts on a
+    // smaller population than intended and the count below drifts.
+    for (let i = 0; i < 50; i++) {
+      const survived = (i % 9) + 1; // 1..9, never 0
+      many[`f${i}.ts`] = [10, 10 - survived, survived];
+    }
+
+    const summary = expectSummary(summarizeSurvivors(report(many), { limit: 20 }));
+
+    expect(Object.keys(summary.survivedByFile)).toHaveLength(20);
+    // Truncation must be visible, not silent: a capped list that looks complete
+    // is how "top 20" gets mistaken for "all files".
+    expect(summary.truncated).toBe(true);
+    expect(summary.filesWithSurvivors).toBe(50);
+  });
+
+  it('does not claim truncation when everything fits', () => {
+    const summary = expectSummary(summarizeSurvivors(report({ 'a.ts': [10, 5, 5] }), { limit: 20 }));
+    expect(summary.truncated).toBe(false);
+  });
+
+  it('omits files with zero survivors', () => {
+    const summary = expectSummary(summarizeSurvivors(report({
+      'clean.ts': [10, 10, 0],
+      'dirty.ts': [10, 4, 6],
+    })));
+
+    expect(summary.survivedByFile).toEqual({ 'dirty.ts': 6 });
+  });
+
+  it('degrades to null instead of inventing zeros when no report is available', () => {
+    // A missing/timed-out report must not be reported as "0 survivors" -- that
+    // is the #544 failure repeated. null means unknown.
+    expect(summarizeSurvivors(null)).toBeNull();
+  });
+
+  it('degrades to null when the report has no per-file section', () => {
+    expect(summarizeSurvivors({
+      mutationScore: 80,
+      nrOfMutants: 10,
+      nrOfKilledMutants: 8,
+      nrOfSurvivedMutants: 2,
+    })).toBeNull();
+  });
+});

package/mutation/gate-m.ts

@@ -522,6 +522,86 @@ function buildMutationScores(fileScores: Record<string, number>): Record<string,
   return scores;
 }
 
+/**
+ * The subset of a runner report that survivor summarisation needs. Declared
+ * structurally rather than as a concrete Stryker type because every runner
+ * (Stryker, mutmut, gremlins, go-mutant) normalises to `MutationRunResult`,
+ * which carries the same field names -- the summary must work for all of them,
+ * not just the TS one.
+ */
+export interface StrykerReportLike {
+  mutationScore: number;
+  nrOfMutants: number;
+  nrOfKilledMutants: number;
+  nrOfSurvivedMutants: number;
+  files?: Record<string, {
+    mutationScore: number;
+    nrOfMutants: number;
+    nrOfKilledMutants: number;
+    nrOfSurvivedMutants: number;
+  }>;
+}
+
+/** Per-file mutant outcome detail for the pre-push journal (#544). */
+export interface SurvivorSummary {
+  /** Files with at least one surviving mutant, worst first, capped by `limit`. */
+  survivedByFile: Record<string, number>;
+  /**
+   * How many files actually had survivors. Present so a capped map can be told
+   * apart from a complete one -- a truncated list that looks exhaustive is how
+   * "top 20" gets read as "all files".
+   */
+  filesWithSurvivors: number;
+  /** True when `survivedByFile` dropped entries to stay under `limit`. */
+  truncated: boolean;
+  mutants: number;
+  killed: number;
+  survived: number;
+}
+
+/**
+ * Condense a Stryker report into survivor detail (#544).
+ *
+ * Returns `null` -- never a summary of zeros -- when the report is missing or
+ * carries no per-file section. A timed-out or failed run has no measurements,
+ * and writing `survived: 0` next to a real-looking score would report
+ * "measured: no survivors" for a run that measured nothing. That is the exact
+ * shape of false success this project keeps finding, so unknown stays `null`.
+ */
+export function summarizeSurvivors(
+  report: StrykerReportLike | null | undefined,
+  options: { limit?: number } = {},
+): SurvivorSummary | null {
+  if (!report || !report.files) return null;
+
+  const limit = options.limit ?? 20;
+  const survivors: Array<[string, number]> = [];
+  let mutants = 0;
+  let killed = 0;
+  let survived = 0;
+
+  for (const [file, entry] of Object.entries(report.files)) {
+    const fileSurvived = entry.nrOfSurvivedMutants ?? 0;
+    mutants += entry.nrOfMutants ?? 0;
+    killed += entry.nrOfKilledMutants ?? 0;
+    survived += fileSurvived;
+    if (fileSurvived > 0) survivors.push([file, fileSurvived]);
+  }
+
+  // Worst first, then by path so equal counts order deterministically.
+  survivors.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const kept = survivors.slice(0, limit);
+
+  return {
+    survivedByFile: Object.fromEntries(kept),
+    filesWithSurvivors: survivors.length,
+    truncated: survivors.length > kept.length,
+    mutants,
+    killed,
+    survived,
+  };
+}
+
 export async function runGateM(options: GateMOptions): Promise<GateMResult> {
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -595,6 +675,22 @@ async function collectTestIntentWarnings(sourceFiles: string[], warnings: string
   }
 }
 
+/**
+ * Read the mutation report the runner left on disk and summarise it (#544).
+ * Returns null when there is no readable report -- the caller then prints
+ * nothing, and the journal field stays absent. Every failure here is silent by
+ * design: #544 explicitly requires that missing detail must not turn Gate M
+ * itself into a failure.
+ */
+async function readSurvivorSummary(): Promise<SurvivorSummary | null> {
+  try {
+    const raw = await fs.readFile('.stryker-report.json', 'utf-8');
+    return summarizeSurvivors(JSON.parse(raw) as StrykerReportLike);
+  } catch {
+    return null;
+  }
+}
+
 export async function main(args: string[]): Promise<number> {
   const options = parseArgs(args);
 
@@ -611,19 +707,14 @@ export async function main(args: string[]): Promise<number> {
 
   const result = await runGateM(options);
 
-  if (result.warnings.length > 0) {
-    console.log('\nWarnings:');
-    for (const warning of result.warnings) {
-      console.log(`  ⚠ ${warning}`);
-    }
+  // #544: survivor detail on a machine-readable line. Printed only when a report
+  // exists -- absent means "not measured", never "measured: zero survivors".
+  const survivors = await readSurvivorSummary();
+  if (survivors) {
+    console.log(`GATE_M_SURVIVORS_JSON=${JSON.stringify(survivors)}`);
   }
 
-  if (result.errors.length > 0) {
-    console.log('\nErrors:');
-    for (const error of result.errors) {
-      console.error(`  ✗ ${error}`);
-    }
-  }
+  logDiagnostics(result.warnings, result.errors);
 
   const statusIcon = result.status === 'pass' ? '✓' :
     result.status === 'skip' ? '⊘' :
@@ -634,6 +725,18 @@ export async function main(args: string[]): Promise<number> {
   return result.exitCode;
 }
 
+/** Print Gate M's warnings and errors. Errors go to stderr. */
+function logDiagnostics(warnings: string[], errors: string[]): void {
+  if (warnings.length > 0) {
+    console.log('\nWarnings:');
+    for (const warning of warnings) console.log(`  ⚠ ${warning}`);
+  }
+  if (errors.length > 0) {
+    console.log('\nErrors:');
+    for (const error of errors) console.error(`  ✗ ${error}`);
+  }
+}
+
 const cliArgs = process.argv.slice(2);
 if (typeof require !== 'undefined' && require.main === module) {
   main(cliArgs)