jules-orchestrator-kit 0.54.0 → 0.55.0

package/README.md

@@ -197,10 +197,13 @@ To maximize PR merge rates, dispatch tasks according to deterministic boundaries
 * **Zero Runtime Dependencies:** Built exclusively on Node.js 20+ built-in modules (`node:fs`, `node:child_process`, `node:crypto`, `node:path`, `node:http`, `node:tty`, `node:test`).
 * **Cross-Platform Parity:** Verified 100% green across Linux, macOS (Darwin), and Windows on Node 20, 22, and 24.
 * **Autonomous Self-Healing Loop:** Captures test stderr/stdout, fingerprints error traces, and feeds structured context back into automated repair turns (up to 3 attempts) before human escalation.
+* **Fail-Closed Verification:** A change that ran no verification command at all is rejected, not approved — "nothing to run" is not a pass. Repositories using only the scope and secret phases opt out explicitly with `verify.required: false`.
+* **Anti-Tamper That Reads Semantics:** Counting assertions cannot see a value check swapped for a truthiness check. The guard tracks assertions that name an expected value, so weakening a test is a violation even when the line count is unchanged.
+* **Binary-Aware Scanning:** Files git renders as `Binary files ... differ` are read directly for structured credentials, and their real size is charged against the diff ceiling, so a leading NUL byte cannot hide a token and a committed blob cannot walk past the payload governor.
 * **Fail-Closed Security & Secret Redaction:** Evaluates explicit Deny rules before Allow rules against canonicalized, case-folded paths. Redacts high-entropy keys and base64-encoded credentials (such as Kubernetes `Secret` manifests).
 * **Complexity & Cost Router:** Zero-dependency heuristic classifier (`src/router.mjs`) routing mechanical tasks to lightweight models while reserving primary models for complex refactors, with a `node --check` syntax-verification gate that transparently escalates a FAST-tier result to the primary provider if it left broken JS on disk.
 * **Terminal UI & Diagnostic Matrix (`agentctl doctor`):** Interactive terminal dashboard, task sidecar manager, and automated transactional self-repair.
-* **Verified Test Suite:** Tested with **827 unit tests across 107 suites passing in < 14.0s**.
+* **Verified Test Suite:** Tested with **842 unit tests across 112 suites passing in < 14.0s**.
 
 <br/>
 

package/bin/agentctl.mjs

