@fitlab-ai/agent-infra 0.11.1 → 0.11.2

package/dist/lib/task/review-finalization.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { parseArtifactName } from './artifact-name.js';
-import { validateCompletedArtifact, hasOpenArtifactRound, validateArtifactPublication } from './artifact-lifecycle.js';
+import { validateCompletedArtifact, validateArtifactPublication } from './artifact-lifecycle.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { finalizeReviewSummaryContent } from './review-artifacts.js';
 import { inspectDecisionDetailDuplicates } from './decision-details.js';
@@ -11,8 +13,6 @@ import { allowsManualOverride } from './guard-override.js';
 import { getArtifactSchema } from './artifact-schema.js';
 import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.js';
 import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.js';
-import { readArtifactRecoveryIntent } from './artifact-repair-intent.js';
-import { beginArtifactRecovery, commitArtifactRecovery, prepareArtifactRecoveryFinal, prepareArtifactRecoveryCommit, reconcileArtifactRecovery, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
 const STAGES = {
     analysis: { family: 'review-analysis' },
     plan: { family: 'review-plan' },
@@ -47,7 +47,7 @@ function preflightFailed(request, code, message, taskId = null, extra = {}) {
         stageStatus: null
     };
 }
-/** Validate and seal a review draft before any finding-ledger write. */
+/** Validate the current review draft before any finding-ledger write. */
 function preflightReviewSummaryUnlocked(request, options = {}) {
     const stage = request.stage;
     const spec = STAGES[stage];
@@ -68,37 +68,16 @@ function preflightReviewSummaryUnlocked(request, options = {}) {
         return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', publicationError.message, resolved.taskId);
     let taskContent;
     let content;
-    let recovery;
     try {
         taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
-        if (request.recoveryId) {
-            const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
-            if (!intent || intent.recoveryOperationId !== request.recoveryId)
-                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal', resolved.taskId);
-            if (!['awaiting-preflight-recovery', 'preflight-ready'].includes(intent.state))
-                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`, resolved.taskId);
-            recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
-            content = fs.existsSync(recovery.stagingPath)
-                ? fs.readFileSync(recovery.stagingPath, 'utf8')
-                : fs.readFileSync(recovery.formalPath, 'utf8');
-        }
-        else {
-            const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
-            if (!validated.ok)
-                return preflightFailed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
-            content = fs.readFileSync(validated.artifact.path, 'utf8');
-            const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact);
-            if (intent?.state === 'preflight-ready')
-                recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
-            if (intent?.state === 'consumed')
-                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', 'review artifact was already finalized', resolved.taskId);
-        }
+        const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
+        if (!validated.ok)
+            return preflightFailed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
+        content = fs.readFileSync(validated.artifact.path, 'utf8');
     }
     catch (error) {
         return preflightFailed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
     }
-    if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round))
-        return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`, resolved.taskId);
     const execution = validateLifecycleExecution(request.taskRef, {
         mode: request.orchestrated ? 'orchestrated' : 'standalone',
         identity: { stage: spec.family, round: parsed.round, artifact: request.artifact, role: 'reviewer' },
@@ -120,17 +99,6 @@ function preflightReviewSummaryUnlocked(request, options = {}) {
     });
     const qualificationError = qualification.ok ? null : qualification;
     if (!detail.ok || !structure.ok || qualificationError) {
-        if (!recovery && !request.dryRun) {
-            try {
-                recovery = beginArtifactRecovery({
-                    taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
-                    requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
-                }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-            }
-            catch (error) {
-                return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId);
-            }
-        }
         const diagnostics = [
             ...(!detail.ok ? [`${detail.code}: ${detail.message}`] : []),
             ...structure.diagnostics.map((item) => `${item.code}: ${item.message}`),
@@ -138,30 +106,18 @@ function preflightReviewSummaryUnlocked(request, options = {}) {
         ].join('; ');
         return preflightFailed(request, !detail.ok ? 'REVIEW_DECISION_DETAIL_INVALID' : !structure.ok ? 'REVIEW_ARTIFACT_STRUCTURE_INVALID' : 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', diagnostics, resolved.taskId, {
             artifactSha256, semanticDigest,
-            ...(recovery ? { recovery: recoveryInfo(recovery) } : {})
         });
     }
-    if (request.dryRun || recovery && readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact)?.state === 'preflight-ready') {
+    if (request.dryRun) {
         return {
-            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, ...(recovery ? { recovery: recoveryInfo(recovery) } : {}) }),
+            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest }),
             status: 'passed', changed: false, error: null
         };
     }
-    try {
-        recovery ??= beginArtifactRecovery({
-            taskId: resolved.taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
-            requestId: `review-preflight:${resolved.taskId}:${stage}:${parsed.round}`
-        }, Buffer.from(content, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-        const staged = stageArtifactCandidate(recovery, Buffer.from(content, 'utf8'), { lockAlreadyHeld: options.lockAlreadyHeld });
-        prepareArtifactRecoveryCommit(recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: options.lockAlreadyHeld });
-        return {
-            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, recovery: recoveryInfo(recovery) }),
-            status: 'passed', changed: false, error: null
-        };
-    }
-    catch (error) {
-        return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', String(error), resolved.taskId, { artifactSha256, semanticDigest });
-    }
+    return {
+        ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest }),
+        status: 'passed', changed: false, error: null
+    };
 }
 function preflightReviewSummary(request, options = {}) {
     if (request.dryRun || options.lockAlreadyHeld)
@@ -178,14 +134,6 @@ function preflightReviewSummary(request, options = {}) {
         return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
     }
 }
