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

package/dist/worker/cli.js

@@ -0,0 +1,957 @@
+#!/usr/bin/env node
+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";
+import { writeMorningReport } from "./report/morning-report.js";
+import { buildBatchRunId, runReadyTasks } from "./runner/run-ready.js";
+import { createProgressReporter } from "./progress-reporter.js";
+import { createCompositeProgressReporter } from "./observability/progress-composite.js";
+import { createRoutedWorkerEventStore } from "./observability/event-store.js";
+import { buildGlobalSnapshot } from "./observability/read-model.js";
+import { diagnoseTaskPoolStates, formatDoctorHuman, loadOperatorMapping, } from "./pool/doctor.js";
+import { migrateTaskPoolStates } from "./pool/migrate-state.js";
+import { markTaskPoolFailed, reconcileTaskPoolAbandon, } from "./pool/reconcile.js";
+import { getTaskPoolRoot, prepareTaskPoolRetry, readFeatureTaskPoolStates, } from "./pool/run-store.js";
+import { TaskPoolStateError } from "./pool/types.js";
+import { taskSpecSchema } from "./task-spec/schema.js";
+import { validateTaskSpec } from "./task-spec/validate.js";
+import { validateFeatureTaskGraph } from "./task-graph/validate.js";
+import { taskGraphSpecSchema } from "./task-graph/task-graph-schema.js";
+import { planReadyTasks } from "./task-graph/ready-planner.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 { advanceFeature, renderFeatureAdvance } from "./feature/advance.js";
+import { diagnoseFeature, renderFeatureDoctor } from "./feature/doctor.js";
+import { FEATURE_SCAFFOLD_TEMPLATES, ScaffoldError, scaffoldFeaturePacket, } from "./feature/scaffold.js";
+import { projectMonthlyMetrics } from "./metrics/projector.js";
+import { defaultFeatureEvidencePaths, runFeatureFinalVerification, } from "./delivery/final-verification.js";
+import { advanceGitCheckpoint } from "./delivery/git-transaction.js";
+import { registerSchedulerCommands } from "./scheduler/cli.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()
+        .enablePositionalOptions();
+    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 consoleCmd = program
+        .command("console")
+        .description("Loop Operator Console (local)");
+    const feature = program
+        .command("feature")
+        .description("Feature-level review and delivery workflow");
+    const pool = program
+        .command("pool")
+        .description("Task Pool state doctor and migration utilities");
+    registerSchedulerCommands(program);
+    pool
+        .command("mark-failed")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--feature-id <feature-id>", "Canonical Feature id")
+        .requiredOption("--task-id <task-id>", "Task id")
+        .requiredOption("--worker-run-id <id>", "Worker run id to mark failed")
+        .requiredOption("--reason <reason>", "Why the emergency projection is justified")
+        .description("Audit-only emergency Task Pool Failed projection (does not mutate DAG lifecycle)")
+        .action(async (options) => {
+        try {
+            const result = await markTaskPoolFailed({
+                repoRoot: path.resolve(options.repo),
+                featureId: options.featureId,
+                taskId: options.taskId,
+                workerRunId: options.workerRunId,
+                reason: options.reason,
+            });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        catch (error) {
+            handlePoolRecoveryCliError(error);
+        }
+    });
+    pool
+        .command("doctor")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit stable JSON instead of the human summary")
+        .option("--mapping <file>", "Optional operator mapping JSON (taskId -> featureId)")
+        .description("Inventory legacy and v2 Task Pool states (read-only)")
+        .action(async (options) => {
+        const repoRoot = path.resolve(options.repo);
+        const mapping = await loadOperatorMapping(options.mapping);
+        const report = await diagnoseTaskPoolStates(repoRoot, { mapping });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(report, null, 2)}\n`
+            : formatDoctorHuman(report));
+    });
+    pool
+        .command("migrate-state")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--dry-run", "Plan migration without writes (default when --apply is omitted)")
+        .option("--apply", "Apply migration (requires --owner and --reason)")
+        .option("--owner <owner>", "Migration owner for apply")
+        .option("--reason <reason>", "Why migration is being applied")
+        .option("--mapping <file>", "Optional operator mapping JSON (taskId -> featureId)")
+        .option("--json", "Emit stable JSON")
+        .description("Migrate legacy flat Task Pool states to feature-scoped v2 (default dry-run)")
+        .action(async (options) => {
+        try {
+            const result = await migrateTaskPoolStates({
+                repoRoot: path.resolve(options.repo),
+                apply: options.apply === true,
+                ...(options.owner ? { owner: options.owner } : {}),
+                ...(options.reason ? { reason: options.reason } : {}),
+                ...(options.mapping ? { mappingPath: options.mapping } : {}),
+            });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            if (result.status === "failed")
+                process.exitCode = 1;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const code = error instanceof TaskPoolStateError
+                ? error.code
+                : "task-pool-migrate-failed";
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify({
+                    schemaVersion: 1,
+                    status: "failed",
+                    error: { code, message: detail },
+                }, null, 2)}\n`);
+            }
+            else {
+                process.stderr.write(`${detail}\n`);
+            }
+            process.exitCode = 1;
+        }
+    });
+    const featureGit = feature
+        .command("git")
+        .description("Feature Git transaction utilities");
+    featureGit
+        .command("advance-checkpoint")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--feature-id <feature-id>", "Canonical Feature id")
+        .requiredOption("--reason <reason>", "Why the manual revision is safe to record")
+        .description("Advance Git transaction lastCheckpoint to current HEAD on a clean owned branch")
+        .action(async (options) => {
+        try {
+            const result = await advanceGitCheckpoint({
+                repoRoot: path.resolve(options.repo),
+                featureId: options.featureId,
+                reason: options.reason,
+            });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        catch (error) {
+            handlePoolRecoveryCliError(error);
+        }
+    });
+    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("advance")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--task-id <id>", "Final verification TaskSpec id (default: resolve FINAL-VERIFY* from Feature review)")
+        .option("--loop-agent-bin <bin>", "loop-agent binary", "loop-agent")
+        .option("--evidence-mode <mode>", "Evidence aggregate for verify-final: auto, qa-execute, or typed", "auto")
+        .option("--qa-evidence <path>", "Override QA pass evidence path")
+        .option("--final-verification <path>", "Override final verification evidence path")
+        .option("--waivers <path>", "Repo-local acceptance waiver decisions JSON")
+        .option("--dry-run", "Run verify-final + delivery dry-run + closeout preview without Delivery writes or closeout apply")
+        .option("--apply", "After ready closeout preview, apply Feature Closeout (requires --owner)")
+        .option("--owner <owner>", "Closeout owner when using --apply")
+        .option("--expected-controller-version <version>", "Exact expected controller version")
+        .option("--expected-controller-fingerprint <value>", "Exact expected controller fingerprint sha256:<hex>")
+        .option("--json", "Emit stable JSON")
+        .description("Orchestrate ADR 0007 delivery path: verify-final → delivery → closeout preview[/apply]")
+        .action(async (options) => {
+        if (options.evidenceMode !== "auto" &&
+            options.evidenceMode !== "qa-execute" &&
+            options.evidenceMode !== "typed") {
+            throw new Error("feature advance --evidence-mode must be auto, qa-execute, or typed");
+        }
+        const repoRoot = path.resolve(options.repo);
+        const client = new LoopAgentClient({
+            loopAgentBin: options.loopAgentBin,
+            artifactRoot: path.join(getTaskPoolRoot(repoRoot), "artifacts", `feature-advance-${Date.now()}`),
+            resolveIdentity: true,
+        });
+        const result = await advanceFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot,
+            ...(options.taskId ? { taskId: options.taskId } : {}),
+            client,
+            controllerIdentity: client.getIdentity(),
+            controllerExpectation: buildIdentityExpectation(options),
+            evidenceMode: options.evidenceMode,
+            ...(options.qaEvidence ? { qaEvidencePath: options.qaEvidence } : {}),
+            ...(options.finalVerification
+                ? { finalVerificationPath: options.finalVerification }
+                : {}),
+            ...(options.waivers ? { waiverPath: options.waivers } : {}),
+            dryRun: options.dryRun ?? false,
+            apply: options.apply ?? false,
+            ...(options.owner ? { owner: options.owner } : {}),
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : renderFeatureAdvance(result));
+        if (result.status === "failed" || result.status === "blocked") {
+            process.exitCode = 1;
+        }
+    });
+    feature
+        .command("doctor")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit stable JSON")
+        .description("Read-only Feature delivery readiness diagnosis (evidence, pool states, dirty worktree)")
+        .action(async (options) => {
+        const result = await diagnoseFeature({
+            featureDir: path.resolve(options.featureDir),
+            repoRoot: path.resolve(options.repo),
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : renderFeatureDoctor(result));
+        if (result.status === "blocked")
+            process.exitCode = 1;
+    });
+    feature
+        .command("scaffold")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--template <id>", `Locked template: ${FEATURE_SCAFFOLD_TEMPLATES.join(" | ")}`)
+        .option("--feature-id <id>", "Feature id (F-YYYY-NNN)")
+        .option("--title <text>", "Human title")
+        .option("--description <text>", "Optional longer description")
+        .option("--be-path <pattern>", "Repo-relative backend allowed path (repeatable)", (value, previous) => [...previous, value], [])
+        .option("--fe-path <pattern>", "Repo-relative frontend allowed path (repeatable)", (value, previous) => [...previous, value], [])
+        .option("--contract-path <path>", "fe-with-api contract path (default docs/contracts/<feature-id>/api.md)")
+        .option("--verify-command <command>", "Explicit verify command for implementation tasks (repeatable)", (value, previous) => [...previous, value], [])
+        .option("--batch <file>", "YAML/JSON batch list (mutually exclusive with single-feature flags)")
+        .option("--dry-run", "Parse/render/validate without writing features/")
+        .option("--json", "Emit stable JSON only")
+        .description("Deterministically scaffold a Feature Packet (no model, no Task Pool, no fullstack-v1 default)")
+        .action(async (options) => {
+        try {
+            const result = options.batch
+                ? await scaffoldFeaturePacket({
+                    repoRoot: path.resolve(options.repo),
+                    batchFile: path.resolve(options.batch),
+                    dryRun: options.dryRun ?? false,
+                })
+                : await scaffoldFeaturePacket({
+                    repoRoot: path.resolve(options.repo),
+                    dryRun: options.dryRun ?? false,
+                    feature: {
+                        featureId: options.featureId ?? "",
+                        title: options.title ?? "",
+                        template: (options.template ?? ""),
+                        description: options.description,
+                        bePaths: options.bePath,
+                        fePaths: options.fePath,
+                        contractPath: options.contractPath,
+                        verifyCommands: options.verifyCommand,
+                    },
+                });
+            process.stdout.write(options.json
+                ? `${JSON.stringify(result, null, 2)}\n`
+                : renderFeatureScaffold(result));
+        }
+        catch (error) {
+            handleScaffoldCliError(error, options.json ?? false);
+        }
+    });
+    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 final verification TaskSpec; typed backend/frontend outcomes are aggregated when present")
+        .option("--loop-agent-bin <bin>", "loop-agent binary", "loop-agent")
+        .option("--json", "Emit stable JSON")
+        .option("--evidence-mode <mode>", "Evidence aggregate: auto, qa-execute, or typed", "auto")
+        .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) => {
+        if (options.evidenceMode !== "auto" &&
+            options.evidenceMode !== "qa-execute" &&
+            options.evidenceMode !== "typed")
+            throw new Error("feature verify-final --evidence-mode must be auto, qa-execute, or typed");
+        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),
+            evidenceMode: options.evidenceMode,
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : `Feature: ${result.featureId}\nFinal verification: ${result.workerRunId}\nEvidence mode: ${result.evidenceMode ?? "qa-execute"}\nQA evidence: ${result.qaEvidencePath}\nFinal evidence: ${result.finalVerificationPath}${result.bundleEvidencePath ? `\nVerification bundle: ${result.bundleEvidencePath}` : ""}\n`);
+    });
+    feature
+        .command("delivery")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--qa-evidence <path>", "Repo-local QA pass evidence (default: .harness/task-pool/evidence/<featureId>/qa-pass.json from verify-final)")
+        .option("--final-verification <path>", "Repo-local final verification evidence (default: .../final-verification.json from verify-final)")
+        .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 featureDir = path.resolve(options.featureDir);
+        const repoRoot = path.resolve(options.repo);
+        // ADR 0007: default to verify-final evidence locations when omitted.
+        let qaEvidencePath = options.qaEvidence;
+        let finalVerificationPath = options.finalVerification;
+        if (!qaEvidencePath || !finalVerificationPath) {
+            const validation = await validateFeatureTaskGraph(featureDir);
+            const defaults = defaultFeatureEvidencePaths(validation.featureId);
+            qaEvidencePath = qaEvidencePath ?? defaults.qaEvidencePath;
+            finalVerificationPath =
+                finalVerificationPath ?? defaults.finalVerificationPath;
+        }
+        const result = await prepareFeatureDelivery({
+            featureDir,
+            repoRoot,
+            qaEvidencePath,
+            finalVerificationPath,
+            ...(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")
+        .description("Validate a TaskSpec and print JSON")
+        .action(async (taskYaml) => {
+        const taskSpecPath = path.resolve(taskYaml);
+        const raw = await readTaskYaml(taskSpecPath);
+        const result = await validateTaskSpec(raw, { taskSpecPath });
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (!result.ok)
+            process.exitCode = 1;
+    });
+    task
+        .command("explain-profile")
+        .argument("<task-yaml>", "TaskSpec YAML file")
+        .description("Explain business profile to loop-agent profile mapping")
+        .action(async (taskYaml) => {
+        const raw = await readTaskYaml(path.resolve(taskYaml));
+        const parsed = taskSpecSchema.parse(raw);
+        const result = resolveLoopAgentProfile(parsed);
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    });
+    task
+        .command("validate-feature")
+        .argument("<feature-dir>", "Feature directory containing acceptance.yaml and tasks/")
+        .description("Validate acceptance ids, task graph, TaskSpecs, paths, and verification commands")
+        .action(async (featureDir) => {
+        const result = await validateFeatureTaskGraph(path.resolve(featureDir));
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (!result.ok)
+            process.exitCode = 1;
+    });
+    task
+        .command("reconcile")
+        .argument("<task-id>", "Task Pool task to reconcile after DAG abandon")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .requiredOption("--feature-id <feature-id>", "Canonical Feature id")
+        .requiredOption("--worker-run-id <id>", "Worker run id bound to the DAG run")
+        .requiredOption("--dag-run-id <id>", "DAG run id to abandon")
+        .requiredOption("--action <action>", "Recovery action (only abandon is supported)")
+        .requiredOption("--reason <reason>", "Why the run is being abandoned")
+        .option("--force-abandon-recoverable", "Override refuse when DAG liveness/canResume indicates recoverable work (document operator intent in --reason)")
+        .description("Worker-aware abandon: DAG reconcile-run + Task Pool Failed projection")
+        .action(async (taskId, options) => {
+        if (options.action !== "abandon") {
+            throw new Error("task reconcile --action must be abandon");
+        }
+        try {
+            const result = await reconcileTaskPoolAbandon({
+                repoRoot: path.resolve(options.repo),
+                taskId,
+                featureId: options.featureId,
+                workerRunId: options.workerRunId,
+                dagRunId: options.dagRunId,
+                reason: options.reason,
+                forceAbandonRecoverable: options.forceAbandonRecoverable === true,
+            });
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        catch (error) {
+            handlePoolRecoveryCliError(error);
+        }
+    });
+    task
+        .command("retry")
+        .argument("<task-id>", "Failed Task Pool task to requeue")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--feature-id <feature-id>", "Canonical Feature id for the Task Pool state (required when identity is ambiguous)")
+        .option("--reason <reason>", "Why the failure is safe to retry")
+        .description("Explicitly requeue a failed task; the next run-ready uses a new workerRunId")
+        .action(async (taskId, options) => {
+        const result = await prepareTaskPoolRetry({
+            repoRoot: path.resolve(options.repo),
+            taskId,
+            ...(options.featureId ? { featureId: options.featureId } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        });
+        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("plan-ready")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing tasks/task-graph.yaml")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--limit <count>", "Maximum ready tasks to select")
+        .option("--json", "Emit stable JSON (default human summary)")
+        .description("Preview the read-only priority-aware ready plan without writing state or artifacts")
+        .action(async (options) => {
+        // Strict zero-write preview: load graph + specs + feature-scoped states only.
+        const featureDir = path.resolve(options.featureDir);
+        const repoRoot = path.resolve(options.repo);
+        const graph = taskGraphSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", "task-graph.yaml"), "utf-8")));
+        const taskSpecs = new Map();
+        for (const node of graph.nodes) {
+            const taskFile = node.task ?? `${node.id}.yaml`;
+            taskSpecs.set(node.id, taskSpecSchema.parse(YAML.parse(await readFile(path.join(featureDir, "tasks", taskFile), "utf-8"))));
+        }
+        const selectionLimit = options.limit
+            ? Number.parseInt(options.limit, 10)
+            : graph.nodes.length;
+        if (!Number.isInteger(selectionLimit) || selectionLimit < 1) {
+            process.stderr.write("selectionLimit must be a positive integer\n");
+            process.exitCode = 1;
+            return;
+        }
+        const plan = planReadyTasks({
+            featureId: graph.feature_id,
+            graph,
+            taskSpecs,
+            states: await readFeatureTaskPoolStates(repoRoot, graph.feature_id),
+            selectionLimit,
+        });
+        process.stdout.write(options.json
+            ? `${JSON.stringify(plan, null, 2)}\n`
+            : `Selected: ${plan.selected.map((task) => task.taskId).join(", ") || "none"}\nDeferred: ${plan.deferred.map((task) => task.taskId).join(", ") || "none"}\nBlocked: ${plan.blocked.length}\n`);
+    });
+    batch
+        .command("run-ready")
+        .requiredOption("--feature-dir <dir>", "Feature directory containing tasks/task-graph.yaml")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--limit <count>", "Maximum ready tasks to run")
+        .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 (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 {
+            const eventStore = createRoutedWorkerEventStore(repoRoot);
+            progress = createCompositeProgressReporter({
+                quiet: options.quiet ?? false,
+                eventStore,
+                context: { batchRunId },
+            });
+        }
+        catch {
+            progress = createProgressReporter({ quiet: options.quiet ?? false });
+        }
+        const result = await runReadyTasks({
+            repoRoot,
+            featureDir: path.resolve(options.featureDir),
+            ...(options.limit
+                ? { limit: Number.parseInt(options.limit, 10) }
+                : {}),
+            batchRunId,
+            client,
+            runCheckRepo: options.checkRepo ?? false,
+            ...(options.checkRepoCommand
+                ? { checkRepoCommand: options.checkRepoCommand }
+                : {}),
+            progress,
+            ...(options.piModel ? { piModel: options.piModel } : {}),
+            controllerIdentity: client.getIdentity(),
+            controllerExpectation: expectedIdentity,
+        });
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (result.status !== "completed")
+            process.exitCode = 1;
+    });
+    observe
+        .command("serve")
+        .option("--repo <repo-root>", "Target repo root (ignored; command removed)")
+        .option("--port <port>", "HTTP port (ignored; command removed)", "8787")
+        .option("--host <host>", "Bind host (ignored; command removed)", "127.0.0.1")
+        .option("--debug", "Ignored; command removed")
+        .description("Removed: independent observe HTTP server (use agent-worker console + /inspect/)")
+        .action(() => {
+        process.stderr.write("[OBSERVE_SERVE_REMOVED] agent-worker observe serve 已下线。\n" +
+            "请改用：agent-worker console --repo <repo> --port 8790\n" +
+            "只读检视：http://127.0.0.1:8790/inspect/\n");
+        process.exitCode = 2;
+    });
+    observe
+        .command("snapshot")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit JSON (default)")
+        .description("Print GlobalSnapshot JSON to stdout")
+        .action(async (options) => {
+        const snapshot = await buildGlobalSnapshot({
+            repoRoot: path.resolve(options.repo),
+        });
+        process.stdout.write(`${JSON.stringify(snapshot)}\n`);
+    });
+    consoleCmd
+        .description("Loop Operator Console (local); bare `agent-worker console` starts it directly (repo defaults to current working directory, port defaults to 8790). Opens the system browser after listen unless --no-open or a non-graphical environment.")
+        .option("--repo <repo-root>", "Target repo root (default: current working directory)", process.cwd())
+        .option("--port <port>", "HTTP port", "8790")
+        .option("--host <host>", "Bind host (default 127.0.0.1; use 0.0.0.0 for LAN, no network auth)", "127.0.0.1")
+        .option("--debug", "Log request source/method/path/status to stderr")
+        .option("--app-data <path>", "Override Console application-data root (Draft/Operation/confirmation)")
+        .option("--default-timeout-ms <ms>", "LoopAgentClient hard timeout for Console operations (ms; default 14400000 / 4h; 0 disables)")
+        .option("--no-open", "Do not open the system browser after the Console listens")
+        .action(async (options, command) => {
+        // Reject unknown tokens such as legacy `console serve` instead of starting HTTP.
+        const extras = command.args.filter((arg) => arg.length > 0);
+        if (extras.length > 0) {
+            process.stderr.write(`error: unknown command '${extras[0]}' for agent-worker console\n`);
+            process.exitCode = 1;
+            return;
+        }
+        await runConsoleServe({
+            repoRoot: path.resolve(options.repo),
+            host: options.host,
+            port: Number.parseInt(options.port, 10),
+            debug: options.debug === true,
+            appDataRoot: options.appData
+                ? path.resolve(options.appData)
+                : undefined,
+            defaultTimeoutMsRaw: options.defaultTimeoutMs,
+            // Commander maps --no-open to open:false; default remains open:true.
+            noOpen: options.open === false,
+        });
+    });
+    consoleCmd
+        .command("doctor")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--json", "Emit JSON report on stdout")
+        .option("--observe-url <url>", "Legacy external Observe base URL to probe (non-blocking)")
+        .option("--console-url <url>", "Unified Console base URL to probe")
+        .description("Report sibling identity, preflight, and unified Inspect readiness")
+        .action(async (options) => {
+        const { formatConsoleDoctorHuman, runConsoleDoctor } = await import("./console/doctor.js");
+        const report = await runConsoleDoctor({
+            repoRoot: path.resolve(options.repo),
+            observeBaseUrl: options.observeUrl,
+            consoleBaseUrl: options.consoleUrl,
+        });
+        if (options.json) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(formatConsoleDoctorHuman(report));
+        }
+    });
+    report
+        .command("morning")
+        .requiredOption("--repo <repo-root>", "Target repo root")
+        .option("--batch-run-id <id>", "Filter to one batch run id")
+        .option("--window <window>", "Report window: all (Task Pool classic) or night (Night Scheduler)", "all")
+        .option("--date <yyyy-mm-dd>", "Local calendar date for --window night (default today)")
+        .option("--tz <timezone>", "IANA timezone for --window night", "Asia/Shanghai")
+        .option("--output <path>", "Write markdown report to this path")
+        .description("Render a markdown morning report from Task Pool runs")
+        .action(async (options) => {
+        const repoRoot = path.resolve(options.repo);
+        if (options.window !== "all" && options.window !== "night") {
+            throw new Error(`--window must be all or night, got ${options.window ?? ""}`);
+        }
+        const window = options.window;
+        const outputPath = options.output ??
+            path.join(getTaskPoolRoot(repoRoot), "reports", window === "night"
+                ? `morning-night-${options.date ?? "latest"}.md`
+                : "morning-report.md");
+        await writeMorningReport({
+            repoRoot,
+            ...(options.batchRunId ? { batchRunId: options.batchRunId } : {}),
+            window,
+            ...(options.date ? { date: options.date } : {}),
+            ...(options.tz ? { timezone: options.tz } : {}),
+            outputPath: path.resolve(outputPath),
+        });
+        process.stdout.write(`${JSON.stringify({ ok: true, outputPath, window }, 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"));
+}
+/** Parse optional `--default-timeout-ms`; undefined keeps Console default. */
+function parseOptionalTimeoutMs(raw) {
+    if (raw === undefined || raw.trim() === "") {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0 || !Number.isInteger(value)) {
+        throw new Error(`--default-timeout-ms must be a non-negative integer (ms); got ${JSON.stringify(raw)}`);
+    }
+    return value;
+}
+/** Console HTTP entry for bare `agent-worker console` (listen first, then optional browser open). */
+async function runConsoleServe(options) {
+    const { createConsoleServer } = await import("./console/server.js");
+    const { maybeOpenConsoleBrowser } = await import("./console/open-browser.js");
+    try {
+        const server = await createConsoleServer({
+            repoRoot: options.repoRoot,
+            host: options.host,
+            port: options.port,
+            debug: options.debug === true,
+            appDataRoot: options.appDataRoot,
+            defaultTimeoutMs: parseOptionalTimeoutMs(options.defaultTimeoutMsRaw),
+        });
+        // Keep stdout bind URL contract (may include 0.0.0.0 / ::); browser URL is normalized separately.
+        process.stdout.write(`${server.url}
+`);
+        await maybeOpenConsoleBrowser({
+            noOpen: options.noOpen === true,
+            serverUrl: server.url,
+        });
+        await new Promise((resolve) => {
+            const shutdown = () => resolve();
+            process.once("SIGINT", shutdown);
+            process.once("SIGTERM", shutdown);
+        });
+        await server.close();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const code = error?.code;
+        const isPortInUse = code === "EADDRINUSE" ||
+            /listen EADDRINUSE/i.test(detail) ||
+            /address already in use/i.test(detail);
+        if (isPortInUse) {
+            process.stderr.write(`端口 ${options.port} 已被占用，请使用 --port <port> 指定其它端口后重试。\n`);
+            process.exit(1);
+        }
+        process.stderr.write(`${detail}\n`);
+        process.exit(1);
+    }
+}
+function handlePoolRecoveryCliError(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${detail}\n`);
+    process.exitCode = 1;
+}
+function handleScaffoldCliError(error, json) {
+    const code = error instanceof ScaffoldError ? error.code : "write-failed";
+    const message = error instanceof Error ? error.message : String(error);
+    const details = error instanceof ScaffoldError ? error.details : undefined;
+    if (json) {
+        process.stdout.write(`${JSON.stringify({
+            schemaVersion: 1,
+            ok: false,
+            code,
+            message,
+            ...(details !== undefined ? { details } : {}),
+        }, null, 2)}\n`);
+    }
+    else {
+        process.stderr.write(`${message}\n`);
+    }
+    process.exitCode = 1;
+}
+function renderFeatureScaffold(result) {
+    const lines = [
+        result.dryRun
+            ? `Feature scaffold dry-run: ${result.features.length} packet(s) validated`
+            : `Feature scaffold wrote ${result.features.length} packet(s)`,
+        "",
+    ];
+    for (const feature of result.features) {
+        lines.push(`- ${feature.featureId} [${feature.template}] → ${feature.featureDir}`);
+    }
+    if (!result.dryRun && result.writtenPaths.length > 0) {
+        lines.push("", "Written:");
+        for (const p of result.writtenPaths)
+            lines.push(`  ${p}`);
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
+}
+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)
+        return false;
+    return path.resolve(entry) === fileURLToPath(import.meta.url);
+}
+if (isDirectRun()) {
+    main().catch((error) => {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    });
+}