@fitlab-ai/agent-infra 0.9.15 → 0.11.0

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

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

package/dist/lib/task/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,8 +1,9 @@
 export const TASK_WORKFLOW_COMMANDS = Object.freeze({
     'artifact-inspect': ['task-artifact', 'inspect'],
     'artifact-init': ['task-artifact', 'init'],
-    'artifact-repair': ['task-artifact', 'repair'],
+    'artifact-preflight': ['task-artifact', 'preflight'],
     'artifact-finalize-local': ['task-artifact', 'finalize-local'],
+    'review-preflight': ['task-review', 'preflight'],
     'review-finalize-summary': ['task-review', 'finalize-summary'],
     event: ['task-event', null],
     'ledger-finding-response': ['task-ledger', 'finding-respond'],

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

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

package/dist/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.11.0",
+  "sourceInputHash": "c67e66a46040d5246d67c751af605b796cd61913b98add01ff327829c01ce3db",
+  "internalExecutableBuildHash": "f6b4be06df12111b3a7614d335c9e802049c3cea194c6e7c040f3251188c694f"
 }

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

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

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) {