-function recoveryInfo(recovery) {
-    return {
-        recoveryId: recovery.recoveryId,
-        candidatePath: recovery.stagingPath,
-        baselineSha256: recovery.baselineSha256,
-        baselineSemanticDigest: recovery.baselineSemanticDigest
-    };
-}
 /** Prepare domain validation, summary bytes and provenance before any publication. */
 function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     let taskId = null;
@@ -219,45 +167,9 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     catch (error) {
         return reject('REVIEW_ARTIFACT_NOT_REGULAR', String(error));
     }
-    let recovery;
-    if (request.recoveryId) {
-        try {
-            const intent = readArtifactRecoveryIntent(resolved.repoRoot, taskId, spec.family, request.artifact);
-            if (!intent || intent.recoveryOperationId !== request.recoveryId)
-                return reject('REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal');
-            if (!['awaiting-preflight-recovery', 'preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready', 'commit-started'].includes(intent.state))
-                return reject('REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' state`);
-            recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
-            artifactContent = fs.existsSync(recovery.stagingPath)
-                ? fs.readFileSync(recovery.stagingPath, 'utf8')
-                : fs.readFileSync(recovery.formalPath, 'utf8');
-        }
-        catch (error) {
-            return reject('REVIEW_PROVENANCE_INVALID', String(error));
-        }
-    }
     const artifactSha256 = sha256Content(artifactContent);
     const semanticDigest = canonicalSemanticDigest(artifactContent);
     const digests = { artifactSha256, semanticDigest };
-    let repairIntent;
-    try {
-        repairIntent = readArtifactRecoveryIntent(resolved.repoRoot, taskId, spec.family, request.artifact);
-    }
-    catch (error) {
-        return reject('REVIEW_PROVENANCE_INVALID', String(error), digests);
-    }
-    if (repairIntent?.state === 'consumed') {
-        if (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest) {
-            return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', digests);
-        }
-    }
-    if (repairIntent?.state === 'passed'
-        && (repairIntent.finalArtifactSha256 !== artifactSha256 || repairIntent.finalSemanticDigest !== semanticDigest)) {
-        repairIntent = undefined;
-    }
-    if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) {
-        return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`);
-    }
     const execution = validateLifecycleExecution(request.taskRef, {
         mode: request.orchestrated ? 'orchestrated' : 'standalone',
         identity: { stage: spec.family, round: parsed.round, artifact: request.artifact, role: 'reviewer' },
@@ -284,67 +196,16 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     const schema = getArtifactSchema(spec.family);
     const structure = inspectArtifactContract(artifactContent, schema);
     if (!structure.ok) {
-        if (!recovery && !request.dryRun && options.startRecovery) {
-            try {
-                recovery = beginArtifactRecovery({
-                    taskId: taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
-                    requestId: `review-finalize:${taskId}:${stage}:${parsed.round}`
-                }, Buffer.from(artifactContent, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-            }
-            catch (error) {
-                return reject('REVIEW_PROVENANCE_INVALID', String(error), digests);
-            }
-        }
-        return {
-            ...reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
-                artifactSha256, semanticDigest: structure.semanticDigest,
-                ...(recovery ? { recovery: {
-                        recoveryId: recovery.recoveryId,
-                        candidatePath: recovery.stagingPath,
-                        baselineSha256: recovery.baselineSha256,
-                        baselineSemanticDigest: recovery.baselineSemanticDigest
-                    } } : {})
-            }),
-            ...(recovery ? { recovery } : {})
-        };
+        return reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
+            artifactSha256, semanticDigest: structure.semanticDigest
+        });
     }
     const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts, {
-        refreshNumericCounts: Boolean(request.recoveryId && recovery)
+        refreshNumericCounts: true
     });
     if (!transformed.ok)
         return reject(transformed.code, transformed.message);
     const finalDigests = { artifactSha256: sha256Content(transformed.content), semanticDigest: canonicalSemanticDigest(transformed.content) };
