@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

package/node_modules/pi-lens/dist/clients/git-guard.js

@@ -1,32 +1,702 @@
+import { createHash } from "node:crypto";
+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 { normalizeMapKey } from "./path-utils.js";
+import { logLatency } from "./latency-logger.js";
+const MAX_AFFECTED_FILES = 256;
+function resolveGuardPath(filePath, cwd) {
+    return path.resolve(cwd, filePath);
+}
+function guardPathKey(filePath, cwd) {
+    return normalizeMapKey(resolveGuardPath(filePath, cwd));
+}
+function fileFingerprint(filePath) {
+    try {
+        return createHash("sha256").update(nodeFs.readFileSync(filePath)).digest("hex");
+    }
+    catch (err) {
+        return `unreadable:${err.code ?? "unknown"}`;
+    }
+}
+function currentFileFingerprint(filePath) {
+    try {
+        nodeFs.statSync(filePath);
+        return fileFingerprint(filePath);
+    }
+    catch (err) {
+        return err.code === "ENOENT"
+            ? "missing"
+            : `unreadable:${err.code ?? "unknown"}`;
+    }
+}
+function snapshotFileHashes(files, cwd) {
+    const hashes = {};
+    for (const file of files) {
+        const resolved = resolveGuardPath(file, cwd);
+        hashes[guardPathKey(resolved, cwd)] = currentFileFingerprint(resolved);
+    }
+    return hashes;
+}
+function capAffectedFiles(files, cwd) {
+    const unique = [...new Set(files.map((file) => resolveGuardPath(file, cwd)))];
+    return {
+        files: unique.slice(0, MAX_AFFECTED_FILES),
+        truncated: unique.length > MAX_AFFECTED_FILES,
+    };
+}
+/** Recovery is safe only when blocker content and its file provenance agree. */
+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("\n").map((line) => {
+        const separator = line.indexOf(": ");
+        if (separator <= 0)
+            return undefined;
+        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")
+    if (typeof raw.command === "string" && raw.command.trim())
         return raw.command;
-    if (typeof raw.cmd === "string")
+    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();
+    // Shell launchers are commonly supplied as resolved Windows paths or as
+    // PATHEXT-qualified names. Guard classification must happen after the same
+    // basename/extension normalization for every wrapper family.
+    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));
+}
+/**
+ * Canonicalize shell parameter separators before command classification. The
+ * quote-aware pass deliberately leaves literal arguments alone; the lexer
+ * then supplies the command-position boundaries used by the guard.
+ */
+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();
+}
+/** Normalize only a command-position token; never apply this to path args. */
+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 undefined;
+}
+function containsGuardedSubstitution(command, depth) {
+    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) ||
+                tokenizeShellCommand(nested).some((segment) => containsCommitOrPush(segment.tokens, depth + 1))) {
+                return true;
+            }
+            i = substitution.end;
+        }
+    }
+    return false;
+}
+function containsCommitOrPush(tokens, depth) {
+    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) => containsCommitOrPush(segment.tokens, depth + 1));
+        }
+    }
+    // These commands consume their following words as text/patterns; a bare
+    // git token in their arguments is not an indirect executable invocation.
+    // `$(git push)` is execution and must block; `"git push"` as literal text
+    // is allowed. Substitutions are screened before this text-consumer escape.
+    if (["echo", "printf", "grep"].includes(executableName(commandTokens[0] ?? ""))) {
+        return false;
+    }
+    const gitIndex = commandTokens.findIndex((token) => isGitExecutable(token));
+    if (gitIndex >= 0) {
+        // Any non-leading git invocation is indirect. Do not maintain a wrapper
+        // or flag allowlist: unknown launchers are the security boundary here.
+        if (gitIndex > 0)
+            return true;
+        const gitTokens = commandTokens.slice(gitIndex);
+        let i = 1;
+        const takesValue = new Set([
+            "-C",
+            "-c",
+            "--config-env",
+            "--git-dir",
+            "--work-tree",
+            "--exec-path",
+            "--namespace",
+        ]);
+        while (i < gitTokens.length && gitTokens[i].startsWith("-")) {
+            const option = gitTokens[i];
+            if (["--help", "-h", "--version", "-v", "-V"].includes(option))
+                return false;
+            if (option === "--")
+                return gitTokens[i + 1] === "commit" || gitTokens[i + 1] === "push";
+            if (["-C", "-c"].some((prefix) => option.startsWith(prefix) && option.length > prefix.length)) {
+                i += 1;
+                continue;
+            }
+            if (["--config-env", "--git-dir", "--work-tree", "--exec-path", "--namespace"].some((prefix) => option.startsWith(`${prefix}=`))) {
+                i += 1;
+                continue;
+            }
+            i += takesValue.has(option) ? 2 : 1;
+        }
+        const verbs = expandGuardVerbToken(gitTokens[i] ?? "");
+        return verbs.length === 1 && (verbs[0] === "commit" || verbs[0] === "push");
+    }
+    const leadingExecutable = commandTokens[0] ?? "";
+    const knownCommandStringWrapper = isShellWrapper(leadingExecutable) || isCommandStringWrapper(leadingExecutable);
+    if (!knownCommandStringWrapper) {
+        // Unknown launchers are a fail-closed boundary only when they explicitly
+        // accept a command string. Re-tokenizing the value keeps literal mentions
+        // such as `myprog -c "echo git push"` out of the guarded-command path.
+        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) => containsCommitOrPush(segment.tokens, depth + 1));
+    }
+    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;
+    // Encoded PowerShell is intentionally unsupported: decoding it here would
+    // be a second shell/parser and could turn an ambiguous command into a false
+    // allow. Plain -Command/-c is safely handed back to the shared lexer.
+    if (lower[switchIndex] === "-encodedcommand")
+        return false;
+    // switchIndex is relative to commandTokens.slice(1), so +2 addresses the
+    // command token after the switch for both cmd and PowerShell. This also
+    // handles cmd options preceding /C (for example `/S /C`).
+    let commandIndex = switchIndex + 2;
+    if (commandTokens[commandIndex] === "--")
+        commandIndex += 1;
+    const nestedCommand = commandTokens.slice(commandIndex).join(" ");
+    return tokenizeShellCommand(canonicalizeGuardCommand(nestedCommand)).some((segment) => containsCommitOrPush(segment.tokens, depth + 1));
+}
+/** Analyze actual executable invocations, not substrings in shell text. */
 export function isGitCommitOrPushAttempt(toolName, input) {
     if (toolName !== "bash")
         return false;
-    const cmd = getShellCommand(input).toLowerCase();
-    if (!cmd)
+    const command = getShellCommand(input);
+    if (!command)
+        return false;
+    const canonical = canonicalizeGuardCommand(command);
+    if (containsGuardedSubstitution(canonical, 0))
+        return true;
+    return tokenizeShellCommand(canonical).some((segment) => containsCommitOrPush(segment.tokens, 0));
+}
+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);
+}
+/** Persist a complete, bounded, content-bound guard record. */
+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 data = {
+        ...record,
+        affectedFiles: capped.files,
+        affectedFilesTruncated: capped.truncated,
+        fileSeqByPath,
+        blockingFiles: Array.isArray(record.blockingFiles)
+            ? capAffectedFiles(record.blockingFiles, cwd).files
+            : undefined,
+        fileContentHashes: snapshotFileHashes(capped.files, cwd),
+    };
+    try {
+        cacheManager.writeCache("turn-end-findings", data, cwd);
+        runtime.clearGitGuardCacheUnknown();
+        return true;
+    }
+    catch {
+        markCacheUnknown(runtime, "cache_write_failed");
         return false;
-    return /(^|\s|&&|;|\|)git\s+(commit|push)(\s|$)/.test(cmd);
+    }
+}
+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: `🔴 COMMIT BLOCKED (--lens-guard): blocker state is unknown (${reasonCategory}). Re-run pi-lens checks or start a fresh session, then retry.`,
+    };
+}
+/**
+ * Reconcile the one persisted record after a per-file dispatch. This is called
+ * on tool_result, never tool_call, and therefore does not add disk I/O to the
+ * edit preflight path.
+ */
+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);
+        }
+    }
+    // A clean per-file dispatch is authoritative for that file. When the
+    // persisted record has explicit blocking-file provenance and the last such
+    // file just reconciled clean, retaining blockerContent would resurrect a
+    // stale blocker on every later git-guard lookup. Records without that
+    // provenance remain fail-closed: they cannot be safely cleared here.
+    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("\n")
+        : clearedLastKnownBlocker
+            ? undefined
+            : existing?.blockerContent;
+    const hasTestFailures = existing?.testFailures === true;
+    const hasBlockers = !!blockerContent || hasTestFailures;
+    const content = [blockerContent, hasTestFailures ? existing?.testFailureContent : undefined]
+        .filter((value) => !!value)
+        .join("\n\n");
+    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,
+    });
+}
+/** Add blocking test failures to the same turn-end record. */
+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("\n\n"),
+        blockerContent,
+        blockingFiles: existing?.blockingFiles ?? [],
+        testFailureContent: content,
+        testFailureFiles: testFailureFiles,
+        hasBlockers: true,
+        affectedFiles: [...(existing?.affectedFiles ?? []), ...failedFiles],
+        sessionId: runtime.telemetrySessionId,
+        projectSeqStart: runtime.turnStartProjectSeq,
+        projectSeqEnd: runtime.projectSeq,
+        fileSeqByPath,
+        fileContentHashes: {},
+        consumed: false,
+        testFailures: true,
+    });
+}
+/** A passing test run resolves only its own previous test failures. */
+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 ? `\n${runtime.gitGuardSummary}` : "";
+        return {
+            block: true,
+            reason: `🔴 COMMIT BLOCKED (--lens-guard): unresolved blockers must be fixed before commit/push.${detail}\nRun 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);
-    const turnEndHasBlockers = !!pending?.data?.content;
-    if (!runtime.gitGuardHasBlockers && !turnEndHasBlockers) {
+    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");
+    }
+    // A deleted/ignored affected file has been resolved; no stale blocker is
+    // allowed to survive solely because its old path remains in the record.
+    if (record.hasBlockers && liveFiles.length === 0 && record.affectedFiles.length > 0) {
+        logDecision(cwd, "allowed", "affected_files_resolved", {
+            projectSeq: record.projectSeqEnd,
+        });
         return { block: false };
     }
-    const details = runtime.gitGuardSummary
-        ? `\n${runtime.gitGuardSummary}`
-        : "";
+    logDecision(cwd, "blocked", "cache_blockers", {
+        projectSeq: record.projectSeqEnd,
+        affectedFileCount: record.affectedFiles.length,
+    });
     return {
         block: true,
-        reason: `🔴 COMMIT BLOCKED (--lens-guard): unresolved blockers must be fixed before commit/push.${details}\nRun lens_diagnostics mode=all for full details, then commit again.`,
+        reason: "🔴 COMMIT BLOCKED (--lens-guard): unresolved blockers must be fixed before commit/push.\nRun lens_diagnostics mode=all for full details, then commit again.",
     };
 }