@@ -484,6 +484,15 @@ async function main() {
             console.log(`💡 Remediation Hint (Exit 188 Offline Network Violation / Infrastructure):`);
             console.log(`   • An unmocked network request was blocked by the preload network guard during verification.`);
             console.log(`   • Ensure dependencies are installed locally (run: npm install) and all network calls in tests are mocked.\n`);
+          } else if (res.phases.find((p) => p.phase === "verify" && !p.ok)?.failure?.stageId === "oracle") {
+            // Nothing exited non-zero here and --fix cannot help: there was no
+            // command to run. Offering the repair loop would send an agent to
+            // fix a failure that does not exist.
+            console.log(`💡 Remediation Hint (Exit ${res.code} No Verification Oracle):`);
+            console.log(`   • Nothing was executed against this change, so the gate cannot approve it.`);
+            console.log(`   • Give it a command:   agentctl bootstrap        (generates one for this stack)`);
+            console.log(`   • Or set it by hand:   verify.test in ${config._file || ".agent/config.yml"}`);
+            console.log(`   • Scope- and secret-scanning only, on purpose? Set verify.required: false there.\n`);
           } else if (failedPhase === "verify" || failedPhase === "evidence") {
             console.log(`💡 Remediation Hint (Exit ${res.code} Verification Failed):`);
             console.log(`   • The stage above exited non-zero. Reproduce it locally, then re-run the gate.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jules-orchestrator-kit",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "Zero-dependency safety gatekeeper, test oracle generator, and multi-agent coordination protocol for autonomous coding agents — Google Jules, Claude Code, Codex and Gemini CLI.",
   "repository": {
     "type": "git",

package/src/config.mjs

@@ -522,6 +522,11 @@ export function loadConfig(root = resolveRoot(), explicitPath = null) {
     teardown: rawTeardown ?? autoVerify.teardown ?? "",
     build: rawBuild ?? autoVerify.build,
     policy: parsed.verify?.policy ?? autoVerify.policy,
+    // Whether the gate may approve a change that ran no verification at all.
+    // True by default: "nothing to run" is not a pass, and a security tool that
+    // says APPROVED after checking nothing is worse than no tool. A repository
+    // that deliberately uses only the scope and secret phases sets this false.
+    required: parsed.verify?.required !== false,
   };
 
   // A hand-written `verify.stages:` is the operator being explicit and always

package/src/engine.mjs

@@ -1,6 +1,6 @@
 import { loadConfig, parseYaml, normalizeScope } from "./config.mjs";
-import { checkScope, scanDiff, redactSecrets } from "./security.mjs";
-import { changedFiles, diffBytes, diffText, showFromOrigin, runCmd } from "./git.mjs";
+import { checkScope, scanDiff, scanBinaryPayloads, redactSecrets } from "./security.mjs";
+import { changedFiles, diffBytes, diffText, binaryDiffEntries, symlinkChanges, showFromOrigin, runCmd } from "./git.mjs";
 import { createProvider, ProviderRateLimitError, ProviderUnavailableError } from "./provider.mjs";
 import { resolveRoutedProvider } from "./router.mjs";
 import { withBudget, appendLedger, getQueueDir, ensureDir, rollbackBudgetReservation, isConcurrencyGroupLocked, checkDailyBudget } from "./state.mjs";
@@ -198,6 +198,9 @@ export async function gate(opts = {}) {
           build: parsed.verify?.build || parsed.build_cmd || config.verify.build,
           stages: parsed.verify?.stages || config.verify.stages,
           policy: parsed.verify?.policy || config.verify.policy,
+          // Read from the base commit like every other trusted field: an
+          // uncommitted `required: false` must not be able to switch the gate off.
+          required: parsed.verify?.required !== undefined ? parsed.verify.required !== false : config.verify.required !== false,
           timeoutMs: parsed.verify?.timeoutMs || parsed.verify?.timeout_ms || config.verify.timeoutMs,
         };
       }
@@ -210,9 +213,37 @@ export async function gate(opts = {}) {
     }
   }
 
-  const scopeResult = checkScope(files, trustedScope, {
+  // A symlink is judged by its own name, so `notes.md -> .agent/config.yml`
+  // walked straight past a deny list that names the target. Judge both: the
+  // link because it is what the diff adds, and the path it resolves to because
+  // that is what it grants reach to.
+  let symlinks = [];
+  try {
+    symlinks = symlinkChanges(root, base, mode);
+  } catch (_) {
+    // Scope must still be enforced on the ordinary file list if git cannot
+    // describe the links.
+  }
+  const scopeCandidates = [...files];
+  const symlinkTargetOf = new Map();
+  for (const { link, target } of symlinks) {
+    if (!target || scopeCandidates.includes(target)) continue;
+    scopeCandidates.push(target);
+    symlinkTargetOf.set(target, link);
+  }
+
+  const scopeResult = checkScope(scopeCandidates, trustedScope, {
     allowProtected: opts.allowProtected || process.env.JULES_ALLOW_COMMAND_FILE_CHANGES === "true",
   });
+  // Report the violation against the link the change actually introduced, not
+  // against a path the diff never names — the operator has to be able to find it.
+  for (const violation of scopeResult.violations || []) {
+    const link = symlinkTargetOf.get(violation.file);
+    if (!link) continue;
+    violation.reason = `${violation.reason} (reached through symlink ${link})`;
+    violation.symlink = link;
+    violation.file = link;
+  }
 
   phases.push({ phase: "scope", ok: scopeResult.ok, violations: scopeResult.violations });
   appendTelemetry(root, "gate_phase", { phase: "scope", ok: scopeResult.ok });
@@ -242,13 +273,25 @@ export async function gate(opts = {}) {
 
   // Phase 3: Diff Secret Scanner & Security Checks
   const secretResult = scanDiff(diffStr, { root });
-  phases.push({ phase: "secrets", ok: secretResult.ok, findings: secretResult.findings });
-  appendTelemetry(root, "gate_phase", { phase: "secrets", ok: secretResult.ok });
+  // A binary file reaches the scanner as one summary line, so its contents were
+  // never looked at — a NUL byte in front of a token was enough to hide it.
+  // Inspect those files directly and fold the verdict in.
+  let binaryFindings = [];
+  try {
+    binaryFindings = scanBinaryPayloads(binaryDiffEntries(root, base, mode), root);
+  } catch (_) {
+    // Never let the extra pass break a gate that would otherwise have run; the
+    // text scan above has already been applied.
+  }
+  const allSecretFindings = [...(secretResult.findings || []), ...binaryFindings];
+  const secretsOk = secretResult.ok && binaryFindings.length === 0;
+  phases.push({ phase: "secrets", ok: secretsOk, findings: allSecretFindings });
+  appendTelemetry(root, "gate_phase", { phase: "secrets", ok: secretsOk });
   if (progressBus && progressToken) {
     progressBus.reportProgress(progressToken, 75, 100, "Phase 3/4: Diff Secret Scanner check complete");
   }
 
-  if (!secretResult.ok) {
+  if (!secretsOk) {
     appendTelemetry(root, "gate_finished", { ok: false, code: 6 });
     return { ok: false, code: 6, phases };
   }
@@ -415,7 +458,23 @@ export async function gate(opts = {}) {
     }
   }
 
-  const verifyOk = !failingCmd && !testTampered;
+  // A gate that ran no verification at all must not report APPROVED.
+  //
+  // `testResult` starts optimistic and the stage loop skips a stage with no
+  // command, so a repository with no test oracle produced zero execution
+  // records and a clean bill of health — syntactically broken code included.
+  // That is the product's central claim inverted: the whole point is that a
+  // change is verified before it is approved, and "nothing to run" is not
+  // verification. Repositories that deliberately use only the scope and secret
+  // phases opt out with `verify.required: false`.
+  // Assertions are guards, not oracles: `assert:test-integrity` proves the diff
+  // did not weaken a test, which says nothing about whether the code works. The
+  // question is whether any command was executed against the change at all.
+  const verificationRequired = trustedVerify.required !== false;
+  const ranNoVerification = !executionRecords.some((r) => r && r.kind !== "assert");
+  const missingOracle = verificationRequired && ranNoVerification;
+
+  const verifyOk = !failingCmd && !testTampered && !missingOracle;
 
   // What actually broke. Without this the verify phase reported `ok: false` and
   // nothing else — not the stage, not the exit code, not a line of output — so
@@ -448,7 +507,21 @@ export async function gate(opts = {}) {
           stderr: `Test files changed during the run (${preTestHash.slice(0, 12)} → ${postTestHash.slice(0, 12)}). evidence.strictTestLock treats a passing suite that the diff also rewrote as unproven.`,
           diagnostics: [],
         }
-      : null;
+      : missingOracle
+        ? {
+            stageId: "oracle",
+            command: null,
+            exitCode: null,
+            stdout: "",
+            stderr:
+              "No verification command ran, so nothing about this change was checked. " +
+              "Set verify.test in .agent/config.yml (or run `agentctl bootstrap` to generate one). " +
+              "If this repository intentionally uses only the scope and secret phases, set verify.required: false.",
+            diagnostics: [
+              "The gate approves a change because verification passed. Zero stages executed is not a pass.",
+            ],
+          }
+        : null;
 
   // Generate & persist Evidence Manifest
   const evidenceManifest = generateEvidenceManifest(root, {

package/src/evidence.mjs

@@ -11,7 +11,7 @@ import {
   renameSync,
   unlinkSync,
 } from "node:fs";
-import { join, resolve, relative, isAbsolute, sep } from "node:path";
+import { join, resolve, relative, isAbsolute, sep, extname } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { execSync } from "node:child_process";
 
@@ -83,6 +83,19 @@ export function findFilesRecursively(dir, baseDir = dir) {
  * @param {string[]} [options.directories] - Specific directory names to scan (e.g. ['test', 'tests'])
  * @returns {{ treeHash: string, fileCount: number, fileHashes: Record<string, string> }}
  */
+/**
+ * Extensions that count as code when scanning the repository root.
+ *
+ * The directory walk above takes everything under `src/` and the test
+ * directories; this list only governs the loose files beside package.json,
+ * where a `.md` is documentation rather than something the evidence attests to.
+ */
+const SOURCE_EXTENSIONS = new Set([
+  ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".mts", ".cts",
+  ".py", ".go", ".rs", ".rb", ".php", ".java", ".kt", ".kts", ".cs", ".fs",
+  ".swift", ".dart", ".ex", ".exs", ".c", ".h", ".cc", ".cpp", ".hpp", ".sol",
+]);
+
 export function computeDirectoryHash(root, options = {}) {
   let fileList = [];
 
@@ -100,6 +113,29 @@ export function computeDirectoryHash(root, options = {}) {
         fileList.push(...found);
       }
     }
+
+    // Plenty of projects keep `app.test.mjs` or `index.js` beside package.json
+    // rather than under one of the directories above, and those files were
+    // invisible to every hash computed here — a manifest could attest to a
+    // pristine test suite while the only test in the repository had been
+    // replaced with garbage.
+    //
+    // Depth one only: recursing from the root would walk node_modules and
+    // vendor trees. Source extensions only: the hash exists to bind the
+    // manifest to the code it verified, and pulling in README.md or the
+    // EVIDENCE.md this very command is about to write would make the hash churn
+    // on its own output.
+    try {
+      for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isFile()) continue;
+        if (entry.name.startsWith(".")) continue;
+        if (!SOURCE_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue;
+        fileList.push(normalizePath(entry.name));
+      }
+    } catch (_) {
+      // An unreadable root yields whatever the directory walk already found.
+    }
+
     fileList = Array.from(new Set(fileList)).sort();
   }
 
@@ -154,6 +190,7 @@ export function computeEvidenceHash(manifest) {
     intent: manifest.intent,
     provenance: manifest.provenance,
     testIntegrity: manifest.testIntegrity,
+    ...(manifest.sourceIntegrity ? { sourceIntegrity: manifest.sourceIntegrity } : {}),
     executionRecords: manifest.executionRecords,
     securityChecks: manifest.securityChecks,
     ...(manifest.status ? { status: manifest.status } : {}),
@@ -235,6 +272,7 @@ export function generateEvidenceManifest(root = process.cwd(), options = {}) {
   // Compute test tree integrity
   const preTestHash = options.preTestHash || null;
   const currentTestState = computeDirectoryHash(root, { testOnly: true });
+  const currentSourceState = computeDirectoryHash(root);
   const postTestHash = currentTestState.treeHash;
 
   let tamperDetected = false;
@@ -278,6 +316,14 @@ export function generateEvidenceManifest(root = process.cwd(), options = {}) {
       testFileCount: currentTestState.fileCount,
       fileHashes: currentTestState.fileHashes,
     },
+    // The manifest attested to the test files and to nothing else, so the code
+    // under test could be replaced wholesale after the fact and verification
+    // still passed. Evidence that survives the thing it attests to being
+    // rewritten is not evidence.
+    sourceIntegrity: {
+      treeHash: currentSourceState.treeHash,
+      fileCount: currentSourceState.fileCount,
+    },
     executionRecords: options.executionRecords || [],
     securityChecks: {
       secretScanOk: options.secretScanOk ?? true,
@@ -466,7 +512,28 @@ export function verifyEvidenceManifest(root = process.cwd(), manifestOrPath = "m
     };
   }
 
-  // 3. Verify security checks
+  // 3. Verify the code the manifest attests to still is that code.
+  //
+  // Without this the manifest proved only that the *tests* had not changed,
+  // so `evidence generate` followed by rewriting src/ and committing left
+  // verification reporting PASSED over an implementation nobody had checked.
+  if (manifest.sourceIntegrity?.treeHash) {
+    const currentSourceState = computeDirectoryHash(root);
+    if (currentSourceState.treeHash !== manifest.sourceIntegrity.treeHash) {
+      return {
+        ok: false,
+        reason: `Source tree has changed since this evidence was generated (${manifest.sourceIntegrity.treeHash.slice(0, 12)} → ${currentSourceState.treeHash.slice(0, 12)}); the manifest no longer attests to what is on disk`,
+        details: {
+          currentHash: currentSourceState.treeHash,
+          manifestHash: manifest.sourceIntegrity.treeHash,
+          manifestCommit: manifest.provenance?.commitSha || null,
+          currentCommit: getGitProvenance(root).commitSha,
+        },
+      };
+    }
+  }
+
+  // 4. Verify security checks
   if (manifest.securityChecks?.secretScanOk === false) {
     return { ok: false, reason: "Evidence manifest records secret scanning failure" };
   }

package/src/git.mjs

@@ -1,7 +1,7 @@
 import { execFileSync, execSync } from "node:child_process";
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, statSync, readlinkSync } from "node:fs";
 import { join, delimiter } from "node:path";
-import { normalizePath } from "./config.mjs";
+import { normalizePath, canonicalizePath } from "./config.mjs";
 
 
 export const NET_GUARD_PRELOAD_URL = new URL("./preload-net-guard.mjs", import.meta.url).href;
@@ -394,9 +394,174 @@ export function diffText(root = process.cwd(), base = "main", mode = "committed"
   return git(["diff", `${resolvedRef}...HEAD`], { cwd: root, raw: true });
 }
 
+/**
+ * Paths git summarised as binary in this diff, with the size of what changed.
+ *
+ * `git diff` prints one 43-byte line for a binary file — "Binary files a/x and
+ * b/x differ" — regardless of whether x grew by a byte or by half a megabyte.
+ * Everything downstream reads the diff *text*, so a binary file is invisible to
+ * both the payload governor and the secret scanner: a 500 KB blob measured 250
+ * bytes, and a credential with a leading NUL byte was never looked at.
+ *
+ * Sizes come from the object git actually recorded where there is one, and from
+ * the working file otherwise, so both `committed` and `working-tree` modes get a
+ * real number.
+ *
+ * @param {string} root
+ * @param {string} base
+ * @param {string} mode
+ * @returns {Array<{ file: string, bytes: number }>}
+ */
+export function parseRawDiff(root = process.cwd(), base = "main", mode = "committed") {
+  const resolvedRef = resolveBase(root, base);
+  const ranges =
+    mode === "working-tree" || mode === "working"
+      ? [[`${resolvedRef}...HEAD`], ["HEAD"]]
+      : [[`${resolvedRef}...HEAD`]];
+
+  const out = [];
+  for (const range of ranges) {
+    let raw = "";
+    try {
+      raw = git(["diff", "--raw", "--no-renames", "-z", ...range], { cwd: root, raw: true, ignoreError: true }) || "";
+    } catch (_) {
+      continue;
+    }
+    // `--raw -z` emits ":<srcmode> <dstmode> <srcsha> <dstsha> <status>\0<path>\0".
+    const fields = raw.split("\0").filter(Boolean);
+    for (let i = 0; i < fields.length; i++) {
+      const meta = fields[i];
+      if (!meta.startsWith(":")) continue;
+      const parts = meta.slice(1).split(/\s+/);
+      const file = fields[i + 1];
+      i += 1;
+      if (!file) continue;
+      out.push({
+        file,
+        srcMode: parts[0] || "",
+        dstMode: parts[1] || "",
+        srcSha: parts[2] || "",
+        dstSha: parts[3] || "",
+        status: (parts[4] || "").charAt(0),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Symlinks this change introduces, with the path each one points at.
+ *
+ * `checkScope` is purely lexical, by design — the paths it judges can come from
+ * a diff and need not exist on disk. But that made a symlink a hole straight
+ * through it: a link named `notes.md` pointing at `.agent/config.yml` is judged
+ * as `notes.md`, and the protected path it resolves to is never considered.
+ * Resolving here, rather than inside `checkScope`, keeps that function lexical
+ * and testable while letting the gate judge both names.
+ *
+ * The target is resolved lexically against the link's own directory: it may
+ * point outside the repository, and following it on disk would be the wrong
+ * thing to do with an untrusted path.
+ *
+ * @param {string} root
+ * @param {string} base
+ * @param {string} mode
+ * @returns {Array<{ link: string, target: string }>}
+ */
+export function symlinkChanges(root = process.cwd(), base = "main", mode = "committed") {
+  const SYMLINK_MODE = "120000";
+  const results = [];
+  const seen = new Set();
+
+  for (const entry of parseRawDiff(root, base, mode)) {
+    if (entry.status === "D") continue;
+    if (entry.dstMode !== SYMLINK_MODE) continue;
+    if (seen.has(entry.file)) continue;
+    seen.add(entry.file);
+
+    // A symlink's blob content is its target path.
+    let target = "";
+    if (entry.dstSha && !/^0+$/.test(entry.dstSha)) {
+      target = (git(["cat-file", "blob", entry.dstSha], { cwd: root, ignoreError: true }) || "").trim();
+    }
+    if (!target) {
+      try {
+        target = readlinkSync(join(root, entry.file));
+      } catch (_) {
+        continue;
+      }
+    }
+    if (!target) continue;
+
+    const linkDir = normalizePath(entry.file).split("/").slice(0, -1).join("/");
+    const resolved = normalizePath(target).startsWith("/")
+      ? normalizePath(target)
+      : canonicalizePath(linkDir ? `${linkDir}/${target}` : target);
+
+    results.push({ link: entry.file, target: resolved });
+  }
+
+  return results;
+}
+
+export function binaryDiffEntries(root = process.cwd(), base = "main", mode = "committed") {
+  const entries = new Map();
+  for (const entry of parseRawDiff(root, base, mode)) {
+    if (entry.status === "D") continue;
+    const { file, dstSha } = entry;
+
+    let bytes = 0;
+    if (dstSha && !/^0+$/.test(dstSha)) {
+      const size = git(["cat-file", "-s", dstSha], { cwd: root, ignoreError: true });
+      bytes = Number(size) || 0;
+    }
+    // An unstaged change has an all-zero destination sha; the working file is
+    // the only place its size exists.
+    if (!bytes) {
+      try {
+        bytes = statSync(join(root, file)).size;
+      } catch (_) {
+        bytes = 0;
+      }
+    }
+    // Keep the largest observation: the same path can appear in both ranges.
+    entries.set(file, Math.max(entries.get(file) || 0, bytes));
+  }
+
+  // Only the paths git itself refused to render as text are relevant; a file
+  // that diffed normally is already counted in the diff text.
+  const binaryPaths = new Set();
+  const text = diffText(root, base, mode);
+  for (const line of text.split("\n")) {
+    const m = line.match(/^Binary files (?:a\/(.+) and )?(?:b\/(.+)|\/dev\/null) differ$/);
+    if (m) binaryPaths.add(normalizePath(m[2] || m[1] || ""));
+    const m2 = line.match(/^Binary files \/dev\/null and b\/(.+) differ$/);
+    if (m2) binaryPaths.add(normalizePath(m2[1]));
+  }
+
+  return [...entries.entries()]
+    .filter(([file]) => binaryPaths.has(normalizePath(file)))
+    .map(([file, bytes]) => ({ file, bytes }));
+}
+
+/**
+ * Total bytes this change actually carries.
+ *
+ * The diff text plus the real size of every binary blob it only summarised.
+ * Without the second term the payload governor could be walked straight past
+ * with a committed binary of any size.
+ */
 export function diffBytes(root = process.cwd(), base = "main", mode = "committed") {
   const text = diffText(root, base, mode);
-  return Buffer.byteLength(text, "utf-8");
+  let bytes = Buffer.byteLength(text, "utf-8");
+  try {
+    for (const entry of binaryDiffEntries(root, base, mode)) bytes += entry.bytes;
+  } catch (_) {
+    // A payload figure that is too low is the dangerous direction, but throwing
+    // here would break every gate on a repo git cannot describe. The text-only
+    // number is still returned.
+  }
+  return bytes;
 }
 
 export function showFromOrigin(root = process.cwd(), base = "main", filePath = "") {

package/src/security.mjs

@@ -1,4 +1,4 @@
-import { openSync, writeSync, fsyncSync, closeSync, renameSync, realpathSync, existsSync, lstatSync, unlinkSync } from "node:fs";
+import { openSync, readFileSync, writeSync, fsyncSync, closeSync, renameSync, realpathSync, existsSync, lstatSync, unlinkSync } from "node:fs";
 import { dirname, join, basename } from "node:path";
 import { randomBytes } from "node:crypto";
 import { canonicalizePath, isWindowsAbsolutePath } from "./config.mjs";
@@ -911,6 +911,102 @@ export function hasHighEntropyToken(text = "", file = null) {
   return false;
 }
 
+/** Bytes of any one binary file the scanner will read. */
+const BINARY_SCAN_CAP_BYTES = 8 * 1024 * 1024;
+
+/** Runs of printable ASCII at least this long are worth classifying. */
+const BINARY_STRING_MIN_RUN = 8;
+
+/**
+ * Scan the contents of files git summarised as "Binary files ... differ".
+ *
+ * Everything else in this module reads the diff *text*, and git renders a
+ * binary file as one 43-byte summary line — so a credential became invisible to
+ * the entire scanner by prefixing the file with a single NUL byte. That is not
+ * a theoretical bypass: `printf '\0ghp_...' > secret.dat` walked a live GitHub
+ * token straight through a green gate.
+ *
+ * Only the *structured* high-confidence patterns are applied here, never
+ * entropy. A real PNG is full of high-entropy bytes and would fail every gate
+ * it touched; a string matching `ghp_[A-Za-z0-9]{36}` inside a file claiming to
+ * be an image is not a coincidence.
+ *
+ * @param {Array<{ file: string, bytes: number }>} entries
+ * @param {string} root
+ * @param {object} [opts]
+ * @param {number} [opts.capBytes] - per-file read ceiling
+ * @returns {Array<{ severity: string, type: string, file: string, line: null, description: string }>}
+ */
+export function scanBinaryPayloads(entries = [], root = process.cwd(), opts = {}) {
+  const cap = Number.isFinite(opts.capBytes) ? opts.capBytes : BINARY_SCAN_CAP_BYTES;
+  const findings = [];
+  // `entries` comes from a git call that returns null on failure, and the
+  // default parameter only covers `undefined`.
+  const list = Array.isArray(entries) ? entries : [];
+
+  for (const entry of list) {
+    if (!entry || !entry.file) continue;
+    // A file too large to read is reported rather than skipped: silence here is
+    // exactly the hole being closed.
+    if (entry.bytes > cap) {
+      findings.push({
+        severity: "HIGH",
+        type: "BINARY_PAYLOAD_UNSCANNED",
+        file: entry.file,
+        line: null,
+        description: `Binary file ${entry.file} is ${Math.round(entry.bytes / 1024)} KB, above the ${Math.round(cap / 1024)} KB scan ceiling, and was not inspected for credentials`,
+      });
+      continue;
+    }
+
+    let buf;
+    try {
+      buf = readFileSync(join(root, entry.file));
+    } catch (_) {
+      continue;
+    }
+
+    // Extract printable runs the way `strings(1)` does: a credential inside a
+    // binary is still ASCII, and decoding the whole buffer as UTF-8 would let
+    // replacement characters split the token apart.
+    const runs = [];
+    let current = "";
+    for (const byte of buf) {
+      if (byte >= 0x20 && byte <= 0x7e) {
+        current += String.fromCharCode(byte);
+      } else {
+        if (current.length >= BINARY_STRING_MIN_RUN) runs.push(current);
+        current = "";
+      }
+    }
+    if (current.length >= BINARY_STRING_MIN_RUN) runs.push(current);
+    if (runs.length === 0) continue;
+
+    const text = runs.join("\n");
+    if (hasHighConfidenceSecret(text)) {
+      findings.push({
+        severity: "CRITICAL",
+        type: "HIGH_CONFIDENCE_SECRET",
+        file: entry.file,
+        line: null,
+        description: `High-confidence secret pattern found inside binary file ${entry.file}, which the diff renders only as "Binary files ... differ"`,
+      });
+      continue;
+    }
+    if (hasEncodedSecret(text)) {
+      findings.push({
+        severity: "CRITICAL",
+        type: "HIGH_CONFIDENCE_SECRET",
+        file: entry.file,
+        line: null,
+        description: `Base64-encoded secret found inside binary file ${entry.file}`,
+      });
+    }
+  }
+
+  return findings;
+}
+
 /**
  * Classify a block of added lines. Returns the single most severe finding, or
  * null when the block is clean.
@@ -1024,6 +1120,24 @@ export function checkTestTampering(diffOrText = "", options = {}) {
   const ASSERTION_PATTERN = /(?:\b(?:assert(?:\.[a-zA-Z0-9_$]+)?|expect|t\.(?:assert|expect|is|equal|true|false|Errorf|Fatalf)|require\.[a-zA-Z0-9_$]+)\b|assert!|assert_eq!|assert_ne!)/i;
   const isCommentLine = (str) => /^\s*(?:\/\/|\/\*|\*|#|--|;)/.test(str);
 
+  // An assertion that states a *specific* expected value. Counting assertions
+  // alone let a test be gutted while looking untouched: swapping
+  // `assert.strictEqual(add(2,3), 5)` for `assert.ok(add(2,3) !== undefined)`
+  // removes one and adds one, so `removed > added` stayed false and the guard
+  // said nothing — while the suite stopped checking the answer.
+  const SPECIFIC_ASSERTION = new RegExp(
+    [
+      "\\bassert(?:\\.strict)?\\.?(?:strictEqual|deepStrictEqual|deepEqual|notStrictEqual|notDeepStrictEqual|equal|notEqual|match|doesNotMatch|throws|rejects|doesNotThrow)\\s*\\(",
+      "\\bexpect\\s*\\([^)]*\\)\\s*\\.(?:toBe|toEqual|toStrictEqual|toMatch|toMatchObject|toContain|toHaveBeenCalledWith|toThrow|toHaveLength|toBeCloseTo)\\s*\\(",
+      "\\bassert\\.(?:equals|deepEquals|include|lengthOf)\\s*\\(",
+      "assert_eq!|assert_ne!",
+      "\\bt\\.(?:Errorf|Fatalf)\\s*\\(",
+      "\\brequire\\.(?:Equal|NotEqual|Len|Contains|Error|NoError)\\s*\\(",
+    ].join("|"),
+    "i"
+  );
+  const isSpecificAssertion = (str) => SPECIFIC_ASSERTION.test(str);
+
   const fileAssertions = new Map();
 
   for (let i = 0; i < lines.length; i++) {
@@ -1055,7 +1169,7 @@ export function checkTestTampering(diffOrText = "", options = {}) {
     }
 
     if (!fileAssertions.has(currentFile)) {
-      fileAssertions.set(currentFile, { removed: [], added: 0 });
+      fileAssertions.set(currentFile, { removed: [], added: 0, removedSpecific: [], addedSpecific: 0 });
     }
     const fileStats = fileAssertions.get(currentFile);
 
@@ -1063,6 +1177,9 @@ export function checkTestTampering(diffOrText = "", options = {}) {
       const deletedText = line.slice(1);
       if (!isCommentLine(deletedText) && ASSERTION_PATTERN.test(deletedText)) {
         fileStats.removed.push({ line: currentOldLineNo, text: deletedText });
+        if (isSpecificAssertion(deletedText)) {
+          fileStats.removedSpecific.push({ line: currentOldLineNo, text: deletedText });
+        }
       }
       if (currentOldLineNo !== null) currentOldLineNo++;
     } else if (line.startsWith("+") && !line.startsWith("+++")) {
@@ -1109,6 +1226,7 @@ export function checkTestTampering(diffOrText = "", options = {}) {
       // If valid non-vacuous, non-commented assertion is added, increment added count
       if (!isVacuous && !isCommented && !isCommentLine(addedText) && ASSERTION_PATTERN.test(addedText)) {
         fileStats.added++;
+        if (isSpecificAssertion(addedText)) fileStats.addedSpecific++;
       }
 
       if (currentNewLineNo !== null) currentNewLineNo++;
@@ -1130,6 +1248,31 @@ export function checkTestTampering(diffOrText = "", options = {}) {
         });
       }
     }
+
+    // Replacing an assertion is not the same as keeping one. Counting totals
+    // let a specific expectation be swapped for a vague one at no cost — one
+    // out, one in, guard silent, suite no longer checking the answer. What must
+    // not fall is the number of assertions that name an expected value.
+    //
+    // Only the *replaced* ones are reported here. An assertion deleted outright
+    // is already an ASSERTION_REMOVAL above, and emitting both would report the
+    // same line twice under two names.
+    const alreadyReportedSpecific = stats.removed
+      .slice(stats.added)
+      .filter((item) => isSpecificAssertion(item.text)).length;
+    const specificLost = Math.max(0, stats.removedSpecific.length - stats.addedSpecific);
+    const weakenedCount = Math.max(0, specificLost - alreadyReportedSpecific);
+
+    if (weakenedCount > 0) {
+      for (const item of stats.removedSpecific.slice(stats.addedSpecific, stats.addedSpecific + weakenedCount)) {
+        violations.push({
+          file,
+          line: item.line,
+          type: "ASSERTION_WEAKENED",
+          reason: `Test Tamper Guard: Assertion weakened in ${file}${item.line ? `:${item.line}` : ""} — an assertion naming an expected value was replaced by one that does not: "${item.text.trim()}"`,
+        });
+      }
+    }
   }
 
   return {