-    if (!recovery && repairIntent?.state === 'commit-started') {
-        if (repairIntent.finalArtifactSha256 !== finalDigests.artifactSha256 || repairIntent.finalSemanticDigest !== finalDigests.semanticDigest) {
-            return reject('REVIEW_PROVENANCE_INVALID', 'formal review artifact does not match the interrupted recovery journal', finalDigests);
-        }
-        recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, repairIntent);
-    }
-    if (!recovery && (repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')) {
-        if (transformed.changed)
-            return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact requires changes after its completed recovery was consumed', finalDigests);
-        return {
-            content: transformed.content,
-            result: {
-                ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', taskId, stageStatus, finalDigests),
-                status: 'no-op',
-                changed: false,
-                error: null
-            },
-            lockAlreadyHeld: options.lockAlreadyHeld
-        };
-    }
-    if (!recovery && !request.dryRun && options.startRecovery) {
-        try {
-            recovery = beginArtifactRecovery({
-                taskId: taskId, family: spec.family, artifact: request.artifact, round: parsed.round,
-                requestId: `review-finalize:${taskId}:${stage}:${parsed.round}`
-            }, Buffer.from(artifactContent, 'utf8'), { repoRoot: resolved.repoRoot, taskDir: resolved.taskDir, lockAlreadyHeld: options.lockAlreadyHeld });
-        }
-        catch (error) {
-            return reject('REVIEW_PROVENANCE_INVALID', String(error), finalDigests);
-        }
-    }
     return {
         content: transformed.content,
         result: {
@@ -354,65 +215,26 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
             operations: transformed.changed ? [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }] : [],
             error: null
         },
-        ...(recovery ? { recovery } : {}),
         lockAlreadyHeld: options.lockAlreadyHeld
     };
 }
 function commitReviewSummaryProvenance(prepared, repoRoot, options = {}) {
-    if (prepared.result.status === 'failed' || !prepared.recovery)
-        return prepared.result;
+    return prepared.result;
+}
+function replaceCurrentArtifactAtomically(file, content) {
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
     try {
-        const intent = readArtifactRecoveryIntent(prepared.recovery.repoRoot, prepared.recovery.taskId, prepared.recovery.family, prepared.recovery.artifact);
-        if (!intent)
-            throw new Error('ARTIFACT_RECOVERY_INTENT_MISSING');
-        let committed;
-        if (intent.state === 'passed' || intent.state === 'consumed') {
-            return {
-                ...prepared.result,
-                status: 'no-op',
-                changed: false,
-                artifactSha256: intent.finalArtifactSha256,
-                semanticDigest: intent.finalSemanticDigest,
-                error: null
-            };
-        }
-        else if (intent.state === 'commit-started') {
-            const reconciled = reconcileArtifactRecovery(prepared.recovery, {
-                lockAlreadyHeld: prepared.lockAlreadyHeld,
-                afterPublish: options.afterPublish
-            });
-            committed = reconciled.intent;
-        }
-        else if (intent.state === 'awaiting-preflight-recovery') {
-            const staged = stageArtifactCandidate(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
-            prepareArtifactRecoveryCommit(prepared.recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: prepared.lockAlreadyHeld });
-            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
-        }
-        else if (intent.state === 'preflight-ready' || intent.state === 'preflight-commit-started') {
-            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
-        }
-        if (committed?.state === 'preflight-passed' || intent.state === 'preflight-passed') {
-            prepareArtifactRecoveryFinal(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
-            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        fs.writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx' });
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporary);
         }
-        else if (intent.state === 'full-finalizer-ready') {
-            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
         }
-        if (!committed || committed.state !== 'passed')
-            throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed?.state ?? intent.state}'`);
-        return {
-            ...prepared.result,
-            artifactSha256: committed.finalArtifactSha256,
-            semanticDigest: committed.finalSemanticDigest,
-            error: null
-        };
-    }
-    catch (error) {
-        if (error instanceof Error && error.message.startsWith('TASK_WORKFLOW_FAULT_INJECTED:'))
-            throw error;
-        return { ...prepared.result, status: 'failed', error: {
-                code: 'REVIEW_RECOVERY_COMMIT_FAILED', message: `cannot publish review candidate: ${String(error)}`
-            } };
     }
 }
 function finalizeReviewSummaryUnlocked(request, options = {}) {
@@ -437,10 +259,23 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
     const prepared = prepareReviewSummaryCandidate(request, content, options);
     if (request.dryRun)
         return prepared.result;
-    return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
+    if (prepared.result.status === 'failed' || !prepared.result.changed)
+        return prepared.result;
+    try {
+        replaceCurrentArtifactAtomically(validated.artifact.path, prepared.content);
+        return {
+            ...prepared.result,
+            status: 'applied',
+            artifactSha256: sha256Content(prepared.content),
+            semanticDigest: canonicalSemanticDigest(prepared.content)
+        };
+    }
+    catch (error) {
+        return failed(request, 'REVIEW_RECOVERY_COMMIT_FAILED', `cannot update current review artifact: ${error instanceof Error ? error.message : String(error)}`, resolved.taskId);
+    }
 }
 function finalizeReviewSummary(request, options = {}) {
-    const effectiveOptions = { ...options, startRecovery: !request.dryRun };
+    const effectiveOptions = options;
     if (request.dryRun || options.lockAlreadyHeld)
         return finalizeReviewSummaryUnlocked(request, effectiveOptions);
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });

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

