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

package/dist/worker/closeout/apply.js

@@ -0,0 +1,73 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { z } from "zod";
+import { validateDeliveryPackage } from "../delivery/package.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { previewFeatureCloseout } from "./preview.js";
+export const appliedFeatureCloseoutSchema = z.object({
+    schema_version: z.literal(1), feature_id: z.string().min(1), status: z.literal("success"), qa_verdict: z.literal("pass"), qa_evidence: z.array(z.string().min(1)).min(1),
+    delivery_manifest_ref: z.string().min(1), owner: z.string().min(1), decided_at: z.string().datetime(), appliedAt: z.string().datetime(), input_facts_hash: z.string().regex(/^[a-f0-9]{64}$/), summary: z.string().min(1),
+}).strict();
+export async function applyFeatureCloseout(input) {
+    if (!input.owner.trim())
+        throw new Error("feature closeout --apply requires a non-empty owner");
+    const repoRoot = await realpath(path.resolve(input.repoRoot));
+    const featureDir = await realpath(path.resolve(input.featureDir));
+    const relative = path.relative(repoRoot, featureDir);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error("Feature Packet must be inside the target repo");
+    const beforeValidation = await validateFeatureTaskGraph(featureDir);
+    if (!beforeValidation.ok)
+        throw new Error(`Feature Packet is invalid before closeout apply: ${beforeValidation.errors.map((error) => error.code).join(", ")}`);
+    const closeoutPath = path.join(featureDir, "closeout.yaml");
+    const deliveryPath = path.join(repoRoot, ".harness", "task-pool", "artifacts", "features", beforeValidation.featureId, "delivery", "delivery-manifest.json");
+    let previous;
+    let reusable;
+    try {
+        previous = await readFile(closeoutPath);
+        const existing = appliedFeatureCloseoutSchema.safeParse(YAML.parse(previous.toString("utf-8")));
+        if (existing.success)
+            reusable = existing.data;
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+    if (reusable && reusable.feature_id !== beforeValidation.featureId)
+        throw new Error(`existing Feature Closeout ownership mismatch: expected ${beforeValidation.featureId}, got ${reusable.feature_id}`);
+    const allowedDirtyPaths = reusable ? [path.relative(repoRoot, closeoutPath).replace(/\\/g, "/")] : undefined;
+    const preview = await previewFeatureCloseout({ featureDir, repoRoot, ...(input.now ? { now: input.now } : {}), ...(allowedDirtyPaths ? { allowedDirtyPaths } : {}) });
+    if (preview.status !== "ready")
+        throw new Error(`Feature Closeout gates are blocked: ${preview.gates.filter((gate) => !gate.passed).map((gate) => `${gate.id} (${gate.message})`).join(", ")}`);
+    const delivery = await validateDeliveryPackage({ featureDir, repoRoot, ...(input.now ? { now: input.now } : {}), ...(allowedDirtyPaths ? { allowedDirtyPaths } : {}) });
+    if (!delivery.valid || !delivery.manifest)
+        throw new Error(`Delivery Package is invalid: ${delivery.blockers.join("; ")}`);
+    const inputFactsHash = createHash("sha256").update(await readFile(deliveryPath)).digest("hex");
+    const appliedAt = (input.now ?? new Date()).toISOString();
+    if (reusable?.input_facts_hash === inputFactsHash)
+        return { schemaVersion: 1, featureId: beforeValidation.featureId, status: "reused", closeoutPath, owner: reusable.owner, appliedAt: reusable.appliedAt, inputFactsHash };
+    const record = appliedFeatureCloseoutSchema.parse({ schema_version: 1, feature_id: preview.featureId, status: "success", qa_verdict: "pass", qa_evidence: [delivery.manifest.qa.evidence.path, delivery.manifest.finalVerification.path], delivery_manifest_ref: path.relative(repoRoot, deliveryPath).replace(/\\/g, "/"), owner: input.owner.trim(), decided_at: appliedAt, appliedAt, input_facts_hash: inputFactsHash, summary: `Feature ${preview.featureId} passed tasks, QA, required AC, risk, final verification, and Delivery gates.` });
+    const temp = path.join(featureDir, `.closeout.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temp, YAML.stringify(record), "utf-8");
+        await rename(temp, closeoutPath);
+        const after = await (input.validateAfterWrite ?? validateFeatureTaskGraph)(featureDir);
+        if (!after.ok)
+            throw new Error(`Feature Packet is invalid after closeout apply: ${after.errors.map((error) => error.code).join(", ")}`);
+        return { schemaVersion: 1, featureId: preview.featureId, status: "applied", closeoutPath, owner: record.owner, appliedAt, inputFactsHash };
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        if (previous) {
+            const rollback = path.join(featureDir, `.closeout.${randomUUID()}.rollback`);
+            await writeFile(rollback, previous);
+            await rename(rollback, closeoutPath);
+        }
+        else
+            await rm(closeoutPath, { force: true });
+        throw error;
+    }
+}
+function isNotFound(error) { return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT"); }

package/dist/worker/closeout/preview.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { validateDeliveryPackage } from "../delivery/package.js";
+import { reviewFeature } from "../feature/review.js";
+import { getTaskPoolRoot } from "../pool/run-store.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+export async function previewFeatureCloseout(input) {
+    const featureDir = path.resolve(input.featureDir);
+    const repoRoot = path.resolve(input.repoRoot);
+    const validation = await validateFeatureTaskGraph(featureDir);
+    const model = await reviewFeature({ featureDir, repoRoot });
+    const manifestPath = path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", validation.featureId, "delivery", "delivery-manifest.json");
+    const delivery = await validateDeliveryPackage({ featureDir, repoRoot, ...(input.now ? { now: input.now } : {}), ...(input.allowedDirtyPaths ? { allowedDirtyPaths: input.allowedDirtyPaths } : {}) });
+    const manifest = delivery.manifest;
+    const requiredIncomplete = model.acceptanceCoverage.filter((item) => item.required && !["covered", "waived"].includes(item.status));
+    const allTasksDone = model.tasks.length > 0 && model.tasks.every((task) => task.status === "Done");
+    const gates = [
+        { id: "feature-validation", passed: validation.ok, message: validation.ok ? "Feature Packet is valid" : "Feature Packet validation failed", evidence: validation.errors.flatMap((error) => error.path ? [error.path] : []) },
+        { id: "tasks-complete", passed: allTasksDone, message: allTasksDone ? "All development and QA tasks are Done" : "One or more required tasks are not Done", evidence: model.tasks.filter((task) => task.status !== "Done").map((task) => task.taskId) },
+        { id: "qa-pass", passed: manifest?.qa.verdict === "passed", message: manifest?.qa.verdict === "passed" ? "QA verdict passed" : "QA pass evidence is missing", evidence: manifest ? [manifest.qa.evidence.path] : [] },
+        { id: "required-ac", passed: requiredIncomplete.length === 0, message: requiredIncomplete.length === 0 ? "Required AC are covered or waived" : "Required AC coverage is incomplete", evidence: requiredIncomplete.map((item) => item.acId) },
+        { id: "risk", passed: model.riskSummary.high === 0, message: model.riskSummary.high === 0 ? "No unresolved high risk" : "Unresolved high risk remains", evidence: model.blockingItems.filter((item) => item.failureCategory && ["RiskyChange", "ContractMismatch", "SpecUnclear", "NeedsHuman"].includes(item.failureCategory)).flatMap((item) => item.evidence) },
+        { id: "final-verification", passed: Boolean(manifest?.finalVerification), message: manifest?.finalVerification ? "Final verification evidence is present" : "Final verification evidence is missing", evidence: manifest ? [manifest.finalVerification.path] : [] },
+        { id: "delivery", passed: delivery.valid && model.evidence.delivery === manifestPath, message: delivery.valid && model.evidence.delivery === manifestPath ? "Delivery manifest and Git facts are valid" : `Delivery is invalid: ${delivery.blockers[0] ?? "missing manifest"}`, evidence: manifest ? [manifestPath] : [] },
+    ];
+    const ready = gates.every((gate) => gate.passed);
+    return { schemaVersion: 1, featureId: validation.featureId, status: ready ? "ready" : "blocked", gates, nextAction: ready ? "Closeout gates are ready; retain this preview for human review until atomic --apply is implemented in M2-08" : "Resolve the first failed closeout gate and preview again" };
+}
+export function renderCloseoutPreview(preview) {
+    return [`Feature: ${preview.featureId}`, `Closeout: ${preview.status === "ready" ? "可应用" : "被阻止"}`, ...preview.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.id}: ${gate.message}`), `下一步: ${preview.nextAction}`].join("\n") + "\n";
+}

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");
+}