@fitlab-ai/agent-infra 0.9.15 → 0.10.0

package/lib/task/pr-delivery-fact.ts

@@ -1,5 +1,4 @@
 import type { ResourceIdentity } from '../platform/resource-identity.ts';
-import { isLegacyCompatibilityEnabled, legacyCompatibilityError, VERSION } from '../version.ts';
 import {
   isResourceIdentity,
   parseResourceIdentity,
@@ -17,14 +16,6 @@ type PrDeliveryIdentity = {
   base: { repository: string; ref: string; sha: string };
 };
 
-type LegacyPrDeliveryIdentity = {
-  repository: string;
-  number: number;
-  nodeId: string;
-  url: string;
-  head: { repository: string; ref: string; sha: string };
-  base: { repository: string; ref: string; sha: string };
-};
 type CurrentPrDeliveryIdentityInput = {
   resource: ResourceIdentity;
   repository: string;
@@ -93,10 +84,6 @@ function timestamp(value: unknown, label: string): string {
   if (Number.isNaN(Date.parse(result))) throw factError(`${label} must be a valid timestamp`);
   return new Date(result).toISOString();
 }
-function positiveNumber(value: unknown, label: string): number {
-  if (!Number.isSafeInteger(value) || (value as number) <= 0) throw factError(`${label} must be a positive integer`);
-  return value as number;
-}
 function parseRef(value: unknown, label: string): { repository: string; ref: string; sha: string } {
   if (!isRecord(value)) throw factError(`${label} must be an object`);
   exactKeys(value, ['repository', 'ref', 'sha'], label);
@@ -115,35 +102,19 @@ function canonicalIdentity(value: unknown): PrDeliveryIdentity {
   };
 }
 
-function decodeLegacyIdentity(value: unknown): PrDeliveryIdentity {
-  if (!isRecord(value)) throw factError('legacy identity must be an object');
-  // TODO(compat): Remove the v1 identity decoder before the first stable v1.0.0 release.
-  exactKeys(value, ['repository', 'number', 'nodeId', 'url', 'head', 'base'], 'legacy identity');
-  const legacy = {
-    number: positiveNumber(value.number, 'legacy identity.number'),
-    repository: text(value.repository, 'identity.repository'),
-    nodeId: text(value.nodeId, 'legacy identity.nodeId'),
-    url: text(value.url, 'identity.url'),
-    head: parseRef(value.head, 'identity.head'),
-    base: parseRef(value.base, 'identity.base')
-  } satisfies LegacyPrDeliveryIdentity;
-  return {
-    resource: { kind: 'number', value: legacy.number },
-    repository: legacy.repository,
-    url: legacy.url,
-    head: legacy.head,
-    base: legacy.base
-  };
-}
-
 function provenanceForSource(source: PrDeliveryBindingSource): PrDeliveryProvenance { return source === 'created' ? 'create-post' : source === 'reused' ? 'reuse' : source; }
 
-function parseFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
+function legacyFactError(): PrDeliveryFactError {
+  return Object.assign(
+    new Error('PLATFORM_IDENTITY_LEGACY_UNSUPPORTED: v1 PR delivery fact is unsupported; use the previous tool version to view this task or migrate its fact to version 2 before using this version'),
+    { code: 'PLATFORM_IDENTITY_LEGACY_UNSUPPORTED' }
+  );
+}
+
+function parseFact(value: unknown): PrDeliveryFact {
   if (!isRecord(value)) throw factError('fact must be an object');
-  if ((value.version !== 1 && value.version !== 2) || typeof value.state !== 'string') throw factError('version or state is invalid');
-  if (value.version === 1 && !isLegacyCompatibilityEnabled(runtimeVersion)) {
-    throw legacyCompatibilityError('v1 PR delivery fact', runtimeVersion);
-  }
+  if (value.version === 1) throw legacyFactError();
+  if (value.version !== 2 || typeof value.state !== 'string') throw factError('version or state is invalid');
   if (value.state === 'unbound') {
     exactKeys(value, ['version', 'state', 'reason'], 'unbound fact');
     if (value.reason !== 'initial') throw factError('unbound reason is invalid');
@@ -155,24 +126,6 @@ function parseFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
     return { version: 2, state: 'skipped', reason: 'explicit', decidedAt: timestamp(value.decidedAt, 'skipped.decidedAt') };
   }
   if (value.state !== 'bound') throw factError('state is invalid');
-  if (value.version === 1) {
-    // TODO(compat): Remove this v1-to-v2 shape conversion before the first stable v1.0.0 release.
-    exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'legacy bound fact');
-    if (!isRecord(value.binding) || !isRecord(value.provenance)) throw factError('legacy binding or provenance is invalid');
-    exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueNumber', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'legacy binding');
-    const issueNumber = value.binding.issueNumber === null ? null : positiveNumber(value.binding.issueNumber, 'legacy binding.issueNumber');
-    return parseFact({
-      version: 2,
-      state: 'bound',
-      identity: decodeLegacyIdentity(value.identity),
-      binding: {
-        status: 'verified', source: value.binding.source, verifiedAt: timestamp(value.binding.verifiedAt, 'binding.verifiedAt'),
-        issueIdentity: issueNumber === null ? null : { kind: 'number', value: issueNumber }, remoteState: value.binding.remoteState,
-        mergedAt: value.binding.mergedAt === null ? null : timestamp(value.binding.mergedAt, 'binding.mergedAt'), mergeCommitSha: nullableText(value.binding.mergeCommitSha, 'binding.mergeCommitSha')
-      },
-      provenance: value.provenance
-    }, runtimeVersion);
-  }
   exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'bound fact');
   if (!isRecord(value.binding) || !isRecord(value.provenance)) throw factError('binding or provenance is invalid');
   exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueIdentity', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'binding');
@@ -195,19 +148,19 @@ function parseFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
   };
 }
 
