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

package/dist/worker/feature/run.js

@@ -0,0 +1,365 @@
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+import { controllerIdentityExpectationFailure, resolveControllerIdentity, } from "../loop-agent/loop-agent-client.js";
+import { buildGlobalSnapshot } from "../observability/read-model.js";
+import { createSnapshotStore } from "../observability/snapshot-store.js";
+import { preflightTargetRepo } from "../preflight.js";
+import { noopProgressReporter } from "../progress-reporter.js";
+import { getTaskPoolRoot } from "../pool/run-store.js";
+import { writeMorningReport } from "../report/morning-report.js";
+import { buildBatchRunId, runReadyTasks } from "../runner/run-ready.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { reviewFeature } from "./review.js";
+import { finalizeGitTask, startGitTransaction } from "../delivery/git-transaction.js";
+export async function runFeature(options) {
+    const featureDir = path.resolve(options.featureDir);
+    const repoRoot = path.resolve(options.repoRoot);
+    const now = options.now ?? new Date();
+    const batchRunId = options.batchRunId ?? buildBatchRunId(now);
+    const progress = options.progress ?? noopProgressReporter;
+    const dependencies = { ...defaultDependencies, ...options.dependencies };
+    const steps = [];
+    const requestedLimit = options.limit ?? 1;
+    const checkpointMode = options.gitMode === "checkpoint";
+    const limitApplied = Number.isInteger(requestedLimit) && requestedLimit > 0
+        ? checkpointMode ? requestedLimit : Math.min(requestedLimit, 1)
+        : 1;
+    let featureId = path.basename(featureDir);
+    let before;
+    let batch;
+    let gitTransaction;
+    const gitTasks = [];
+    const expectedArtifacts = expectedArtifactPaths(repoRoot, batchRunId);
+    let controllerIdentity;
+    try {
+        controllerIdentity = resolveControllerIdentity(options.client, options.controllerIdentity);
+    }
+    catch (error) {
+        return failedResult({
+            featureId,
+            mode: options.dryRun ? "dry-run" : "executed",
+            steps: [{ id: "preflight", status: "failed", durationMs: 0, message: errorMessage(error) }],
+            limitApplied,
+            code: "controller-identity-client-mismatch",
+            message: errorMessage(error),
+            evidence: [],
+            expectedArtifacts,
+            controllerIdentity: options.controllerIdentity,
+        });
+    }
+    const identityFailure = controllerIdentityExpectationFailure(controllerIdentity, options.controllerExpectation);
+    if (identityFailure) {
+        return failedResult({
+            featureId,
+            mode: options.dryRun ? "dry-run" : "executed",
+            steps: [{ id: "preflight", status: "failed", durationMs: 0, message: identityFailure.message }],
+            limitApplied,
+            code: identityFailure.code,
+            message: identityFailure.message,
+            evidence: [],
+            expectedArtifacts,
+            controllerIdentity,
+        });
+    }
+    progress.step("feature validate");
+    const validation = await timedStep(steps, "validate", async () => dependencies.validateFeature(featureDir));
+    if (!validation.value?.ok) {
+        markLastStepFailed(steps, "Feature validation failed");
+        const errors = validation.value?.errors ?? [];
+        return failedResult({
+            featureId: validation.value?.featureId ?? featureId,
+            mode: options.dryRun ? "dry-run" : "executed",
+            steps,
+            limitApplied,
+            code: "feature-validation-failed",
+            message: errors.map((error) => `${error.code}: ${error.message}`).join("; ") || validation.error || "Feature validation failed",
+            evidence: errors.flatMap((error) => error.path ? [error.path] : []),
+            nextCommand: `agent-worker task validate-feature ${JSON.stringify(featureDir)}`,
+            expectedArtifacts,
+            controllerIdentity,
+        });
+    }
+    featureId = validation.value.featureId;
+    if (options.dryRun)
+        steps.push(planned("preflight", "target repo preflight"));
+    if (!options.dryRun) {
+        progress.step("target repo preflight");
+        const preflight = await timedStep(steps, "preflight", async () => dependencies.preflight({
+            repoRoot,
+            client: options.client,
+            runCheckRepo: options.runCheckRepo,
+            ...(options.checkRepoCommand ? { checkRepoCommand: options.checkRepoCommand } : {}),
+            ...(options.controllerExpectation ? { expectation: options.controllerExpectation } : {}),
+        }));
+        if (!preflight.value?.ok) {
+            markLastStepFailed(steps, preflight.value && !preflight.value.ok ? preflight.value.message : preflight.error ?? "target repo preflight failed");
+            return preflightFailure({ featureId, repoRoot, steps, limitApplied, preflight: preflight.value, fallbackMessage: preflight.error, expectedArtifacts,
+                controllerIdentity: preflight.value?.controllerIdentity ?? controllerIdentity });
+        }
+        controllerIdentity = preflight.value.controllerIdentity ?? controllerIdentity;
+        steps.at(-1).artifacts = preflight.value.commands.map((command) => command.result.artifacts.resultPath);
+    }
+    if (checkpointMode) {
+        const canonicalRepo = await realpath(repoRoot).catch(() => repoRoot);
+        const canonicalFeature = await realpath(featureDir).catch(() => featureDir);
+        const featureRelative = path.relative(canonicalRepo, canonicalFeature);
+        if (featureRelative.startsWith("..") || path.isAbsolute(featureRelative)) {
+            return failedResult({ featureId, mode: options.dryRun ? "dry-run" : "executed", steps, limitApplied, code: "git-feature-repo-mismatch", message: "Feature Packet must be inside the Git target repo for checkpoint mode", evidence: [featureDir, repoRoot], expectedArtifacts,
+                controllerIdentity });
+        }
+        if (options.dryRun) {
+            steps.push(planned("git-preflight", `create or reuse agent/${featureId.toLowerCase()} and checkpoint each task`));
+        }
+        else {
+            const gitStep = await timedStep(steps, "git-preflight", async () => dependencies.startGit({ repoRoot, featureId, now }));
+            if (!gitStep.value)
+                return failedResult({ featureId, mode: "executed", steps, limitApplied, code: "git-preflight-failed", message: gitStep.error ?? "Git transaction preflight failed", evidence: [], expectedArtifacts,
+                    controllerIdentity });
+            gitTransaction = gitStep.value;
+            steps.at(-1).artifacts = [gitTransaction.recordPath];
+        }
+    }
+    const beforeStep = await timedStep(steps, "review-before", async () => dependencies.review({ featureDir, repoRoot }));
+    if (!beforeStep.value) {
+        return failedResult({ featureId, mode: options.dryRun ? "dry-run" : "executed", steps, limitApplied, code: "feature-review-failed", message: beforeStep.error ?? "Feature review failed", evidence: [], expectedArtifacts,
+            controllerIdentity });
+    }
+    before = beforeStep.value;
+    const readyTasks = before.tasks.filter((task) => task.status === "Ready").map((task) => task.taskId);
+    if (options.dryRun) {
+        steps.push({ ...planned("run-ready", readyTasks.length > 0 ? `execute at most ${limitApplied} Ready task` : "no Ready task"), artifacts: [expectedArtifacts.batchRun] }, { ...planned("morning-report", "refresh morning report"), artifacts: [expectedArtifacts.morningReport] }, { ...planned("observe-snapshot", "refresh Observe snapshot"), artifacts: [expectedArtifacts.observeSnapshot] }, planned("review-after", "derive final Feature review"));
+        return {
+            schemaVersion: 1,
+            featureId,
+            mode: "dry-run",
+            status: readyTasks.length > 0 ? "completed" : "no-ready",
+            noReadyReason: readyTasks.length > 0 ? null : classifyNoReady(before),
+            statusBefore: before.status,
+            statusAfter: before.status,
+            steps,
+            readyTasks,
+            executedTasks: [],
+            artifacts: { batchRun: null, morningReport: null, observeSnapshot: null, ...(checkpointMode ? { gitTransaction: expectedArtifacts.gitTransaction ?? null } : {}) },
+            expectedArtifacts,
+            reviewBefore: before,
+            reviewAfter: before,
+            nextActions: before.nextAction ? [before.nextAction] : [],
+            batch: null,
+            gitTasks,
+            limitApplied,
+            controllerIdentity,
+        };
+    }
+    if (readyTasks.length > 0 && limitApplied > 0) {
+        progress.batch(`feature ${featureId}: executing ${Math.min(readyTasks.length, limitApplied)} of ${readyTasks.length} Ready task(s)`);
+        const runStep = await timedStep(steps, "run-ready", async () => dependencies.runReady({
+            repoRoot,
+            featureDir,
+            client: options.client,
+            limit: limitApplied,
+            batchRunId,
+            now,
+            progress,
+            skipTaskPreflight: true,
+            ...(options.piModel ? { piModel: options.piModel } : {}),
+            ...(controllerIdentity ? { controllerIdentity } : {}),
+            ...(options.controllerExpectation ? { controllerExpectation: options.controllerExpectation } : {}),
+            ...(gitTransaction ? { onTaskFinalized: async (task) => {
+                    const gitResult = await dependencies.finalizeGit(gitTransaction, { ...task, keepFailedDiff: options.keepFailedDiff, now });
+                    gitTasks.push(gitResult);
+                    if (gitResult.status === "kept-failed-diff")
+                        throw new Error(`git-keep-failed-diff:${gitResult.artifactDir}`);
+                } } : {}),
+        }));
+        batch = runStep.value;
+        if (!batch) {
+            const kept = runStep.error?.startsWith("git-keep-failed-diff:") ?? false;
+            const failed = failedResult({ featureId, mode: "executed", steps, limitApplied, code: kept ? "git-failed-diff-kept" : "run-ready-failed", message: kept ? "Failed task diff was kept by explicit request; automatic execution stopped" : runStep.error ?? "run-ready failed", evidence: kept ? [runStep.error.slice("git-keep-failed-diff:".length)] : [], before, readyTasks, expectedArtifacts,
+                controllerIdentity });
+            return kept ? { ...failed, status: "needs-action", gitTasks, artifacts: { ...failed.artifacts, gitTransaction: gitTransaction?.recordPath ?? null } } : failed;
+        }
+        steps.at(-1).artifacts = [batch.batchRunPath];
+        if (batch.status === "failed" || batch.tasks.some((task) => task.status === "failed")) {
+            markLastStepFailed(steps, batch.status === "failed" ? "run-ready completed with run or record errors" : "one or more tasks failed");
+        }
+    }
+    else {
+        steps.push({ id: "run-ready", status: "skipped", durationMs: 0, message: "no Ready task" });
+    }
+    const morningReportPath = path.join(getTaskPoolRoot(repoRoot), "reports", "morning-report.md");
+    progress.step("refresh morning report");
+    const report = await timedStep(steps, "morning-report", async () => dependencies.writeReport({ repoRoot, ...(batch ? { batchRunId: batch.batchRunId } : {}), outputPath: morningReportPath }));
+    if (!report.value)
+        return failedResult({ featureId, mode: "executed", steps, limitApplied, code: "morning-report-failed", message: report.error ?? "morning report failed", evidence: [], before, readyTasks, batch, expectedArtifacts,
+            controllerIdentity });
+    steps.at(-1).artifacts = [report.value];
+    const snapshotPath = path.join(getTaskPoolRoot(repoRoot), "observability", "snapshot.json");
+    progress.step("refresh Observe snapshot");
+    const snapshot = await timedStep(steps, "observe-snapshot", async () => {
+        const value = await dependencies.buildSnapshot({ repoRoot });
+        await dependencies.writeSnapshot(snapshotPath, value);
+        return snapshotPath;
+    });
+    if (!snapshot.value)
+        return failedResult({ featureId, mode: "executed", steps, limitApplied, code: "observe-snapshot-failed", message: snapshot.error ?? "Observe snapshot failed", evidence: [report.value], before, readyTasks, batch, artifacts: { morningReport: report.value }, expectedArtifacts,
+            controllerIdentity });
+    steps.at(-1).artifacts = [snapshot.value];
+    progress.step("derive final Feature review");
+    const after = await timedStep(steps, "review-after", async () => dependencies.review({ featureDir, repoRoot }));
+    if (!after.value)
+        return failedResult({ featureId, mode: "executed", steps, limitApplied, code: "feature-review-failed", message: after.error ?? "final Feature review failed", evidence: [report.value, snapshot.value], before, readyTasks, batch, artifacts: { morningReport: report.value, observeSnapshot: snapshot.value }, expectedArtifacts,
+            controllerIdentity });
+    const taskFailures = batch?.tasks.filter((task) => task.status === "failed") ?? [];
+    const runInfrastructureFailed = batch?.status === "failed";
+    const executionError = runInfrastructureFailed
+        ? { code: "run-ready-failed", message: "run-ready completed with run or record errors", evidence: batch ? [batch.batchRunPath] : [] }
+        : taskFailures.length > 0
+            ? { code: "task-failures", message: `${taskFailures.length} task(s) failed`, evidence: taskFailures.flatMap((task) => task.runRecordPath ? [task.runRecordPath] : []) }
+            : undefined;
+    return {
+        schemaVersion: 1,
+        featureId,
+        mode: "executed",
+        status: readyTasks.length === 0 ? "no-ready" : runInfrastructureFailed ? "failed" : taskFailures.length > 0 ? "needs-action" : "completed",
+        noReadyReason: readyTasks.length === 0 ? classifyNoReady(after.value) : null,
+        statusBefore: before.status,
+        statusAfter: after.value.status,
+        steps,
+        readyTasks,
+        executedTasks: batch?.tasks ?? [],
+        artifacts: { batchRun: batch?.batchRunPath ?? null, morningReport: report.value, observeSnapshot: snapshot.value, ...(gitTransaction ? { gitTransaction: gitTransaction.recordPath } : {}) },
+        expectedArtifacts,
+        reviewBefore: before,
+        reviewAfter: after.value,
+        nextActions: after.value.nextAction ? [after.value.nextAction] : [],
+        batch: batch ?? null,
+        gitTasks,
+        ...(executionError ? { error: executionError } : {}),
+        limitApplied,
+        controllerIdentity,
+    };
+}
+export function renderFeatureRun(result) {
+    const executed = result.executedTasks.length === 0
+        ? "无"
+        : result.executedTasks.map((task) => `${task.taskId}:${task.status}`).join(", ");
+    const reason = result.error?.message ?? `状态 ${result.statusBefore} → ${result.statusAfter}；执行 ${executed}`;
+    const evidence = result.error?.evidence[0] ?? result.artifacts.batchRun ?? result.artifacts.morningReport ?? result.artifacts.observeSnapshot ?? "暂无";
+    return [
+        `Feature: ${result.featureId}`,
+        `结果: ${result.status}`,
+        `原因: ${reason}`,
+        `下一步: ${result.error?.nextCommand ?? result.nextActions[0]?.command ?? result.nextActions[0]?.label ?? "当前无行动"}`,
+        `证据: ${evidence}`,
+    ].join("\n") + "\n";
+}
+const defaultDependencies = {
+    validateFeature: validateFeatureTaskGraph,
+    review: reviewFeature,
+    preflight: preflightTargetRepo,
+    runReady: runReadyTasks,
+    writeReport: writeMorningReport,
+    buildSnapshot: buildGlobalSnapshot,
+    writeSnapshot: async (snapshotPath, snapshot) => {
+        const store = createSnapshotStore(snapshotPath);
+        await store.write(snapshot);
+        const persisted = await store.read();
+        if (!persisted || JSON.stringify(persisted) !== JSON.stringify(snapshot)) {
+            throw new Error(`snapshot was not written: ${snapshotPath}`);
+        }
+    },
+    startGit: startGitTransaction,
+    finalizeGit: finalizeGitTask,
+};
+async function timedStep(steps, id, run) {
+    const startedAt = Date.now();
+    try {
+        const value = await run();
+        steps.push({ id, status: "completed", durationMs: Date.now() - startedAt });
+        return { value };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        steps.push({ id, status: "failed", durationMs: Date.now() - startedAt, message: detail });
+        return { error: detail };
+    }
+}
+function planned(id, message) {
+    return { id, status: "planned", durationMs: 0, message };
+}
+function markLastStepFailed(steps, message) {
+    const step = steps.at(-1);
+    if (!step)
+        return;
+    step.status = "failed";
+    step.message = message;
+}
+function failedResult(input) {
+    return {
+        schemaVersion: 1,
+        featureId: input.featureId,
+        mode: input.mode,
+        status: "failed",
+        noReadyReason: null,
+        statusBefore: input.before?.status ?? "unknown",
+        statusAfter: input.before?.status ?? "unknown",
+        steps: input.steps,
+        readyTasks: input.readyTasks ?? [],
+        executedTasks: input.batch?.tasks ?? [],
+        artifacts: {
+            batchRun: input.batch?.batchRunPath ?? null,
+            morningReport: input.artifacts?.morningReport ?? null,
+            observeSnapshot: input.artifacts?.observeSnapshot ?? null,
+        },
+        expectedArtifacts: input.expectedArtifacts,
+        reviewBefore: input.before ?? null,
+        reviewAfter: input.before ?? null,
+        nextActions: input.before?.nextAction ? [input.before.nextAction] : [],
+        batch: input.batch ?? null,
+        error: { code: input.code, message: input.message, evidence: input.evidence, ...(input.nextCommand ? { nextCommand: input.nextCommand } : {}) },
+        limitApplied: input.limitApplied,
+        controllerIdentity: input.controllerIdentity,
+    };
+}
+function expectedArtifactPaths(repoRoot, batchRunId) {
+    const taskPoolRoot = getTaskPoolRoot(repoRoot);
+    return {
+        batchRun: path.join(taskPoolRoot, "artifacts", batchRunId, "batch-run.json"),
+        morningReport: path.join(taskPoolRoot, "reports", "morning-report.md"),
+        observeSnapshot: path.join(taskPoolRoot, "observability", "snapshot.json"),
+        gitTransaction: path.join(taskPoolRoot, "artifacts", "features", "<feature-id>", "git", "transaction.json"),
+    };
+}
+function classifyNoReady(review) {
+    if (review.tasks.length === 0)
+        return "empty";
+    if (review.status === "closed")
+        return "closed";
+    if (review.status === "deliverable")
+        return "deliverable";
+    if (review.status === "awaiting_qa")
+        return "awaiting-qa";
+    if (review.blockingItems.some((item) => item.type === "blocked_task"))
+        return "dependency-blocked";
+    if (review.status === "needs_action")
+        return "needs-action";
+    return "other";
+}
+function preflightFailure(input) {
+    const failed = input.preflight && !input.preflight.ok ? input.preflight : undefined;
+    return failedResult({
+        featureId: input.featureId,
+        mode: "executed",
+        steps: input.steps,
+        limitApplied: input.limitApplied,
+        code: failed?.code ?? "preflight-failed",
+        message: failed?.message ?? input.fallbackMessage ?? "target repo preflight failed",
+        evidence: failed?.commands.flatMap((command) => [command.result.artifacts.resultPath]) ?? [],
+        nextCommand: `cd ${JSON.stringify(input.repoRoot)} && loop-agent doctor`,
+        expectedArtifacts: input.expectedArtifacts,
+        controllerIdentity: failed?.controllerIdentity ?? input.controllerIdentity,
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/worker/feature/types.js

@@ -0,0 +1 @@
+export {};

package/dist/worker/follow-up/approve.js

@@ -0,0 +1,270 @@
+import { randomUUID } from "node:crypto";
+import { cp, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import { appendTaskPoolEvent, getEventsJsonlPath, getTaskStatePath, readTaskPoolState, writeTaskPoolState } from "../pool/run-store.js";
+import { taskGraphSpecSchema } from "../task-graph/task-graph-schema.js";
+import { validateFeatureTaskGraph } from "../task-graph/validate.js";
+import { taskSpecSchema } from "../task-spec/schema.js";
+import { assertSafeRuntimeId, assertSafeTaskFile, followUpDir } from "./paths.js";
+import { followUpApprovalSchema, followUpDraftSchema, followUpEvidenceSchema } from "./schema.js";
+import { cleanupPath, hashFeaturePacket, readFollowUpIndex, repoRef, resolveRepoFile, sha256File, withFollowUpLock, writeFollowUpIndex, writeJsonAtomic, writeTextAtomic } from "./store.js";
+export async function approveFollowUp(input) {
+    if (!input.owner.trim())
+        throw new Error("approve-followup requires a non-empty owner");
+    assertSafeRuntimeId(input.followUpId, "followUpId");
+    const repoRoot = path.resolve(input.repoRoot);
+    const featureDir = path.resolve(input.featureDir);
+    const graphPath = path.join(featureDir, "tasks", "task-graph.yaml");
+    const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(graphPath, "utf-8")));
+    const featureId = graph.feature_id;
+    assertSafeRuntimeId(featureId, "featureId");
+    if (input.dryRun)
+        return prepareApproval({ ...input, repoRoot, featureDir, featureId });
+    return withFollowUpLock(repoRoot, featureId, async () => executeApproval({ ...input, repoRoot, featureDir, featureId }));
+}
+async function prepareApproval(input) {
+    const loaded = await loadApprovalInputs(input);
+    if (loaded.existingApproval)
+        return resultFromApproval(loaded.existingApproval, input.repoRoot, loaded.approvalPath, true);
+    await assertApprovalPreconditions(loaded);
+    return {
+        schemaVersion: 1,
+        status: "planned",
+        idempotent: false,
+        followUpId: loaded.draft.follow_up_id,
+        proposedTaskId: loaded.draft.proposed_task_id,
+        taskSpecPath: repoRef(input.repoRoot, loaded.taskSpecPath),
+        graphPath: repoRef(input.repoRoot, loaded.graphPath),
+        statePath: repoRef(input.repoRoot, loaded.statePath),
+        approvalPath: repoRef(input.repoRoot, loaded.approvalPath),
+        eventPath: repoRef(input.repoRoot, getEventsJsonlPath(input.repoRoot)),
+    };
+}
+async function executeApproval(input) {
+    const loaded = await loadApprovalInputs(input);
+    if (loaded.existingApproval)
+        return resultFromApproval(loaded.existingApproval, input.repoRoot, loaded.approvalPath, true);
+    await assertApprovalPreconditions(loaded);
+    const beforeGraphText = await readFile(loaded.graphPath, "utf-8");
+    const beforeGraphHash = await sha256File(loaded.graphPath);
+    const stageDir = path.join(path.dirname(input.featureDir), `.followup-stage-${input.followUpId}-${randomUUID()}`);
+    await cp(input.featureDir, stageDir, { recursive: true });
+    const changedFiles = new Map();
+    let stateWritten = false;
+    let approvalWritten = false;
+    let indexWritten = false;
+    const originalIndex = await readFollowUpIndex(input.repoRoot, input.featureId);
+    try {
+        const stagedGraphPath = path.join(stageDir, "tasks", "task-graph.yaml");
+        const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(stagedGraphPath, "utf-8")));
+        graph.nodes.push(loaded.draft.proposed_graph_patch.add_node);
+        for (const rewire of loaded.draft.proposed_graph_patch.rewire_dependents) {
+            const node = graph.nodes.find((candidate) => candidate.id === rewire.task_id);
+            if (!node)
+                throw new Error(`rewire target is missing: ${rewire.task_id}`);
+            assertSafeTaskFile(node.task, `rewire task file for ${node.id}`);
+            node.depends_on = node.depends_on.map((dependency) => dependency === rewire.from_dependency ? rewire.to_dependency : dependency);
+            const stagedTaskPath = path.join(stageDir, "tasks", node.task);
+            const task = taskSpecSchema.parse(YAML.parse(await readFile(stagedTaskPath, "utf-8")));
+            task.depends_on = [...node.depends_on];
+            await writeTextAtomic(stagedTaskPath, YAML.stringify(task));
+        }
+        await writeTextAtomic(path.join(stageDir, "tasks", `${loaded.draft.proposed_task_id}.yaml`), YAML.stringify(loaded.draft.proposed_task_spec));
+        await writeTextAtomic(stagedGraphPath, YAML.stringify(graph));
+        const validation = await validateFeatureTaskGraph(stageDir);
+        if (!validation.ok)
+            throw new Error(`staged Feature validation failed: ${validation.errors.map((error) => error.code).join(", ")}`);
+        const afterGraphHash = await sha256File(stagedGraphPath);
+        const stagedRelativeFiles = [
+            path.join("tasks", `${loaded.draft.proposed_task_id}.yaml`),
+            "tasks/task-graph.yaml",
+            ...loaded.draft.proposed_graph_patch.rewire_dependents.map((rewire) => {
+                const node = graph.nodes.find((candidate) => candidate.id === rewire.task_id);
+                return path.join("tasks", node.task);
+            }),
+        ];
+        for (const relative of [...new Set(stagedRelativeFiles)]) {
+            const target = path.join(input.featureDir, relative);
+            changedFiles.set(target, await readOptional(target));
+            const temp = path.join(path.dirname(target), `.${path.basename(target)}.${randomUUID()}.tmp`);
+            try {
+                await writeFile(temp, await readFile(path.join(stageDir, relative)));
+                await input.faultInjector?.("before-packet-rename", relative);
+                await rename(temp, target);
+            }
+            finally {
+                await unlink(temp).catch(() => { });
+            }
+        }
+        await input.faultInjector?.("before-state-write");
+        await writeTaskPoolState(input.repoRoot, {
+            taskId: loaded.draft.proposed_task_id,
+            status: "Ready",
+            updatedAt: (input.now ?? new Date()).toISOString(),
+        });
+        stateWritten = true;
+        const approvedAt = (input.now ?? new Date()).toISOString();
+        const approval = {
+            schemaVersion: 1,
+            followUpId: loaded.draft.follow_up_id,
+            proposedTaskId: loaded.draft.proposed_task_id,
+            owner: input.owner,
+            approvedAt,
+            draftHash: await sha256File(loaded.draftPath),
+            beforeGraphHash,
+            afterGraphHash,
+            taskSpecPath: repoRef(input.repoRoot, loaded.taskSpecPath),
+            graphPath: repoRef(input.repoRoot, loaded.graphPath),
+            statePath: repoRef(input.repoRoot, loaded.statePath),
+            eventPath: repoRef(input.repoRoot, getEventsJsonlPath(input.repoRoot)),
+        };
+        followUpApprovalSchema.parse(approval);
+        await input.faultInjector?.("before-approval-write");
+        await writeJsonAtomic(loaded.approvalPath, approval);
+        approvalWritten = true;
+        const index = structuredClone(originalIndex);
+        const entry = index.entries.find((candidate) => candidate.followUpId === input.followUpId);
+        entry.status = "Approved";
+        entry.approvalPath = repoRef(input.repoRoot, loaded.approvalPath);
+        entry.approvedAt = approvedAt;
+        await input.faultInjector?.("before-index-write");
+        await writeFollowUpIndex(input.repoRoot, index);
+        indexWritten = true;
+        await input.faultInjector?.("before-event-append");
+        await appendTaskPoolEvent(input.repoRoot, {
+            schemaVersion: 1,
+            at: approvedAt,
+            type: "follow-up-approved",
+            featureId: input.featureId,
+            followUpId: input.followUpId,
+            proposedTaskId: loaded.draft.proposed_task_id,
+            parentTaskId: loaded.draft.lineage.parent_task_id,
+            workerRunId: loaded.draft.generated_from.worker_run_id,
+            owner: input.owner,
+            draftHash: approval.draftHash,
+            beforeGraphHash,
+            afterGraphHash,
+            artifactRefs: [repoRef(input.repoRoot, loaded.draftPath), repoRef(input.repoRoot, loaded.approvalPath)],
+        });
+        return resultFromApproval(approval, input.repoRoot, loaded.approvalPath, false);
+    }
+    catch (error) {
+        if (indexWritten)
+            await writeFollowUpIndex(input.repoRoot, originalIndex).catch(() => { });
+        if (approvalWritten)
+            await unlink(loaded.approvalPath).catch(() => { });
+        if (stateWritten)
+            await unlink(loaded.statePath).catch(() => { });
+        for (const [target, original] of [...changedFiles.entries()].reverse()) {
+            if (original === undefined)
+                await unlink(target).catch(() => { });
+            else
+                await writeTextAtomic(target, original).catch(() => { });
+        }
+        await writeTextAtomic(loaded.graphPath, beforeGraphText).catch(() => { });
+        throw error;
+    }
+    finally {
+        await cleanupPath(stageDir);
+    }
+}
+async function loadApprovalInputs(input) {
+    const index = await readFollowUpIndex(input.repoRoot, input.featureId);
+    const entry = index.entries.find((candidate) => candidate.followUpId === input.followUpId);
+    if (!entry)
+        throw new Error(`follow-up not found: ${input.followUpId}`);
+    if (entry.kind !== "TaskDraft" || !entry.proposedTaskId)
+        throw new Error(`follow-up is not an approvable TaskDraft: ${entry.kind}`);
+    const draftPath = await resolveRepoFile(input.repoRoot, entry.draftPath);
+    const approvalPath = path.join(followUpDir(input.repoRoot, input.featureId, input.followUpId), "approval.json");
+    const evidencePath = path.join(followUpDir(input.repoRoot, input.featureId, input.followUpId), "evidence.json");
+    let existingApproval;
+    try {
+        existingApproval = followUpApprovalSchema.parse(JSON.parse(await readFile(approvalPath, "utf-8")));
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            throw error;
+    }
+    const draft = followUpDraftSchema.parse(YAML.parse(await readFile(draftPath, "utf-8")));
+    for (const [value, label] of [
+        [draft.follow_up_id, "draft.followUpId"],
+        [draft.proposed_task_id, "draft.proposedTaskId"],
+        [draft.generated_from.feature_id, "draft.featureId"],
+        [draft.generated_from.task_id, "draft.taskId"],
+        [draft.lineage.parent_task_id, "draft.parentTaskId"],
+        ...draft.proposed_graph_patch.rewire_dependents.flatMap((rewire) => [[rewire.task_id, "rewire.taskId"], [rewire.from_dependency, "rewire.fromDependency"], [rewire.to_dependency, "rewire.toDependency"]]),
+    ])
+        assertSafeRuntimeId(value, label);
+    return {
+        entry, draft, draftPath, evidencePath, approvalPath, existingApproval,
+        taskSpecPath: path.join(input.featureDir, "tasks", `${draft.proposed_task_id}.yaml`),
+        graphPath: path.join(input.featureDir, "tasks", "task-graph.yaml"),
+        statePath: getTaskStatePath(input.repoRoot, draft.proposed_task_id),
+        featureId: input.featureId,
+        featureDir: input.featureDir,
+        repoRoot: input.repoRoot,
+    };
+}
+async function assertApprovalPreconditions(loaded) {
+    if (loaded.entry.status !== "Draft" || loaded.draft.status !== "Draft")
+        throw new Error(`follow-up is not Draft: ${loaded.entry.status}`);
+    if (loaded.draft.generated_from.feature_id !== loaded.featureId)
+        throw new Error("follow-up Feature lineage does not match its index");
+    if (await sha256File(loaded.draftPath) !== loaded.entry.draftHash)
+        throw new Error("follow-up draft hash changed; regenerate and review the draft");
+    const evidenceHash = await sha256File(loaded.evidencePath);
+    if (evidenceHash !== loaded.entry.evidenceHash || evidenceHash !== loaded.draft.evidence_manifest_hash)
+        throw new Error("follow-up evidence manifest changed; regenerate and review the draft");
+    const evidence = followUpEvidenceSchema.parse(JSON.parse(await readFile(loaded.evidencePath, "utf-8")));
+    if (evidence.followUpId !== loaded.draft.follow_up_id)
+        throw new Error("follow-up evidence lineage does not match the draft");
+    if (evidence.evidence.map((item) => item.ref).join("\0") !== loaded.draft.evidence_refs.join("\0"))
+        throw new Error("follow-up evidence refs do not match the draft");
+    for (const item of evidence.evidence) {
+        const evidencePath = await realpath(path.resolve(loaded.repoRoot, item.ref));
+        const canonicalRoot = await realpath(loaded.repoRoot);
+        const relative = path.relative(canonicalRoot, evidencePath).split(path.sep).join("/");
+        if (relative !== item.ref || relative.startsWith("..") || path.isAbsolute(relative) || await sha256File(evidencePath) !== item.sha256) {
+            throw new Error(`follow-up evidence changed or escaped the repo: ${item.ref}`);
+        }
+    }
+    if (await hashFeaturePacket(loaded.featureDir) !== loaded.draft.feature_packet_hash)
+        throw new Error("Feature Packet baseline changed; regenerate the follow-up draft");
+    if (await readOptional(loaded.taskSpecPath) !== undefined)
+        throw new Error(`proposed TaskSpec already exists: ${loaded.draft.proposed_task_id}`);
+    const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(loaded.graphPath, "utf-8")));
+    if (graph.nodes.some((node) => node.id === loaded.draft.proposed_task_id))
+        throw new Error(`proposed graph node already exists: ${loaded.draft.proposed_task_id}`);
+    if (await readTaskPoolState(loaded.repoRoot, loaded.draft.proposed_task_id))
+        throw new Error(`Task Pool state already exists: ${loaded.draft.proposed_task_id}`);
+}
+function resultFromApproval(approval, repoRoot, approvalPath, idempotent) {
+    return {
+        schemaVersion: 1,
+        status: "approved",
+        idempotent,
+        followUpId: approval.followUpId,
+        proposedTaskId: approval.proposedTaskId,
+        taskSpecPath: approval.taskSpecPath,
+        graphPath: approval.graphPath,
+        statePath: approval.statePath,
+        approvalPath: repoRef(repoRoot, approvalPath),
+        eventPath: approval.eventPath,
+        approval,
+    };
+}
+async function readOptional(filePath) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+function isNotFound(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}