@duckmind/dm-linux-x64 0.63.9 → 0.64.2

package/extensions/dm-lens/clients/git-guard.js

@@ -0,0 +1,721 @@
+import * as nodeFs from "node:fs";
+import * as path from "node:path";
+import { isPathIgnoredByProject } from "./file-utils.js";
+import { tokenizeShellCommand } from "./bash-file-access.js";
+import { logLatency } from "./latency-logger.js";
+import {
+  advisoryFileHash,
+  advisoryPathKey,
+  MAX_ADVISORY_AFFECTED_FILES,
+  snapshotAdvisoryProvenance
+} from "./advisory-provenance.js";
+function resolveGuardPath(filePath, cwd) {
+  return path.resolve(cwd, filePath);
+}
+function guardPathKey(filePath, cwd) {
+  return advisoryPathKey(filePath, cwd);
+}
+function fileFingerprint(filePath) {
+  return advisoryFileHash(filePath);
+}
+function currentFileFingerprint(filePath) {
+  try {
+    nodeFs.statSync(filePath);
+    return fileFingerprint(filePath);
+  } catch (err) {
+    return err.code === "ENOENT" ? "missing" : `unreadable:${err.code ?? "unknown"}`;
+  }
+}
+function capAffectedFiles(files, cwd) {
+  const unique = [...new Set(files.map((file) => resolveGuardPath(file, cwd)))];
+  return {
+    files: unique.slice(0, MAX_ADVISORY_AFFECTED_FILES),
+    truncated: unique.length > MAX_ADVISORY_AFFECTED_FILES
+  };
+}
+function hasCompleteBlockingProvenance(blockerContent, blockingFiles, cwd) {
+  if (typeof blockerContent !== "string" || blockerContent.length === 0)
+    return false;
+  if (!Array.isArray(blockingFiles) || blockingFiles.length === 0)
+    return false;
+  if (blockingFiles.some((file) => typeof file !== "string" || file.trim().length === 0)) {
+    return false;
+  }
+  const provenanceKeys = blockingFiles.map((file) => guardPathKey(file, cwd));
+  if (new Set(provenanceKeys).size !== provenanceKeys.length)
+    return false;
+  const blockerKeys = blockerContent.split(`
+`).map((line) => {
+    const separator = line.indexOf(": ");
+    if (separator <= 0)
+      return;
+    const file = line.slice(0, separator).trim();
+    return file.length > 0 ? guardPathKey(file, cwd) : undefined;
+  });
+  if (blockerKeys.some((key) => key === undefined))
+    return false;
+  const uniqueBlockerKeys = new Set(blockerKeys);
+  return uniqueBlockerKeys.size === blockerKeys.length && uniqueBlockerKeys.size === provenanceKeys.length && [...uniqueBlockerKeys].every((key) => provenanceKeys.includes(key));
+}
+function getShellCommand(input) {
+  if (!input || typeof input !== "object")
+    return "";
+  const raw = input;
+  if (typeof raw.command === "string" && raw.command.trim())
+    return raw.command;
+  if (typeof raw.cmd === "string" && raw.cmd.trim())
+    return raw.cmd;
+  if (typeof raw.command === "string")
+    return raw.command;
+  return "";
+}
+function executableName(value) {
+  const normalized = value.replace(/\\/g, "/");
+  let name = (normalized.slice(normalized.lastIndexOf("/") + 1) ?? "").toLowerCase();
+  return name.replace(/\.(?:exe|com|bat|cmd)$/i, "");
+}
+function isShellWrapper(value) {
+  return new Set([
+    "sh",
+    "bash",
+    "dash",
+    "zsh",
+    "ash",
+    "cmd",
+    "pwsh",
+    "powershell"
+  ]).has(executableName(value));
+}
+function isGitExecutable(value) {
+  return new Set(["git", "git.exe", "git.cmd", "git.bat"]).has(executableName(value));
+}
+const COMMAND_STRING_WRAPPERS = new Set(["busybox", "toybox", "nix-shell"]);
+function isCommandStringWrapper(value) {
+  return COMMAND_STRING_WRAPPERS.has(executableName(value));
+}
+function canonicalizeGuardCommand(command) {
+  let result = "";
+  let quote;
+  let escaped = false;
+  for (let i = 0;i < command.length; i++) {
+    const ch = command[i];
+    if (quote === "single") {
+      result += ch;
+      if (ch === "'")
+        quote = undefined;
+      continue;
+    }
+    if (quote === "double") {
+      result += ch;
+      if (escaped)
+        escaped = false;
+      else if (ch === "\\")
+        escaped = true;
+      else if (ch === '"')
+        quote = undefined;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch === "'" ? "single" : "double";
+      result += ch;
+      continue;
+    }
+    const parameter = command.slice(i).match(/^\$\{IFS[^}]*\}/)?.[0];
+    const positional = command.slice(i).match(/^\$IFS(?:\$[0-9]+)?/)?.[0];
+    if (parameter || positional) {
+      result += " ";
+      i += (parameter ?? positional ?? "").length - 1;
+      continue;
+    }
+    result += ch;
+  }
+  let collapsed = "";
+  let pendingSpace = false;
+  quote = undefined;
+  for (const ch of result) {
+    if (!quote && /\s/.test(ch)) {
+      pendingSpace = collapsed.length > 0;
+      continue;
+    }
+    if (pendingSpace)
+      collapsed += " ";
+    pendingSpace = false;
+    collapsed += ch;
+    if (!quote && (ch === "'" || ch === '"')) {
+      quote = ch === "'" ? "single" : "double";
+    } else if (quote === "single" && ch === "'" || quote === "double" && ch === '"') {
+      quote = undefined;
+    }
+  }
+  return collapsed.trim();
+}
+function normalizeGuardVerbToken(value) {
+  return value.replace(/\\(?=[A-Za-z0-9_])/g, "").replace(/`(?=.)/g, "").replace(/\^(?=.)/g, "");
+}
+function expandGuardVerbToken(value) {
+  return normalizeGuardVerbToken(value).trim().split(/\s+/).filter(Boolean);
+}
+function delimitedSubstitutionBody(command, start, opener, closer) {
+  let depth = 1;
+  let quote;
+  let escaped = false;
+  for (let i = start + opener.length;i < command.length; i++) {
+    const ch = command[i];
+    if (quote === "single") {
+      if (ch === "'")
+        quote = undefined;
+      continue;
+    }
+    if (quote === "double" && ch === '"') {
+      quote = undefined;
+      continue;
+    }
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch === "'" ? "single" : "double";
+      continue;
+    }
+    if (command.startsWith(opener, i)) {
+      depth += 1;
+      i += opener.length - 1;
+      continue;
+    }
+    if (command.startsWith(closer, i) && --depth === 0) {
+      return { body: command.slice(start + opener.length, i), end: i };
+    }
+  }
+  return;
+}
+const COMMIT_PUSH_MATCHER = {
+  id: "commit-push",
+  matchesVerb: (verb) => verb === "commit" || verb === "push",
+  indirectAlwaysMatches: true,
+  suppressPostVerbHelp: false
+};
+function containsGuardedSubstitution(command, depth, matcher) {
+  if (depth > 3)
+    return false;
+  let quote;
+  let escaped = false;
+  for (let i = 0;i < command.length; i++) {
+    const ch = command[i];
+    if (quote === "single") {
+      if (ch === "'")
+        quote = undefined;
+      continue;
+    }
+    if (quote === "double" && ch === '"') {
+      quote = undefined;
+      continue;
+    }
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch === "'" ? "single" : "double";
+      continue;
+    }
+    const substitution = command.startsWith("$(", i) ? delimitedSubstitutionBody(command, i, "$(", ")") : command.startsWith("<(", i) ? delimitedSubstitutionBody(command, i, "<(", ")") : command.startsWith(">(", i) ? delimitedSubstitutionBody(command, i, ">(", ")") : ch === "`" ? {
+      body: command.slice(i + 1, command.indexOf("`", i + 1)),
+      end: command.indexOf("`", i + 1)
+    } : undefined;
+    if (substitution && substitution.end >= 0) {
+      const nested = canonicalizeGuardCommand(substitution.body);
+      if (containsGuardedSubstitution(nested, depth + 1, matcher) || tokenizeShellCommand(nested).some((segment) => containsGuardedGitVerb(segment.tokens, depth + 1, matcher))) {
+        return true;
+      }
+      i = substitution.end;
+    }
+  }
+  return false;
+}
+const GIT_GLOBAL_OPTIONS_WITH_VALUE = new Set([
+  "-C",
+  "-c",
+  "--config-env",
+  "--git-dir",
+  "--work-tree",
+  "--exec-path",
+  "--namespace"
+]);
+const GIT_GLOBAL_OPTIONS_WITH_INLINE_VALUE = [
+  "--config-env",
+  "--git-dir",
+  "--work-tree",
+  "--exec-path",
+  "--namespace"
+];
+function gitVerbIndex(gitTokens) {
+  let i = 1;
+  while (i < gitTokens.length && gitTokens[i].startsWith("-")) {
+    const option = gitTokens[i];
+    if (["--help", "-h", "--version", "-v", "-V"].includes(option)) {
+      return;
+    }
+    if (option === "--")
+      return i + 1 < gitTokens.length ? i + 1 : undefined;
+    if (["-C", "-c"].some((prefix) => option.startsWith(prefix) && option.length > prefix.length)) {
+      i += 1;
+      continue;
+    }
+    if (GIT_GLOBAL_OPTIONS_WITH_INLINE_VALUE.some((prefix) => option.startsWith(`${prefix}=`))) {
+      i += 1;
+      continue;
+    }
+    i += GIT_GLOBAL_OPTIONS_WITH_VALUE.has(option) ? 2 : 1;
+  }
+  return i < gitTokens.length ? i : undefined;
+}
+export function matchGitVerbAtCommandPosition(gitTokens, matcher) {
+  const index = gitVerbIndex(gitTokens);
+  if (index === undefined)
+    return false;
+  const argsAfterVerb = gitTokens.slice(index + 1);
+  if (matcher.suppressPostVerbHelp && (argsAfterVerb[0] === "--help" || argsAfterVerb[0] === "-h")) {
+    return false;
+  }
+  const verbs = expandGuardVerbToken(gitTokens[index] ?? "");
+  return verbs.length === 1 && matcher.matchesVerb(verbs[0], argsAfterVerb);
+}
+function unquoteGuardValue(value) {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === '"' || first === "'") && first === last) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+export function resolveGitTargetDirectory(gitTokens, cwd) {
+  let base = cwd;
+  let workTree;
+  let i = 1;
+  while (i < gitTokens.length && gitTokens[i].startsWith("-")) {
+    const option = gitTokens[i];
+    if (["--help", "-h", "--version", "-v", "-V"].includes(option))
+      break;
+    if (option === "--")
+      break;
+    if (option === "-C" && i + 1 < gitTokens.length) {
+      base = path.resolve(base, unquoteGuardValue(gitTokens[i + 1]));
+      i += 2;
+      continue;
+    }
+    if (option.startsWith("-C") && option.length > 2) {
+      base = path.resolve(base, unquoteGuardValue(option.slice(2)));
+      i += 1;
+      continue;
+    }
+    if (option === "--work-tree" && i + 1 < gitTokens.length) {
+      workTree = unquoteGuardValue(gitTokens[i + 1]);
+      i += 2;
+      continue;
+    }
+    if (option.startsWith("--work-tree=")) {
+      workTree = unquoteGuardValue(option.slice("--work-tree=".length));
+      i += 1;
+      continue;
+    }
+    if (option.startsWith("-c") && option.length > 2 && !option.startsWith("--")) {
+      i += 1;
+      continue;
+    }
+    if (GIT_GLOBAL_OPTIONS_WITH_INLINE_VALUE.some((prefix) => option.startsWith(`${prefix}=`))) {
+      i += 1;
+      continue;
+    }
+    i += GIT_GLOBAL_OPTIONS_WITH_VALUE.has(option) ? 2 : 1;
+  }
+  return workTree === undefined ? base : path.resolve(base, workTree);
+}
+export function collectGitInvocations(toolName, input) {
+  if (toolName !== "bash")
+    return [];
+  const command = getShellCommand(input);
+  if (!command)
+    return [];
+  const invocations = [];
+  for (const segment of tokenizeShellCommand(canonicalizeGuardCommand(command))) {
+    const gitIndex = segment.tokens.findIndex((token) => isGitExecutable(token));
+    if (gitIndex >= 0)
+      invocations.push(segment.tokens.slice(gitIndex));
+  }
+  return invocations;
+}
+function containsGuardedGitVerb(tokens, depth, matcher) {
+  if (depth > 3 || tokens.length === 0)
+    return false;
+  let commandTokens = tokens;
+  while (/^[A-Za-z_][A-Za-z0-9_]*=/.test(commandTokens[0] ?? "")) {
+    commandTokens = commandTokens.slice(1);
+  }
+  if (commandTokens.length === 0)
+    return false;
+  const expandedHead = expandGuardVerbToken(commandTokens[0] ?? "");
+  if (expandedHead.length > 1) {
+    commandTokens = [...expandedHead, ...commandTokens.slice(1)];
+  }
+  if (isCommandStringWrapper(commandTokens[0] ?? "")) {
+    const lower = commandTokens.slice(1).map((token) => token.toLowerCase());
+    const runIndex = lower.findIndex((token) => token === "--run");
+    if (runIndex >= 0 && runIndex + 1 < commandTokens.length) {
+      const nestedCommand = commandTokens.slice(runIndex + 2).join(" ");
+      return tokenizeShellCommand(canonicalizeGuardCommand(nestedCommand)).some((segment) => containsGuardedGitVerb(segment.tokens, depth + 1, matcher));
+    }
+  }
+  if (["echo", "printf", "grep"].includes(executableName(commandTokens[0] ?? ""))) {
+    return false;
+  }
+  const gitIndex = commandTokens.findIndex((token) => isGitExecutable(token));
+  if (gitIndex >= 0) {
+    if (gitIndex > 0 && matcher.indirectAlwaysMatches)
+      return true;
+    return matchGitVerbAtCommandPosition(commandTokens.slice(gitIndex), matcher);
+  }
+  const leadingExecutable = commandTokens[0] ?? "";
+  const knownCommandStringWrapper = isShellWrapper(leadingExecutable) || isCommandStringWrapper(leadingExecutable);
+  if (!knownCommandStringWrapper) {
+    const unknownSwitchIndex = commandTokens.slice(1).findIndex((token) => (token.startsWith("-") || token.startsWith("/")) && token.length > 1);
+    if (unknownSwitchIndex < 0)
+      return false;
+    const commandIndex = unknownSwitchIndex + 2;
+    if (commandIndex >= commandTokens.length)
+      return false;
+    const nestedCommand = commandTokens.slice(commandIndex).join(" ");
+    return tokenizeShellCommand(canonicalizeGuardCommand(nestedCommand)).some((segment) => containsGuardedGitVerb(segment.tokens, depth + 1, matcher));
+  }
+  const lower = commandTokens.slice(1).map((token) => token.toLowerCase());
+  const switchIndex = lower.findIndex((token) => token === "-c" || token === "--run" || token === "-lc" || /^-[^-]*c$/.test(token) && !token.startsWith("--") || token === "/c" || token === "-command" || token === "-command:" || token === "-encodedcommand");
+  if (switchIndex < 0 || switchIndex + 1 >= commandTokens.length)
+    return false;
+  if (lower[switchIndex] === "-encodedcommand")
+    return false;
+  let commandIndex = switchIndex + 2;
+  if (commandTokens[commandIndex] === "--")
+    commandIndex += 1;
+  const nestedCommand = commandTokens.slice(commandIndex).join(" ");
+  return tokenizeShellCommand(canonicalizeGuardCommand(nestedCommand)).some((segment) => containsGuardedGitVerb(segment.tokens, depth + 1, matcher));
+}
+export function detectGuardedGitVerb(toolName, input, matcher) {
+  if (toolName !== "bash")
+    return false;
+  const command = getShellCommand(input);
+  if (!command)
+    return false;
+  const canonical = canonicalizeGuardCommand(command);
+  if (containsGuardedSubstitution(canonical, 0, matcher))
+    return true;
+  return tokenizeShellCommand(canonical).some((segment) => containsGuardedGitVerb(segment.tokens, 0, matcher));
+}
+export function isGitCommitOrPushAttempt(toolName, input) {
+  return detectGuardedGitVerb(toolName, input, COMMIT_PUSH_MATCHER);
+}
+function isTurnEndFindingsCache(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const record = value;
+  return typeof record.content === "string" && typeof record.hasBlockers === "boolean" && Array.isArray(record.affectedFiles) && record.affectedFiles.every((file) => typeof file === "string") && typeof record.sessionId === "string" && typeof record.projectSeqStart === "number" && typeof record.projectSeqEnd === "number" && Number.isFinite(record.projectSeqStart) && Number.isFinite(record.projectSeqEnd) && !!record.fileSeqByPath && typeof record.fileSeqByPath === "object" && Object.values(record.fileSeqByPath).every((seq) => typeof seq === "number" && Number.isFinite(seq)) && !!record.fileContentHashes && typeof record.fileContentHashes === "object" && Object.values(record.fileContentHashes).every((hash) => typeof hash === "string") && (record.affectedFilesTruncated === undefined || typeof record.affectedFilesTruncated === "boolean") && (record.blockingFiles === undefined || Array.isArray(record.blockingFiles));
+}
+function cacheRecord(cacheManager, cwd) {
+  const entry = cacheManager.readCache("turn-end-findings", cwd);
+  return entry && isTurnEndFindingsCache(entry.data) ? entry.data : undefined;
+}
+function markCacheUnknown(runtime, reason) {
+  runtime.markGitGuardCacheUnknown(reason);
+}
+export function writeGitGuardRecord(cacheManager, runtime, cwd, record) {
+  const capped = capAffectedFiles(Array.isArray(record.affectedFiles) ? record.affectedFiles : [], cwd);
+  const fileSeqByPath = { ...record.fileSeqByPath };
+  for (const file of capped.files) {
+    const key = guardPathKey(file, cwd);
+    if (fileSeqByPath[key] === undefined) {
+      fileSeqByPath[key] = runtime.getFileSeq(resolveGuardPath(file, cwd));
+    }
+  }
+  const currentProvenance = snapshotAdvisoryProvenance({
+    cwd,
+    runtime,
+    generation: 0,
+    files: capped.files.map((file) => ({
+      path: file,
+      role: "affected"
+    })),
+    truncated: capped.truncated
+  });
+  const fileContentHashes = Object.fromEntries(currentProvenance.files.map((file) => [
+    guardPathKey(file.path, cwd),
+    file.sha256
+  ]));
+  const data = {
+    ...record,
+    affectedFiles: capped.files,
+    affectedFilesTruncated: capped.truncated,
+    fileSeqByPath,
+    blockingFiles: Array.isArray(record.blockingFiles) ? capAffectedFiles(record.blockingFiles, cwd).files : undefined,
+    fileContentHashes,
+    provenance: record.provenance ?? currentProvenance
+  };
+  try {
+    cacheManager.writeCache("turn-end-findings", data, cwd);
+    runtime.clearGitGuardCacheUnknown();
+    return true;
+  } catch {
+    markCacheUnknown(runtime, "cache_write_failed");
+    return false;
+  }
+}
+function logDecision(cwd, decision, reasonCategory, metadata = {}) {
+  logLatency({
+    type: "phase",
+    toolName: "git-guard",
+    filePath: cwd,
+    phase: "decision",
+    durationMs: 0,
+    result: decision,
+    metadata: { decision, reasonCategory, ...metadata }
+  });
+}
+function unknown(cwd, reasonCategory, metadata = {}) {
+  logDecision(cwd, "unknown", reasonCategory, metadata);
+  return {
+    block: true,
+    unknown: true,
+    reason: `\uD83D\uDD34 COMMIT BLOCKED (--lens-guard): blocker state is unknown (${reasonCategory}). Re-run dm-lens checks or start a fresh session, then retry.`
+  };
+}
+export function retireInlineBlockerAndResyncGuard(args) {
+  const retired = args.runtime.retireInlineBlockerOnConfirmedClean(args.filePath, args.writeIndex, args.coveredSources);
+  if (!retired)
+    return false;
+  args.runtime.updateGitGuardStatus(false, "");
+  if (args.lensGuardEnabled) {
+    syncGitGuardRecord(args.runtime, args.cacheManager, args.cwd, args.filePath);
+  }
+  return true;
+}
+export function syncGitGuardRecord(runtime, cacheManager, cwd, editedFilePath) {
+  const entries = runtime.getInlineBlockersSnapshot?.() ?? [];
+  const inspection = cacheManager.inspectCache("turn-end-findings", cwd);
+  const existing = cacheRecord(cacheManager, cwd);
+  if (existing && existing.sessionId !== runtime.telemetrySessionId && entries.length === 0) {
+    markCacheUnknown(runtime, "session_mismatch");
+    return;
+  }
+  if (!existing && inspection !== "missing" && entries.length === 0) {
+    markCacheUnknown(runtime, `cache_${inspection}`);
+    return;
+  }
+  const fileSeqByPath = {};
+  for (const [filePath, seq] of runtime.getFileSeqEntries?.() ?? []) {
+    fileSeqByPath[guardPathKey(filePath, cwd)] = seq;
+  }
+  const inlineFiles = entries.map((entry) => resolveGuardPath(entry.filePath, cwd));
+  const existingBlockingFiles = existing?.blockingFiles ?? [];
+  const provenanceComplete = existing?.blockerContent ? hasCompleteBlockingProvenance(existing.blockerContent, existingBlockingFiles, cwd) : true;
+  if (existing?.blockerContent && !provenanceComplete) {
+    markCacheUnknown(runtime, "blocking_provenance_untrusted");
+    return;
+  }
+  const editedKey = editedFilePath ? guardPathKey(editedFilePath, cwd) : undefined;
+  const testFiles = existing?.testFailureFiles ?? [];
+  const remainingBlockingFiles = editedKey && existingBlockingFiles.length > 0 ? existingBlockingFiles.filter((file) => guardPathKey(file, cwd) !== editedKey) : existingBlockingFiles;
+  let affectedFiles = [...existing?.affectedFiles ?? [], ...inlineFiles];
+  if (!entries.length && editedKey && existing) {
+    const isStillTestFailure = testFiles.some((file) => guardPathKey(file, cwd) === editedKey);
+    const isUnknownBlockingPath = existingBlockingFiles.length === 0 && !!existing.blockerContent;
+    if (!isStillTestFailure && !isUnknownBlockingPath) {
+      affectedFiles = affectedFiles.filter((file) => guardPathKey(file, cwd) !== editedKey);
+    }
+  }
+  const clearedLastKnownBlocker = !entries.length && !!editedKey && provenanceComplete && existingBlockingFiles.length > 0 && remainingBlockingFiles.length === 0;
+  const blockerContent = entries.length > 0 ? entries.map((entry) => `${entry.filePath}: ${entry.summary}`).join(`
+`) : clearedLastKnownBlocker ? undefined : existing?.blockerContent;
+  const hasTestFailures = existing?.testFailures === true;
+  const hasBlockers = !!blockerContent || hasTestFailures;
+  const content = [
+    blockerContent,
+    hasTestFailures ? existing?.testFailureContent : undefined
+  ].filter((value) => !!value).join(`
+
+`);
+  if (!hasBlockers && !content) {
+    cacheManager.clearCache("turn-end-findings", cwd);
+    return;
+  }
+  writeGitGuardRecord(cacheManager, runtime, cwd, {
+    content: content || existing?.content || "",
+    blockerContent,
+    blockingFiles: entries.length > 0 ? inlineFiles : remainingBlockingFiles,
+    hasBlockers,
+    affectedFiles,
+    sessionId: runtime.telemetrySessionId,
+    projectSeqStart: runtime.turnStartProjectSeq,
+    projectSeqEnd: runtime.projectSeq,
+    fileSeqByPath,
+    fileContentHashes: {},
+    consumed: false,
+    testFailures: existing?.testFailures,
+    testFailureContent: existing?.testFailureContent,
+    testFailureFiles: existing?.testFailureFiles
+  });
+}
+export function mergeGitGuardTestFailure(cacheManager, cwd, runtime, content, files) {
+  const existing = cacheRecord(cacheManager, cwd);
+  const fileSeqByPath = {};
+  for (const [filePath, seq] of runtime.getFileSeqEntries?.() ?? []) {
+    fileSeqByPath[guardPathKey(filePath, cwd)] = seq;
+  }
+  const failedFiles = files.map((file) => resolveGuardPath(file, cwd));
+  const blockerContent = existing?.blockerContent;
+  const testFailureFiles = [
+    ...existing?.testFailureFiles ?? [],
+    ...failedFiles
+  ].filter((file, index, all) => all.findIndex((candidate) => guardPathKey(candidate, cwd) === guardPathKey(file, cwd)) === index);
+  writeGitGuardRecord(cacheManager, runtime, cwd, {
+    content: [blockerContent, content].filter(Boolean).join(`
+
+`),
+    blockerContent,
+    blockingFiles: existing?.blockingFiles ?? [],
+    testFailureContent: content,
+    testFailureFiles,
+    hasBlockers: true,
+    affectedFiles: [...existing?.affectedFiles ?? [], ...failedFiles],
+    sessionId: runtime.telemetrySessionId,
+    projectSeqStart: runtime.turnStartProjectSeq,
+    projectSeqEnd: runtime.projectSeq,
+    fileSeqByPath,
+    fileContentHashes: {},
+    consumed: false,
+    testFailures: true
+  });
+}
+export function clearGitGuardTestFailure(cacheManager, cwd, runtime, passedFiles = []) {
+  const existing = cacheRecord(cacheManager, cwd);
+  if (!existing?.testFailures)
+    return;
+  const passedKeys = new Set((passedFiles.length > 0 ? passedFiles : existing.testFailureFiles ?? []).map((file) => guardPathKey(file, cwd)));
+  const remainingFiles = (existing.testFailureFiles ?? []).filter((file) => !passedKeys.has(guardPathKey(file, cwd)));
+  const blockerContent = existing.blockerContent ?? "";
+  if (!blockerContent && remainingFiles.length === 0) {
+    cacheManager.clearCache("turn-end-findings", cwd);
+    return;
+  }
+  const blockingKeys = new Set((existing.blockingFiles ?? []).map((file) => guardPathKey(file, cwd)));
+  const affectedFiles = existing.affectedFiles.filter((file) => blockingKeys.has(guardPathKey(file, cwd)) || remainingFiles.some((testFile) => guardPathKey(testFile, cwd) === guardPathKey(file, cwd)));
+  writeGitGuardRecord(cacheManager, runtime, cwd, {
+    ...existing,
+    content: blockerContent,
+    blockerContent,
+    affectedFiles,
+    testFailures: remainingFiles.length > 0,
+    testFailureContent: remainingFiles.length > 0 ? existing.testFailureContent : undefined,
+    testFailureFiles: remainingFiles.length > 0 ? remainingFiles : undefined,
+    hasBlockers: !!blockerContent || remainingFiles.length > 0,
+    sessionId: runtime.telemetrySessionId,
+    projectSeqStart: runtime.turnStartProjectSeq,
+    projectSeqEnd: runtime.projectSeq,
+    fileSeqByPath: Object.fromEntries(runtime.getFileSeqEntries().map(([filePath, seq]) => [guardPathKey(filePath, cwd), seq])),
+    fileContentHashes: {}
+  });
+}
+export function evaluateGitGuard(runtime, cacheManager, cwd) {
+  if (runtime.gitGuardHasBlockers) {
+    logDecision(cwd, "blocked", "runtime_blockers", {
+      projectSeq: runtime.projectSeq
+    });
+    const detail = runtime.gitGuardSummary ? `
+${runtime.gitGuardSummary}` : "";
+    return {
+      block: true,
+      reason: `\uD83D\uDD34 COMMIT BLOCKED (--lens-guard): unresolved blockers must be fixed before commit/push.${detail}
+Run lens_diagnostics mode=all for full details, then commit again.`
+    };
+  }
+  if (runtime.gitGuardCacheUnknownReason) {
+    return unknown(cwd, runtime.gitGuardCacheUnknownReason);
+  }
+  const inspection = cacheManager.inspectCache("turn-end-findings", cwd);
+  if (inspection === "missing") {
+    logDecision(cwd, "allowed", "no_record");
+    return { block: false };
+  }
+  if (inspection !== "fresh")
+    return unknown(cwd, `cache_${inspection}`);
+  const pending = cacheManager.readCache("turn-end-findings", cwd);
+  if (!pending || !isTurnEndFindingsCache(pending.data)) {
+    return unknown(cwd, "cache_malformed");
+  }
+  const record = pending.data;
+  if (!record.hasBlockers) {
+    logDecision(cwd, "allowed", "advisory_only");
+    return { block: false };
+  }
+  if (record.affectedFilesTruncated) {
+    return unknown(cwd, "affected_files_truncated");
+  }
+  if (record.sessionId !== runtime.telemetrySessionId) {
+    return unknown(cwd, "session_mismatch");
+  }
+  if (record.projectSeqEnd !== runtime.projectSeq) {
+    return unknown(cwd, "project_sequence_mismatch", {
+      recordedProjectSeq: record.projectSeqEnd,
+      currentProjectSeq: runtime.projectSeq
+    });
+  }
+  const liveFiles = [];
+  for (const file of record.affectedFiles) {
+    const resolved = resolveGuardPath(file, cwd);
+    const key = guardPathKey(resolved, cwd);
+    const recordedSeq = record.fileSeqByPath[key];
+    if (recordedSeq === undefined || recordedSeq !== (runtime.getFileSeq?.(resolved) ?? 0)) {
+      return unknown(cwd, "file_sequence_mismatch", { file: resolved });
+    }
+    try {
+      if (!isPathIgnoredByProject(resolved, runtime.projectRoot || cwd, false)) {
+        const currentHash = currentFileFingerprint(resolved);
+        if (currentHash !== "missing") {
+          liveFiles.push(resolved);
+          const expectedHash = record.fileContentHashes[key];
+          if (!expectedHash || expectedHash.startsWith("unreadable:") || currentHash.startsWith("unreadable:") || expectedHash !== currentHash) {
+            return unknown(cwd, "file_content_changed", { file: resolved });
+          }
+        }
+      }
+    } catch {
+      return unknown(cwd, "file_unreadable", { file: resolved });
+    }
+  }
+  if (record.hasBlockers && record.affectedFiles.length === 0) {
+    return unknown(cwd, "blocker_without_affected_file");
+  }
+  if (record.hasBlockers && liveFiles.length === 0 && record.affectedFiles.length > 0) {
+    logDecision(cwd, "allowed", "affected_files_resolved", {
+      projectSeq: record.projectSeqEnd
+    });
+    return { block: false };
+  }
+  logDecision(cwd, "blocked", "cache_blockers", {
+    projectSeq: record.projectSeqEnd,
+    affectedFileCount: record.affectedFiles.length
+  });
+  return {
+    block: true,
+    reason: `\uD83D\uDD34 COMMIT BLOCKED (--lens-guard): unresolved blockers must be fixed before commit/push.
+Run lens_diagnostics mode=all for full details, then commit again.`
+  };
+}