@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/worker/delivery/git-transaction.js

@@ -0,0 +1,497 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { cp, lstat, mkdir, readFile, readlink, realpath, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import path from "node:path";
+import { z } from "zod";
+import { getTaskPoolRoot } from "../pool/run-store.js";
+import { assertSafeRuntimeId } from "../follow-up/paths.js";
+import { isEphemeralToolCachePath } from "../../executors/shell-write-guard.js";
+import { expandAllowedPathsForWorkflow } from "../materialize/harness-task-materializer.js";
+import { resolveWorkflow } from "../task-spec/workflow-routing.js";
+const execFileAsync = promisify(execFile);
+const checkpointSchema = z.object({
+    taskId: z.string().min(1),
+    workerRunId: z.string().min(1),
+    commit: z.string().regex(/^[a-f0-9]{40}$/),
+    changedFiles: z.array(z.string()),
+    createdAt: z.string().datetime(),
+}).strict();
+const ignoredSensitiveBaselineEntrySchema = z.object({
+    path: z.string().min(1),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+}).strict();
+export const gitTransactionRecordSchema = z.object({
+    schemaVersion: z.literal(1),
+    featureId: z.string().min(1),
+    branch: z.string().min(1),
+    baseBranch: z.string().min(1),
+    baseCommit: z.string().regex(/^[a-f0-9]{40}$/),
+    lastCheckpoint: z.string().regex(/^[a-f0-9]{40}$/),
+    authorizedBy: z.literal("cli --git-mode checkpoint"),
+    startedAt: z.string().datetime(),
+    ignoredBaseline: z.array(ignoredSensitiveBaselineEntrySchema),
+    ignoredSensitiveBaseline: z.array(ignoredSensitiveBaselineEntrySchema),
+    checkpoints: z.array(checkpointSchema),
+}).strict();
+export async function startGitTransaction(input) {
+    const repoRoot = await realpath(path.resolve(input.repoRoot));
+    assertSafeRuntimeId(input.featureId, "featureId");
+    const gitRoot = await git(repoRoot, ["rev-parse", "--show-toplevel"]);
+    if (await realpath(gitRoot) !== repoRoot)
+        throw new Error(`Git root does not match target repo: ${gitRoot}`);
+    const head = await git(repoRoot, ["rev-parse", "HEAD"]);
+    const baseBranch = await git(repoRoot, ["branch", "--show-current"]);
+    if (!baseBranch)
+        throw new Error("Git checkpoint requires a named current branch");
+    await assertClean(repoRoot);
+    const branch = input.branch ?? `agent/${input.featureId.toLowerCase()}`;
+    assertSafeBranch(branch);
+    const recordPath = transactionRecordPath(repoRoot, input.featureId);
+    const existing = await readOptionalRecord(recordPath);
+    const branchExists = await gitOk(repoRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+    if (branchExists) {
+        if (!existing)
+            throw new Error(`Feature branch already exists without transaction ownership: ${branch}`);
+        if (existing.branch !== branch || existing.featureId !== input.featureId)
+            throw new Error(`Feature branch ownership mismatch: ${branch}`);
+        if (baseBranch === existing.baseBranch && head !== existing.baseCommit)
+            throw new Error(`Feature base branch moved from recorded commit: ${existing.baseCommit}`);
+        if (baseBranch === branch && head !== existing.lastCheckpoint)
+            throw new Error(`Feature branch HEAD does not match recorded checkpoint: ${head}`);
+        if (baseBranch !== existing.baseBranch && baseBranch !== branch)
+            throw new Error(`Current branch is not owned by this Feature transaction: ${baseBranch}`);
+        await git(repoRoot, ["switch", branch]);
+        const branchHead = await git(repoRoot, ["rev-parse", "HEAD"]);
+        if (branchHead !== existing.lastCheckpoint)
+            throw new Error(`Feature branch HEAD does not match recorded checkpoint: ${branchHead}`);
+        return { repoRoot, recordPath, record: existing };
+    }
+    if (existing)
+        throw new Error(`Git transaction record exists but branch is missing: ${branch}`);
+    await git(repoRoot, ["switch", "-c", branch]);
+    const ignoredBaseline = await readIgnoredBaseline(repoRoot);
+    const record = {
+        schemaVersion: 1,
+        featureId: input.featureId,
+        branch,
+        baseBranch,
+        baseCommit: head,
+        lastCheckpoint: head,
+        authorizedBy: "cli --git-mode checkpoint",
+        startedAt: (input.now ?? new Date()).toISOString(),
+        ignoredBaseline,
+        ignoredSensitiveBaseline: ignoredBaseline.filter((entry) => isSensitivePath(entry.path)),
+        checkpoints: [],
+    };
+    try {
+        await writeJsonAtomic(recordPath, record);
+    }
+    catch (error) {
+        await git(repoRoot, ["switch", baseBranch]).catch(() => { });
+        await git(repoRoot, ["branch", "-D", branch]).catch(() => { });
+        throw error;
+    }
+    return { repoRoot, recordPath, record };
+}
+export async function finalizeGitTask(transaction, outcome) {
+    const current = gitTransactionRecordSchema.parse(JSON.parse(await readFile(transaction.recordPath, "utf-8")));
+    if (JSON.stringify(current) !== JSON.stringify(transaction.record))
+        throw new Error("Git transaction record changed outside the finalizer");
+    await assertTransactionPosition(transaction.repoRoot, current);
+    const currentIgnored = await readIgnoredBaseline(transaction.repoRoot);
+    const ignoredBaselineByPath = new Map(current.ignoredBaseline.map((entry) => [entry.path, entry.sha256]));
+    const changedBaselineIgnored = currentIgnored
+        .filter((entry) => ignoredBaselineByPath.has(entry.path) && ignoredBaselineByPath.get(entry.path) !== entry.sha256)
+        .map((entry) => entry.path);
+    const missingBaselineIgnored = current.ignoredBaseline
+        .filter((entry) => !currentIgnored.some((candidate) => candidate.path === entry.path))
+        .map((entry) => entry.path);
+    const existing = current.checkpoints.find((entry) => entry.workerRunId === outcome.workerRunId);
+    if (outcome.status === "reused" || existing) {
+        if (!existing)
+            throw new Error(`reused Worker run has no recorded checkpoint: ${outcome.workerRunId}`);
+        if (existing.taskId !== outcome.taskSpec.id || current.featureId !== outcome.taskSpec.feature_id)
+            throw new Error(`reused Worker run does not match current TaskSpec: ${outcome.workerRunId}`);
+        if (!await gitOk(transaction.repoRoot, ["cat-file", "-e", `${existing.commit}^{commit}`]))
+            throw new Error(`recorded checkpoint is missing from Git history: ${existing.commit}`);
+        if (!await gitOk(transaction.repoRoot, ["merge-base", "--is-ancestor", existing.commit, current.lastCheckpoint]))
+            throw new Error(`recorded checkpoint is outside the Feature transaction history: ${existing.commit}`);
+        await assertCheckpointMetadata(transaction.repoRoot, existing.commit, outcome.taskSpec, existing.workerRunId);
+        return { status: "reused", taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, commit: existing.commit, changedFiles: existing.changedFiles };
+    }
+    const changes = await readChanges(transaction.repoRoot);
+    const newIgnored = currentIgnored.map((entry) => entry.path).filter((entry) => !ignoredBaselineByPath.has(entry));
+    if (outcome.status === "succeeded") {
+        const allowedPaths = expandAllowedPathsForWorkflow(resolveWorkflow(outcome.taskSpec).workflow, outcome.taskSpec.constraints.allowed_paths);
+        const isAllowedEvidencePath = (entry) => !isSensitivePath(entry) &&
+            !isEphemeralToolCachePath(entry) &&
+            allowedPaths.some((glob) => matchesGlob(entry, glob));
+        // Pre-existing ignored evidence under allowed_paths may be rewritten by
+        // FINAL-VERIFY smoke / verify-final and must force-add into the checkpoint.
+        // Other baseline ignored mutations remain fail-closed (e.g. dist/, secrets).
+        const blockedBaselineChanged = changedBaselineIgnored.filter((entry) => !isAllowedEvidencePath(entry));
+        const blockedBaselineMissing = missingBaselineIgnored.filter((entry) => !isEphemeralToolCachePath(entry) && !isAllowedEvidencePath(entry));
+        if (blockedBaselineChanged.length > 0 || blockedBaselineMissing.length > 0) {
+            throw new Error(`pre-existing ignored file changed during Git transaction: ${[...blockedBaselineChanged, ...blockedBaselineMissing].join(", ")}`);
+        }
+        // Evidence under allowed_paths may be gitignored for local convenience (e.g.
+        // reports/welcome/** smoke JSON) but must still checkpoint for Task Pool Done.
+        // Sensitive / out-of-scope ignored files remain fail-closed; ephemeral tool
+        // caches neither block nor force-add.
+        const forceAddIgnored = [];
+        const blockedIgnored = [];
+        const rewrittenBaselineEvidence = changedBaselineIgnored.filter((entry) => isAllowedEvidencePath(entry));
+        for (const entry of rewrittenBaselineEvidence) {
+            if (!forceAddIgnored.includes(entry))
+                forceAddIgnored.push(entry);
+        }
+        for (const entry of newIgnored) {
+            if (isEphemeralToolCachePath(entry))
+                continue;
+            if (isSensitivePath(entry)) {
+                blockedIgnored.push(entry);
+                continue;
+            }
+            if (allowedPaths.some((glob) => matchesGlob(entry, glob))) {
+                if (!forceAddIgnored.includes(entry))
+                    forceAddIgnored.push(entry);
+            }
+            else {
+                blockedIgnored.push(entry);
+            }
+        }
+        if (blockedIgnored.length > 0) {
+            throw new Error(`task created ignored files outside the Git checkpoint: ${blockedIgnored.join(", ")}`);
+        }
+        const checkpointFiles = [...changes, ...forceAddIgnored];
+        if (checkpointFiles.length === 0) {
+            throw new Error(`successful task produced no checkpointable changes: ${outcome.taskSpec.id}`);
+        }
+        auditChangedPaths(checkpointFiles, outcome.taskSpec);
+        if (changes.length > 0) {
+            await git(transaction.repoRoot, ["add", "--", ...changes]);
+        }
+        if (forceAddIgnored.length > 0) {
+            await git(transaction.repoRoot, ["add", "-f", "--", ...forceAddIgnored]);
+        }
+        const message = commitMessage(outcome.taskSpec, outcome.workerRunId);
+        await git(transaction.repoRoot, ["commit", "-m", message]);
+        const commit = await git(transaction.repoRoot, ["rev-parse", "HEAD"]);
+        const checkpoint = { taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, commit, changedFiles: checkpointFiles, createdAt: (outcome.now ?? new Date()).toISOString() };
+        const previousCheckpoint = current.lastCheckpoint;
+        try {
+            await assertTransactionPosition(transaction.repoRoot, { ...current, lastCheckpoint: commit });
+            await assertCheckpointMetadata(transaction.repoRoot, commit, outcome.taskSpec, outcome.workerRunId);
+            const afterCommitIgnored = await readIgnoredBaseline(transaction.repoRoot);
+            // force-add may promote allowed evidence from ignored → tracked; drop those
+            // paths from the post-commit baseline equality check.
+            const forceAdded = new Set(forceAddIgnored);
+            assertIgnoredBaselineUnchanged(current.ignoredBaseline.filter((entry) => !isEphemeralToolCachePath(entry.path) && !forceAdded.has(entry.path)), afterCommitIgnored.filter((entry) => !isEphemeralToolCachePath(entry.path) && !forceAdded.has(entry.path)));
+        }
+        catch (error) {
+            const branch = await git(transaction.repoRoot, ["branch", "--show-current"]).catch(() => "");
+            if (branch === current.branch) {
+                await git(transaction.repoRoot, ["reset", "--hard", previousCheckpoint]).catch(() => { });
+                const afterFailureIgnored = await readIgnoredBaseline(transaction.repoRoot).catch(() => []);
+                const baselinePaths = new Set(current.ignoredBaseline.map((entry) => entry.path));
+                for (const entry of afterFailureIgnored)
+                    if (!baselinePaths.has(entry.path))
+                        await rm(path.join(transaction.repoRoot, entry.path), { recursive: true, force: true });
+            }
+            throw error;
+        }
+        current.lastCheckpoint = commit;
+        current.checkpoints.push(checkpoint);
+        try {
+            await writeJsonAtomic(transaction.recordPath, current);
+        }
+        catch (error) {
+            await git(transaction.repoRoot, ["reset", "--hard", previousCheckpoint]).catch(() => { });
+            throw error;
+        }
+        transaction.record = current;
+        await assertClean(transaction.repoRoot);
+        return {
+            status: "checkpointed",
+            taskId: outcome.taskSpec.id,
+            workerRunId: outcome.workerRunId,
+            commit,
+            changedFiles: checkpointFiles,
+        };
+    }
+    // Failed / keep-diff paths still fail closed on unexpected baseline ignored mutations.
+    if (changedBaselineIgnored.length > 0 || missingBaselineIgnored.length > 0) {
+        throw new Error(`pre-existing ignored file changed during Git transaction: ${[...changedBaselineIgnored, ...missingBaselineIgnored].join(", ")}`);
+    }
+    const artifactDir = path.join(path.dirname(transaction.recordPath), "failures", outcome.workerRunId);
+    await captureFailureArtifacts(transaction.repoRoot, artifactDir, changes, newIgnored, outcome);
+    if (outcome.keepFailedDiff) {
+        return { status: "kept-failed-diff", taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, artifactDir, changedFiles: changes };
+    }
+    await git(transaction.repoRoot, ["reset", "--hard", current.lastCheckpoint]);
+    await git(transaction.repoRoot, ["clean", "-fd"]);
+    for (const relative of newIgnored)
+        await rm(path.join(transaction.repoRoot, relative), { recursive: true, force: true });
+    await assertClean(transaction.repoRoot);
+    return { status: "restored", taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, artifactDir, changedFiles: changes };
+}
+/**
+ * Operator-only: advance recorded lastCheckpoint to current HEAD after manual
+ * revisions on the owned Feature branch. Does not append checkpoints[] entries.
+ */
+export async function advanceGitCheckpoint(input) {
+    const reason = input.reason.trim();
+    if (!reason)
+        throw new Error("feature git advance-checkpoint requires --reason <text>");
+    const repoRoot = await realpath(path.resolve(input.repoRoot));
+    assertSafeRuntimeId(input.featureId, "featureId");
+    const recordPath = transactionRecordPath(repoRoot, input.featureId);
+    const record = await readOptionalRecord(recordPath);
+    if (!record)
+        throw new Error(`Git transaction record not found for feature ${input.featureId}`);
+    if (record.featureId !== input.featureId) {
+        throw new Error(`Git transaction ownership mismatch: expected ${input.featureId}, found ${record.featureId}`);
+    }
+    await assertClean(repoRoot);
+    const branch = await git(repoRoot, ["branch", "--show-current"]);
+    if (branch !== record.branch) {
+        throw new Error(`current branch is outside the Feature transaction: expected ${record.branch}, got ${branch || "detached HEAD"}`);
+    }
+    const head = await git(repoRoot, ["rev-parse", "HEAD"]);
+    if (head === record.lastCheckpoint) {
+        const evidencePath = await writeAdvanceCheckpointEvidence(repoRoot, input.featureId, {
+            status: "unchanged",
+            reason,
+            previousCheckpoint: record.lastCheckpoint,
+            lastCheckpoint: head,
+            at: (input.now ?? new Date()).toISOString(),
+        });
+        return {
+            schemaVersion: 1,
+            featureId: input.featureId,
+            status: "unchanged",
+            previousCheckpoint: record.lastCheckpoint,
+            lastCheckpoint: head,
+            reason,
+            evidencePath: path.relative(repoRoot, evidencePath).split(path.sep).join("/"),
+        };
+    }
+    if (!await gitOk(repoRoot, ["merge-base", "--is-ancestor", record.lastCheckpoint, head])) {
+        throw new Error(`current HEAD is not descended from recorded checkpoint ${record.lastCheckpoint}`);
+    }
+    const previousCheckpoint = record.lastCheckpoint;
+    const updated = { ...record, lastCheckpoint: head };
+    await writeJsonAtomic(recordPath, updated);
+    const at = (input.now ?? new Date()).toISOString();
+    const evidencePath = await writeAdvanceCheckpointEvidence(repoRoot, input.featureId, {
+        status: "advanced",
+        reason,
+        previousCheckpoint,
+        lastCheckpoint: head,
+        at,
+    });
+    return {
+        schemaVersion: 1,
+        featureId: input.featureId,
+        status: "advanced",
+        previousCheckpoint,
+        lastCheckpoint: head,
+        reason,
+        evidencePath: path.relative(repoRoot, evidencePath).split(path.sep).join("/"),
+    };
+}
+export function transactionRecordPath(repoRoot, featureId) {
+    return path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", featureId, "git", "transaction.json");
+}
+async function captureFailureArtifacts(repoRoot, artifactDir, changes, ignoredFiles, outcome) {
+    await mkdir(path.join(artifactDir, "untracked"), { recursive: true });
+    const patchText = await gitRaw(repoRoot, ["diff", "--binary", "HEAD"]);
+    await writeFile(path.join(artifactDir, "changes.patch"), patchText, "utf-8");
+    const untracked = (await gitRaw(repoRoot, ["ls-files", "--others", "--exclude-standard"])).split(/\r?\n/).filter(Boolean);
+    for (const relative of untracked) {
+        const source = path.join(repoRoot, relative);
+        const target = path.join(artifactDir, "untracked", relative);
+        if ((await stat(source)).isFile()) {
+            await mkdir(path.dirname(target), { recursive: true });
+            await cp(source, target);
+        }
+    }
+    await writeJsonAtomic(path.join(artifactDir, "failure.json"), {
+        schemaVersion: 1,
+        featureId: outcome.taskSpec.feature_id,
+        taskId: outcome.taskSpec.id,
+        workerRunId: outcome.workerRunId,
+        changedFiles: changes,
+        untrackedFiles: untracked,
+        ignoredFiles,
+        ignoredSensitiveFiles: ignoredFiles.filter(isSensitivePath),
+        writeBoundaryAudit: auditChangedPathsReport([...changes, ...ignoredFiles], outcome.taskSpec),
+        lastCheckpoint: await git(repoRoot, ["rev-parse", "HEAD"]),
+        ...(outcome.runRecordPath ? { runRecordPath: outcome.runRecordPath } : {}),
+        capturedAt: (outcome.now ?? new Date()).toISOString(),
+    });
+}
+function auditChangedPaths(changes, taskSpec) {
+    const audit = auditChangedPathsReport(changes, taskSpec);
+    if (audit.violations.length > 0)
+        throw new Error(audit.violations[0]);
+}
+function auditChangedPathsReport(changes, taskSpec) {
+    const allowedPaths = expandAllowedPathsForWorkflow(resolveWorkflow(taskSpec).workflow, taskSpec.constraints.allowed_paths);
+    const violations = [];
+    for (const changed of changes) {
+        // Match shell write-guard: tool caches are not product evidence and must not
+        // fail checkpoint after a green frontend-test browser run.
+        if (isEphemeralToolCachePath(changed))
+            continue;
+        if (/(^|\/)(\.env(?:\.|$)|[^/]*\.(?:pem|key|p12|pfx))$/i.test(changed))
+            violations.push(`changed path may contain sensitive material: ${changed}`);
+        else if (taskSpec.constraints.forbidden_paths.some((glob) => matchesGlob(changed, glob)))
+            violations.push(`changed path is forbidden for ${taskSpec.id}: ${changed}`);
+        else if (!allowedPaths.some((glob) => matchesGlob(changed, glob)))
+            violations.push(`changed path is outside allowed_paths for ${taskSpec.id}: ${changed}`);
+    }
+    return { ok: violations.length === 0, violations };
+}
+function matchesGlob(filePath, glob) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    const normalizedGlob = glob.replace(/\\/g, "/");
+    let pattern = "^";
+    for (let index = 0; index < normalizedGlob.length; index += 1) {
+        const char = normalizedGlob[index];
+        if (char === "*" && normalizedGlob[index + 1] === "*") {
+            pattern += ".*";
+            index += 1;
+            continue;
+        }
+        if (char === "*") {
+            pattern += "[^/]*";
+            continue;
+        }
+        pattern += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`${pattern}$`).test(normalizedPath);
+}
+function commitMessage(taskSpec, workerRunId) {
+    const type = taskSpec.type === "bugfix" || taskSpec.type === "fix-from-failure" ? "fix" : taskSpec.type.startsWith("qa-") ? "test" : "feat";
+    return `${type}(${taskSpec.id.toLowerCase()}): ${taskSpec.title}\n\nFeature: ${taskSpec.feature_id}\nTask: ${taskSpec.id}\nAcceptance: ${taskSpec.acceptance_refs.join(", ")}\nAgent-Run: ${workerRunId}\nWorker-Run: ${workerRunId}`;
+}
+function assertSafeBranch(branch) {
+    if (!/^agent\/[a-z0-9][a-z0-9._-]*$/.test(branch) || branch.includes("..") || branch.endsWith("."))
+        throw new Error(`unsafe Feature branch name: ${branch}`);
+}
+async function assertClean(repoRoot) {
+    const statusText = await gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]);
+    if (statusText.trim())
+        throw new Error(`Git worktree is not clean:\n${statusText.trim()}`);
+}
+async function assertTransactionPosition(repoRoot, record) {
+    const branch = await git(repoRoot, ["branch", "--show-current"]);
+    if (branch !== record.branch)
+        throw new Error(`current branch is outside the Feature transaction: expected ${record.branch}, got ${branch || "detached HEAD"}`);
+    const head = await git(repoRoot, ["rev-parse", "HEAD"]);
+    if (head !== record.lastCheckpoint)
+        throw new Error(`Feature branch HEAD does not match recorded checkpoint: expected ${record.lastCheckpoint}, got ${head}`);
+}
+async function assertCheckpointMetadata(repoRoot, commit, taskSpec, workerRunId) {
+    const message = await gitRaw(repoRoot, ["show", "-s", "--format=%B", commit]);
+    for (const trailer of [`Feature: ${taskSpec.feature_id}`, `Task: ${taskSpec.id}`, `Acceptance: ${taskSpec.acceptance_refs.join(", ")}`, `Worker-Run: ${workerRunId}`]) {
+        if (!message.split(/\r?\n/).includes(trailer))
+            throw new Error(`recorded checkpoint metadata mismatch: ${trailer}`);
+    }
+}
+function assertIgnoredBaselineUnchanged(baseline, current) {
+    const baselineByPath = new Map(baseline.map((entry) => [entry.path, entry.sha256]));
+    const changed = current.filter((entry) => baselineByPath.has(entry.path) && baselineByPath.get(entry.path) !== entry.sha256).map((entry) => entry.path);
+    const missing = baseline.filter((entry) => !current.some((candidate) => candidate.path === entry.path)).map((entry) => entry.path);
+    const added = current.filter((entry) => !baselineByPath.has(entry.path)).map((entry) => entry.path);
+    if (changed.length > 0 || missing.length > 0 || added.length > 0)
+        throw new Error(`ignored files changed during Git checkpoint: ${[...changed, ...missing, ...added].join(", ")}`);
+}
+async function readChanges(repoRoot) {
+    const raw = await gitRaw(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+    const fields = raw.split("\0");
+    const changes = new Set();
+    for (let index = 0; index < fields.length; index += 1) {
+        const field = fields[index];
+        if (!field)
+            continue;
+        const status = field.slice(0, 2);
+        changes.add(field.slice(3).replace(/\\/g, "/"));
+        if (/[RC]/.test(status)) {
+            const source = fields[index + 1];
+            if (source)
+                changes.add(source.replace(/\\/g, "/"));
+            index += 1;
+        }
+    }
+    return [...changes];
+}
+async function listIgnoredFiles(repoRoot) {
+    const raw = await gitRaw(repoRoot, ["ls-files", "-z", "--others", "--ignored", "--exclude-standard"]);
+    return raw.split("\0").filter((entry) => entry && !entry.startsWith(".harness/")).sort();
+}
+async function readIgnoredBaseline(repoRoot) {
+    const paths = await listIgnoredFiles(repoRoot);
+    return Promise.all(paths.map(async (relative) => {
+        const absolute = path.join(repoRoot, relative);
+        const info = await lstat(absolute);
+        const content = info.isSymbolicLink() ? `symlink:${await readlink(absolute)}` : await readFile(absolute);
+        return { path: relative, sha256: createHash("sha256").update(content).digest("hex") };
+    }));
+}
+function isSensitivePath(relative) {
+    return /(^|\/)(\.env(?:\.|$)|[^/]*\.(?:pem|key|p12|pfx))$/i.test(relative);
+}
+async function writeAdvanceCheckpointEvidence(repoRoot, featureId, payload) {
+    const evidenceDir = path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", featureId, "git");
+    await mkdir(evidenceDir, { recursive: true });
+    const stamp = typeof payload.at === "string"
+        ? payload.at.replace(/[:.]/g, "-")
+        : new Date().toISOString().replace(/[:.]/g, "-");
+    const evidencePath = path.join(evidenceDir, `advance-checkpoint-${stamp}.json`);
+    await writeJsonAtomic(evidencePath, { schemaVersion: 1, featureId, ...payload });
+    return evidencePath;
+}
+async function readOptionalRecord(filePath) {
+    try {
+        return gitTransactionRecordSchema.parse(JSON.parse(await readFile(filePath, "utf-8")));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+async function writeJsonAtomic(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const temp = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+        await rename(temp, filePath);
+    }
+    finally {
+        await unlink(temp).catch(() => { });
+    }
+}
+async function git(repoRoot, args) {
+    const result = await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
+    return result.stdout.trim();
+}
+async function gitRaw(repoRoot, args) {
+    const result = await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8", maxBuffer: 10 * 1024 * 1024 });
+    return result.stdout;
+}
+async function gitOk(repoRoot, args) {
+    try {
+        await git(repoRoot, args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isNotFound(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}