@tea-agent/loop-agent 0.9.0 → 0.10.0-alpha.0

package/dist/worker/delivery/final-verification.js

@@ -0,0 +1,194 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import YAML from "yaml";
+import { controllerIdentitiesMatch, controllerIdentityExpectationFailure, resolveControllerIdentity, } from "../loop-agent/loop-agent-client.js";
+import { acceptanceSpecSchema } from "../task-graph/acceptance-schema.js";
+import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { getRunsJsonlPath, getTaskPoolRoot, readJsonlFile, recordTaskPoolRun } from "../pool/run-store.js";
+import { buildWorkerRunId, runTaskSpec } from "../run-task/run-task.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { preflightTargetRepo } from "../preflight.js";
+import { gitTransactionRecordSchema, transactionRecordPath } from "./git-transaction.js";
+const execFileAsync = promisify(execFile);
+export async function runFeatureFinalVerification(input) {
+    const dependencies = {
+        preflight: preflightTargetRepo,
+        runTask: runTaskSpec,
+        git,
+        gitRaw,
+        ...input.dependencies,
+    };
+    let controllerIdentity = resolveControllerIdentity(input.client, input.controllerIdentity);
+    const identityFailure = controllerIdentityExpectationFailure(controllerIdentity, input.controllerExpectation);
+    if (identityFailure) {
+        throw new Error(`${identityFailure.code}: ${identityFailure.message}`);
+    }
+    const repoRoot = await realpath(path.resolve(input.repoRoot));
+    const featureDir = await realpath(path.resolve(input.featureDir));
+    const relativeFeature = path.relative(repoRoot, featureDir);
+    if (!relativeFeature || relativeFeature.startsWith("..") || path.isAbsolute(relativeFeature))
+        throw new Error("Feature Packet must be inside the target repo");
+    const validation = await validateFeatureTaskGraph(featureDir);
+    if (!validation.ok)
+        throw new Error(`Feature Packet is invalid: ${validation.errors.map((error) => error.code).join(", ")}`);
+    const featureId = validation.featureId;
+    const preflight = await dependencies.preflight({
+        repoRoot,
+        client: input.client,
+        ...(input.controllerExpectation ? { expectation: input.controllerExpectation } : {}),
+    });
+    if (!preflight.ok) {
+        throw new Error(`target repo preflight failed: ${preflight.code}: ${preflight.message}`);
+    }
+    controllerIdentity = preflight.controllerIdentity ?? controllerIdentity;
+    const record = gitTransactionRecordSchema.parse(JSON.parse(await readFile(transactionRecordPath(repoRoot, featureId), "utf-8")));
+    const branch = await dependencies.git(repoRoot, ["branch", "--show-current"]);
+    const headSha = await dependencies.git(repoRoot, ["rev-parse", "HEAD"]);
+    const status = await dependencies.gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]);
+    if (branch !== record.branch || headSha !== record.lastCheckpoint)
+        throw new Error("final verification requires the recorded Feature branch at lastCheckpoint");
+    if (status.trim())
+        throw new Error(`final verification requires a clean worktree:\n${status.trim()}`);
+    const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
+    const node = graph.nodes.find((candidate) => candidate.id === input.taskId);
+    if (!node)
+        throw new Error(`final verification task is not in the Feature graph: ${input.taskId}`);
+    const taskSpecPath = path.join(featureDir, "tasks", node.task);
+    const taskSpec = taskSpecSchema.parse(YAML.parse(await readFile(taskSpecPath, "utf-8")));
+    if (taskSpec.type !== "qa-execute")
+        throw new Error(`final verification requires a qa-execute TaskSpec: ${input.taskId}`);
+    if (taskSpec.verify.commands.filter((command) => command.required).length === 0)
+        throw new Error("final verification TaskSpec has no required commands");
+    const verificationTaskSpec = {
+        ...taskSpec,
+        constraints: {
+            ...taskSpec.constraints,
+            allowed_paths: [],
+            hard_constraints: [...taskSpec.constraints.hard_constraints, "Dedicated final verification is read-only; do not modify repository files"],
+        },
+    };
+    const now = input.now ?? new Date();
+    let runs = await readJsonlFile(getRunsJsonlPath(repoRoot));
+    let finalRun = await reusableFinalRun(repoRoot, runs, taskSpec.id, featureId, record, now, controllerIdentity);
+    if (!finalRun) {
+        const workerRunId = buildWorkerRunId(`${input.taskId}-final`, now);
+        const result = await dependencies.runTask({
+            repoRoot,
+            taskSpec: verificationTaskSpec,
+            taskSpecPath,
+            client: input.client,
+            now,
+            workerRunId,
+            skipSuccessFinalization: true,
+            preflight: false,
+            ...(controllerIdentity ? { controllerIdentity } : {}),
+            ...(input.controllerExpectation ? { controllerExpectation: input.controllerExpectation } : {}),
+        });
+        if (result.status !== "succeeded")
+            throw new Error(`dedicated final verification failed: ${workerRunId}`);
+        const afterHead = await dependencies.git(repoRoot, ["rev-parse", "HEAD"]);
+        const afterStatus = await dependencies.gitRaw(repoRoot, ["status", "--porcelain=v1", "--untracked-files=all"]);
+        if (afterHead !== headSha || afterStatus.trim())
+            throw new Error("dedicated final verification changed the Delivery HEAD or worktree");
+        finalRun = { schemaVersion: 1, batchRunId: `final-verification-${workerRunId}`, workerRunId, taskId: taskSpec.id, featureId, status: "succeeded", harnessTaskId: result.harnessTaskId, runRecordPath: result.runRecordPath, dagPath: result.dagPath, recordedAt: now.toISOString(), ...(controllerIdentity ? { controllerIdentity } : {}) };
+        await recordTaskPoolRun({ repoRoot, run: finalRun });
+        runs = [...runs, finalRun];
+    }
+    const allSpecs = new Map();
+    for (const graphNode of graph.nodes) {
+        allSpecs.set(graphNode.id, taskSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", graphNode.task), "utf-8"))));
+    }
+    const acceptance = acceptanceSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "acceptance.yaml"), "utf-8")));
+    const qaRuns = latestSuccessfulQaRuns(runs, allSpecs, taskSpec.id, featureId);
+    if (qaRuns.length === 0)
+        throw new Error("no prior successful qa-execute runs are available for the QA aggregate");
+    const coveredAcIds = [...new Set(qaRuns.flatMap((run) => allSpecs.get(run.taskId)?.acceptance_refs ?? []))];
+    const requiredAcIds = acceptance.acceptance.filter((item) => item.priority === "must").map((item) => item.id);
+    for (const acId of requiredAcIds)
+        if (!coveredAcIds.includes(acId))
+            throw new Error(`QA aggregate does not cover required acceptance: ${acId}`);
+    const summaryRelative = path.join(".harness", "dag-runs", "completed", finalRun.workerRunId, "verify-shell", "result.summary.md").replace(/\\/g, "/");
+    const summaryAbsolute = path.join(repoRoot, ...summaryRelative.split("/"));
+    const summary = await readFile(summaryAbsolute);
+    const evidenceDir = path.join(getTaskPoolRoot(repoRoot), "evidence", featureId);
+    const qaEvidencePath = path.join(evidenceDir, "qa-pass.json");
+    const finalVerificationPath = path.join(evidenceDir, "final-verification.json");
+    await writeEvidencePairAtomic(evidenceDir, {
+        qa: { schemaVersion: 1, featureId, verdict: "passed", acIds: requiredAcIds, runs: qaRuns.map(runRef) },
+        final: { schemaVersion: 1, featureId, kind: "final-verification", status: "passed", headSha, run: runRef(finalRun), shellSummary: { path: summaryRelative, sha256: createHash("sha256").update(summary).digest("hex") } },
+    });
+    return { schemaVersion: 1, featureId, taskId: taskSpec.id, workerRunId: finalRun.workerRunId, headSha, qaEvidencePath: repoRef(repoRoot, qaEvidencePath), finalVerificationPath: repoRef(repoRoot, finalVerificationPath), qaRunCount: qaRuns.length, ...(controllerIdentity ? { controllerIdentity } : {}) };
+}
+export function latestSuccessfulQaRuns(runs, specs, excludedTaskId, featureId) {
+    const byTask = new Map();
+    for (const run of runs)
+        if (run.featureId === featureId && run.status === "succeeded" && run.taskId !== excludedTaskId && specs.get(run.taskId)?.type === "qa-execute")
+            byTask.set(run.taskId, run);
+    return [...byTask.values()].sort((a, b) => a.taskId.localeCompare(b.taskId));
+}
+async function reusableFinalRun(repoRoot, runs, taskId, featureId, record, now, controllerIdentity) {
+    const latestCheckpointAt = Math.max(...record.checkpoints.map((entry) => new Date(entry.createdAt).getTime()));
+    for (const run of [...runs].reverse()) {
+        if (run.taskId !== taskId || run.featureId !== featureId || run.status !== "succeeded" || !run.workerRunId.includes("-final-") || !run.runRecordPath)
+            continue;
+        if (controllerIdentity && !controllerIdentitiesMatch(run.controllerIdentity, controllerIdentity))
+            continue;
+        const recordedAt = new Date(run.recordedAt).getTime();
+        if (recordedAt < latestCheckpointAt || now.getTime() - recordedAt > 24 * 60 * 60 * 1000)
+            continue;
+        try {
+            const canonical = JSON.parse(await readFile(run.runRecordPath, "utf-8"));
+            if (canonical.workerRunId !== run.workerRunId || canonical.businessId !== taskId || canonical.featureId !== featureId || canonical.status !== "succeeded")
+                continue;
+            await readFile(path.join(repoRoot, ".harness", "dag-runs", "completed", run.workerRunId, "verify-shell", "result.summary.md"));
+            return run;
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+function runRef(run) { return { taskId: run.taskId, workerRunId: run.workerRunId, recordedAt: run.recordedAt, ...(run.controllerIdentity ? { controllerIdentity: run.controllerIdentity } : {}) }; }
+function repoRef(repoRoot, absolute) { return path.relative(repoRoot, absolute).replace(/\\/g, "/"); }
+export async function writeEvidencePairAtomic(evidenceDir, value, fs = { rm }) {
+    const parent = path.dirname(evidenceDir);
+    const staging = path.join(parent, `.evidence.${randomUUID()}.staging`);
+    const backup = path.join(parent, `.evidence.${randomUUID()}.backup`);
+    await mkdir(staging, { recursive: true });
+    await writeFile(path.join(staging, "qa-pass.json"), `${JSON.stringify(value.qa, null, 2)}\n`);
+    await writeFile(path.join(staging, "final-verification.json"), `${JSON.stringify(value.final, null, 2)}\n`);
+    let backedUp = false;
+    try {
+        await rename(evidenceDir, backup);
+        backedUp = true;
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+    let installed = false;
+    try {
+        await rename(staging, evidenceDir);
+        installed = true;
+    }
+    catch (error) {
+        if (installed)
+            await fs.rm(evidenceDir, { recursive: true, force: true }).catch(() => { });
+        if (backedUp)
+            await rename(backup, evidenceDir).catch(() => { });
+        throw error;
+    }
+    finally {
+        await fs.rm(staging, { recursive: true, force: true }).catch(() => { });
+    }
+    if (backedUp)
+        await fs.rm(backup, { recursive: true, force: true }).catch(() => { });
+}
+async function git(repoRoot, args) { return (await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8" })).stdout.trim(); }
+async function gitRaw(repoRoot, args) { return (await execFileAsync("git", args, { cwd: repoRoot, encoding: "utf8" })).stdout; }
+function isNotFound(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT"); }

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

@@ -0,0 +1,354 @@
+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";
+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);
+    if (changedBaselineIgnored.length > 0 || missingBaselineIgnored.length > 0) {
+        throw new Error(`pre-existing ignored file changed during Git transaction: ${[...changedBaselineIgnored, ...missingBaselineIgnored].join(", ")}`);
+    }
+    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") {
+        if (changes.length === 0)
+            throw new Error(`successful task produced no checkpointable changes: ${outcome.taskSpec.id}`);
+        if (newIgnored.length > 0)
+            throw new Error(`task created ignored files outside the Git checkpoint: ${newIgnored.join(", ")}`);
+        auditChangedPaths(changes, outcome.taskSpec);
+        await git(transaction.repoRoot, ["add", "--", ...changes]);
+        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: changes, 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);
+            assertIgnoredBaselineUnchanged(current.ignoredBaseline, afterCommitIgnored);
+        }
+        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: changes };
+    }
+    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 };
+}
+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 violations = [];
+    for (const changed of changes) {
+        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 (!taskSpec.constraints.allowed_paths.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 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");
+}