-function decodePrDeliveryFact(value: unknown, runtimeVersion = VERSION): PrDeliveryFact {
+function decodePrDeliveryFact(value: unknown, _runtimeVersion?: string): PrDeliveryFact {
   if (typeof value === 'string') {
     let decoded: unknown;
     try { decoded = JSON.parse(value); }
     catch { throw factError('value is not valid JSON'); }
-    return parseFact(decoded, runtimeVersion);
+    return parseFact(decoded);
   }
-  return parseFact(value, runtimeVersion);
+  return parseFact(value);
 }
 function encodePrDeliveryFact(fact: PrDeliveryFact): string { return JSON.stringify(parseFact(fact)); }
-function readPrDeliveryFact(metadata: Record<string, unknown>, runtimeVersion = VERSION): PrDeliveryFactReadResult {
+function readPrDeliveryFact(metadata: Record<string, unknown>, _runtimeVersion?: string): PrDeliveryFactReadResult {
   if (!Object.hasOwn(metadata, PR_DELIVERY_FACT_KEY) || metadata[PR_DELIVERY_FACT_KEY] === '') return { status: 'missing', fact: null };
-  try { return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY], runtimeVersion) }; }
+  try { return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY]) }; }
   catch (error) { return { status: 'invalid', fact: null, error: asFactError(error) }; }
 }
 function buildUnboundFact(): PrDeliveryFact { return { version: 2, state: 'unbound', reason: 'initial' }; }

package/lib/task/recovery-warning.ts

@@ -0,0 +1,21 @@
+export type RecoveryWarning = Readonly<{ code: string; message: string; action: string }>;
+
+function warningText(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.trim() === value && !/[\r\n]/u.test(value);
+}
+
+export function isRecoveryWarning(value: unknown): value is RecoveryWarning {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const warning = value as Record<string, unknown>;
+  return Object.keys(warning).sort().join(',') === 'action,code,message'
+    && warningText(warning.code)
+    && warningText(warning.message)
+    && warningText(warning.action);
+}
+
+export function sameRecoveryWarning(left: unknown, right: unknown): boolean {
+  return isRecoveryWarning(left) && isRecoveryWarning(right)
+    && left.code === right.code
+    && left.message === right.message
+    && left.action === right.action;
+}

package/lib/task/review-command.ts

