@fitlab-ai/agent-infra 0.10.0 → 0.11.0

package/lib/task/review-finalization.ts

@@ -14,11 +14,14 @@ import { allowsManualOverride } from './guard-override.ts';
 import type { ManualOverrideCapability } from './guard-override.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
 import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.ts';
+import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.ts';
 import { readArtifactRecoveryIntent } from './artifact-repair-intent.ts';
 import {
   beginArtifactRecovery,
   commitArtifactRecovery,
+  prepareArtifactRecoveryFinal,
   prepareArtifactRecoveryCommit,
+  reconcileArtifactRecovery,
   recoveryContextFromIntent,
   stageArtifactCandidate
 } from './artifact-recovery.ts';
@@ -36,6 +39,7 @@ type ReviewFinalizationErrorCode =
   | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
   | 'REVIEW_SUMMARY_COUNT_MISMATCH'
   | 'REVIEW_ARTIFACT_STRUCTURE_INVALID'
+  | 'REVIEW_ARTIFACT_QUALIFICATION_INVALID'
   | 'REVIEW_DECISION_DETAIL_INVALID'
   | 'REVIEW_ARTIFACT_CONFLICT'
   | 'REVIEW_PROVENANCE_INVALID'
@@ -73,6 +77,11 @@ type ReviewFinalizationResult = {
   }[];
   error: ReviewFinalizationError | null;
 };
+type ReviewPreflightResult = Omit<ReviewFinalizationResult, 'status' | 'intent' | 'stageStatus'> & {
+  status: 'passed' | 'failed';
+  intent: 'preflight';
+  stageStatus: null;
+};
 type ReviewFileSystem = {
   readFileSync: (file: string) => string;
 };
@@ -118,6 +127,149 @@ function failed(
   };
 }
 
