@fitlab-ai/agent-infra 0.9.12 → 0.9.14

package/dist/lib/task/finalization.js

@@ -42,7 +42,7 @@ function failed(taskId, error, overrides = {}) {
         ...overrides
     };
 }
-function emptyReceipt(taskId) {
+function emptyReceipt(taskId, controlBinding) {
     return {
         version: RECEIPT_VERSION,
         taskId,
@@ -54,6 +54,7 @@ function emptyReceipt(taskId) {
         verification: 'pending',
         warningProjection: 'done',
         warnings: [],
+        ...(controlBinding ? { controlBinding } : {}),
         updatedAt: now(),
         lastError: null
     };
@@ -79,6 +80,7 @@ function validateReceipt(value, taskId) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         throw new Error('receipt must be an object');
     const receipt = value;
+    const controlBinding = receipt.controlBinding;
     const states = ['pending', 'done', 'skipped'];
     if (receipt.version !== RECEIPT_VERSION || receipt.taskId !== taskId || receipt.intent !== 'complete'
         || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
@@ -89,7 +91,11 @@ function validateReceipt(value, taskId) {
         || !['pending', 'done'].includes(String(receipt.warningProjection))
         || !Array.isArray(receipt.warnings) || receipt.warnings.some((warning) => !validWarning(warning))
         || typeof receipt.updatedAt !== 'string'
-        || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError))))
+        || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)))
+        || (receipt.controlBinding !== undefined && (!controlBinding || typeof controlBinding !== 'object'
+            || Array.isArray(controlBinding)
+            || typeof controlBinding.generation !== 'string' || controlBinding.generation.length === 0
+            || typeof controlBinding.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(controlBinding.requestId))))
         throw new Error('receipt schema is invalid');
     return receipt;
 }
@@ -100,6 +106,13 @@ function readReceipt(repoRoot, taskId) {
     const value = JSON.parse(fs.readFileSync(file, 'utf8'));
     return validateReceipt(value, taskId);
 }
+function readTaskFinalizationReceipt(repoRoot, taskId) {
+    return readReceipt(path.resolve(repoRoot), taskId);
+}
+function controlBindingMatches(receipt, binding) {
+    return receipt.controlBinding?.generation === binding.generation
+        && receipt.controlBinding.requestId === binding.requestId;
+}
 function writeReceipt(repoRoot, receipt) {
     const directory = finalizationRoot(repoRoot);
     fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
@@ -346,7 +359,7 @@ function reconcileWarningProjection(repoRoot, taskId, receipt, consumed) {
         return receipt;
     }
 }