@@ -7,6 +7,7 @@ export function parseReviewCommand(args: readonly string[]): ReviewFinalizationR
   const values: Record<string, string | boolean> = {};
   const flags = {
     '--stage': 'stage', '--artifact': 'artifact', '--orchestrated': 'orchestrated', '--dry-run': 'dryRun',
+    '--recovery-id': 'recoveryId',
     '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
   } as const;
   for (let index = 2; index < args.length; index += 1) {

package/lib/task/review-finalization.ts

@@ -1,6 +1,4 @@
 import fs from 'node:fs';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
 
 import { parseArtifactName } from './artifact-name.ts';
 import { validateCompletedArtifact, hasOpenArtifactRound, validateArtifactPublication } from './artifact-lifecycle.ts';
@@ -16,9 +14,15 @@ 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 { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.ts';
-import type { ArtifactRepairOperation } from './artifact-operations.ts';
-import type { ArtifactRepairIntent } from './artifact-repair-intent.ts';
+import { readArtifactRecoveryIntent } from './artifact-repair-intent.ts';
+import {
+  beginArtifactRecovery,
+  commitArtifactRecovery,
+  prepareArtifactRecoveryCommit,
+  recoveryContextFromIntent,
+  stageArtifactCandidate
+} from './artifact-recovery.ts';
+import type { ArtifactRecoveryContext } from './artifact-recovery.ts';
 
 type ReviewFinalizationErrorCode =
   | ResolveTaskRefErrorCode
@@ -35,8 +39,7 @@ type ReviewFinalizationErrorCode =
   | 'REVIEW_DECISION_DETAIL_INVALID'
   | 'REVIEW_ARTIFACT_CONFLICT'
   | 'REVIEW_PROVENANCE_INVALID'
-  | 'REVIEW_TEMP_WRITE_FAILED'
-  | 'REVIEW_RENAME_FAILED';
+  | 'REVIEW_RECOVERY_COMMIT_FAILED';
 type ReviewFinalizationError = { code: ReviewFinalizationErrorCode; message: string };
 type ReviewFinalizationRequest = {
   taskRef: string;
@@ -44,6 +47,7 @@ type ReviewFinalizationRequest = {
   artifact: string;
   orchestrated?: boolean;
   dryRun?: boolean;
+  recoveryId?: string;
 };
 type ReviewFinalizationResult = {
   status: 'planned' | 'applied' | 'no-op' | 'failed';
@@ -56,8 +60,12 @@ type ReviewFinalizationResult = {
   stageStatus: LedgerStageStatus | null;
   artifactSha256: string | null;
   semanticDigest: string | null;
-  repairable: boolean;
-  operation: ArtifactRepairOperation | null;
+  recovery?: Readonly<{
+    recoveryId: string;
+    candidatePath: string;
+    baselineSha256: string;
+    baselineSemanticDigest: string;
+  }>;
   operations: readonly {
     kind: 'artifact';
     artifact: string;
@@ -67,17 +75,13 @@ type ReviewFinalizationResult = {
 };
 type ReviewFileSystem = {
   readFileSync: (file: string) => string;
-  statModeSync: (file: string) => number;
-  writeFileSync: (file: string, content: string, mode: number) => void;
-  renameSync: (from: string, to: string) => void;
-  unlinkSync: (file: string) => void;
 };
 type ReviewFinalizationOptions = {
   repoRoot?: string;
-  randomSuffix?: () => string;
   fileSystem?: Partial<ReviewFileSystem>;
   manualOverride?: ManualOverrideCapability;
   lockAlreadyHeld?: boolean;
+  startRecovery?: boolean;
 };
 
 const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code' }> = {
@@ -86,11 +90,7 @@ const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' |
   code: { family: 'review-code' }
 };
 const DEFAULT_FILE_SYSTEM: ReviewFileSystem = {
-  readFileSync: (file) => fs.readFileSync(file, 'utf8'),
-  statModeSync: (file) => fs.statSync(file).mode,
-  writeFileSync: (file, content, mode) => fs.writeFileSync(file, content, { encoding: 'utf8', flag: 'wx', mode }),
-  renameSync: (from, to) => fs.renameSync(from, to),
-  unlinkSync: (file) => fs.unlinkSync(file)
+  readFileSync: (file) => fs.readFileSync(file, 'utf8')
 };
 
 function failed(
@@ -112,27 +112,17 @@ function failed(
     stageStatus,
     artifactSha256: null,
     semanticDigest: null,
-    repairable: false,
-    operation: null,
     operations: [],
     error: { code, message },
     ...extra
   };
 }
 
-function cleanupTemp(fileSystem: ReviewFileSystem, tempPath: string): void {
-  try {
-    fileSystem.unlinkSync(tempPath);
-  } catch {
-    // Best-effort cleanup preserves the primary failure.
-  }
-}
-
 type ReviewSummaryCandidatePreparation = Readonly<{
   result: ReviewFinalizationResult;
   content: string;
-  provenance?: Parameters<typeof writeArtifactRepairIntent>[1];
-  expectedIntent?: ArtifactRepairIntent | null;
+  recovery?: ArtifactRecoveryContext;
+  lockAlreadyHeld?: boolean;
 }>;
 
 /** Prepare domain validation, summary bytes and provenance before any publication. */
@@ -163,39 +153,28 @@ function prepareReviewSummaryCandidate(
   let taskContent: string;
   try { taskContent = (options.fileSystem?.readFileSync ?? DEFAULT_FILE_SYSTEM.readFileSync)(resolved.taskMdPath); }
   catch (error) { return reject('REVIEW_ARTIFACT_NOT_REGULAR', String(error)); }
+  let recovery: ArtifactRecoveryContext | undefined;
+  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-recovery', 'finalize-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 = readArtifactRepairIntent(resolved.repoRoot, taskId!, spec.family, request.artifact); }
+  try { repairIntent = readArtifactRecoveryIntent(resolved.repoRoot, taskId!, spec.family, request.artifact); }
   catch (error) { return reject('REVIEW_PROVENANCE_INVALID', String(error), digests); }
-  const schema = getArtifactSchema(spec.family)!;
-  const structure = inspectArtifactContract(artifactContent, schema);
-  if (!structure.ok) {
-    const repairable = structure.repair !== null && structure.diagnostics.length === 1 && structure.diagnostics[0]?.repairable === true;
-    if (repairable && repairIntent && (repairIntent.state !== 'awaiting-repair'
-      || repairIntent.artifactSha256 !== artifactSha256 || repairIntent.semanticDigest !== structure.semanticDigest)) {
-      return reject('REVIEW_PROVENANCE_INVALID', 'a different review repair baseline is already recorded for this artifact', digests);
+  if (repairIntent?.state === 'passed' || 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);
     }
-    return {
-      ...reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
-        artifactSha256, semanticDigest: structure.semanticDigest, repairable, operation: structure.repair
-      }),
-      ...(repairable && !repairIntent ? { provenance: {
-        version: 2 as const, taskId: taskId!, family: spec.family, artifact: request.artifact,
-        state: 'awaiting-repair' as const, baselineSemanticDigest: structure.semanticDigest,
-        artifactSha256, semanticDigest: structure.semanticDigest,
-        recoveryOperationId: null, phase: null, authorityDigest: null,
-        requestId: `review-finalize:${taskId!}`, createdAt: Date.now(), updatedAt: Date.now()
-      }, expectedIntent: null } : {})
-    };
-  }
-  if (repairIntent?.state === 'awaiting-repair' && repairIntent.baselineSemanticDigest !== semanticDigest) {
-    return reject('REVIEW_PROVENANCE_INVALID', 'the repaired review artifact semantic digest does not match the recorded repair baseline', digests);
-  }
-  if ((repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')
-    && (repairIntent.artifactSha256 !== artifactSha256 || repairIntent.semanticDigest !== semanticDigest)) {
-    return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', digests);
   }
   if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) {
     return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`);
@@ -217,9 +196,54 @@ function prepareReviewSummaryCandidate(
   } catch (error) { return reject('REVIEW_LEDGER_INVALID', String(error)); }
   const detail = inspectDecisionDetailDuplicates(artifactContent);
   if (!detail.ok) return reject('REVIEW_DECISION_DETAIL_INVALID', `${detail.code}: ${detail.message}`);
+  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 } : {})
+    };
+  }
   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 === '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: {
@@ -229,10 +253,8 @@ function prepareReviewSummaryCandidate(
       operations: transformed.changed ? [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }] : [],
       error: null
     },
-    ...(repairIntent?.state === 'awaiting-repair' ? {
-      provenance: { ...repairIntent, state: 'passed' as const, ...finalDigests },
-      expectedIntent: repairIntent
-    } : {})
+    ...(recovery ? { recovery } : {}),
+    lockAlreadyHeld: options.lockAlreadyHeld
   };
 }
 
@@ -240,14 +262,28 @@ function commitReviewSummaryProvenance(
   prepared: ReviewSummaryCandidatePreparation,
   repoRoot: string
 ): ReviewFinalizationResult {
+  if (prepared.result.status === 'failed' || !prepared.recovery) return prepared.result;
   try {
-    if (prepared.provenance) {
-      writeArtifactRepairIntent(repoRoot, prepared.provenance, { expected: prepared.expectedIntent ?? null });
+    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 {
+      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 });
     }
-    return prepared.result;
+    if (committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed.state}'`);
+    return {
+      ...prepared.result,
+      artifactSha256: committed.finalArtifactSha256,
+      semanticDigest: committed.finalSemanticDigest,
+      error: null
+    };
   } catch (error) {
     return { ...prepared.result, status: 'failed', error: {
-      code: 'REVIEW_PROVENANCE_INVALID', message: `cannot record review provenance: ${String(error)}`
+      code: 'REVIEW_RECOVERY_COMMIT_FAILED', message: `cannot publish review candidate: ${String(error)}`
     } };
   }
 }
@@ -270,24 +306,6 @@ function finalizeReviewSummaryUnlocked(
   catch (error) { return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId); }
   const prepared = prepareReviewSummaryCandidate(request, content, options);
   if (request.dryRun) return prepared.result;
-  if (prepared.result.status !== 'applied') return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
-  const tempPath = path.join(resolved.taskDir, `.${request.artifact}.tmp-${process.pid}-${(options.randomSuffix ?? randomUUID)()}`);
-  try {
-    fileSystem.writeFileSync(tempPath, prepared.content, fileSystem.statModeSync(validated.artifact.path));
-  } catch (error) {
-    cleanupTemp(fileSystem, tempPath);
-    return failed(request, 'REVIEW_TEMP_WRITE_FAILED', String(error), resolved.taskId, prepared.result.stageStatus);
-  }
-  try {
-    if (fileSystem.readFileSync(validated.artifact.path) !== content) {
-      cleanupTemp(fileSystem, tempPath);
-      return failed(request, 'REVIEW_ARTIFACT_CONFLICT', `${request.artifact} changed during finalization`, resolved.taskId, prepared.result.stageStatus);
-    }
-    fileSystem.renameSync(tempPath, validated.artifact.path);
-  } catch (error) {
-    cleanupTemp(fileSystem, tempPath);
-    return failed(request, 'REVIEW_RENAME_FAILED', String(error), resolved.taskId, prepared.result.stageStatus);
-  }
   return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
 }
 
