@tea-agent/loop-agent 0.16.1-beta.2 → 0.16.1

package/dist/infrastructure/evaluation/experiment-store.js

@@ -0,0 +1,124 @@
+import { access, mkdir, mkdtemp, readdir, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { experimentIdSchema, experimentRecordSchema, } from "../../application/evaluation/types.js";
+import { sha256Hex } from "../../application/evaluation/candidate-hash.js";
+import { writeJsonAtomic, writeTextAtomic } from "../harness/atomic-write.js";
+import { EVALUATION_ROOT } from "./store.js";
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MANIFEST_INTEGRITY_FILE = "manifest.sha256";
+export function assertExperimentId(value) {
+    experimentIdSchema.parse(value);
+}
+export function experimentDir(repoRoot, experimentId) {
+    assertExperimentId(experimentId);
+    return path.join(repoRoot, EVALUATION_ROOT, "experiments", experimentId);
+}
+export function experimentManifestPath(repoRoot, experimentId) {
+    return path.join(experimentDir(repoRoot, experimentId), "manifest.json");
+}
+/** Repo-relative content path for experimental learned proposal (allowed as contentRef). */
+export function experimentProposalRepoPath(experimentId) {
+    assertExperimentId(experimentId);
+    return path.posix.join("ai_workspace/loop-agent/evaluation/experiments", experimentId, "learned-proposal.md");
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function serializeRecord(record) {
+    return `${JSON.stringify(record, null, 2)}\n`;
+}
+function recordsEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+export async function readExperimentRecord(repoRoot, experimentId) {
+    assertExperimentId(experimentId);
+    const manifestPath = experimentManifestPath(repoRoot, experimentId);
+    const rawText = await readFile(manifestPath, "utf-8");
+    const expected = (await readFile(path.join(experimentDir(repoRoot, experimentId), MANIFEST_INTEGRITY_FILE), "utf-8")).trim();
+    const actual = sha256Hex(rawText);
+    if (expected !== actual) {
+        throw new Error(`experiment manifest integrity mismatch for ${experimentId}`);
+    }
+    const stored = experimentRecordSchema.parse(JSON.parse(rawText));
+    if (stored.experimentId !== experimentId) {
+        throw new Error(`experiment identity mismatch: directory=${experimentId}, manifest=${stored.experimentId}`);
+    }
+    return stored;
+}
+export async function listExperimentIds(repoRoot) {
+    const root = path.join(repoRoot, EVALUATION_ROOT, "experiments");
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && SAFE_ID.test(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+export async function writeExperimentRecord(input) {
+    const { repoRoot, record } = input;
+    assertExperimentId(record.experimentId);
+    const parsed = experimentRecordSchema.parse(record);
+    const manifestPath = experimentManifestPath(repoRoot, parsed.experimentId);
+    if (await pathExists(manifestPath)) {
+        const existing = await readExperimentRecord(repoRoot, parsed.experimentId);
+        if (!recordsEqual(existing, parsed)) {
+            throw new Error(`experiment already exists with different content: ${parsed.experimentId}`);
+        }
+        return { record: existing, idempotent: true, manifestPath };
+    }
+    const root = path.dirname(experimentDir(repoRoot, parsed.experimentId));
+    await mkdir(root, { recursive: true });
+    const stagingDir = await mkdtemp(path.join(root, `.${parsed.experimentId}.register-`));
+    try {
+        await writeJsonAtomic(path.join(stagingDir, "manifest.json"), parsed, {
+            repoRoot,
+        });
+        await writeTextAtomic(path.join(stagingDir, MANIFEST_INTEGRITY_FILE), `${sha256Hex(serializeRecord(parsed))}\n`, { repoRoot });
+        try {
+            await rename(stagingDir, experimentDir(repoRoot, parsed.experimentId));
+        }
+        catch (error) {
+            const code = error.code;
+            const isCreateRace = code === "EEXIST" ||
+                code === "ENOTEMPTY" ||
+                (code === "EPERM" &&
+                    (await pathExists(experimentDir(repoRoot, parsed.experimentId))));
+            if (!isCreateRace)
+                throw error;
+            await rm(stagingDir, { recursive: true, force: true });
+            const existing = await readExperimentRecord(repoRoot, parsed.experimentId);
+            if (!recordsEqual(existing, parsed)) {
+                throw new Error(`experiment already exists with different content: ${parsed.experimentId}`);
+            }
+            return { record: existing, idempotent: true, manifestPath };
+        }
+    }
+    catch (error) {
+        await rm(stagingDir, { recursive: true, force: true });
+        throw error;
+    }
+    return { record: parsed, idempotent: false, manifestPath };
+}
+export async function updateExperimentRecord(input) {
+    const parsed = experimentRecordSchema.parse(input.record);
+    const manifestPath = experimentManifestPath(input.repoRoot, parsed.experimentId);
+    if (!(await pathExists(manifestPath))) {
+        throw new Error(`experiment not found: ${parsed.experimentId}`);
+    }
+    await writeJsonAtomic(manifestPath, parsed, { repoRoot: input.repoRoot });
+    await writeTextAtomic(path.join(experimentDir(input.repoRoot, parsed.experimentId), MANIFEST_INTEGRITY_FILE), `${sha256Hex(serializeRecord(parsed))}\n`, { repoRoot: input.repoRoot });
+    return manifestPath;
+}

package/dist/infrastructure/evaluation/ignition-store.js

@@ -0,0 +1,82 @@
+import { access, mkdir, mkdtemp, readdir, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { ignitionIdSchema, ignitionReportSchema, } from "../../application/evaluation/types.js";
+import { sha256Hex } from "../../application/evaluation/candidate-hash.js";
+import { writeJsonAtomic, writeTextAtomic } from "../harness/atomic-write.js";
+import { EVALUATION_ROOT } from "./store.js";
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MANIFEST_INTEGRITY_FILE = "manifest.sha256";
+export function assertIgnitionId(value) {
+    ignitionIdSchema.parse(value);
+}
+export function ignitionDir(repoRoot, ignitionId) {
+    assertIgnitionId(ignitionId);
+    return path.join(repoRoot, EVALUATION_ROOT, "ignition", ignitionId);
+}
+export function ignitionReportPath(repoRoot, ignitionId) {
+    return path.join(ignitionDir(repoRoot, ignitionId), "report.json");
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function serialize(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}
+export async function readIgnitionReport(repoRoot, ignitionId) {
+    assertIgnitionId(ignitionId);
+    const reportPath = ignitionReportPath(repoRoot, ignitionId);
+    if (!(await pathExists(reportPath)))
+        return undefined;
+    const rawText = await readFile(reportPath, "utf-8");
+    const expected = (await readFile(path.join(ignitionDir(repoRoot, ignitionId), MANIFEST_INTEGRITY_FILE), "utf-8")).trim();
+    if (sha256Hex(rawText) !== expected) {
+        throw new Error(`ignition report integrity mismatch for ${ignitionId}`);
+    }
+    return ignitionReportSchema.parse(JSON.parse(rawText));
+}
+export async function writeIgnitionReport(input) {
+    const parsed = ignitionReportSchema.parse(input.report);
+    const reportPath = ignitionReportPath(input.repoRoot, parsed.ignitionId);
+    const root = path.dirname(ignitionDir(input.repoRoot, parsed.ignitionId));
+    await mkdir(root, { recursive: true });
+    if (await pathExists(reportPath)) {
+        await writeJsonAtomic(reportPath, parsed, { repoRoot: input.repoRoot });
+        await writeTextAtomic(path.join(ignitionDir(input.repoRoot, parsed.ignitionId), MANIFEST_INTEGRITY_FILE), `${sha256Hex(serialize(parsed))}\n`, { repoRoot: input.repoRoot });
+        return reportPath;
+    }
+    const stagingDir = await mkdtemp(path.join(root, `.${parsed.ignitionId}.register-`));
+    try {
+        await writeJsonAtomic(path.join(stagingDir, "report.json"), parsed, {
+            repoRoot: input.repoRoot,
+        });
+        await writeTextAtomic(path.join(stagingDir, MANIFEST_INTEGRITY_FILE), `${sha256Hex(serialize(parsed))}\n`, { repoRoot: input.repoRoot });
+        await rename(stagingDir, ignitionDir(input.repoRoot, parsed.ignitionId));
+    }
+    catch (error) {
+        await rm(stagingDir, { recursive: true, force: true });
+        throw error;
+    }
+    return reportPath;
+}
+export async function listIgnitionIds(repoRoot) {
+    const root = path.join(repoRoot, EVALUATION_ROOT, "ignition");
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && SAFE_ID.test(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return [];
+        throw error;
+    }
+}

package/dist/infrastructure/evaluation/private-verifier-store.js

@@ -0,0 +1,145 @@
+import { access, mkdir, mkdtemp, readdir, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { assertPrivateVerifierHash, computePrivateVerifierManifestHash, } from "../../application/evaluation/campaign-hash.js";
+import { formatContentSha, normalizeContentSha, sha256Hex, } from "../../application/evaluation/candidate-hash.js";
+import { privateVerifierIdSchema, privateVerifierManifestInputSchema, privateVerifierManifestSchema, } from "../../application/evaluation/types.js";
+import { writeJsonAtomic, writeTextAtomic } from "../harness/atomic-write.js";
+import { EVALUATION_ROOT } from "./store.js";
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MANIFEST_INTEGRITY_FILE = "manifest.sha256";
+export function assertPrivateVerifierId(value) {
+    privateVerifierIdSchema.parse(value);
+}
+export function privateVerifierDir(repoRoot, privateVerifierId) {
+    assertPrivateVerifierId(privateVerifierId);
+    return path.join(repoRoot, EVALUATION_ROOT, "private-verifiers", privateVerifierId);
+}
+export function privateVerifierManifestPath(repoRoot, privateVerifierId) {
+    return path.join(privateVerifierDir(repoRoot, privateVerifierId), "manifest.json");
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function serializeManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+export async function materializePrivateVerifierManifest(raw) {
+    const input = privateVerifierManifestInputSchema.parse(raw);
+    const withoutHash = {
+        schemaVersion: 1,
+        privateVerifierId: input.privateVerifierId,
+        createdAt: input.createdAt,
+        ...(input.description !== undefined
+            ? { description: input.description }
+            : {}),
+        checks: input.checks,
+    };
+    const manifestHash = computePrivateVerifierManifestHash(withoutHash);
+    if (input.manifestHash) {
+        const provided = formatContentSha(normalizeContentSha(input.manifestHash));
+        if (provided !== manifestHash) {
+            throw new Error(`privateVerifier manifestHash mismatch: expected ${manifestHash}, got ${provided}`);
+        }
+    }
+    return privateVerifierManifestSchema.parse({
+        ...withoutHash,
+        manifestHash,
+    });
+}
+export async function loadPrivateVerifierManifestFromPath(repoRoot, manifestPath) {
+    const resolved = path.isAbsolute(manifestPath)
+        ? manifestPath
+        : path.resolve(repoRoot, manifestPath);
+    const raw = JSON.parse(await readFile(resolved, "utf-8"));
+    return privateVerifierManifestInputSchema.parse(raw);
+}
+export async function readPrivateVerifierManifest(repoRoot, privateVerifierId) {
+    assertPrivateVerifierId(privateVerifierId);
+    const manifestPath = privateVerifierManifestPath(repoRoot, privateVerifierId);
+    const rawText = await readFile(manifestPath, "utf-8");
+    const integrityPath = path.join(privateVerifierDir(repoRoot, privateVerifierId), MANIFEST_INTEGRITY_FILE);
+    const expected = (await readFile(integrityPath, "utf-8")).trim();
+    const actual = sha256Hex(rawText);
+    if (expected !== actual) {
+        throw new Error(`privateVerifier manifest integrity mismatch for ${privateVerifierId}`);
+    }
+    const stored = privateVerifierManifestSchema.parse(JSON.parse(rawText));
+    if (stored.privateVerifierId !== privateVerifierId) {
+        throw new Error(`privateVerifier identity mismatch: directory=${privateVerifierId}, manifest=${stored.privateVerifierId}`);
+    }
+    assertPrivateVerifierHash(stored);
+    return stored;
+}
+export async function listPrivateVerifierIds(repoRoot) {
+    const root = path.join(repoRoot, EVALUATION_ROOT, "private-verifiers");
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && SAFE_ID.test(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+function manifestsEqual(a, b) {
+    return (a.privateVerifierId === b.privateVerifierId &&
+        a.manifestHash === b.manifestHash &&
+        a.createdAt === b.createdAt &&
+        (a.description ?? "") === (b.description ?? "") &&
+        JSON.stringify(a.checks) === JSON.stringify(b.checks));
+}
+export async function registerPrivateVerifierManifest(input) {
+    const { repoRoot, manifest } = input;
+    assertPrivateVerifierId(manifest.privateVerifierId);
+    const manifestPath = privateVerifierManifestPath(repoRoot, manifest.privateVerifierId);
+    if (await pathExists(manifestPath)) {
+        const existing = await readPrivateVerifierManifest(repoRoot, manifest.privateVerifierId);
+        if (!manifestsEqual(existing, manifest)) {
+            throw new Error(`privateVerifier already exists with different content: ${manifest.privateVerifierId}`);
+        }
+        return { manifest: existing, idempotent: true, manifestPath };
+    }
+    const root = path.dirname(privateVerifierDir(repoRoot, manifest.privateVerifierId));
+    await mkdir(root, { recursive: true });
+    const stagingDir = await mkdtemp(path.join(root, `.${manifest.privateVerifierId}.register-`));
+    try {
+        await writeJsonAtomic(path.join(stagingDir, "manifest.json"), manifest, {
+            repoRoot,
+        });
+        await writeTextAtomic(path.join(stagingDir, MANIFEST_INTEGRITY_FILE), `${sha256Hex(serializeManifest(manifest))}\n`, { repoRoot });
+        try {
+            await rename(stagingDir, privateVerifierDir(repoRoot, manifest.privateVerifierId));
+        }
+        catch (error) {
+            const code = error.code;
+            const isCreateRace = code === "EEXIST" ||
+                code === "ENOTEMPTY" ||
+                (code === "EPERM" &&
+                    (await pathExists(privateVerifierDir(repoRoot, manifest.privateVerifierId))));
+            if (!isCreateRace)
+                throw error;
+            await rm(stagingDir, { recursive: true, force: true });
+            const existing = await readPrivateVerifierManifest(repoRoot, manifest.privateVerifierId);
+            if (!manifestsEqual(existing, manifest)) {
+                throw new Error(`privateVerifier already exists with different content: ${manifest.privateVerifierId}`);
+            }
+            return { manifest: existing, idempotent: true, manifestPath };
+        }
+    }
+    catch (error) {
+        await rm(stagingDir, { recursive: true, force: true });
+        throw error;
+    }
+    return { manifest, idempotent: false, manifestPath };
+}

package/dist/infrastructure/evaluation/proposer-store.js

@@ -0,0 +1,78 @@
+import { access, mkdir, mkdtemp, readdir, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { proposerRunIdSchema, proposerRunSchema, } from "../../application/evaluation/types.js";
+import { sha256Hex } from "../../application/evaluation/candidate-hash.js";
+import { writeJsonAtomic, writeTextAtomic } from "../harness/atomic-write.js";
+import { EVALUATION_ROOT } from "./store.js";
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MANIFEST_INTEGRITY_FILE = "manifest.sha256";
+export function assertProposerRunId(value) {
+    proposerRunIdSchema.parse(value);
+}
+export function proposerRunDir(repoRoot, proposerRunId) {
+    assertProposerRunId(proposerRunId);
+    return path.join(repoRoot, EVALUATION_ROOT, "proposer-runs", proposerRunId);
+}
+export function proposerRunManifestPath(repoRoot, proposerRunId) {
+    return path.join(proposerRunDir(repoRoot, proposerRunId), "manifest.json");
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function serialize(record) {
+    return `${JSON.stringify(record, null, 2)}\n`;
+}
+export async function writeProposerRun(input) {
+    const parsed = proposerRunSchema.parse(input.run);
+    const root = path.dirname(proposerRunDir(input.repoRoot, parsed.proposerRunId));
+    await mkdir(root, { recursive: true });
+    const stagingDir = await mkdtemp(path.join(root, `.${parsed.proposerRunId}.register-`));
+    const manifestPath = proposerRunManifestPath(input.repoRoot, parsed.proposerRunId);
+    try {
+        if (await pathExists(manifestPath)) {
+            throw new Error(`proposer run already exists: ${parsed.proposerRunId}`);
+        }
+        await writeJsonAtomic(path.join(stagingDir, "manifest.json"), parsed, {
+            repoRoot: input.repoRoot,
+        });
+        await writeTextAtomic(path.join(stagingDir, MANIFEST_INTEGRITY_FILE), `${sha256Hex(serialize(parsed))}\n`, { repoRoot: input.repoRoot });
+        await rename(stagingDir, proposerRunDir(input.repoRoot, parsed.proposerRunId));
+    }
+    catch (error) {
+        await rm(stagingDir, { recursive: true, force: true });
+        throw error;
+    }
+    return manifestPath;
+}
+export async function readProposerRun(repoRoot, proposerRunId) {
+    assertProposerRunId(proposerRunId);
+    const manifestPath = proposerRunManifestPath(repoRoot, proposerRunId);
+    const rawText = await readFile(manifestPath, "utf-8");
+    const expected = (await readFile(path.join(proposerRunDir(repoRoot, proposerRunId), MANIFEST_INTEGRITY_FILE), "utf-8")).trim();
+    if (sha256Hex(rawText) !== expected) {
+        throw new Error(`proposer run integrity mismatch for ${proposerRunId}`);
+    }
+    return proposerRunSchema.parse(JSON.parse(rawText));
+}
+export async function listProposerRunIds(repoRoot) {
+    const root = path.join(repoRoot, EVALUATION_ROOT, "proposer-runs");
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory() && SAFE_ID.test(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return [];
+        throw error;
+    }
+}

package/dist/records/promotion.js

@@ -23,7 +23,9 @@ export async function closeoutTask(repoRoot, taskId) {
     const verify = await readFile(verifyPath, 'utf-8').catch(() => '');
     const slug = taskId.replace(/^\d{4}-\d{2}-\d{2}-/, '');
     const datePrefix = taskId.match(/^\d{4}-\d{2}-\d{2}/)?.[0] ?? new Date().toISOString().slice(0, 10);
-    const progressDir = path.join(repoRoot, 'docs', 'progress');
+    // Runtime bridge evidence stays under .harness/ so promote/closeout never
+    // invents tracked docs/progress writes outside TaskSpec allowed_paths.
+    const progressDir = path.join(repoRoot, '.harness', 'task-pool', 'artifacts', 'closeout');
     await mkdir(progressDir, { recursive: true });
     const progressPath = path.join(progressDir, `${datePrefix}-${slug}.md`);
     const verificationSummary = summarizeVerification(verify);

package/dist/worker/cli.js

@@ -16,6 +16,7 @@ import { buildGlobalSnapshot } from "./observability/read-model.js";
 import { createObserveServer } from "./observe/server.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";
@@ -32,6 +33,7 @@ import { previewFeatureCloseout, renderCloseoutPreview } from "./closeout/previe
 import { applyFeatureCloseout } from "./closeout/apply.js";
 import { projectMonthlyMetrics } from "./metrics/projector.js";
 import { runFeatureFinalVerification } from "./delivery/final-verification.js";
+import { advanceGitCheckpoint } from "./delivery/git-transaction.js";
 export function buildAgentWorkerProgram() {
     const program = new Command();
     program
@@ -46,6 +48,29 @@ export function buildAgentWorkerProgram() {
     const observe = program.command("observe").description("Observe UI server and snapshot utilities");
     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");
+    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")
@@ -97,6 +122,28 @@ export function buildAgentWorkerProgram() {
             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/")
@@ -262,6 +309,37 @@ export function buildAgentWorkerProgram() {
         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")
@@ -498,6 +576,11 @@ export async function main(argv = process.argv) {
 async function readTaskYaml(taskSpecPath) {
     return YAML.parse(await readFile(taskSpecPath, "utf-8"));
 }
+function handlePoolRecoveryCliError(error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${detail}\n`);
+    process.exitCode = 1;
+}
 function handleFollowUpCliError(error, json, action) {
     const detail = error instanceof Error ? error.message : String(error);
     if (!json)

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

@@ -173,6 +173,71 @@ export async function finalizeGitTask(transaction, outcome) {
     await assertClean(transaction.repoRoot);
     return { status: "restored", taskId: outcome.taskSpec.id, workerRunId: outcome.workerRunId, artifactDir, changedFiles: changes };
 }
+/**
+ * Operator-only: advance recorded lastCheckpoint to current HEAD after manual
+ * revisions on the owned Feature branch. Does not append checkpoints[] entries.
+ */
+export async function advanceGitCheckpoint(input) {
+    const reason = input.reason.trim();
+    if (!reason)
+        throw new Error("feature git advance-checkpoint requires --reason <text>");
+    const repoRoot = await realpath(path.resolve(input.repoRoot));
+    assertSafeRuntimeId(input.featureId, "featureId");
+    const recordPath = transactionRecordPath(repoRoot, input.featureId);
+    const record = await readOptionalRecord(recordPath);
+    if (!record)
+        throw new Error(`Git transaction record not found for feature ${input.featureId}`);
+    if (record.featureId !== input.featureId) {
+        throw new Error(`Git transaction ownership mismatch: expected ${input.featureId}, found ${record.featureId}`);
+    }
+    await assertClean(repoRoot);
+    const branch = await git(repoRoot, ["branch", "--show-current"]);
+    if (branch !== record.branch) {
+        throw new Error(`current branch is outside the Feature transaction: expected ${record.branch}, got ${branch || "detached HEAD"}`);
+    }
+    const head = await git(repoRoot, ["rev-parse", "HEAD"]);
+    if (head === record.lastCheckpoint) {
+        const evidencePath = await writeAdvanceCheckpointEvidence(repoRoot, input.featureId, {
+            status: "unchanged",
+            reason,
+            previousCheckpoint: record.lastCheckpoint,
+            lastCheckpoint: head,
+            at: (input.now ?? new Date()).toISOString(),
+        });
+        return {
+            schemaVersion: 1,
+            featureId: input.featureId,
+            status: "unchanged",
+            previousCheckpoint: record.lastCheckpoint,
+            lastCheckpoint: head,
+            reason,
+            evidencePath: path.relative(repoRoot, evidencePath).split(path.sep).join("/"),
+        };
+    }
+    if (!await gitOk(repoRoot, ["merge-base", "--is-ancestor", record.lastCheckpoint, head])) {
+        throw new Error(`current HEAD is not descended from recorded checkpoint ${record.lastCheckpoint}`);
+    }
+    const previousCheckpoint = record.lastCheckpoint;
+    const updated = { ...record, lastCheckpoint: head };
+    await writeJsonAtomic(recordPath, updated);
+    const at = (input.now ?? new Date()).toISOString();
+    const evidencePath = await writeAdvanceCheckpointEvidence(repoRoot, input.featureId, {
+        status: "advanced",
+        reason,
+        previousCheckpoint,
+        lastCheckpoint: head,
+        at,
+    });
+    return {
+        schemaVersion: 1,
+        featureId: input.featureId,
+        status: "advanced",
+        previousCheckpoint,
+        lastCheckpoint: head,
+        reason,
+        evidencePath: path.relative(repoRoot, evidencePath).split(path.sep).join("/"),
+    };
+}
 export function transactionRecordPath(repoRoot, featureId) {
     return path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", featureId, "git", "transaction.json");
 }
@@ -311,6 +376,16 @@ async function readIgnoredBaseline(repoRoot) {
 function isSensitivePath(relative) {
     return /(^|\/)(\.env(?:\.|$)|[^/]*\.(?:pem|key|p12|pfx))$/i.test(relative);
 }
+async function writeAdvanceCheckpointEvidence(repoRoot, featureId, payload) {
+    const evidenceDir = path.join(getTaskPoolRoot(repoRoot), "artifacts", "features", featureId, "git");
+    await mkdir(evidenceDir, { recursive: true });
+    const stamp = typeof payload.at === "string"
+        ? payload.at.replace(/[:.]/g, "-")
+        : new Date().toISOString().replace(/[:.]/g, "-");
+    const evidencePath = path.join(evidenceDir, `advance-checkpoint-${stamp}.json`);
+    await writeJsonAtomic(evidencePath, { schemaVersion: 1, featureId, ...payload });
+    return evidencePath;
+}
 async function readOptionalRecord(filePath) {
     try {
         return gitTransactionRecordSchema.parse(JSON.parse(await readFile(filePath, "utf-8")));