-function syncPendingTaskComment(input) {
+async function syncPendingTaskComment(input) {
     const { repoRoot, taskId, agent, commentSync, consumedCapabilities } = input;
     let receipt = input.receipt;
     if (receipt.taskComment !== 'pending') {
@@ -358,7 +371,7 @@ function syncPendingTaskComment(input) {
         };
     }
     try {
-        const result = commentSync(taskId, { kind: 'task', agent, cwd: repoRoot });
+        const result = await commentSync(taskId, { kind: 'task', agent, cwd: repoRoot });
         const step = commentStep(result);
         if (result.status === 'applied' || result.status === 'no-op') {
             const skipped = result.error?.code === 'ISSUE_NOT_LINKED';
@@ -416,7 +429,7 @@ function terminalResult(taskId, receipt, steps, changed, error = null) {
         error: hardError ? error : postLifecyclePending ? null : error
     };
 }
-function applyUnderLock(request, taskId, options) {
+async function applyUnderLock(request, taskId, options) {
     const repoRoot = path.resolve(options.repoRoot);
     const lifecycle = options.lifecycle ?? applyTaskLifecycle;
     const commentSync = options.commentSync ?? syncPlatformComment;
@@ -426,17 +439,28 @@ function applyUnderLock(request, taskId, options) {
     try {
         const file = receiptPath(repoRoot, taskId);
         const existed = fs.existsSync(file);
-        receipt = readReceipt(repoRoot, taskId) ?? emptyReceipt(taskId);
+        receipt = readReceipt(repoRoot, taskId) ?? emptyReceipt(taskId, options.controlBinding);
         if (!existed)
             writeReceipt(repoRoot, receipt);
     }
     catch (error) {
         return failed(taskId, errorOf(error, 'TASK_FINALIZATION_RECEIPT_INVALID'));
     }
+    if (options.controlBinding && !controlBindingMatches(receipt, options.controlBinding)) {
+        const error = {
+            code: 'TASK_FINALIZATION_CONTROL_BINDING_CONFLICT',
+            message: 'finalization receipt belongs to a different sandbox request or generation',
+            retryable: false
+        };
+        return failed(taskId, error, {
+            completedSteps: completedSteps(receipt),
+            pendingSteps: pendingSteps(receipt)
+        });
+    }
     const preflightState = resolveTaskRef(taskId, { repoRoot });
     if (options.preflight && preflightState.ok && preflightState.state === 'active') {
         try {
-            const preflight = options.preflight({ taskRef: taskId, event: 'complete-task.preflight' }, { repoRoot });
+            const preflight = await options.preflight({ taskRef: taskId, event: 'complete-task.preflight' }, { repoRoot });
             if (preflight.status !== 'pass') {
                 const detail = verificationFailure(preflight);
                 return failed(taskId, detail, {
@@ -510,7 +534,7 @@ function applyUnderLock(request, taskId, options) {
     }
     let taskComment = null;
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    const initialComment = syncPendingTaskComment({
+    const initialComment = await syncPendingTaskComment({
         repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
     });
     receipt = initialComment.receipt;
@@ -526,7 +550,7 @@ function applyUnderLock(request, taskId, options) {
             verification = { status: 'no-op', changed: false, error: null };
         }
         else {
-            const result = verify({ taskRef: taskId, event: 'complete-task.completed' }, { repoRoot });
+            const result = await verify({ taskRef: taskId, event: 'complete-task.completed' }, { repoRoot });
             verification = verificationStep(result);
             if (result.status === 'pass') {
                 const capability = issueCapability(receipt, 'verification');
@@ -534,7 +558,7 @@ function applyUnderLock(request, taskId, options) {
                     scope: 'verification', operation: 'succeeded'
                 }, consumedCapabilities);
                 receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-                const finalComment = syncPendingTaskComment({
+                const finalComment = await syncPendingTaskComment({
                     repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
                 });
                 receipt = finalComment.receipt;
@@ -571,7 +595,7 @@ function applyUnderLock(request, taskId, options) {
     receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
     return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification }, changed);
 }
-function applyTaskFinalization(request, options) {
+async function applyTaskFinalization(request, options) {
     if (request.intent !== 'complete' || !request.taskRef || !request.agent) {
         return failed(null, { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'complete finalization requires taskRef and agent', retryable: false });
     }
@@ -580,7 +604,7 @@ function applyTaskFinalization(request, options) {
     if (!resolved.ok)
         return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
     try {
-        return withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.complete', () => applyUnderLock(request, resolved.taskId, options));
+        return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.complete', () => applyUnderLock(request, resolved.taskId, options));
     }
     catch (error) {
         const detail = error instanceof TaskExecutionLockError
@@ -589,5 +613,5 @@ function applyTaskFinalization(request, options) {
         return failed(resolved.taskId, detail);
     }
 }
-export { applyFinalizationReceiptMutation, applyTaskFinalization, issueCapability as createFinalizationCapability };
+export { applyFinalizationReceiptMutation, applyTaskFinalization, issueCapability as createFinalizationCapability, readTaskFinalizationReceipt };
 //# sourceMappingURL=finalization.js.map

package/dist/lib/task/human-override.js

@@ -20,6 +20,8 @@ import { verifyTaskEvent } from './verification.js';
 import { verifyInProcess } from './verification-engine.js';
 import { canonicalTimestamp, writeTask } from './write.js';
 import { readPrDeliveryFact } from './pr-delivery-fact.js';
+import { resourceIdentity, resourceIdentityNumber } from '../platform/provider-bridge.js';
+import { taskIssueIdentity } from '../platform/task-identities.js';
 const LIFECYCLE_PRODUCER = 'lifecycle.apply';
 const HUMAN_OVERRIDE_SECTION_ALIASES = ['人工豁免账本', 'Human Override Ledger'];
 const HUMAN_OVERRIDE_COLUMNS = [
@@ -402,13 +404,20 @@ function snapshotEvidence(taskId, failureIdValue, target, content, frontmatter,
 }
 function resourceForSnapshot(policy, options, frontmatter) {
     if (policy.producerId === 'platform.issue') {
-        const number = options.probeIssueNumber ?? toPositiveInteger(frontmatter?.issue_number);
-        return number === null ? null : { kind: 'issue', number };
+        const identity = options.probeIssueNumber !== undefined
+            ? resourceIdentity(options.probeIssueNumber)
+            : taskIssueIdentity((frontmatter || {})) || (() => {
+                const number = toPositiveInteger(frontmatter?.issue_number);
+                return number === null ? null : resourceIdentity(number);
+            })();
+        return identity ? { kind: 'issue', identity, number: resourceIdentityNumber(identity) } : null;
     }
     if (policy.producerId === 'platform.pull-request') {
         const fact = frontmatter ? readPrDeliveryFact(frontmatter) : null;
-        const number = options.probePullRequestNumber ?? (fact?.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null);
-        return number === null ? null : { kind: 'pull-request', number };
+        const identity = options.probePullRequestNumber !== undefined
+            ? resourceIdentity(options.probePullRequestNumber)
+            : fact?.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
+        return identity ? { kind: 'pull-request', identity, number: resourceIdentityNumber(identity) } : null;
     }
     return null;
 }
@@ -461,7 +470,7 @@ function probeResult(policy, result, state) {
 function probeNotObserved(policy) {
     return error('OVERRIDE_FAILURE_NOT_PRESENT', `producer ${policy.producerId} did not produce ${policy.code}`);
 }
-function probePlatformFailure(taskRef, policy, resolved, options) {
+async function probePlatformFailure(taskRef, policy, resolved, options) {
     let frontmatter;
     try {
         frontmatter = parseTypedTaskFrontmatter(fs.readFileSync(path.join(resolved.taskDir, 'task.md'), 'utf8'));
@@ -469,30 +478,40 @@ function probePlatformFailure(taskRef, policy, resolved, options) {
     catch (cause) {
         return error('OVERRIDE_DOCUMENT_INVALID', cause instanceof Error ? cause.message : String(cause));
     }
-    const issueNumber = options.probeIssueNumber ?? toPositiveInteger(frontmatter.issue_number);
+    const issueIdentity = options.probeIssueNumber !== undefined
+        ? resourceIdentity(options.probeIssueNumber)
+        : taskIssueIdentity(frontmatter) || (() => {
+            const number = toPositiveInteger(frontmatter.issue_number);
+            return number === null ? null : resourceIdentity(number);
+        })();
     const fact = readPrDeliveryFact(frontmatter);
-    const pullRequestNumber = options.probePullRequestNumber ?? (fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null);
-    const operation = policy.producerId === 'platform.issue'
-        ? issueNumber === null
+    const pullRequestIdentity = options.probePullRequestNumber !== undefined
+        ? resourceIdentity(options.probePullRequestNumber)
+        : fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
+    const token = (identity) => identity ? String(identity.value) : null;
+    const issueToken = token(issueIdentity);
+    const pullRequestToken = token(pullRequestIdentity);
+    const operation = await (policy.producerId === 'platform.issue'
+        ? issueToken === null
             ? null
             : bindPlatformIssue(taskRef, {
-                issue: issueNumber,
+                issue: issueToken,
                 agent: options.probeOperator ?? 'local-operator',
                 dryRun: true,
                 cwd: resolved.repoRoot,
                 ...(options.platformClient ? { client: options.platformClient } : {})
             })
-        : pullRequestNumber === null
+        : pullRequestToken === null
             ? null
             : bindPlatformPullRequest(taskRef, {
-                pr: pullRequestNumber,
+                pr: pullRequestToken,
                 agent: options.probeOperator ?? 'local-operator',
                 dryRun: true,
                 cwd: resolved.repoRoot,
                 ...(options.platformClient ? { client: options.platformClient } : {})
-            });
+            }));
     if (!operation)
-        return error('OVERRIDE_PROBE_INPUT_MISSING', `${policy.producerId} requires a bound issue or pull request number`);
+        return error('OVERRIDE_PROBE_INPUT_MISSING', `${policy.producerId} requires a bound issue or pull request identity`);
     if (operation.status !== 'failed' && operation.status !== 'blocked')
         return probeNotObserved(policy);
     if (!operation.error)
@@ -530,6 +549,9 @@ function probeTaskEventFailure(taskRef, policy, resolved) {
             event: candidate.event,
             agent: 'codex',
             dryRun: true,
+            initiator: 'model',
+            requestId: `override-probe:${taskRef}:${candidate.event}`,
+            reasonCode: 'user-request',
             ...(candidate.artifact ? { artifact: candidate.artifact } : {})
         }, { repoRoot: resolved.repoRoot, lockAlreadyHeld: true });
         const matched = probeResult(policy, result, resolved.state);
@@ -538,8 +560,8 @@ function probeTaskEventFailure(taskRef, policy, resolved) {
     }
     return probeNotObserved(policy);
 }
-function probeVerificationFailure(taskRef, policy, resolved) {
-    const result = verifyTaskEvent({
+async function probeVerificationFailure(taskRef, policy, resolved) {
+    const result = await verifyTaskEvent({
         taskRef,
         event: 'review-code.completed',
         artifact: policy.code === 'VERIFY_ARTIFACT_INVALID' ? 'invalid-artifact.md' : 'review-code.md'
@@ -562,7 +584,7 @@ function latestArtifact(taskDir, family) {
     });
     return candidates[0];
 }
-function probeVerificationEngineFailure(policy, resolved) {
+async function probeVerificationEngineFailure(policy, resolved) {
     const candidates = [
         { skillName: 'review-code', family: 'review-code' },
         { skillName: 'review-plan', family: 'review-plan' },
@@ -577,7 +599,7 @@ function probeVerificationEngineFailure(policy, resolved) {
         if (candidate.family && !artifactFile)
             continue;
         try {
-            const payload = verifyInProcess({
+            const payload = await verifyInProcess({
                 mode: 'gate',
                 skillName: candidate.skillName,
                 taskDir: resolved.taskDir,
@@ -601,7 +623,7 @@ function probeVerificationEngineFailure(policy, resolved) {
     }
     return probeNotObserved(policy);
 }
-function probeGenericFailure(taskRef, policy, resolved, options = {}) {
+async function probeGenericFailure(taskRef, policy, resolved, options = {}) {
     switch (policy.producerId) {
         case 'task.resolve':
             return probeNotObserved(policy);
@@ -610,9 +632,9 @@ function probeGenericFailure(taskRef, policy, resolved, options = {}) {
         case 'task-event':
             return probeTaskEventFailure(taskRef, policy, resolved);
         case 'task-verify':
-            return probeVerificationFailure(taskRef, policy, resolved);
+            return await probeVerificationFailure(taskRef, policy, resolved);
         case 'verification-engine':
-            return probeVerificationEngineFailure(policy, resolved);
+            return await probeVerificationEngineFailure(policy, resolved);
         case 'activity-intent':
             return probeResult(policy, applyPrReviewActivityIntent({
                 kind: 'pr-review-start', taskRef, agent: 'codex', artifact: 'pr-review.md', head: '0'.repeat(40), dryRun: true
@@ -648,7 +670,7 @@ function probeGenericFailure(taskRef, policy, resolved, options = {}) {
         }
         case 'platform.issue':
         case 'platform.pull-request':
-            return probePlatformFailure(taskRef, policy, resolved, options);
+            return await probePlatformFailure(taskRef, policy, resolved, options);
         default:
             return error('OVERRIDE_PROBE_INPUT_MISSING', `no producer probe is registered for ${policy.producerId}`);
     }
@@ -656,7 +678,7 @@ function probeGenericFailure(taskRef, policy, resolved, options = {}) {
 function isProducerFailure(value) {
     return 'observedFacts' in value && 'state' in value && Array.isArray(value.observedFacts);
 }
-function captureFailureSnapshot(taskRef, failureIdValue, target, options = {}) {
+async function captureFailureSnapshot(taskRef, failureIdValue, target, options = {}) {
     const policy = policyFor(failureIdValue);
     if (!policy)
         return error('OVERRIDE_FAILURE_UNKNOWN', `failure policy '${failureIdValue}' is not registered`);
@@ -679,7 +701,7 @@ function captureFailureSnapshot(taskRef, failureIdValue, target, options = {}) {
     catch { /* probe reports an unconfirmed identity */ }
     const producer = policy.producerId === LIFECYCLE_PRODUCER
         ? probeLifecycleFailure(taskRef, policy, resolved, options)
-        : probeGenericFailure(taskRef, policy, resolved, options);
+        : await probeGenericFailure(taskRef, policy, resolved, options);
     if (!isProducerFailure(producer))
         return producer;
     const digest = computeFailureDigest(snapshotEvidence(resolved.taskId, failureIdValue, target, content, frontmatter, producer, resourceForSnapshot(policy, options, frontmatter)));
@@ -736,7 +758,7 @@ function validateResourceNumbers(request) {
     }
     return null;
 }
-function issueHumanOverride(request, options = {}) {
+async function issueHumanOverride(request, options = {}) {
     const invalid = validateCommon(request);
     if (invalid)
         return failedIssue(invalid.code, invalid.message);
@@ -765,7 +787,7 @@ function issueHumanOverride(request, options = {}) {
         return failedIssue(document.code, document.message, resolved.taskId);
     if (document.frontmatter.id !== resolved.taskId)
         return failedIssue('OVERRIDE_DOCUMENT_INVALID', 'task frontmatter id does not match resolved task', resolved.taskId);
-    const snapshotResult = captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
+    const snapshotResult = await captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
         ...options,
         probeIntent: request.intent,
         probeOperator: request.operator,
@@ -891,14 +913,14 @@ function lifecycleRequestFor(taskRef, intent, operator, reason, values = {}) {
         return error('OVERRIDE_EFFECT_INPUT_MISSING', 'restore requires the original staging directory and issue number');
     return { taskRef, intent: 'restore', agent: operator, stagingDir, issueNumber };
 }
-function applyOutcomeEffect(request, row, snapshot, outcome, options) {
+async function applyOutcomeEffect(request, row, snapshot, outcome, options) {
     if (outcome.effect === 'no-write' || outcome.effect === 'record-only')
         return null;
     const intent = outcome.target === 'safe-close' ? 'cancel' : row.intent || request.intent;
     if (!intent && outcome.target === 'continue-local') {
         if (!options.effectExecutor)
             return error('OVERRIDE_EFFECT_EXECUTOR_MISSING', 'the producer must supply an effect executor for a continue-local outcome');
-        return options.effectExecutor({
+        return await options.effectExecutor({
             failureId: request.failureId,
             operator: row.operator ?? 'local-operator',
             reason: row.reason ?? snapshot.message
@@ -991,7 +1013,7 @@ function snapshotFromTicket(taskId, row) {
         source: 'producer-result'
     };
 }
-function consumeHumanOverride(request, options = {}) {
+async function consumeHumanOverride(request, options = {}) {
     const values = [request.taskRef, request.ticketId, request.failureId, request.target, request.scope];
     if (values.some((value) => !singleLine(value))) {
         return failedConsume('OVERRIDE_PAYLOAD_INVALID', 'consume fields must be non-empty single-line values', request.ticketId || null);
@@ -1043,7 +1065,7 @@ function consumeHumanOverride(request, options = {}) {
         snapshot = recoverySnapshot;
     }
     else {
-        const snapshotResult = captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
+        const snapshotResult = await captureFailureSnapshot(request.taskRef, request.failureId, request.target, {
             ...options,
             probeIntent: row.values.intent ? row.values.intent : request.intent,
             probeOperator: row.values.operator,
@@ -1097,7 +1119,7 @@ function consumeHumanOverride(request, options = {}) {
             return failedConsume('OVERRIDE_WRITE_INVALID', 'override writes cannot be planned', request.ticketId, resolved.taskId);
         effectRow = { ...row.values, status: 'consuming', effect: outcome.effect, result: outcome.result, context_id: outcome.contextId, residual: `effect pending: ${outcome.residual}` };
     }
-    const effectError = applyOutcomeEffect(request, effectRow, snapshot, outcome, options);
+    const effectError = await applyOutcomeEffect(request, effectRow, snapshot, outcome, options);
     if (effectError)
         return failedConsume(effectError.code, effectError.message, request.ticketId, resolved.taskId);
     const after = resolveTask(request.taskRef, options);
@@ -1137,7 +1159,7 @@ function diagnoseHumanOverride(failure, target) {
         error: null
     };
 }
-function diagnoseHumanOverrideForTask(taskRef, failure, target, options = {}) {
+async function diagnoseHumanOverrideForTask(taskRef, failure, target, options = {}) {
     const resolved = resolveTask(taskRef, options);
     if (!resolved.ok) {
         return {
@@ -1176,12 +1198,12 @@ function diagnoseHumanOverrideForTask(taskRef, failure, target, options = {}) {
             error: error('OVERRIDE_FAILURE_UNKNOWN', `failure policy '${failure}' is not registered`)
         };
     }
-    const probes = policies
+    const probes = await Promise.all(policies
         .filter((policy) => !target || policy.targets.includes(target))
-        .map((policy) => {
+        .map(async (policy) => {
         const producer = policy.producerId === LIFECYCLE_PRODUCER
             ? probeLifecycleFailure(taskRef, policy, resolved, options)
-            : probeGenericFailure(taskRef, policy, resolved, options);
+            : await probeGenericFailure(taskRef, policy, resolved, options);
         const observed = isProducerFailure(producer);
         return {
             failureId: policy.id,
@@ -1195,7 +1217,7 @@ function diagnoseHumanOverrideForTask(taskRef, failure, target, options = {}) {
             message: observed ? producer.message : producer.message,
             errorCode: observed ? null : producer.code
         };
-    });
+    }));
     const blockedBy = probes.filter((probe) => probe.status === 'observed');
     return {
         status: 'ready',

package/dist/lib/task/index.js

@@ -1,3 +1,4 @@
+import { PUBLIC_CLI_ROUTE_SELECTORS, PUBLIC_CLI_SELECTOR_ALIASES } from '../internal/cli-route-inventory.js';
 const USAGE = `Usage: ai task <command> [options]
 
 Commands:
@@ -30,6 +31,7 @@ Examples:
   ai task status --task 11
 
 Run 'ai task <command> --help' for details.`;
+const TASK_OPERATIONS = PUBLIC_CLI_ROUTE_SELECTORS.task;
 export async function runTask(args) {
     const [subcommand, ...rest] = args;
     if (!subcommand) {
@@ -41,14 +43,20 @@ export async function runTask(args) {
         process.stdout.write(`${USAGE}\n`);
         return;
     }
-    switch (subcommand) {
+    const routeSelector = PUBLIC_CLI_SELECTOR_ALIASES.task[subcommand] ?? subcommand;
+    if (!TASK_OPERATIONS.includes(routeSelector)) {
+        process.stderr.write(`Unknown task command: ${subcommand}\n\n`);
+        process.stdout.write(`${USAGE}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    switch (routeSelector) {
         case 'cat': {
             const { cat } = await import('./commands/cat.js');
             cat(rest);
             break;
         }
-        case 'decisions':
-        case 'd': {
+        case 'decisions': {
             const { decisions } = await import('./commands/decisions.js');
             decisions(rest);
             break;

package/dist/lib/task/invalidation-command.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArtifactReceipts, sha256File } from './artifact-receipts.js';
+import { invalidationMutation, parseInvalidationDocument, reconcileInvalidation } from './invalidation.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { writeTask } from './write.js';
+function reconcileTaskInvalidation(taskRef, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return { status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: 0, error: { code: resolved.code, message: resolved.message } };
+    let content;
+    try {
+        content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    }
+    catch (error) {
+        return { status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: 0, error: { code: 'TASK_READ_FAILED', message: error instanceof Error ? error.message : String(error) } };
+    }
+    const parsed = parseInvalidationDocument(content);
+    if (!parsed.ok)
+        return { status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: 0, error: { code: parsed.code, message: parsed.message } };
+    if (!parsed.present)
+        return { status: 'no-op', changed: false, taskId: resolved.taskId, processed: 0, remaining: 0, error: null };
+    const beforePending = parsed.document.targets.filter((target) => target.status !== 'completed').length;
+    let receipts;
+    try {
+        receipts = parseArtifactReceipts(content).rows;
+    }
+    catch (error) {
+        if (parsed.document.targets.some((target) => target.status !== 'completed' && target.targetKind === 'receipt')) {
+            return {
+                status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending,
+                error: { code: 'INVALIDATION_TARGET_HASH_CONFLICT', message: error instanceof Error ? error.message : String(error) }
+            };
+        }
+        receipts = [];
+    }
+    for (const target of parsed.document.targets) {
+        if (target.status === 'completed')
+            continue;
+        if (target.targetKind === 'receipt') {
+            const receipt = receipts.find((candidate) => candidate.output === target.targetArtifact);
+            if (!receipt || receipt.inputSha256 !== target.targetSha256) {
+                return {
+                    status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending,
+                    error: { code: 'INVALIDATION_TARGET_HASH_CONFLICT', message: `invalidation receipt target '${target.targetArtifact}' changed before reconcile` }
+                };
+            }
+            continue;
+        }
+        const targetPath = path.join(resolved.taskDir, target.targetArtifact);
+        try {
+            const stat = fs.lstatSync(targetPath);
+            if (!stat.isFile() || stat.isSymbolicLink() || sha256File(targetPath) !== target.targetSha256) {
+                return {
+                    status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending,
+                    error: { code: 'INVALIDATION_TARGET_HASH_CONFLICT', message: `invalidation target '${target.targetArtifact}' changed before reconcile` }
+                };
+            }
+        }
+        catch {
+            return {
+                status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending,
+                error: { code: 'INVALIDATION_TARGET_HASH_CONFLICT', message: `invalidation target '${target.targetArtifact}' is unavailable before reconcile` }
+            };
+        }
+    }
+    const reconciled = reconcileInvalidation(parsed.document, (options.now ?? (() => new Date().toISOString()))(), options.maxTargets);
+    if (!reconciled.ok)
+        return { status: 'failed', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending, error: { code: reconciled.code, message: reconciled.message } };
+    if (!reconciled.changed)
+        return { status: 'no-op', changed: false, taskId: resolved.taskId, processed: 0, remaining: beforePending, error: null };
+    const result = writeTask({
+        taskRef, expectedState: resolved.state, dryRun: options.dryRun,
+        mutations: [invalidationMutation(content, reconciled.document)]
+    }, { ...options, invalidationContext: 'reconcile', taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state } });
+    if (result.status === 'failed')
+        return { status: 'failed', changed: false, taskId: resolved.taskId, processed: beforePending - reconciled.document.targets.filter((target) => target.status !== 'completed').length, remaining: reconciled.document.targets.filter((target) => target.status !== 'completed').length, error: result.error };
+    return {
+        status: result.status, changed: result.changed, taskId: resolved.taskId,
+        processed: beforePending - reconciled.document.targets.filter((target) => target.status !== 'completed').length,
+        remaining: reconciled.document.targets.filter((target) => target.status !== 'completed').length,
+        error: null
+    };
+}
+export { reconcileTaskInvalidation };
+//# sourceMappingURL=invalidation-command.js.map