@@ -295,15 +313,16 @@ function finalizeReviewSummary(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
 ): ReviewFinalizationResult {
-  if (request.dryRun || options.lockAlreadyHeld) return finalizeReviewSummaryUnlocked(request, options);
+  const effectiveOptions = { ...options, startRecovery: !request.dryRun };
+  if (request.dryRun || options.lockAlreadyHeld) return finalizeReviewSummaryUnlocked(request, effectiveOptions);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
-  if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, options);
+  if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, effectiveOptions);
   try {
     return withTaskExecutionLock(
       resolved.repoRoot,
       resolved.taskId,
       'task-review.finalize-summary',
-      () => finalizeReviewSummaryUnlocked(request, options)
+      () => finalizeReviewSummaryUnlocked(request, { ...effectiveOptions, lockAlreadyHeld: true })
     );
   } catch (error) {
     if (!(error instanceof TaskExecutionLockError)) throw error;

package/lib/task/short-id.ts

@@ -329,14 +329,18 @@ function mutateShortIdRegistryAt(
   activeDir: string,
   width: number,
   taskId: string,
-  requested: ShortIdMutationEffect
+  requested: ShortIdMutationEffect,
+  onlyReleaseWhenInactive = false,
+  pruneOrphans = true
 ): ShortIdMutationResult {
   const registryPath = path.join(activeDir, REGISTRY_NAME);
   return withRegistryLock(activeDir, () => {
     const registry = readRegistryStrict(registryPath, width);
     const original = JSON.stringify(registry.ids);
-    for (const [key, candidate] of Object.entries(registry.ids)) {
-      if (candidate !== taskId && !fs.existsSync(path.join(activeDir, candidate, 'task.md'))) delete registry.ids[key];
+    if (pruneOrphans) {
+      for (const [key, candidate] of Object.entries(registry.ids)) {
+        if (candidate !== taskId && !fs.existsSync(path.join(activeDir, candidate, 'task.md'))) delete registry.ids[key];
+      }
     }
     const existing = Object.entries(registry.ids).find(([, candidate]) => candidate === taskId);
     let result: ShortIdMutationResult;
@@ -356,8 +360,13 @@ function mutateShortIdRegistryAt(
         result = { effect: 'allocated', shortId: key, changed: true };
       }
     } else if (requested === 'release') {
-      if (!existing) result = { effect: 'unchanged', shortId: null, changed: false };
-      else { delete registry.ids[existing[0]]; result = { effect: 'released', shortId: existing[0], changed: true }; }
+      const taskIsActive = fs.existsSync(path.join(activeDir, taskId, 'task.md'));
+      if (!existing || (onlyReleaseWhenInactive && taskIsActive)) {
+        result = { effect: 'unchanged', shortId: existing?.[0] ?? null, changed: false };
+      } else {
+        delete registry.ids[existing[0]];
+        result = { effect: 'released', shortId: existing[0], changed: true };
+      }
     } else result = { effect: 'unchanged', shortId: existing ? existing[0] : null, changed: false };
     const changed = original !== JSON.stringify(registry.ids);
     if (changed) writeRegistry(registryPath, registry);
@@ -365,6 +374,18 @@ function mutateShortIdRegistryAt(
   });
 }
 
+function releaseStaleShortIdRegistry(repoRoot: string, taskId: string): ShortIdMutationResult {
+  const activeDir = path.join(repoRoot, '.agents', 'workspace', 'active');
+  return mutateShortIdRegistryAt(
+    activeDir,
+    configuredShortIdLength(repoRoot),
+    taskId,
+    'release',
+    true,
+    false
+  );
+}
+
 function executeShortIdCommand(request: ShortIdCommandRequest): ShortIdCommandResult {
   try {
     if (!Number.isInteger(request.shortIdLength) || request.shortIdLength < 1) {
@@ -550,6 +571,7 @@ export {
   inspectShortIdRegistry,
   configuredShortIdLength,
   mutateShortIdRegistry,
+  releaseStaleShortIdRegistry,
   executeShortIdCommand
 };
 export type {

package/lib/task/task-execution-lock.ts

@@ -293,7 +293,7 @@ function withTaskExecutionLock<T>(
     return value;
   } catch (error) {
     if (error instanceof TaskExecutionLockError) throw error;
-    if (error instanceof Error && error.name === 'OrchestrationStateError') throw error;
+    if (error instanceof Error && ['OrchestrationStateError', 'ArtifactRecoveryError'].includes(error.name)) throw error;
     throw new TaskExecutionLockError(
       'ORCHESTRATION_LOCK_FAILED',
       'lifecycle task lock operation failed',

package/lib/task/verification-engine.ts

@@ -48,6 +48,7 @@ import { manualValidationFinalSummaryProjectionMatches } from "./manual-validati
 import { readManualValidationCompletion } from "./manual-validation-completion.ts";
 import { sha256File } from "./artifact-receipts.ts";
 import { summaryCommentState } from "../platform/pr-summary.ts";
+import { taskIssueIdentity } from "../platform/task-identities.ts";
 
 const TASK_ENUMS = {
   type: ["feature", "bugfix", "refactor", "docs", "chore"],
@@ -100,8 +101,6 @@ const sharedUtils = {
   failResult,
   blockedResult,
   safeStat,
-  parseIssueNumber,
-  parsePrNumber
 };
 
 async function runCheck(type: any, context: any, shared: any): Promise<any> {
@@ -361,8 +360,8 @@ function checkTaskMeta({ taskDir, config, repositoryRoot }: any): any {
     );
   }
 
-  if (config.require_issue_number && !parseIssueNumber(metadata.issue_number)) {
-    return failResult("task-meta", "Expected a valid issue_number in task metadata");
+  if (config.require_platform_issue_identity && !taskIssueIdentity(metadata)) {
+    return failResult("task-meta", "Expected a valid platform_issue_identity in task metadata");
   }
 
   if (config.require_completed_at && isBlank(metadata.completed_at)) {
@@ -1376,19 +1375,6 @@ function getCheckedRequirements(content: any): any {
     .map((match: any) => match[1].trim());
 }
 
-function parseIssueNumber(value: any): any {
-  if (isBlank(value) || value === "N/A") {
-    return null;
-  }
-
-  const match = String(value).match(/\d+/);
-  return match ? Number(match[0]) : null;
-}
-
-function parsePrNumber(value: any): any {
-  return parseIssueNumber(value);
-}
-
 // === Utilities ===
 
 function normalizeContent(text: any): any {

package/lib/task/verification-types.ts

@@ -11,8 +11,6 @@ export type VerificationShared = {
   failResult: (type: string, message: string, failType?: string) => VerificationCheckResult;
   blockedResult: (type: string, message: string, failType?: string) => VerificationCheckResult;
   safeStat: (filePath: string) => fs.Stats | null;
-  parseIssueNumber: (value: unknown) => number | null;
-  parsePrNumber: (value: unknown) => number | null;
 };
 
 type VerificationStatus = 'pass' | 'fail' | 'blocked';

package/lib/task/workflow-command.ts

@@ -1,7 +1,6 @@
 export const TASK_WORKFLOW_COMMANDS = Object.freeze({
   'artifact-inspect': ['task-artifact', 'inspect'],
   'artifact-init': ['task-artifact', 'init'],
-  'artifact-repair': ['task-artifact', 'repair'],
   'artifact-finalize-local': ['task-artifact', 'finalize-local'],
   'review-finalize-summary': ['task-review', 'finalize-summary'],
   event: ['task-event', null],

package/lib/version.ts

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from 'node:fs';
-import semver from 'semver';
 
 const packageJsonUrl = [
   new URL('../package.json', import.meta.url),
@@ -13,22 +12,9 @@ if (!packageJsonUrl) {
 const { version } = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
 const VERSION = `v${version}`;
 const AGENT_INFRA_VERSION_PATTERN = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
-const LEGACY_COMPATIBILITY_CUTOFF_VERSION = '1.0.0';
 
 function isValidAgentInfraVersion(value: unknown): value is string {
   return typeof value === 'string' && AGENT_INFRA_VERSION_PATTERN.test(value);
 }
 
-function isLegacyCompatibilityEnabled(runtimeVersion = VERSION): boolean {
-  const normalized = runtimeVersion.startsWith('v') ? runtimeVersion.slice(1) : runtimeVersion;
-  const parsed = semver.valid(normalized);
-  return parsed !== null && semver.lt(parsed, LEGACY_COMPATIBILITY_CUTOFF_VERSION);
-}
-
-function legacyCompatibilityError(resource: string, runtimeVersion = VERSION): Error & { code: string } {
-  return Object.assign(new Error(
-    `PLATFORM_IDENTITY_LEGACY_UNSUPPORTED: ${resource} requires migration to the current schema before v${LEGACY_COMPATIBILITY_CUTOFF_VERSION} runtime ${runtimeVersion}`
-  ), { code: 'PLATFORM_IDENTITY_LEGACY_UNSUPPORTED' });
-}
-
-export { LEGACY_COMPATIBILITY_CUTOFF_VERSION, VERSION, isLegacyCompatibilityEnabled, isValidAgentInfraVersion, legacyCompatibilityError };
+export { VERSION, isValidAgentInfraVersion };

package/package.json

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