@@ -9,10 +9,13 @@ export const TASK_WORKFLOW_COMMANDS = Object.freeze({
     'ledger-finding-response': ['task-ledger', 'finding-respond'],
     'ledger-finding-review': ['task-ledger', 'finding-review'],
     'ledger-finding-upsert': ['task-ledger', 'finding-upsert'],
+    'ledger-stage-status': ['task-ledger', 'stage-status'],
     'decision-next-id': ['task-ledger', 'decision-next-id'],
     'decision-upsert': ['task-ledger', 'decision-upsert'],
     'invalidation-reconcile': ['task-invalidation', 'reconcile'],
-    'warning-add': ['task-warning', 'add']
+    'warning-add': ['task-warning', 'add'],
+    'warning-list': ['task-warning', 'list'],
+    'warning-set-status': ['task-warning', 'set-status']
 });
 export const TASK_WORKFLOW_OPERATIONS = Object.freeze(Object.keys(TASK_WORKFLOW_COMMANDS));
 //# sourceMappingURL=workflow-command.js.map

package/dist/lib/task/workflow-dispatch.js

@@ -1,5 +1,8 @@
+import fs from 'node:fs';
 import { reconcileTaskInvalidation } from './invalidation-command.js';
 import { applyLedgerIntent } from './ledger-intents.js';
