@fitlab-ai/agent-infra 0.10.0 → 0.11.0

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

@@ -10,8 +10,9 @@ import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-
 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, prepareArtifactRecoveryCommit, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
+import { beginArtifactRecovery, commitArtifactRecovery, prepareArtifactRecoveryFinal, prepareArtifactRecoveryCommit, reconcileArtifactRecovery, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
 const STAGES = {
     analysis: { family: 'review-analysis' },
     plan: { family: 'review-plan' },
@@ -37,6 +38,162 @@ function failed(request, code, message, taskId = null, stageStatus = null, extra
         ...extra
     };
 }
+function preflightFailed(request, code, message, taskId = null, extra = {}) {
+    const { status: _status, intent: _intent, stageStatus: _stageStatus, ...finalizationExtra } = extra;
+    return {
+        ...failed(request, code, message, taskId, null, finalizationExtra),
+        status: 'failed',
+        intent: 'preflight',
+        stageStatus: null
+    };
+}
+/** Validate and seal a review draft before any finding-ledger write. */
+function preflightReviewSummaryUnlocked(request, options = {}) {
+    const stage = request.stage;
+    const spec = STAGES[stage];
+    if (!spec)
+        return preflightFailed(request, 'REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
+    if (!request.taskRef || !request.artifact)
+        return preflightFailed(request, 'REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return preflightFailed(request, resolved.code, resolved.message, resolved.taskId ?? null);
+    if (resolved.state !== 'active')
+        return preflightFailed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+    const parsed = parseArtifactName(request.artifact);
+    if (!parsed || parsed.family !== spec.family)
+        return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${spec.family}`, resolved.taskId);
+    const publicationError = validateArtifactPublication(resolved.taskDir, spec.family, request.artifact);
+    if (publicationError)
+        return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', publicationError.message, resolved.taskId);
+    let taskContent;
+    let content;
+    let recovery;
+    let existingIntent;
+    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);
+            existingIntent = intent;
+            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);
+        }
+    }
+    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' },
+        dryRun: request.dryRun
+    }, { repoRoot: options.repoRoot });
+    if (!execution.ok)
+        return preflightFailed(request, 'REVIEW_PROVENANCE_INVALID', `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`, resolved.taskId);
+    const artifactSha256 = sha256Content(content);
+    const semanticDigest = canonicalSemanticDigest(content);
+    const detail = inspectDecisionDetailDuplicates(content);
+    const structure = inspectArtifactContract(content, getArtifactSchema(spec.family));
+    const expected = expectedQualificationRelations(taskContent, spec.family);
+    if (!expected.ok)
+        return preflightFailed(request, 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', `${expected.code}: ${expected.message}`, resolved.taskId, { artifactSha256, semanticDigest });
+    const qualification = validateQualificationAudit(taskContent, content, {
+        family: spec.family,
+        artifact: request.artifact,
+        expectedUpstreamRelations: expected.relations
+    });
+    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}`),
+            ...(qualificationError ? [`${qualificationError.code}: ${qualificationError.message}`] : [])
+        ].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 (!recovery && existingIntent?.state === 'passed') {
+        return {
+            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest }),
+            status: 'passed', changed: false, error: null
+        };
+    }
+    if (request.dryRun || recovery && readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, spec.family, request.artifact)?.state === 'preflight-ready') {
+        return {
+            ...preflightFailed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, { artifactSha256, semanticDigest, ...(recovery ? { recovery: recoveryInfo(recovery) } : {}) }),
+            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 });
+    }
+}
+function preflightReviewSummary(request, options = {}) {
+    if (request.dryRun || options.lockAlreadyHeld)
+        return preflightReviewSummaryUnlocked(request, options);
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return preflightReviewSummaryUnlocked(request, options);
+    try {
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.preflight', () => preflightReviewSummaryUnlocked(request, { ...options, lockAlreadyHeld: true }));
+    }
+    catch (error) {
+        if (!(error instanceof TaskExecutionLockError))
+            throw error;
+        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;
@@ -76,7 +233,7 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
             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-recovery', 'finalize-ready', 'commit-started'].includes(intent.state))
+            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)
@@ -97,11 +254,15 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     catch (error) {
         return reject('REVIEW_PROVENANCE_INVALID', String(error), digests);
     }
-    if (repairIntent?.state === 'passed' || repairIntent?.state === 'consumed') {
+    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`);
     }
@@ -159,6 +320,12 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     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);
@@ -197,7 +364,7 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
         lockAlreadyHeld: options.lockAlreadyHeld
     };
 }
-function commitReviewSummaryProvenance(prepared, repoRoot) {
+function commitReviewSummaryProvenance(prepared, repoRoot, options = {}) {
     if (prepared.result.status === 'failed' || !prepared.recovery)
         return prepared.result;
     try {
@@ -205,16 +372,40 @@ function commitReviewSummaryProvenance(prepared, repoRoot) {
         if (!intent)
             throw new Error('ARTIFACT_RECOVERY_INTENT_MISSING');
         let committed;
-        if (intent.state === 'finalize-ready' || intent.state === 'commit-started') {
-            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+        if (intent.state === 'passed' || intent.state === 'consumed') {
+            return {
+                ...prepared.result,
+                status: 'no-op',
+                changed: false,
+                artifactSha256: intent.finalArtifactSha256,
+                semanticDigest: intent.finalSemanticDigest,
+                error: null
+            };
         }
-        else {
+        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 });
         }
-        if (committed.state !== 'passed')
-            throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed.state}'`);
+        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 });
+        }
+        else if (intent.state === 'full-finalizer-ready') {
+            committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+        }
+        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,
@@ -223,6 +414,8 @@ function commitReviewSummaryProvenance(prepared, repoRoot) {
         };
     }
     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)}`
             } };
@@ -268,5 +461,5 @@ function finalizeReviewSummary(request, options = {}) {
         return failed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
     }
 }
-export { finalizeReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
+export { finalizeReviewSummary, preflightReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 //# sourceMappingURL=review-finalization.js.map

package/dist/lib/{host-control → task}/secure-fs.js

@@ -1,6 +1,6 @@
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createHash } from 'node:crypto';
 const NO_FOLLOW = fs.constants.O_NOFOLLOW ?? 0;
 const DIRECTORY = fs.constants.O_DIRECTORY ?? 0;
 export class SecureFileError extends Error {
@@ -15,11 +15,8 @@ function conflict(message) {
     throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', message);
 }
 function sameStat(left, right) {
-    return left.dev === right.dev
-        && left.ino === right.ino
-        && left.size === right.size
-        && left.mtimeNs === right.mtimeNs
-        && left.ctimeNs === right.ctimeNs;
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size
+        && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
 }
 function assertNoSymlinkAncestors(candidate) {
     let current = path.dirname(candidate);
@@ -36,15 +33,12 @@ function assertNoSymlinkAncestors(candidate) {
 export async function readStableFile(candidate, options) {
     return readStableFileSync(candidate, options);
 }
-/** Shared bounded reader for synchronous domain commands and async workflow callers. */
 export function readStableFileSync(candidate, options) {
-    if (!path.isAbsolute(candidate)) {
+    if (!path.isAbsolute(candidate))
         conflict('candidate path must be absolute and terminal');
-    }
     assertNoSymlinkAncestors(candidate);
     let descriptor;
     try {
-        // O_NONBLOCK lets fstat reject a FIFO even when it has no writer.
         descriptor = fs.openSync(candidate, fs.constants.O_RDONLY | NO_FOLLOW | (fs.constants.O_NONBLOCK ?? 0));
         const before = fs.fstatSync(descriptor, { bigint: true });
         if (!before.isFile())
@@ -63,18 +57,16 @@ export function readStableFileSync(candidate, options) {
         if (!sameStat(before, after))
             conflict('candidate identity or metadata changed during read');
         const sha256 = createHash('sha256').update(bytes).digest('hex');
-        if (options.expectedSha256 !== undefined && sha256 !== options.expectedSha256) {
+        if (options.expectedSha256 !== undefined && sha256 !== options.expectedSha256)
             conflict('candidate digest does not match the expected digest');
-        }
         return { bytes, sha256, stat: after };
     }
     catch (error) {
         if (error instanceof SecureFileError)
             throw error;
         const code = error.code;
-        if (code === 'ELOOP' || code === 'ENOTSUP' || code === 'EINVAL') {
+        if (code === 'ELOOP' || code === 'ENOTSUP' || code === 'EINVAL')
             conflict('candidate terminal is not a stable non-symlink file');
-        }
         throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', error instanceof Error ? error.message : String(error));
     }
     finally {
@@ -93,9 +85,8 @@ export async function writeAtomicFile(target, bytes, mode = 0o600, expectedSha25
         catch {
             throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is missing');
         }
-        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        if (!stat.isDirectory() || stat.isSymbolicLink())
             throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is not a real directory');
-        }
         const next = path.dirname(current);
         if (next === current)
             break;
@@ -103,9 +94,8 @@ export async function writeAtomicFile(target, bytes, mode = 0o600, expectedSha25
     }
     try {
         const existing = await fs.promises.lstat(target);
-        if (existing.isSymbolicLink() || !existing.isFile()) {
+        if (existing.isSymbolicLink() || !existing.isFile())
             throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative target is not a regular file');
-        }
     }
     catch (error) {
         if (error.code !== 'ENOENT')
@@ -120,7 +110,6 @@ export async function writeAtomicFile(target, bytes, mode = 0o600, expectedSha25
         await handle.chmod(mode);
         await handle.close();
         handle = undefined;
-        // Check after all asynchronous preparation; keep the final check/rename adjacent.
         if (expectedSha256 !== undefined)
             readStableFileSync(target, { maxBytes: 1024 * 1024, expectedSha256 });
         fs.renameSync(temporary, target);

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

@@ -1,7 +1,9 @@
 export const TASK_WORKFLOW_COMMANDS = Object.freeze({
     'artifact-inspect': ['task-artifact', 'inspect'],
     'artifact-init': ['task-artifact', 'init'],
+    'artifact-preflight': ['task-artifact', 'preflight'],
     'artifact-finalize-local': ['task-artifact', 'finalize-local'],
+    'review-preflight': ['task-review', 'preflight'],
     'review-finalize-summary': ['task-review', 'finalize-summary'],
     event: ['task-event', null],
     'ledger-finding-response': ['task-ledger', 'finding-respond'],

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

@@ -0,0 +1,161 @@
+import { reconcileTaskInvalidation } from './invalidation-command.js';
+import { applyLedgerIntent } from './ledger-intents.js';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
+import { applyWorkflowWarningIntent } from './workflow-warning-intents.js';
+function failed(code, message) {
+    return { status: 'failed', changed: false, error: { code, message } };
+}
+function isFailure(value) {
+    return Boolean(value) && typeof value === 'object' && value.status === 'failed';
+}
+function options(args, allowed) {
+    const values = {};
+    for (let index = 2; index < args.length; index += 1) {
+        const flag = args[index];
+        if (flag === '--dry-run') {
+            if (!Object.hasOwn(allowed, flag) || values[flag] !== undefined)
+                return failed('TASK_WORKFLOW_PAYLOAD_INVALID', `invalid option '${flag}'`);
+            values[flag] = true;
+            continue;
+        }
+        const key = allowed[flag];
+        if (!key || values[flag] !== undefined)
+            return failed('TASK_WORKFLOW_PAYLOAD_INVALID', `invalid option '${flag}'`);
+        const value = args[++index];
+        if (value === undefined || value.startsWith('--'))
+            return failed('TASK_WORKFLOW_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+        if (flag === '--needs-implementation' && value !== 'true' && value !== 'false') {
+            return failed('TASK_WORKFLOW_PAYLOAD_INVALID', "option '--needs-implementation' must be true or false");
+        }
+        values[flag] = value;
+    }
+    return values;
+}
+function value(values, flag) {
+    const candidate = values[flag];
+    return typeof candidate === 'string' ? candidate : undefined;
+}
+function required(values, flags) {
+    const missing = flags.find((flag) => value(values, flag) === undefined);
+    return missing ? failed('TASK_WORKFLOW_PAYLOAD_INVALID', `option '${missing}' is required`) : null;
+}
+function resultForLock(error) {
+    if (error instanceof TaskExecutionLockError)
+        return failed(error.code, error.message);
+    throw error;
+}
+function ledgerIntent(operation, args) {
+    const [taskRef, kind] = args;
+    const mappings = {
+        'ledger-finding-response': {
+            kind: 'finding-respond', required: ['--id', '--round', '--status', '--evidence'],
+            flags: { '--id': 'id', '--round': 'round', '--status': 'status', '--evidence': 'evidence', '--dry-run': 'dryRun' }
+        },
+        'ledger-finding-review': {
+            kind: 'finding-review', required: ['--id', '--status', '--evidence'],
+            flags: { '--id': 'id', '--status': 'status', '--evidence': 'evidence', '--needs-implementation': 'needsImplementation', '--dry-run': 'dryRun' }
+        },
+        'ledger-finding-upsert': {
+            kind: 'finding-upsert', required: ['--stage', '--review-artifact', '--ordinal', '--severity', '--evidence'],
+            flags: { '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal', '--severity': 'severity', '--evidence': 'evidence', '--dry-run': 'dryRun' }
+        },
+        'decision-next-id': { kind: 'decision-next-id', required: [], flags: {} },
+        'decision-upsert': {
+            kind: 'decision-upsert', required: ['--id', '--stage', '--artifact'],
+            flags: { '--id': 'id', '--stage': 'stage', '--artifact': 'artifact', '--needs-implementation': 'needsImplementation', '--dry-run': 'dryRun' }
+        }
+    };
+    const mapping = mappings[operation];
+    if (!mapping || !taskRef || kind === undefined)
+        return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task workflow ledger request is invalid');
+    const values = options(args, mapping.flags);
+    if (isFailure(values))
+        return values;
+    const missing = required(values, mapping.required);
+    if (missing)
+        return missing;
+    const dryRun = values['--dry-run'] === true;
+    if (mapping.kind === 'decision-next-id')
+        return { kind: mapping.kind, taskRef };
+    if (mapping.kind === 'finding-respond')
+        return {
+            kind: mapping.kind, taskRef, id: value(values, '--id'), round: Number(value(values, '--round')),
+            status: value(values, '--status'), evidence: value(values, '--evidence'), ...(dryRun ? { dryRun } : {})
+        };
+    if (mapping.kind === 'finding-review')
+        return {
+            kind: mapping.kind, taskRef, id: value(values, '--id'), status: value(values, '--status'),
+            evidence: value(values, '--evidence'), ...(value(values, '--needs-implementation') === 'true' ? { needsImplementation: true } : {}),
+            ...(dryRun ? { dryRun } : {})
+        };
+    if (mapping.kind === 'finding-upsert')
+        return {
+            kind: mapping.kind, taskRef, stage: value(values, '--stage'), reviewArtifact: value(values, '--review-artifact'),
+            ordinal: Number(value(values, '--ordinal')), severity: value(values, '--severity'), evidence: value(values, '--evidence'),
+            ...(dryRun ? { dryRun } : {})
+        };
+    return {
+        kind: mapping.kind, taskRef, id: value(values, '--id'), stage: value(values, '--stage'),
+        artifact: value(values, '--artifact'), ...(value(values, '--needs-implementation') === 'true' ? { needsImplementation: true } : {}),
+        ...(dryRun ? { dryRun } : {})
+    };
+}
+function warningIntent(args) {
+    const [taskRef, kind] = args;
+    if (!taskRef || kind !== 'add')
+        return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task workflow warning request is invalid');
+    const values = options(args, {
+        '--step': 'step', '--severity': 'severity', '--code': 'code', '--target': 'target',
+        '--message': 'message', '--action': 'action', '--dry-run': 'dryRun'
+    });
+    if (isFailure(values))
+        return values;
+    const missing = required(values, ['--step', '--severity', '--code', '--target', '--message', '--action']);
+    if (missing)
+        return missing;
+    return {
+        kind: 'add', taskRef, step: value(values, '--step'), severity: value(values, '--severity'),
+        code: value(values, '--code'), target: value(values, '--target'), message: value(values, '--message'),
+        action: value(values, '--action'), ...(values['--dry-run'] === true ? { dryRun: true } : {})
+    };
+}
+/**
+ * The caller has already selected and authorized the execution boundary.
+ * This function deliberately invokes task domains in that process: starting a
+ * second CLI process would discard the broker binding and could misclassify a
+ * sandbox process with cleared environment variables as direct-host.
+ */
+export function dispatchWorkflowCommand(repoRoot, operation, args) {
+    const taskRef = args[0];
+    if (!taskRef)
+        return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task ref is required');
+    try {
+        if (operation === 'invalidation-reconcile') {
+            const values = options(args, { '--max-targets': 'maxTargets', '--dry-run': 'dryRun' });
+            if (isFailure(values))
+                return values;
+            const maxTargets = value(values, '--max-targets');
+            if (maxTargets !== undefined && (!Number.isSafeInteger(Number(maxTargets)) || Number(maxTargets) < 1)) {
+                return failed('TASK_WORKFLOW_PAYLOAD_INVALID', '--max-targets must be a positive integer');
+            }
+            return withTaskExecutionLock(repoRoot, taskRef, 'task-invalidation.reconcile', () => reconcileTaskInvalidation(taskRef, {
+                repoRoot, ...(maxTargets === undefined ? {} : { maxTargets: Number(maxTargets) }),
+                ...(values['--dry-run'] === true ? { dryRun: true } : {})
+            }));
+        }
+        if (operation === 'warning-add') {
+            const intent = warningIntent(args);
+            if (isFailure(intent))
+                return intent;
+            return withTaskExecutionLock(repoRoot, taskRef, 'task-warning.add', () => applyWorkflowWarningIntent(intent, { repoRoot }));
+        }
+        const intent = ledgerIntent(operation, args);
+        if (isFailure(intent))
+            return intent;
+        return withTaskExecutionLock(repoRoot, taskRef, `task-ledger.${intent.kind}`, () => applyLedgerIntent(intent, { repoRoot }));
+    }
+    catch (error) {
+        return resultForLock(error);
+    }
+}
+//# sourceMappingURL=workflow-dispatch.js.map

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.10.0",
-  "sourceInputHash": "d7af8de4bd6c1996a920335dfc766e23b8d391cd4db2965d7d9dfaa2cb112059",
-  "internalExecutableBuildHash": "63a6d2d9113dd353dfce165efccf82a5ea25398c2aad9f1b2c5543dc28e8b833"
+  "packageVersion": "0.11.0",
+  "sourceInputHash": "c67e66a46040d5246d67c751af605b796cd61913b98add01ff327829c01ce3db",
+  "internalExecutableBuildHash": "f6b4be06df12111b3a7614d335c9e802049c3cea194c6e7c040f3251188c694f"
 }

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

@@ -36,7 +36,6 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'task-create': ['input'],
   'task-qualification': ['proposal', 'confirm', 'supersede', 'revoke'],
   'sandbox-control': ['serve', 'execute', 'recover', 'client'],
-  'host-control': ['serve', 'status', 'install', 'uninstall'],
   'agent-client': ['next-steps', 'model-selection'],
   'codex-lifecycle': ['preflight', 'capability-arm', 'hook-event', 'resolve-start', 'resolve-stop', 'consume'],
   'codex-sandbox-controller': ['verify-context', 'run'],
@@ -47,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', 'owner', 'backfill', 'sync'],
+  'platform-comment': ['list', 'recover', 'owner', 'backfill', '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'],
@@ -57,9 +56,9 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'task-ledger': ['decision-next-id', 'stage-status', 'finding-upsert', 'finding-respond', 'finding-review', 'decision-upsert', 'rework-intent-upsert'],
   'task-warning': ['list', 'add', 'set-status'],
   'task-activity': ['pr-review-inspect', 'pr-review-start', 'pr-review-complete', 'pr-review-terminate'],
-  'task-artifact': ['inspect', 'init', 'finalize-local'],
+  'task-artifact': ['inspect', 'init', 'preflight', 'finalize-local'],
   'task-orchestration': ['status', 'progress'],
-  'task-review': ['finalize-summary'],
+  'task-review': ['preflight', 'finalize-summary'],
   'task-event': ['event'],
   'task-invalidation': ['reconcile'],
   'task-override': ['diagnose', 'issue', 'consume'],