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

package/dist/sidecars/cursor-prompt/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_CURSOR_MODEL, DEFAULT_CURSOR_TIMEOUT_MS, DEFAULT_CURSOR_STREAM_IDLE_TIMEOUT_MS, WAIT_AFTER_STREAM_GRACE_MS, MAX_CURSOR_STDOUT_BYTES, MAX_CURSOR_STDERR_BYTES, buildCursorPrompt, buildArtifactPathPrompt, resolveArtifactWriteDir, buildRedactedExecutorRecord, buildCursorExecutorEnv, classifyCursorFailure, mapRunStatusToExecutionStatus, CursorTimeoutError, isCursorTimeoutError, withCursorTimeout, buildStreamIdleTimeoutMessage, bestEffortCancelRun, extractCursorTokenUsage, executeCursorTask, redactApiKey, } from "./executor.js";
+export { truncateOutput, redactPromptForLog, } from "../../shared/output-truncation.js";
+export { executeCursorPromptStream, } from "./stream.js";

package/dist/sidecars/cursor-prompt/stream.js

@@ -0,0 +1,121 @@
+import { bestEffortCancelRun, buildCursorPrompt, classifyCursorFailure, mapRunStatusToExecutionStatus, } from "./executor.js";
+async function createCursorStreamAgent(input) {
+    const { Agent } = await import("@cursor/sdk");
+    return Agent.create({
+        apiKey: input.apiKey,
+        name: "pi-cursor-prompt",
+        model: { id: input.model },
+        local: { cwd: input.cwd },
+    });
+}
+/**
+ * One-shot streaming path for cursor-prompt CLI. Loads @cursor/sdk only here.
+ */
+export async function executeCursorPromptStream(input) {
+    const apiKey = input.apiKey ?? process.env.CURSOR_API_KEY;
+    if (!apiKey?.trim()) {
+        return {
+            ok: false,
+            status: "failed",
+            failureCategory: "missing-api-key",
+            model: input.model,
+            durationMs: 0,
+            stdout: "",
+            stderr: "CURSOR_API_KEY environment variable is not set.",
+            details: { startupError: true },
+        };
+    }
+    const prompt = buildCursorPrompt(input.task, { runDir: input.runDir });
+    const startedAt = Date.now();
+    let timeoutHandle;
+    let agent;
+    let run;
+    let timedOut = false;
+    try {
+        agent = await (input.agentFactory ?? createCursorStreamAgent)({
+            apiKey,
+            cwd: input.cwd,
+            model: input.model,
+        });
+        const runPromise = (async () => {
+            run = await agent.send(prompt);
+            for await (const event of run.stream()) {
+                if (event.type === "assistant") {
+                    for (const block of event.message.content) {
+                        if (block.type === "text" && block.text) {
+                            input.callbacks?.onAssistantText?.(block.text);
+                        }
+                    }
+                }
+            }
+            return run.wait();
+        })();
+        const timeoutRace = new Promise((resolve) => {
+            timeoutHandle = setTimeout(() => resolve("timeout"), input.timeoutMs);
+        });
+        const raced = await Promise.race([
+            runPromise.then((value) => ({ kind: "done", value })),
+            timeoutRace.then(() => ({ kind: "timeout" })),
+        ]);
+        if (raced.kind === "timeout") {
+            timedOut = true;
+            await bestEffortCancelRun(run);
+            return {
+                ok: false,
+                status: "timeout",
+                failureCategory: "timeout",
+                model: input.model,
+                durationMs: Date.now() - startedAt,
+                stdout: "",
+                stderr: `Cursor execution timed out after ${input.timeoutMs}ms`,
+                details: { timedOut: true, timeoutKind: "total" },
+            };
+        }
+        const sdkResult = raced.value;
+        const runStatus = String(sdkResult.status ?? "");
+        const status = mapRunStatusToExecutionStatus(runStatus, false);
+        const ok = status === "completed";
+        return {
+            ok,
+            status,
+            failureCategory: ok
+                ? "success"
+                : classifyCursorFailure({ runStatus, stderr: "", stdout: "" }),
+            model: input.model,
+            durationMs: sdkResult.durationMs ?? Date.now() - startedAt,
+            stdout: "",
+            stderr: "",
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            status: "failed",
+            failureCategory: classifyCursorFailure({
+                startupError: message,
+                stderr: message,
+            }),
+            model: input.model,
+            durationMs: Date.now() - startedAt,
+            stdout: "",
+            stderr: message,
+            details: { startupError: true },
+        };
+    }
+    finally {
+        if (timeoutHandle)
+            clearTimeout(timeoutHandle);
+        if (!timedOut && run?.status === "running") {
+            await bestEffortCancelRun(run);
+        }
+        if (agent) {
+            try {
+                await agent[Symbol.asyncDispose]();
+            }
+            catch {
+                // The one-shot result remains authoritative; disposal is best effort.
+            }
+        }
+    }
+}