+function preflightFailed(
+  request: ReviewFinalizationRequest,
+  code: ReviewFinalizationErrorCode,
+  message: string,
+  taskId: string | null = null,
+  extra: Partial<ReviewPreflightResult> = {}
+): ReviewPreflightResult {
+  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: ReviewFinalizationRequest,
+  options: ReviewFinalizationOptions = {}
+): ReviewPreflightResult {
+  const stage = request.stage as ReviewStage;
+  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: string;
+  let content: string;
+  let recovery: ArtifactRecoveryContext | undefined;
+  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: ReviewFinalizationRequest,
+  options: ReviewFinalizationOptions = {}
+): ReviewPreflightResult {
+  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);
+  }
+}
+
 type ReviewSummaryCandidatePreparation = Readonly<{
   result: ReviewFinalizationResult;
   content: string;
@@ -125,6 +277,15 @@ type ReviewSummaryCandidatePreparation = Readonly<{
   lockAlreadyHeld?: boolean;
 }>;
 
+function recoveryInfo(recovery: ArtifactRecoveryContext): NonNullable<ReviewFinalizationResult['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: ReviewFinalizationRequest,
@@ -158,7 +319,7 @@ function prepareReviewSummaryCandidate(
     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-recovery', 'finalize-ready', 'commit-started'].includes(intent.state)) return reject('REVIEW_PROVENANCE_INVALID', `recovery journal is in '${intent.state}' 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)
         ? fs.readFileSync(recovery.stagingPath, 'utf8')
@@ -171,11 +332,15 @@ function prepareReviewSummaryCandidate(
   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 === '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`);
   }
@@ -223,6 +388,12 @@ function prepareReviewSummaryCandidate(
   const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
   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 {
@@ -260,21 +431,43 @@ function prepareReviewSummaryCandidate(
 
 function commitReviewSummaryProvenance(
   prepared: ReviewSummaryCandidatePreparation,
-  repoRoot: string
+  repoRoot: string,
+  options: Readonly<{ afterPublish?: () => void }> = {}
 ): ReviewFinalizationResult {
   if (prepared.result.status === 'failed' || !prepared.recovery) return prepared.result;
   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 === 'finalize-ready' || intent.state === 'commit-started') {
-      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
-    } else {
+    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 });
+    } else if (intent.state === 'full-finalizer-ready') {
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
     }
-    if (committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed.state}'`);
+    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,
@@ -282,6 +475,7 @@ function commitReviewSummaryProvenance(
       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)}`
     } };
@@ -335,12 +529,13 @@ function finalizeReviewSummary(
   }
 }
 
-export { finalizeReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
+export { finalizeReviewSummary, preflightReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 export type {
   ReviewFinalizationError,
   ReviewFinalizationErrorCode,
   ReviewFinalizationOptions,
   ReviewFinalizationRequest,
   ReviewFinalizationResult,
+  ReviewPreflightResult,
   ReviewSummaryCandidatePreparation
 };

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

@@ -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;
@@ -25,11 +25,8 @@ function conflict(message: string): never {
 }
 
 function sameStat(left: fs.BigIntStats, right: fs.BigIntStats): boolean {
-  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: string): void {
@@ -43,25 +40,15 @@ function assertNoSymlinkAncestors(candidate: string): void {
   }
 }
 
-export async function readStableFile(
-  candidate: string,
-  options: Readonly<{ maxBytes: number; expectedSha256?: string }>
-): Promise<StableFile> {
+export async function readStableFile(candidate: string, options: Readonly<{ maxBytes: number; expectedSha256?: string }>): Promise<StableFile> {
   return readStableFileSync(candidate, options);
 }
 
-/** Shared bounded reader for synchronous domain commands and async workflow callers. */
-export function readStableFileSync(
-  candidate: string,
-  options: Readonly<{ maxBytes: number; expectedSha256?: string }>
-): StableFile {
-  if (!path.isAbsolute(candidate)) {
-    conflict('candidate path must be absolute and terminal');
-  }
+export function readStableFileSync(candidate: string, options: Readonly<{ maxBytes: number; expectedSha256?: string }>): StableFile {
+  if (!path.isAbsolute(candidate)) conflict('candidate path must be absolute and terminal');
   assertNoSymlinkAncestors(candidate);
   let descriptor: number | undefined;
   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()) conflict('candidate is not a regular file');
@@ -76,16 +63,12 @@ export function readStableFileSync(
     const after = fs.fstatSync(descriptor, { bigint: true });
     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) {
-      conflict('candidate digest does not match the expected digest');
-    }
+    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 as NodeJS.ErrnoException).code;
-    if (code === 'ELOOP' || code === 'ENOTSUP' || code === 'EINVAL') {
-      conflict('candidate terminal is not a stable non-symlink file');
-    }
+    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 {
     if (descriptor !== undefined) fs.closeSync(descriptor);
@@ -99,18 +82,14 @@ export async function writeAtomicFile(target: string, bytes: Buffer, mode = 0o60
     let stat: fs.Stats;
     try { stat = await fs.promises.lstat(current); }
     catch { throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is missing'); }
-    if (!stat.isDirectory() || stat.isSymbolicLink()) {
-      throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative parent directory is not a real directory');
-    }
+    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;
     current = next;
   }
   try {
     const existing = await fs.promises.lstat(target);
-    if (existing.isSymbolicLink() || !existing.isFile()) {
-      throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative target is not a regular file');
-    }
+    if (existing.isSymbolicLink() || !existing.isFile()) throw new SecureFileError('TASK_ARTIFACT_WRITE_CONFLICT', 'authoritative target is not a regular file');
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
   }
@@ -123,7 +102,6 @@ export async function writeAtomicFile(target: string, bytes: Buffer, mode = 0o60
     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);
     const directory = await fs.promises.open(parent, fs.constants.O_RDONLY | DIRECTORY);

package/lib/task/workflow-command.ts

@@ -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/lib/task/workflow-dispatch.ts

@@ -0,0 +1,171 @@
+import { reconcileTaskInvalidation } from './invalidation-command.ts';
+import { applyLedgerIntent } from './ledger-intents.ts';
+import type { LedgerIntent } from './ledger-intents.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
+import type { TaskWorkflowOperation } from './workflow-command.ts';
+import { applyWorkflowWarningIntent } from './workflow-warning-intents.ts';
+import type { WorkflowWarningIntent } from './workflow-warning-intents.ts';
+
+export type WorkflowDispatchResult = Readonly<Record<string, unknown>>;
+
+type OptionValues = Readonly<Record<string, string | boolean>>;
+type DispatchFailure = Readonly<{
+  status: 'failed';
+  changed: false;
+  error: Readonly<{ code: string; message: string }>;
+}>;
+
+function failed(code: string, message: string): DispatchFailure {
+  return { status: 'failed', changed: false, error: { code, message } };
+}
+
+function isFailure(value: unknown): value is DispatchFailure {
+  return Boolean(value) && typeof value === 'object' && (value as { status?: unknown }).status === 'failed';
+}
+
+function options(
+  args: readonly string[],
+  allowed: Readonly<Record<string, string>>
+): OptionValues | DispatchFailure {
+  const values: Record<string, string | boolean> = {};
+  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: OptionValues, flag: string): string | undefined {
+  const candidate = values[flag];
+  return typeof candidate === 'string' ? candidate : undefined;
+}
+
+function required(values: OptionValues, flags: readonly string[]): DispatchFailure | null {
+  const missing = flags.find((flag) => value(values, flag) === undefined);
+  return missing ? failed('TASK_WORKFLOW_PAYLOAD_INVALID', `option '${missing}' is required`) : null;
+}
+
+function resultForLock(error: unknown): WorkflowDispatchResult {
+  if (error instanceof TaskExecutionLockError) return failed(error.code, error.message);
+  throw error;
+}
+
+function ledgerIntent(operation: TaskWorkflowOperation, args: readonly string[]): LedgerIntent | DispatchFailure {
+  const [taskRef, kind] = args;
+  const mappings: Partial<Record<TaskWorkflowOperation, {
+    kind: LedgerIntent['kind']; required: readonly string[]; flags: Readonly<Record<string, string>>;
+  }>> = {
+    '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') as never, evidence: value(values, '--evidence')!, ...(dryRun ? { dryRun } : {})
+  } as LedgerIntent;
+  if (mapping.kind === 'finding-review') return {
+    kind: mapping.kind, taskRef, id: value(values, '--id')!, status: value(values, '--status') as never,
+    evidence: value(values, '--evidence')!, ...(value(values, '--needs-implementation') === 'true' ? { needsImplementation: true } : {}),
+    ...(dryRun ? { dryRun } : {})
+  } as LedgerIntent;
+  if (mapping.kind === 'finding-upsert') return {
+    kind: mapping.kind, taskRef, stage: value(values, '--stage') as never, reviewArtifact: value(values, '--review-artifact')!,
+    ordinal: Number(value(values, '--ordinal')), severity: value(values, '--severity') as never, evidence: value(values, '--evidence')!,
+    ...(dryRun ? { dryRun } : {})
+  } as LedgerIntent;
+  return {
+    kind: mapping.kind, taskRef, id: value(values, '--id')!, stage: value(values, '--stage') as never,
+    artifact: value(values, '--artifact')!, ...(value(values, '--needs-implementation') === 'true' ? { needsImplementation: true } : {}),
+    ...(dryRun ? { dryRun } : {})
+  } as LedgerIntent;
+}
+
+function warningIntent(args: readonly string[]): WorkflowWarningIntent | DispatchFailure {
+  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') as never,
+    code: value(values, '--code')!, target: value(values, '--target')!, message: value(values, '--message')!,
+    action: value(values, '--action')!, ...(values['--dry-run'] === true ? { dryRun: true } : {})
+  } as WorkflowWarningIntent;
+}
+
+/**
+ * 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: string,
+  operation: TaskWorkflowOperation,
+  args: readonly string[]
+): WorkflowDispatchResult {
+  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);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/rules/issue-sync.en.md

@@ -11,12 +11,18 @@
 | `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+| `recoveryAction` | `<!-- sync-issue:{task-id}:recovery-action:{action-id} -->` |
+| `recoveryPrepare` | `<!-- sync-issue:{task-id}:recovery-prepare:{commit-id} -->` |
+| `recoveryCommit` | `<!-- sync-issue:{task-id}:recovery-commit:{commit-id} -->` |
 
 `pr-review` content is synced only as an Issue artifact comment (via the `artifact` / `artifactChunk` markers) and is never a `restore-task` recovery source; restore still accepts only an Issue token and reads only registered Issue markers, with no PR source.
 
 Comments use `platform-comment`; Issue resources use `platform-issue`:
 
 ```bash
+agent-infra-internal platform-comment list --issue <issue-token> [--cwd <path>]
+agent-infra-internal platform-comment recover --issue <issue-token> --task-id <TASK-id> \
+  --output <.agents/workspace/.restore-staging-*/task.md> [--cwd <path>]
 agent-infra-internal platform-issue inspect {task-id}
 agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
 agent-infra-internal platform-issue bind {task-id} --issue {issue-token} --agent {standard-agent-token}
@@ -25,7 +31,9 @@ agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token
 
 The core owns status/in labels, assignees, milestones, Issue Type, pinned fields, requirements, state, capabilities, dry-run, retries, errors, and idempotency. Omitted flags preserve values; `none` explicitly clears them. Status labels converge to at most one, and ambiguous requirement identity fails closed.
 
-Task content over the platform comment byte limit is not uploaded; the core returns a skipped operation with `COMMENT_PAYLOAD_TOO_LARGE`. The local task file is unchanged, and platform verification skips the task marker/content check for the same oversized input.
+The task comment synchronizes only a deterministic current-task projection. Process sections such as the Activity Log, Artifact Lifecycle Receipts, and invalidation records are carried by the recovery transaction. Byte preflight and platform verification consume the same final rendered UTF-8 body.
+
+Recovery comments use `recovery-action`, `recovery-prepare`, and `recovery-commit` markers with a stable recovery id and a body file. Task sync publishes prepare, action, a task snapshot that is written and re-read, and then commit. Replaying identical content is a no-op; conflicting immutable content fails with `RECOVERY_IMMUTABLE_CONFLICT`. Restore accepts only an author-consistent, complete, phase/digest/marker-valid transaction bound to the current task comment body SHA-256.
 
 PR event `in:` synchronization uses `agent-infra-internal platform-pr sync-in-labels --pr <N> [--cwd <path>]`. PR files are the event evidence; a unique closing Issue is written and re-read before the PR. Zero or multiple closing Issues update only the PR and return `degraded`; unknown side effects or failed convergence return `blocked` with `IN_LABEL_SYNC_PARTIAL`.