+import { isReviewStage, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
+import { resolveTaskRef } from './resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 import { applyWorkflowWarningIntent } from './workflow-warning-intents.js';
 function failed(code, message) {
@@ -102,8 +105,27 @@ function ledgerIntent(operation, args) {
 }
 function warningIntent(args) {
     const [taskRef, kind] = args;
-    if (!taskRef || kind !== 'add')
+    if (!taskRef || !['add', 'list', 'set-status'].includes(kind ?? '')) {
         return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task workflow warning request is invalid');
+    }
+    if (kind === 'list') {
+        const values = options(args, { '--status': 'status' });
+        if (isFailure(values))
+            return values;
+        return { kind, taskRef, ...(value(values, '--status') ? { status: value(values, '--status') } : {}) };
+    }
+    if (kind === 'set-status') {
+        const values = options(args, { '--id': 'id', '--status': 'status', '--resolution': 'resolution', '--dry-run': 'dryRun' });
+        if (isFailure(values))
+            return values;
+        const missing = required(values, ['--id', '--status', '--resolution']);
+        if (missing)
+            return missing;
+        return {
+            kind, taskRef, id: value(values, '--id'), status: value(values, '--status'),
+            resolution: value(values, '--resolution'), ...(values['--dry-run'] === true ? { dryRun: true } : {})
+        };
+    }
     const values = options(args, {
         '--step': 'step', '--severity': 'severity', '--code': 'code', '--target': 'target',
         '--message': 'message', '--action': 'action', '--dry-run': 'dryRun'
@@ -119,6 +141,32 @@ function warningIntent(args) {
         action: value(values, '--action'), ...(values['--dry-run'] === true ? { dryRun: true } : {})
     };
 }
+function stageStatus(repoRoot, args) {
+    const [taskRef, kind] = args;
+    if (!taskRef || kind !== 'stage-status')
+        return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task workflow ledger request is invalid');
+    const values = options(args, { '--stage': 'stage' });
+    if (isFailure(values))
+        return values;
+    const stage = value(values, '--stage');
+    if (!stage || !isReviewStage(stage))
+        return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'stage-status requires a valid review stage');
+    const resolved = resolveTaskRef(taskRef, { repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message);
+    try {
+        const ledger = parseLedgerDocument(fs.readFileSync(resolved.taskMdPath, 'utf8'));
+        if (!ledger.present)
+            return failed('LEDGER_SECTION_MISSING', 'review disagreement ledger section is missing');
+        const invalid = validateLedgerRows(ledger.rows);
+        if (invalid)
+            return failed(invalid.code, invalid.message);
+        return { status: 'ready', changed: false, taskId: resolved.taskId, stageStatus: summarizeLedgerStage(ledger.rows, stage), error: null };
+    }
+    catch (error) {
+        return failed('LEDGER_DOCUMENT_INVALID', error instanceof Error ? error.message : String(error));
+    }
+}
 /**
  * The caller has already selected and authorized the execution boundary.
  * This function deliberately invokes task domains in that process: starting a
@@ -143,11 +191,15 @@ export function dispatchWorkflowCommand(repoRoot, operation, args) {
                 ...(values['--dry-run'] === true ? { dryRun: true } : {})
             }));
         }
-        if (operation === 'warning-add') {
+        if (operation === 'ledger-stage-status')
+            return stageStatus(repoRoot, args);
+        if (operation === 'warning-add' || operation === 'warning-list' || operation === 'warning-set-status') {
             const intent = warningIntent(args);
             if (isFailure(intent))
                 return intent;
-            return withTaskExecutionLock(repoRoot, taskRef, 'task-warning.add', () => applyWorkflowWarningIntent(intent, { repoRoot }));
+            if (intent.kind === 'list')
+                return applyWorkflowWarningIntent(intent, { repoRoot });
+            return withTaskExecutionLock(repoRoot, taskRef, `task-warning.${intent.kind}`, () => applyWorkflowWarningIntent(intent, { repoRoot }));
         }
         const intent = ledgerIntent(operation, args);
         if (isFailure(intent))

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.11.1",
-  "sourceInputHash": "0d66fb32bbdc0982d38a04b86b0278768bb6091eb945ebd90a432f9bae363712",
-  "internalExecutableBuildHash": "4b1edd20ed87d3d742e5e7975fd49b1ac1fb0ff14f837d52ee9ba3ab11318365"
+  "packageVersion": "0.11.2",
+  "sourceInputHash": "0a1ffa8b90a0d157f9b2aabea6a43f946d68a622bde337befe71059f63b3812b",
+  "internalExecutableBuildHash": "b6742e1b5d1b997bf7e21e644bfde2bafaa608f7ede7ca308ff61c2cd19da831"
 }

package/lib/internal/cli-route-inventory.ts

@@ -46,7 +46,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'platform-security': ['read', 'dismiss'],
   'platform-metadata': ['init-labels', 'init-milestones'],
   'platform-context': ['resolve'],
-  'platform-comment': ['list', 'recover', 'owner', 'backfill', 'sync'],
+  'platform-comment': ['list', 'recover', 'owner', 'backfill', 'stage-summary', 'sync'],
   'platform-issue': ['inspect', 'create', 'bind', 'sync'],
   'platform-pr': ['inspect', 'summary-context', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'change-report', 'summary-sync', 'sync-in-labels'],
   'platform-pr-review': ['inspect', 'list', 'publish-pr', 'publish-task'],

package/lib/internal/platform-comment.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
 
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
@@ -8,15 +9,19 @@ import {
   syncPlatformComment
 } from '../platform/issue-comments.ts';
 import type { CommentKind } from '../platform/issue-comments.ts';
+import { canonicalizeSummaryBody } from '../platform/comment-safety.ts';
+import { platformResult } from '../platform/types.ts';
 import type { PlatformResult } from '../platform/types.ts';
 import { recoverTaskFromComments } from '../platform/task-recovery.ts';
 import { backfillCompletionComments } from '../platform/completion-backfill.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-comment list --issue <token> [--cwd <path>]
        agent-infra-internal platform-comment recover --issue <token> --task-id <TASK-id> --output <staging-task.md> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
        agent-infra-internal platform-comment backfill <task-ref> --agent <agent> [--cwd <path>]
+       agent-infra-internal platform-comment stage-summary <task-ref> --body-file <path|-> [--cwd <path>]
        agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
 `;
 
@@ -64,6 +69,7 @@ async function platformComment(args: string[] = []): Promise<void> {
     internalHandlerRoute('platform-comment', 'recover', operation),
     internalHandlerRoute('platform-comment', 'owner', operation),
     internalHandlerRoute('platform-comment', 'backfill', operation),
+    internalHandlerRoute('platform-comment', 'stage-summary', operation),
     internalHandlerRoute('platform-comment', 'sync', operation)
   ].some(Boolean)) { fail('a valid operation is required'); return; }
   const hasTaskRef = operation !== 'list' && operation !== 'recover';
@@ -144,6 +150,38 @@ async function platformComment(args: string[] = []): Promise<void> {
     finish(await backfillCompletionComments(taskRef!, { cwd, agent: normalizedAgent }));
     return;
   }
+  if (internalHandlerRoute('platform-comment', 'stage-summary', operation)) {
+    const unexpected = Object.keys(parsed.values).find((key) => !['cwd', 'bodyFile'].includes(key));
+    if (unexpected) { fail(`stage-summary does not accept '--${unexpected}'`); return; }
+    if (typeof parsed.values.bodyFile !== 'string') { fail('stage-summary requires --body-file'); return; }
+    let body: string;
+    try { body = readBodyFile(parsed.values.bodyFile, cwd); }
+    catch (error) { fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`); return; }
+    const canonical = canonicalizeSummaryBody(body);
+    if (!canonical.ok) { fail(`unable to stage summary: ${canonical.error.code}: ${canonical.error.message}`); return; }
+    body = canonical.value;
+    const resolved = resolveTaskRef(taskRef!, { repoRoot: cwd });
+    if (!resolved.ok || resolved.state !== 'active') { fail('stage-summary requires an active task'); return; }
+    const target = path.join(resolved.taskDir, '.delivery-summary.json');
+    const value = { taskId: resolved.taskId, body, sha256: createHash('sha256').update(body).digest('hex') };
+    const previous = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+    const next = `${JSON.stringify(value)}\n`;
+    if (previous === next) {
+      finish(platformResult('no-op'));
+      return;
+    }
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      fs.writeFileSync(temporary, next, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      fs.renameSync(temporary, target);
+    } catch (error) {
+      try { fs.unlinkSync(temporary); } catch { /* preserve primary error */ }
+      fail(`unable to stage summary: ${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    finish(platformResult('applied', { operations: [{ name: 'delivery-summary', status: 'applied', reasonCode: null }] }));
+    return;
+  }
   if (!internalHandlerRoute('platform-comment', 'sync', operation)) { fail('operation is not registered'); return; }
   const kind = parsed.values.kind;
   const agent = parsed.values.agent;