package/dist/task/config-types.js

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import { taskExecutorSchema } from "../governance/manifest-types.js";
 export const taskFlowSchema = z.enum([
     "auto",
     "micro",
@@ -8,7 +7,12 @@ export const taskFlowSchema = z.enum([
     "loop",
     "feature-study",
 ]);
-export const taskKindSchema = z.enum(["standard", "feature-study"]);
+export const taskKindSchema = z.enum([
+    "standard",
+    "feature-study",
+    "frontend-implementation",
+    "backend-test",
+]);
 export const referenceRepoConfigSchema = z.object({
     name: z.string().min(1),
     path: z.string().min(1),
@@ -40,11 +44,13 @@ export const dagVerifyStrategySchema = z
         .default("adapter"),
 })
     .optional();
-export const loopAutoWritePolicySchema = z.enum([
+export const loopAutoExecutionPolicySchema = z.enum([
     "off",
     "approval-required",
     "enabled",
 ]);
+export const LOOP_AUTO_WRITE_POLICY_REMOVED_ERROR = "task field loopAutoWritePolicy is no longer supported; use loopAutoExecutionPolicy (off | approval-required | enabled)";
+export const CURSOR_TASK_FIELD_REMOVED_ERROR = 'task fields "executor" and "cursorModel" are no longer supported; governed runtime is Pi-only';
 export const convergenceConfigSchema = z.object({
     enabled: z.boolean().optional().default(false),
     maxPasses: z.number().int().positive().optional().default(3),
@@ -52,11 +58,11 @@ export const convergenceConfigSchema = z.object({
     stopOnHardVerifyPass: z.boolean().optional().default(true),
     pauseOnRegression: z.boolean().optional().default(true),
 });
-export const taskConfigSchema = z.object({
+const taskConfigObjectSchema = z.object({
     taskId: z.string(),
     title: z.string(),
     sourceFiles: z.array(z.string()),
-    /** standard: 本仓库需求实现；feature-study: 参考外部代码特性并在目标仓库落地 */
+    /** standard: 本仓库需求实现；feature-study: 参考外部代码特性并在目标仓库落地；frontend-implementation: 使用前端实现 DAG 模板 */
     taskKind: taskKindSchema.optional().default("standard"),
     referenceRepos: z.array(referenceRepoConfigSchema).optional().default([]),
     referenceDocs: z.array(referenceDocConfigSchema).optional().default([]),
@@ -67,7 +73,7 @@ export const taskConfigSchema = z.object({
     hardConstraints: z.array(z.string()).optional().default([]),
     autoCommitAfterVerify: z.boolean().optional().default(true),
     autoCommitMessage: z.string().optional().default(""),
-    /** Explicit reason that a medium/large task could not use DAG before loop cursor-fix. */
+    /** Explicit reason that a medium/large task could not use DAG before loop auto execution. */
     dagFallbackReason: z.string().optional(),
     /** full: attach governance bundle; slim: analyze/plan 只带最少仓库上下文（source + harness 等） */
     contextProfile: contextProfileSchema.optional().default("full"),
@@ -76,7 +82,7 @@ export const taskConfigSchema = z.object({
     complexity: taskComplexitySchema.optional().default("medium"),
     /** Explicit delivery capabilities that affect writer contracts/model tier without changing risk. */
     capabilities: z.array(taskCapabilitySchema).optional(),
-    verifyMode: verifyModeSchema.optional().default("parallel"),
+    verifyMode: verifyModeSchema.optional().default("serial"),
     verifyPreset: verifyPresetSchema.optional().default("auto"),
     /** Task-contract commands that must be included in final DAG shell verification. */
     verifyCommands: z.array(taskVerifyCommandSchema).optional().default([]),
@@ -90,8 +96,10 @@ export const taskConfigSchema = z.object({
     maxFixLoops: z.number().int().min(0).optional().default(2),
     /** Supervised DAG convergence is opt-in until runtime smoke evidence is stronger. */
     convergence: convergenceConfigSchema.optional().default({ enabled: false }),
-    /** Outer loop auto mode never writes by default; cursor-fix requires this policy plus bounded path guards. */
-    loopAutoWritePolicy: loopAutoWritePolicySchema.optional().default("off"),
+    /** Outer loop auto mode never writes by default; DAG execute requires this policy plus path/writeSet gates. */
+    loopAutoExecutionPolicy: loopAutoExecutionPolicySchema
+        .optional()
+        .default("off"),
     requireRetrospective: z.boolean().optional().default(false),
     /** inherit: use host shell env; clean: sanitized env for deterministic verify */
     verifyEnv: z.enum(["inherit", "clean"]).optional().default("clean"),
@@ -99,9 +107,18 @@ export const taskConfigSchema = z.object({
     maxGoalContinuationsPerRun: z.number().int().positive().optional().default(5),
     /** Pi subagent assisted mode: 'off' (default), 'analyze-plan', or 'full' */
     piSubagentMode: piSubagentModeSchema.optional().default("off"),
-    /** Leaf executor: default pi; cursor requires delegate + worktree isolation */
-    executor: taskExecutorSchema.optional().default("pi"),
-    /** Cursor model override (e.g. gpt-5.5); falls back to harness executors.cursor.defaultModel */
-    cursorModel: z.string().optional(),
     notes: z.string().optional().default(""),
 });
+export const taskConfigSchema = z.preprocess((raw) => {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return raw;
+    }
+    const obj = raw;
+    if ("loopAutoWritePolicy" in obj) {
+        throw new Error(LOOP_AUTO_WRITE_POLICY_REMOVED_ERROR);
+    }
+    if ("executor" in obj || "cursorModel" in obj) {
+        throw new Error(CURSOR_TASK_FIELD_REMOVED_ERROR);
+    }
+    return raw;
+}, taskConfigObjectSchema);

package/dist/task/delegate.js

@@ -9,31 +9,24 @@ import { getTaskPaths, loadTaskConfig } from './runtime.js';
 import { copyDir } from '../records/harvest.js';
 import { saveWorkflowState } from './state.js';
 import { workflowStateSchema } from '../shared/types.js';
-import { assertCursorExecutorAvailable, resolveTaskExecutor, validateCursorTaskPreflight } from '../executors/config-core.js';
-import { resolveDelegateExecutionMode } from '../executors/cursor-execution-log.js';
 /**
  * Atomic delegation: validate source → check conflicts → create worktree →
  * sync source → optionally symlink node_modules.
  *
- * Execution runs in-process for Cursor SDK; Pi worktrees are prepared for manual DAG follow-up.
+ * Default is isolation only; callers may run Pi DAG via application use cases.
  */
 export async function delegateTask(repoRoot, manifest, taskId, opts = {}) {
     const symlinkEnabled = opts.symlinkNodeModules !== false;
     await validateSourceMaterials(repoRoot, taskId);
-    const taskConfig = await loadTaskConfig(repoRoot, taskId);
+    await loadTaskConfig(repoRoot, taskId);
     const effectiveManifest = manifest ?? (await loadHarnessManifest(repoRoot));
-    const executor = resolveTaskExecutor(taskConfig, opts.executor);
-    if (executor === 'cursor') {
-        assertCursorExecutorAvailable(effectiveManifest);
-        validateCursorTaskPreflight(taskConfig);
-    }
     await validateNoConflicts(repoRoot, taskId, opts.branch);
     const worktree = await createWorktree(repoRoot, effectiveManifest, {
         taskId,
         branch: opts.branch,
         base: opts.base,
     });
-    await syncSourceToWorktree(repoRoot, taskId, worktree.path, executor);
+    await syncSourceToWorktree(repoRoot, taskId, worktree.path);
     let symlinkedNodeModules = false;
     if (symlinkEnabled) {
         symlinkedNodeModules = await setupNodeModulesSymlink(repoRoot, worktree.path);
@@ -46,13 +39,9 @@ export async function delegateTask(repoRoot, manifest, taskId, opts = {}) {
         branch: worktree.branch,
         baseBranch: worktree.base,
         symlinkedNodeModules,
-        executor,
-        executionMode: resolveDelegateExecutionMode(executor),
+        executionMode: 'pi-worktree',
     };
 }
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
 async function validateSourceMaterials(repoRoot, taskId) {
     const { taskConfigPath, sourceDir } = getTaskPaths(repoRoot, taskId);
     try {
@@ -96,7 +85,7 @@ async function validateNoConflicts(repoRoot, taskId, branch) {
         console.error(`[delegate] warning: branch "${targetBranch}" already exists; will reuse it for the worktree.`);
     }
 }
-async function syncSourceToWorktree(repoRoot, taskId, worktreePath, executor) {
+async function syncSourceToWorktree(repoRoot, taskId, worktreePath) {
     const srcPaths = getTaskPaths(repoRoot, taskId);
     const destPaths = getTaskPaths(worktreePath, taskId);
     const destTaskDir = destPaths.taskDir;
@@ -106,16 +95,15 @@ async function syncSourceToWorktree(repoRoot, taskId, worktreePath, executor) {
     await copyDir(srcPaths.sourceDir, destSourceDir);
     const rawJson = await readFile(srcPaths.taskConfigPath, 'utf-8');
     const parsedTaskConfig = JSON.parse(rawJson);
-    parsedTaskConfig.executor = executor;
     await mkdir(path.dirname(destTaskConfigPath), { recursive: true });
     await writeTaskConfig(worktreePath, taskId, parsedTaskConfig);
     await mkdir(destPaths.logsDir, { recursive: true });
     await initializeArtifacts(destTaskDir);
     await initializeTaskLogStubs(worktreePath, taskId);
-    const state = await loadOrCreateWorkflowState(srcPaths.statePath, taskId, executor);
+    const state = await loadOrCreateWorkflowState(srcPaths.statePath, taskId);
     await saveWorkflowState(destPaths.statePath, state);
 }
-async function loadOrCreateWorkflowState(statePath, taskId, executor) {
+async function loadOrCreateWorkflowState(statePath, taskId) {
     try {
         const raw = await readFile(statePath, 'utf-8');
         return workflowStateSchema.parse(JSON.parse(raw));
@@ -129,8 +117,8 @@ async function loadOrCreateWorkflowState(statePath, taskId, executor) {
             completedSteps: [],
             lastUpdated: now,
             executor: {
-                name: executor,
-                mode: executor === 'cursor' ? 'sdk' : 'json',
+                name: 'pi',
+                mode: 'json',
             },
             artifacts: {
                 analysis: false,

package/dist/task/runtime.js

@@ -102,7 +102,7 @@ export async function createTask(repoRoot, taskId, title) {
         complexity: 'medium',
         dagFallbackReason: '',
         contextProfile: 'full',
-        verifyMode: 'parallel',
+        verifyMode: 'serial',
         verifyPreset: 'auto',
         verifyCommands: [],
         verifyQuota: 'full',
@@ -117,11 +117,10 @@ export async function createTask(repoRoot, taskId, title) {
             stopOnHardVerifyPass: true,
             pauseOnRegression: true,
         },
-        loopAutoWritePolicy: 'off',
+        loopAutoExecutionPolicy: 'off',
         verifyEnv: 'clean',
         maxGoalContinuationsPerRun: 5,
         piSubagentMode: 'off',
-        executor: 'pi',
         notes: '',
     };
     const state = {

package/dist/worker/cli.js

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
+import { readPackageVersion } from "../shared/package-metadata.js";
 import YAML from "yaml";
 import { LoopAgentClient } from "./loop-agent/loop-agent-client.js";
 import { resolveLoopAgentProfile } from "./profile-mapping.js";
@@ -17,17 +18,158 @@ import { getTaskPoolRoot, prepareTaskPoolRetry } from "./pool/run-store.js";
 import { taskSpecSchema } from "./task-spec/schema.js";
 import { validateTaskSpec } from "./task-spec/validate.js";
 import { validateFeatureTaskGraph } from "./task-graph/validate.js";
+import { renderFeatureReview, reviewFeature } from "./feature/review.js";
+import { renderFeatureRun, runFeature } from "./feature/run.js";
+import { draftFollowUpDecision } from "./follow-up/factory.js";
+import { approveFollowUp } from "./follow-up/approve.js";
+import { prepareFeatureDelivery } from "./delivery/package.js";
+import { previewFeatureCloseout, renderCloseoutPreview } from "./closeout/preview.js";
+import { applyFeatureCloseout } from "./closeout/apply.js";
+import { projectMonthlyMetrics } from "./metrics/projector.js";
+import { runFeatureFinalVerification } from "./delivery/final-verification.js";
 export function buildAgentWorkerProgram() {
     const program = new Command();
     program
         .name("agent-worker")
         .description("Local product-line worker utilities for TaskSpec validation")
+        .version(readPackageVersion(path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))))) ?? "0.0.0", "-V, --version", "display version")
         .showHelpAfterError()
         .showSuggestionAfterError();
     const task = program.command("task").description("TaskSpec utilities");
     const batch = program.command("batch").description("Task Pool batch utilities");
     const report = program.command("report").description("Task Pool reporting utilities");
     const observe = program.command("observe").description("Observe UI server and snapshot utilities");
+    const feature = program.command("feature").description("Feature-level review and delivery workflow");
+    feature
+        .command("review")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit stable JSON instead of the human summary")
+        .description("Derive Feature status, blockers, acceptance coverage, and next action")
+        .action(async (options) => {
+        const result = await reviewFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot: path.resolve(options.repo),
+        });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderFeatureReview(result));
+    });
+    feature
+        .command("run")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--dry-run", "Show validation, Ready tasks, steps, and expected artifacts without writes")
+        .option("--json", "Emit stable JSON instead of the human summary")
+        .option("--limit <count>", "Maximum Ready tasks (without checkpoint mode capped at 1)", "1")
+        .option("--git-mode <mode>", "Git mode: none or checkpoint", "none")
+        .option("--keep-failed-diff", "Keep a failed task diff and stop instead of restoring")
+        .option("--loop-agent-bin <bin>", "loop-agent binary", "loop-agent")
+        .option("--batch-run-id <id>", "Batch run id")
+        .option("--check-repo", "Run bash scripts/check-repo.sh during target repo preflight")
+        .option("--check-repo-command <command...>", "Override the check-repo preflight command")
+        .option("--quiet", "Suppress human-readable progress on stderr")
+        .option("--pi-model <model>", "Smoke override for pi executor nodes")
+        .option("--expected-controller-version <version>", "Exact expected controller version (fail before writes if mismatched)")
+        .option("--expected-controller-fingerprint <value>", "Exact expected controller fingerprint sha256:<hex> (fail before writes if mismatched)")
+        .description("Validate and advance one Ready Feature task through the existing Worker pipeline")
+        .action(async (options) => {
+        if (options.gitMode !== "none" && options.gitMode !== "checkpoint")
+            throw new Error("feature run --git-mode must be none or checkpoint");
+        if (options.keepFailedDiff && options.gitMode !== "checkpoint")
+            throw new Error("--keep-failed-diff requires --git-mode checkpoint");
+        const repoRoot = path.resolve(options.repo);
+        const batchRunId = options.batchRunId ?? buildBatchRunId(new Date());
+        const expectedIdentity = buildIdentityExpectation(options);
+        const client = new LoopAgentClient({
+            loopAgentBin: options.loopAgentBin,
+            artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", batchRunId),
+            resolveIdentity: true,
+        });
+        let progress;
+        try {
+            progress = createCompositeProgressReporter({
+                quiet: options.quiet ?? options.dryRun ?? false,
+                eventStore: createRoutedWorkerEventStore(repoRoot),
+                context: { batchRunId },
+            });
+        }
+        catch {
+            progress = createProgressReporter({ quiet: options.quiet ?? options.dryRun ?? false });
+        }
+        const result = await runFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot,
+            client,
+            dryRun: options.dryRun ?? false,
+            limit: Number.parseInt(options.limit, 10),
+            batchRunId,
+            runCheckRepo: options.checkRepo ?? false,
+            ...(options.checkRepoCommand ? { checkRepoCommand: options.checkRepoCommand } : {}),
+            progress,
+            ...(options.piModel ? { piModel: options.piModel } : {}),
+            gitMode: options.gitMode === "checkpoint" ? "checkpoint" : "none",
+            keepFailedDiff: options.keepFailedDiff ?? false,
+            controllerIdentity: client.getIdentity(),
+            controllerExpectation: expectedIdentity,
+        });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderFeatureRun(result));
+        if (result.status === "failed" || result.status === "needs-action")
+            process.exitCode = 1;
+    });
+    feature
+        .command("verify-final")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--task-id <id>", "Completed qa-execute TaskSpec to rerun as dedicated final verification")
+        .option("--loop-agent-bin <bin>", "loop-agent binary", "loop-agent")
+        .option("--json", "Emit stable JSON")
+        .option("--expected-controller-version <version>", "Exact expected controller version (fail before writes if mismatched)")
+        .option("--expected-controller-fingerprint <value>", "Exact expected controller fingerprint sha256:<hex> (fail before writes if mismatched)")
+        .description("Run an independent HEAD-bound final QA verification and project Delivery evidence")
+        .action(async (options) => {
+        const repoRoot = path.resolve(options.repo);
+        const client = new LoopAgentClient({ loopAgentBin: options.loopAgentBin, artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", `final-verification-${Date.now()}`), resolveIdentity: true });
+        const result = await runFeatureFinalVerification({ featureDir: path.resolve(options.featureDir), repoRoot, taskId: options.taskId, client, controllerIdentity: client.getIdentity(), controllerExpectation: buildIdentityExpectation(options) });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : `Feature: ${result.featureId}\nFinal verification: ${result.workerRunId}\nQA evidence: ${result.qaEvidencePath}\nFinal evidence: ${result.finalVerificationPath}\n`);
+    });
+    feature
+        .command("delivery")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--qa-evidence <path>", "Repo-local QA pass evidence")
+        .requiredOption("--final-verification <path>", "Repo-local fresh final verification evidence")
+        .option("--waivers <path>", "Repo-local acceptance waiver decisions JSON")
+        .option("--dry-run", "Validate and show the Delivery Package plan without writes")
+        .option("--json", "Emit stable JSON")
+        .description("Validate checkpointed Feature evidence and prepare a local Delivery Package")
+        .action(async (options) => {
+        const result = await prepareFeatureDelivery({
+            featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo),
+            qaEvidencePath: options.qaEvidence, finalVerificationPath: options.finalVerification,
+            ...(options.waivers ? { waiverPath: options.waivers } : {}), dryRun: options.dryRun ?? false,
+        });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : `Feature: ${result.featureId}\nDelivery: ${result.status}\nArtifacts: ${Object.values(result.artifacts).join(", ")}\nBlockers: ${result.blockers.join("; ") || "none"}\n`);
+        if (result.status === "blocked")
+            process.exitCode = 1;
+    });
+    feature
+        .command("closeout")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--apply", "Apply Feature Closeout (reserved for M2-08)")
+        .option("--owner <owner>", "Closeout owner for apply")
+        .option("--json", "Emit stable JSON")
+        .description("Preview Feature Closeout gates without modifying the Feature Packet")
+        .action(async (options) => {
+        if (options.apply) {
+            const result = await applyFeatureCloseout({ featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo), owner: options.owner ?? "" });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            return;
+        }
+        const result = await previewFeatureCloseout({ featureDir: path.resolve(options.featureDir), repoRoot: path.resolve(options.repo) });
+        process.stdout.write(options.json ? `${JSON.stringify(result, null, 2)}\n` : renderCloseoutPreview(result));
+        if (result.status === "blocked")
+            process.exitCode = 1;
+    });
     task
         .command("validate")
         .argument("<task-yaml>", "TaskSpec YAML file")
@@ -74,6 +216,58 @@ export function buildAgentWorkerProgram() {
         });
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     });
+    task
+        .command("draft-followup")
+        .argument("<task-id>", "Failed parent Task id")
+        .requiredOption("--worker-run-id <id>", "Failed Worker run id")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--feature-dir <dir>", "Feature Packet directory")
+        .option("--json", "Emit JSON instead of the human summary")
+        .description("Create or reuse a classified Follow-up Task draft or human action card")
+        .action(async (taskId, options) => {
+        try {
+            const result = await draftFollowUpDecision({
+                repoRoot: path.resolve(options.repo),
+                featureDir: path.resolve(options.featureDir),
+                taskId,
+                workerRunId: options.workerRunId,
+            });
+            process.stdout.write(options.json
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : result.kind === "TaskDraft"
+                    ? `Follow-up: ${result.followUpId}\n结果: ${result.created ? "已生成任务草稿" : "复用现有任务草稿"}\n下一步: agent-worker feature approve-followup --feature-dir ${JSON.stringify(path.resolve(options.featureDir))} --followup-id ${result.followUpId} --repo ${JSON.stringify(path.resolve(options.repo))} --owner <owner>\n证据: ${result.draftPath}\n`
+                    : `Follow-up: ${result.followUpId}\n结果: ${result.created ? "已生成人工行动卡" : "复用现有行动卡"}\n下一步: ${result.actionCard.command ?? result.actionCard.label}\n证据: ${result.draftPath}\n`);
+        }
+        catch (error) {
+            handleFollowUpCliError(error, options.json ?? false, "draft-followup");
+        }
+    });
+    feature
+        .command("approve-followup")
+        .requiredOption("--feature-dir <dir>", "Feature Packet directory")
+        .requiredOption("--followup-id <id>", "Follow-up approval id")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--owner <name>", "Human owner approving the Follow-up")
+        .option("--dry-run", "Validate baseline and show the transaction plan without writes")
+        .option("--json", "Emit JSON instead of the human summary")
+        .description("Approve a Follow-up and atomically add its TaskSpec to the Feature")
+        .action(async (options) => {
+        try {
+            const result = await approveFollowUp({
+                repoRoot: path.resolve(options.repo),
+                featureDir: path.resolve(options.featureDir),
+                followUpId: options.followupId,
+                owner: options.owner,
+                dryRun: options.dryRun ?? false,
+            });
+            process.stdout.write(options.json
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : `Follow-up: ${result.followUpId}\n结果: ${result.status === "planned" ? "批准事务预览通过" : result.idempotent ? "已批准（幂等复用）" : "已批准并进入 Ready"}\n下一步: agent-worker feature review --feature-dir ${JSON.stringify(path.resolve(options.featureDir))} --repo ${JSON.stringify(path.resolve(options.repo))}\n证据: ${result.approvalPath}\n`);
+        }
+        catch (error) {
+            handleFollowUpCliError(error, options.json ?? false, "approve-followup");
+        }
+    });
     batch
         .command("run-ready")
         .requiredOption("--feature-dir <dir>", "Feature directory containing tasks/task-graph.yaml")
@@ -85,13 +279,17 @@ export function buildAgentWorkerProgram() {
         .option("--check-repo-command <command...>", "Override the check-repo preflight command")
         .option("--quiet", "Suppress human-readable progress on stderr (JSON still goes to stdout)")
         .option("--pi-model <model>", "Smoke override: force every pi executor node to this model (drops --strict-models)")
+        .option("--expected-controller-version <version>", "Exact expected controller version (fail before writes if mismatched)")
+        .option("--expected-controller-fingerprint <value>", "Exact expected controller fingerprint sha256:<hex> (fail before writes if mismatched)")
         .description("Run ready TaskSpec tasks serially")
         .action(async (options) => {
         const repoRoot = path.resolve(options.repo);
         const batchRunId = options.batchRunId ?? buildBatchRunId(new Date());
+        const expectedIdentity = buildIdentityExpectation(options);
         const client = new LoopAgentClient({
             loopAgentBin: options.loopAgentBin,
             artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", batchRunId),
+            resolveIdentity: true,
         });
         let progress;
         try {
@@ -117,6 +315,8 @@ export function buildAgentWorkerProgram() {
                 : {}),
             progress,
             ...(options.piModel ? { piModel: options.piModel } : {}),
+            controllerIdentity: client.getIdentity(),
+            controllerExpectation: expectedIdentity,
         });
         process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
         if (result.status !== "completed")
@@ -169,14 +369,57 @@ export function buildAgentWorkerProgram() {
         });
         process.stdout.write(`${JSON.stringify({ ok: true, outputPath }, null, 2)}\n`);
     });
+    report
+        .command("metrics")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--month <yyyy-mm>", "UTC reporting month")
+        .option("--json", "Emit the metrics JSON on stdout")
+        .description("Project monthly Feature delivery metrics to JSON and Markdown")
+        .action(async (options) => {
+        const result = await projectMonthlyMetrics({ repoRoot: path.resolve(options.repo), month: options.month });
+        process.stdout.write(options.json ? `${JSON.stringify(result.metrics, null, 2)}\n` : `${JSON.stringify({ ok: true, jsonPath: result.jsonPath, markdownPath: result.markdownPath }, null, 2)}\n`);
+    });
     return program;
 }
+export function buildIdentityExpectation(options) {
+    if (options.expectedControllerVersion || options.expectedControllerFingerprint) {
+        const expectation = {};
+        if (options.expectedControllerVersion)
+            expectation.expectedVersion = options.expectedControllerVersion;
+        if (options.expectedControllerFingerprint)
+            expectation.expectedFingerprint = options.expectedControllerFingerprint;
+        return expectation;
+    }
+    return undefined;
+}
 export async function main(argv = process.argv) {
     await buildAgentWorkerProgram().parseAsync(argv);
 }
 async function readTaskYaml(taskSpecPath) {
     return YAML.parse(await readFile(taskSpecPath, "utf-8"));
 }
+function handleFollowUpCliError(error, json, action) {
+    const detail = error instanceof Error ? error.message : String(error);
+    if (!json)
+        throw error;
+    const code = detail.includes("only supports ProductBug")
+        ? "unsupported-failure-category"
+        : detail.includes("baseline changed")
+            ? "stale-feature-baseline"
+            : detail.includes("already exists") || detail.includes("collision")
+                ? "follow-up-conflict"
+                : detail.includes("evidence") || detail.includes("draft hash")
+                    ? "follow-up-evidence-invalid"
+                    : "follow-up-failed";
+    process.stdout.write(`${JSON.stringify({
+        schemaVersion: 1,
+        status: "failed",
+        action,
+        error: { code, message: detail },
+        nextAction: action === "draft-followup" ? "Inspect the failed Worker run and failure category." : "Regenerate and review the Follow-up draft before approving.",
+    }, null, 2)}\n`);
+    process.exitCode = 1;
+}
 function isDirectRun() {
     const entry = process.argv[1];
     if (!entry)