@fitlab-ai/agent-infra 0.9.15 → 0.10.0

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

@@ -1,6 +1,4 @@
 import fs from 'node:fs';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
 import { parseArtifactName } from './artifact-name.js';
 import { validateCompletedArtifact, hasOpenArtifactRound, validateArtifactPublication } from './artifact-lifecycle.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
@@ -12,18 +10,15 @@ 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 { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.js';
+import { readArtifactRecoveryIntent } from './artifact-repair-intent.js';
+import { beginArtifactRecovery, commitArtifactRecovery, prepareArtifactRecoveryCommit, recoveryContextFromIntent, stageArtifactCandidate } from './artifact-recovery.js';
 const STAGES = {
     analysis: { family: 'review-analysis' },
     plan: { family: 'review-plan' },
     code: { family: 'review-code' }
 };
 const DEFAULT_FILE_SYSTEM = {
-    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(request, code, message, taskId = null, stageStatus = null, extra = {}) {
     return {
@@ -37,21 +32,11 @@ function failed(request, code, message, taskId = null, stageStatus = null, extra
         stageStatus,
         artifactSha256: null,
         semanticDigest: null,
-        repairable: false,
-        operation: null,
         operations: [],
         error: { code, message },
         ...extra
     };
 }
-function cleanupTemp(fileSystem, tempPath) {
-    try {
-        fileSystem.unlinkSync(tempPath);
-    }
-    catch {
-        // Best-effort cleanup preserves the primary failure.
-    }
-}
 /** Prepare domain validation, summary bytes and provenance before any publication. */
 function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     let taskId = null;
@@ -85,43 +70,37 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     catch (error) {
         return reject('REVIEW_ARTIFACT_NOT_REGULAR', String(error));
     }
+    let recovery;
+    if (request.recoveryId) {
+        try {
+            const intent = readArtifactRecoveryIntent(resolved.repoRoot, taskId, spec.family, request.artifact);
+            if (!intent || intent.recoveryOperationId !== request.recoveryId)
+                return reject('REVIEW_PROVENANCE_INVALID', 'recovery id does not match the artifact journal');
+            if (!['awaiting-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);
+        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, taskId: taskId, family: spec.family, artifact: request.artifact,
-                    state: 'awaiting-repair', 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`);
@@ -149,10 +128,62 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
     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: {
@@ -162,22 +193,38 @@ function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
             operations: transformed.changed ? [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }] : [],
             error: null
         },
-        ...(repairIntent?.state === 'awaiting-repair' ? {
-            provenance: { ...repairIntent, state: 'passed', ...finalDigests },
-            expectedIntent: repairIntent
-        } : {})
+        ...(recovery ? { recovery } : {}),
+        lockAlreadyHeld: options.lockAlreadyHeld
     };
 }
 function commitReviewSummaryProvenance(prepared, repoRoot) {
+    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 });
         }
-        return prepared.result;
+        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 });
+        }
+        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)}`
             } };
     }
 }
@@ -203,37 +250,17 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
     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);
 }
 function finalizeReviewSummary(request, options = {}) {
+    const effectiveOptions = { ...options, startRecovery: !request.dryRun };
     if (request.dryRun || options.lockAlreadyHeld)
-        return finalizeReviewSummaryUnlocked(request, options);
+        return finalizeReviewSummaryUnlocked(request, effectiveOptions);
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
-        return finalizeReviewSummaryUnlocked(request, options);
+        return finalizeReviewSummaryUnlocked(request, effectiveOptions);
     try {
-        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', () => finalizeReviewSummaryUnlocked(request, options));
+        return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', () => finalizeReviewSummaryUnlocked(request, { ...effectiveOptions, lockAlreadyHeld: true }));
     }
     catch (error) {
         if (!(error instanceof TaskExecutionLockError))

package/dist/lib/task/short-id.js

@@ -199,14 +199,16 @@ function mutateShortIdRegistry(repoRoot, taskId, requested) {
     const activeDir = path.join(repoRoot, '.agents', 'workspace', 'active');
     return mutateShortIdRegistryAt(activeDir, configuredShortIdLength(repoRoot), taskId, requested);
 }
-function mutateShortIdRegistryAt(activeDir, width, taskId, requested) {
+function mutateShortIdRegistryAt(activeDir, width, taskId, requested, onlyReleaseWhenInactive = false, pruneOrphans = true) {
     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;
@@ -232,8 +234,10 @@ function mutateShortIdRegistryAt(activeDir, width, taskId, requested) {
             }
         }
         else if (requested === 'release') {
-            if (!existing)
-                result = { effect: 'unchanged', shortId: null, changed: false };
+            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 };
@@ -247,6 +251,10 @@ function mutateShortIdRegistryAt(activeDir, width, taskId, requested) {
         return { ...result, changed };
     });
 }
+function releaseStaleShortIdRegistry(repoRoot, taskId) {
+    const activeDir = path.join(repoRoot, '.agents', 'workspace', 'active');
+    return mutateShortIdRegistryAt(activeDir, configuredShortIdLength(repoRoot), taskId, 'release', true, false);
+}
 function executeShortIdCommand(request) {
     try {
         if (!Number.isInteger(request.shortIdLength) || request.shortIdLength < 1) {
@@ -429,5 +437,5 @@ function lookupShortIdByBranch(branch, repoRoot, _opts) {
     }
     return matches[0];
 }
-export { normalizeShortIdInput, isRemovedHashShortIdInput, resolveShortIdReadOnly, lookupShortIdByBranch, loadShortIdByTaskId, inspectShortIdRegistry, configuredShortIdLength, mutateShortIdRegistry, executeShortIdCommand };
+export { normalizeShortIdInput, isRemovedHashShortIdInput, resolveShortIdReadOnly, lookupShortIdByBranch, loadShortIdByTaskId, inspectShortIdRegistry, configuredShortIdLength, mutateShortIdRegistry, releaseStaleShortIdRegistry, executeShortIdCommand };
 //# sourceMappingURL=short-id.js.map

package/dist/lib/task/task-execution-lock.js

@@ -231,7 +231,7 @@ function withTaskExecutionLock(repoRoot, taskId, ownerName, callback, options =
     catch (error) {
         if (error instanceof TaskExecutionLockError)
             throw error;
-        if (error instanceof Error && error.name === 'OrchestrationStateError')
+        if (error instanceof Error && ['OrchestrationStateError', 'ArtifactRecoveryError'].includes(error.name))
             throw error;
         throw new TaskExecutionLockError('ORCHESTRATION_LOCK_FAILED', 'lifecycle task lock operation failed', { operation: ownsFixed ? 'callback' : 'acquire', errno: errno(error), key });
     }

package/dist/lib/task/verification-engine.js

@@ -33,6 +33,7 @@ import { manualValidationFinalSummaryProjectionMatches } from "./manual-validati
 import { readManualValidationCompletion } from "./manual-validation-completion.js";
 import { sha256File } from "./artifact-receipts.js";
 import { summaryCommentState } from "../platform/pr-summary.js";
+import { taskIssueIdentity } from "../platform/task-identities.js";
 const TASK_ENUMS = {
     type: ["feature", "bugfix", "refactor", "docs", "chore"],
     workflow: ["feature-development", "bug-fix", "refactoring"],
@@ -78,8 +79,6 @@ const sharedUtils = {
     failResult,
     blockedResult,
     safeStat,
-    parseIssueNumber,
-    parsePrNumber
 };
 async function runCheck(type, context, shared) {
     switch (type) {
@@ -314,8 +313,8 @@ function checkTaskMeta({ taskDir, config, repositoryRoot }) {
     if (expectedStatus && metadata.status !== expectedStatus) {
         return failResult("task-meta", `Expected status '${expectedStatus}', got '${metadata.status || "(empty)"}'`);
     }
-    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)) {
         return failResult("task-meta", "Expected completed_at to be present");
@@ -1185,16 +1184,6 @@ function getCheckedRequirements(content) {
         .filter(Boolean)
         .map((match) => match[1].trim());
 }
-function parseIssueNumber(value) {
-    if (isBlank(value) || value === "N/A") {
-        return null;
-    }
-    const match = String(value).match(/\d+/);
-    return match ? Number(match[0]) : null;
-}
-function parsePrNumber(value) {
-    return parseIssueNumber(value);
-}
 // === Utilities ===
 function normalizeContent(text) {
     return String(text || "")

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

@@ -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/dist/lib/version.js

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from 'node:fs';
-import semver from 'semver';
 const packageJsonUrl = [
     new URL('../package.json', import.meta.url),
     new URL('../../package.json', import.meta.url),
@@ -10,17 +9,8 @@ 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) {
     return typeof value === 'string' && AGENT_INFRA_VERSION_PATTERN.test(value);
 }
-function isLegacyCompatibilityEnabled(runtimeVersion = VERSION) {
-    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, runtimeVersion = VERSION) {
-    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 };
 //# sourceMappingURL=version.js.map

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.9.15",
-  "sourceInputHash": "d6521519c8d772a6d81c177d8c6e6795c080b04d9f8afcec19bca45c486a70df",
-  "internalExecutableBuildHash": "f0ab80c423acc4def5130e075a209a64349296985701506e7d9e73f8151bcb2a"
+  "packageVersion": "0.10.0",
+  "sourceInputHash": "d7af8de4bd6c1996a920335dfc766e23b8d391cd4db2965d7d9dfaa2cb112059",
+  "internalExecutableBuildHash": "63a6d2d9113dd353dfce165efccf82a5ea25398c2aad9f1b2c5543dc28e8b833"
 }

package/lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.ts

@@ -26,6 +26,7 @@ import {
 type ControllerControl = Readonly<{
   token: string;
   generation: string;
+  rootId?: string;
   channelDir: string;
   statusDir: string;
   runtimeDir: string;
@@ -83,13 +84,14 @@ function copyRegular(source: string, destination: string, mode: number): void {
 function controlFromEnvironment(): ControllerControl {
   const token = process.env.AGENT_INFRA_CONTROL_TOKEN;
   const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+  const rootId = process.env.AGENT_INFRA_CONTROL_ROOT_ID;
   const channelDir = process.env.AGENT_INFRA_CONTROL_DIR;
   const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
   const runtimeDir = process.env.AGENT_INFRA_RUNTIME_DIR;
-  if (!token || !generation || !channelDir || !statusDir || !runtimeDir) {
+  if (!token || !generation || !rootId || !channelDir || !statusDir || !runtimeDir) {
     throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_MISSING');
   }
-  return { token, generation, channelDir, statusDir, runtimeDir };
+  return { token, generation, rootId, channelDir, statusDir, runtimeDir };
 }
 
 function verifyRuntime(runtimeDir: string): void {
@@ -255,6 +257,9 @@ function isolatedEnvironment(
     AGENT_INFRA_TASK_ID: taskId,
     AGENT_INFRA_CONTROL_TOKEN: control.token,
     AGENT_INFRA_CONTROL_GENERATION: control.generation,
+    ...(control.rootId || sourceEnvironment.AGENT_INFRA_CONTROL_ROOT_ID
+      ? { AGENT_INFRA_CONTROL_ROOT_ID: control.rootId ?? sourceEnvironment.AGENT_INFRA_CONTROL_ROOT_ID }
+      : {}),
     AGENT_INFRA_CONTROL_DIR: control.channelDir,
     AGENT_INFRA_CONTROL_STATUS_DIR: control.statusDir,
     AGENT_INFRA_RUNTIME_DIR: control.runtimeDir,

package/lib/agent-clients/adapters/codex-lifecycle/store.ts

@@ -43,11 +43,23 @@ type ActiveCodexLifecycleEvidenceQuery = Readonly<{
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 1_000;
 const LOCK_STALE_MS = 30_000;
+const RECOVERY_CONSUMER_RE = /^lifecycle-recovery:([^:\r\n]+):([^:\r\n]+)$/u;
 
 function digest(value: string): string {
   return crypto.createHash('sha256').update(value).digest('hex');
 }
 
+function isRecoveryConsumer(value: string): boolean {
+  return RECOVERY_CONSUMER_RE.test(value);
+}
+
+function recoveryConsumer(taskId: string, receiptId: string): string {
+  if (!/^[^:\r\n]+$/u.test(taskId) || !/^[^:\r\n]+$/u.test(receiptId)) {
+    throw new Error('Codex lifecycle recovery claim identity is invalid');
+  }
+  return `lifecycle-recovery:${taskId}:${receiptId}`;
+}
+
 function readRecord(file: string): StoredCodexLifecycle {
   const value = JSON.parse(fs.readFileSync(file, 'utf8')) as StoredCodexLifecycle;
   if (
@@ -249,11 +261,12 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
 
   function read(childThreadId: string): StoredCodexLifecycle {
     const matches = findByChild(childThreadId);
-    if (matches.length !== 1) throw new Error(`Codex lifecycle child '${childThreadId}' was not found uniquely`);
+    if (matches.length === 0) throw new Error(`Codex lifecycle child '${childThreadId}' was not found uniquely`);
+    if (matches.length > 1) throw new Error(`Codex lifecycle child '${childThreadId}' is ambiguous`);
     return readRecord(matches[0]!);
   }
 
-  function consume(
+  function consumeInternal(
     childThreadId: string,
     consumer: string,
     expectedHookDefinitionHash?: string
@@ -291,12 +304,51 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
     });
   }
 
+  function consume(
+    childThreadId: string,
+    consumer: string,
+    expectedHookDefinitionHash?: string
+  ): StoredCodexLifecycle {
+    if (!consumer.trim()) throw new Error('Codex lifecycle consumer is required');
+    if (consumer.startsWith('lifecycle-recovery:')) {
+      throw new Error('Codex lifecycle recovery claims require claimRecovery');
+    }
+    return consumeInternal(childThreadId, consumer, expectedHookDefinitionHash);
+  }
+
+  function claimRecovery(
+    childThreadId: string,
+    taskId: string,
+    receiptId: string,
+    expectedHookDefinitionHash?: string
+  ): StoredCodexLifecycle {
+    return consumeInternal(
+      childThreadId,
+      recoveryConsumer(taskId, receiptId),
+      expectedHookDefinitionHash
+    );
+  }
+
+  function releaseRecovery(childThreadId: string, consumer: string): boolean {
+    if (!/^lifecycle-recovery:[^:\r\n]+:[^:\r\n]+$/.test(consumer)) return false;
+    return withWriteLock(() => {
+      const matches = findByChild(childThreadId);
+      if (matches.length !== 1) return false;
+      const file = matches[0]!;
+      const current = readRecord(file);
+      if (current.state.status !== 'stop-ready' || current.consumer !== consumer || !current.consumedAt) return false;
+      fs.unlinkSync(file);
+      return true;
+    });
+  }
+
   function expireBefore(cutoff: string): number {
     return withWriteLock(() => {
       let changed = 0;
       for (const file of recordFiles(root)) {
         const current = readRecord(file);
         if (current.updatedAt >= cutoff) continue;
+        if (current.consumer && isRecoveryConsumer(current.consumer)) continue;
         if (current.consumer || ['invalid', 'expired', 'stop-ready'].includes(current.state.status)) {
           fs.unlinkSync(file);
           changed += 1;
@@ -316,7 +368,7 @@ function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
     });
   }
 
-  return Object.freeze({ root, apply, applyToSpawn, consume, expireBefore, findByParent, read });
+  return Object.freeze({ root, apply, applyToSpawn, consume, claimRecovery, releaseRecovery, expireBefore, findByParent, read });
 }
 
 export { createCodexLifecycleStore, hasActiveCodexLifecycleEvidence };

package/lib/fs/durable-write.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 export function fsyncDirectory(directory: string): void {
+  if (process.platform === 'win32') return;
   const descriptor = fs.openSync(directory, 'r');
   try { fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); }
 }

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

@@ -57,7 +57,7 @@ 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', 'repair', 'finalize-local'],
+  'task-artifact': ['inspect', 'init', 'finalize-local'],
   'task-orchestration': ['status', 'progress'],
   'task-review': ['finalize-summary'],
   'task-event': ['event'],

package/lib/internal/manual-validation.ts

@@ -43,15 +43,24 @@ function printFailure(format: OutputFormat, error: { code: string; message: stri
   process.exitCode = 1;
 }
 
+const MANUAL_VALIDATION_STATUS_SECTION = /^###\s+(?:⚠️\s+(?:需人工校验|Manual Validation Required)|✅\s+(?:人工验证已通过|无需人工校验|Manual Validation Passed|No Manual Validation Required)|⏳\s+(?:人工验证待收尾|Manual Validation Pending))\s*$[\s\S]*?(?=^#{1,3}\s|(?![\s\S]))/gmu;
+
 function manualSummaryBody(body: string, phase: 'pending' | 'final', transactionId: string, receiptDigest = '', evidenceDigest = '', prHeadSha = ''): string {
-  const withoutPrevious = body
-    .replace(/^###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)\s*$/gmu, '')
-    .replace(/^###\s+⏳\s+(?:Manual Validation Pending|人工验证待收尾)\s*$/gmu, '')
-    .replace(/Manual validation passed(?:\s+→)?/giu, 'Manual validation pending');
+  const chinese = /###\s+(?:⚠️\s+需人工校验|✅\s+(?:人工验证已通过|无需人工校验)|⏳\s+人工验证待收尾)\s*$/mu.test(body);
   const section = phase === 'pending'
-    ? `### ⏳ Manual Validation Pending\n\nManual validation evidence is staged; transaction ${transactionId} is awaiting final promotion.`
-    : `### ✅ Manual Validation Passed\n\nManual validation passed; transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`;
-  return `${withoutPrevious.replace(/\s+$/u, '')}\n\n${section}\n`;
+    ? chinese
+      ? `### ⏳ 人工验证待收尾\n\n人工验证证据已暂存；事务 ${transactionId} 正在等待最终完成。`
+      : `### ⏳ Manual Validation Pending\n\nManual validation evidence is staged; transaction ${transactionId} is awaiting final promotion.`
+    : chinese
+      ? `### ✅ 人工验证已通过\n\n人工验证已通过；transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`
+      : `### ✅ Manual Validation Passed\n\nManual validation passed; transaction=${transactionId}; receipt=${receiptDigest}; evidence=${evidenceDigest}; head=${prHeadSha}.`;
+  let inserted = false;
+  const updated = body.replace(MANUAL_VALIDATION_STATUS_SECTION, () => {
+    if (inserted) return '';
+    inserted = true;
+    return `${section}\n\n`;
+  });
+  return inserted ? `${updated.replace(/\s+$/u, '')}\n` : `${body.replace(/\s+$/u, '')}\n\n${section}\n`;
 }
 
 function openManualValidationStarted(taskMdPath: string): { present: boolean; transactionId: string | null } {
@@ -246,7 +255,7 @@ async function executeManualValidationTransactionLocked(
     });
     if (!['applied', 'no-op'].includes(promoted.status)) transactionFailure(promoted.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'final summary promotion failed' });
     const postWrite = await summaryCommentState(taskRef, { cwd, client: options.client });
-    if (!postWrite.comment?.body.includes('### ✅ Manual Validation Passed') || postWrite.pullRequest?.head.sha !== receipt.prHeadSha || !manualValidationFinalSummaryProjectionMatches(postWrite.comment.body, receipt)) transactionFailure({ code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'final summary post-write verification failed' });
+    if (!/^###\s+✅\s+(?:Manual Validation Passed|人工验证已通过)\s*$/mu.test(postWrite.comment?.body ?? '') || postWrite.pullRequest?.head.sha !== receipt.prHeadSha || !manualValidationFinalSummaryProjectionMatches(postWrite.comment?.body ?? '', receipt)) transactionFailure({ code: 'MANUAL_VALIDATION_TRANSACTION_RECOVERY_REQUIRED', message: 'final summary post-write verification failed' });
     transitionAndPersist('committed', { postWriteVerified: true });
     return result('applied', null, { transaction, receipt, idempotent: false });
   } catch (error) {

package/lib/internal/task-artifact.ts

@@ -1,7 +1,7 @@
 import { parseArtifactCommand, executeArtifactCommand } from '../task/artifact-command.ts';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> repair --family <family> --artifact <artifact> --expected-sha256 <sha256> --expected-semantic-digest <digest>\n       agent-infra-internal task-artifact <N | TASK-id> finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, repair, or finalize a workflow artifact without changing task state.\n`;
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> finalize-local --family <analysis|plan|code> --artifact <artifact> [--recovery-id <id>]\n\nInspect, initialize, or finalize a workflow artifact without changing task state.\n`;
 
 
 function taskArtifact(args: string[] = []): void {