@fitlab-ai/agent-infra 0.11.7 → 0.11.8

package/dist/lib/task/platform-operation-recovery.js

@@ -0,0 +1,459 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { inspectPlatformCommentOperation, normalizeCommentContent, syncPlatformComment } from '../platform/issue-comments.js';
+import { inspectPlatformIssue, syncPlatformIssue } from '../platform/issues.js';
+import { resolvePlatformProviderContext } from '../platform/context.js';
+import { providerOperationContext, providerError, unsupportedProviderOperation } from '../platform/provider-bridge.js';
+import { inLabelMappingDigest } from '../platform/in-label-sync.js';
+import { bindPlatformPullRequest, inspectPlatformPullRequest, recoverCreatedPullRequest, syncPlatformPullRequest } from '../platform/pull-requests.js';
+import { syncPullRequestSummary } from '../platform/pr-summary.js';
+import { publishPrReview, readReviewBodyFile } from '../platform/pr-review.js';
+import { parseTaskFrontmatter } from './frontmatter.js';
+import { taskIssueIdentity } from '../platform/task-identities.js';
+import { parseResourceIdentity, resourceIdentityEquals } from '../platform/resource-identity.js';
+import { operationId } from './platform-operation-journal.js';
+import { canonicalizeSummaryBody } from '../platform/comment-safety.js';
+import { platformResult } from '../platform/types.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { readPlatformOperationJournal, recordPlatformOperation } from './platform-operation-journal.js';
+function labelsMatchOwnedPrefix(actual, expected, prefix) {
+    return actual.filter((label) => label.startsWith(prefix)).sort().join('\0')
+        === expected.filter((label) => label.startsWith(prefix)).sort().join('\0');
+}
+function fieldsMatchExpected(actual, expected) {
+    return Object.entries(expected).every(([name, value]) => actual[name] === value);
+}
+function result(status, recovered, pending, error = null) {
+    return { status, changed: recovered.length > 0, recovered, pending, error };
+}
+function summaryPayload(taskDir, taskId) {
+    const file = path.join(taskDir, '.delivery-summary.json');
+    if (!fs.existsSync(file))
+        return null;
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const canonical = typeof data.body === 'string' ? canonicalizeSummaryBody(data.body) : null;
+    if (data.taskId !== taskId || typeof data.body !== 'string' || typeof data.sha256 !== 'string'
+        || !canonical?.ok || canonical.value !== data.body
+        || createHash('sha256').update(data.body).digest('hex') !== data.sha256) {
+        throw Object.assign(new Error('delivery summary staging record is invalid'), { code: 'SUMMARY_STAGING_INVALID' });
+    }
+    return { body: data.body, sha256: data.sha256 };
+}
+async function replayComment(taskId, taskDir, operation, agent, cwd, client) {
+    if (operation.kind === 'task-comment') {
+        return syncPlatformComment(taskId, { kind: 'task', agent, cwd, client, dependency: operation.dependency, skipQueue: true });
+    }
+    if (operation.kind === 'artifact-comment') {
+        return syncPlatformComment(taskId, { kind: 'artifact', artifact: operation.target, agent, cwd, client, dependency: operation.dependency, skipQueue: true });
+    }
+    if (operation.kind === 'summary-comment') {
+        const summary = summaryPayload(taskDir, taskId);
+        if (!summary)
+            return platformResult('failed', { error: { code: 'SUMMARY_STAGING_MISSING', message: 'delivery summary staging record is unavailable', retryable: false } });
+        return syncPlatformComment(taskId, {
+            kind: 'summary', body: summary.body, agent, cwd,
+            summaryAuthorization: { sha256: summary.sha256 }, dependency: operation.dependency, client, skipQueue: true
+        });
+    }
+    if (operation.kind === 'cancel-comment') {
+        return syncPlatformComment(taskId, { kind: 'cancel', agent, cwd, client, dependency: operation.dependency, skipQueue: true });
+    }
+    return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_UNSUPPORTED', message: `operation kind '${operation.kind}' has no registered recovery handler`, retryable: false } });
+}
+function currentIssueMetadataOperation(taskId, taskMdPath, repoRoot, operation) {
+    if (operation.kind !== 'issue-metadata' || !operation.issueMetadata)
+        return null;
+    const content = fs.readFileSync(taskMdPath, 'utf8');
+    const frontmatter = parseTaskFrontmatter(content);
+    const identity = taskIssueIdentity(frontmatter);
+    if (!identity)
+        return null;
+    let fromDiffFiles;
+    let mappingDigest;
+    if (operation.issueMetadata.inLabels === 'from-diff') {
+        const taskBase = typeof frontmatter.delivery_base_ref === 'string' ? frontmatter.delivery_base_ref.trim() : '';
+        if (!taskBase || (operation.issueMetadata.base && operation.issueMetadata.base !== taskBase))
+            return null;
+        try {
+            fromDiffFiles = execFileSync('git', ['diff', `${taskBase}...HEAD`, '--name-only'], {
+                cwd: repoRoot, encoding: 'utf8'
+            }).trim().split(/\r?\n/).filter(Boolean).sort();
+            const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
+            const mapping = inLabelMappingDigest(config.labels?.in);
+            if (!mapping.ok)
+                return null;
+            mappingDigest = mapping.digest;
+        }
+        catch {
+            return null;
+        }
+    }
+    const currentMetadata = {
+        ...operation.issueMetadata,
+        ...(fromDiffFiles ? { fromDiffFiles } : {}),
+        ...(mappingDigest ? { inLabelMappingDigest: mappingDigest } : {})
+    };
+    const target = JSON.stringify(identity);
+    const expectedDigest = createHash('sha256').update(JSON.stringify({
+        ...currentMetadata,
+        task: taskId,
+        taskContent: createHash('sha256').update(content).digest('hex')
+    })).digest('hex');
+    return { kind: 'issue-metadata', target, expectedDigest, issueMetadata: currentMetadata, id: operationId({ kind: 'issue-metadata', target, expectedDigest }) };
+}
+async function replayIssueMetadata(taskId, operation, agent, cwd, client) {
+    if (!operation.issueMetadata)
+        return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Issue metadata recovery parameters are missing', retryable: false } });
+    let expectedIdentity;
+    try {
+        expectedIdentity = parseResourceIdentity(JSON.parse(operation.target), 'journal Issue identity');
+    }
+    catch {
+        return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Journal Issue identity is invalid', retryable: false } });
+    }
+    const before = await inspectPlatformIssue(taskId, { cwd, client });
+    if (before.status !== 'no-op' || before.error || !before.issue
+        || !resourceIdentityEquals(before.issue.identity, expectedIdentity)) {
+        return platformResult('blocked', { error: before.error ?? { code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Bound Issue identity differs from the journal target', retryable: false } });
+    }
+    const sync = await syncPlatformIssue(taskId, { ...operation.issueMetadata, agent, cwd, client, dependency: operation.dependency, skipQueue: true });
+    if ((sync.status !== 'applied' && sync.status !== 'no-op') || sync.error)
+        return sync;
+    const after = await inspectPlatformIssue(taskId, { cwd, client });
+    if (after.status !== 'no-op' || after.error || !after.issue
+        || !resourceIdentityEquals(after.issue.identity, expectedIdentity)) {
+        return platformResult('blocked', { error: after.error ?? { code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Issue identity changed during metadata recovery', retryable: false } });
+    }
+    const issue = after.issue;
+    const metadata = operation.issueMetadata;
+    const failedOperation = sync.operations.find((item) => item.status === 'failed' || item.status === 'skipped');
+    if (failedOperation)
+        return platformResult('blocked', { error: {
+                code: failedOperation.reasonCode || 'PLATFORM_OPERATION_METADATA_UNCONFIRMED',
+                message: `Issue metadata recovery did not confirm operation '${failedOperation.name}'`, retryable: true
+            } });
+    const unconfirmed = sync.operations.some((item) => {
+        if (!('value' in item) || item.value === undefined)
+            return false;
+        if (item.name === 'labels:status' || item.name === 'labels:in') {
+            const prefix = item.name === 'labels:status' ? 'status:' : 'in:';
+            return !labelsMatchOwnedPrefix(issue.labels, item.value, prefix);
+        }
+        if (item.name === 'assignees')
+            return [...issue.assignees].sort().join('\0') !== [...item.value].sort().join('\0');
+        if (item.name === 'milestone')
+            return issue.milestone !== item.value;
+        if (item.name === 'requirements')
+            return issue.body !== item.value;
+        if (item.name === 'state')
+            return issue.state !== item.value;
+        if (item.name === 'issue-type')
+            return issue.issueType !== item.value;
+        if (item.name === 'fields')
+            return !fieldsMatchExpected(issue.fields, item.value);
+        return false;
+    }) || (metadata.state !== undefined && issue.state !== metadata.state)
+        || (metadata.assignees === 'none' && issue.assignees.length !== 0)
+        || (metadata.milestone === 'none' && issue.milestone !== null);
+    if (unconfirmed)
+        return platformResult('blocked', { error: {
+                code: 'PLATFORM_OPERATION_METADATA_UNCONFIRMED',
+                message: 'Issue metadata differs from the requested recovery target after reread', retryable: true
+            } });
+    return platformResult('no-op', { changed: sync.changed || after.changed });
+}
+async function verifyIssueCreate(taskId, operation, cwd, client) {
+    if (!operation.issueCreate)
+        return platformResult('failed', { error: {
+                code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Issue creation recovery identity is missing', retryable: false
+            } });
+    const current = await inspectPlatformIssue(taskId, { cwd, client });
+    if (!current.issue)
+        return platformResult('blocked', { error: current.error ?? {
+                code: 'PLATFORM_OPERATION_TARGET_UNAVAILABLE',
+                message: 'Issue creation outcome is unknown and the task has no bound Issue identity; bind the verified remote Issue before continuing',
+                retryable: true
+            } });
+    if (current.issue.title !== operation.issueCreate.title
+        || createHash('sha256').update(current.issue.body).digest('hex') !== operation.issueCreate.bodyDigest)
+        return platformResult('blocked', { error: {
+                code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Bound Issue does not match the queued creation intent', retryable: false
+            } });
+    return platformResult('no-op');
+}
+async function replayPullRequestSummary(taskId, operation, agent, cwd, client) {
+    let identity;
+    try {
+        identity = parseResourceIdentity(JSON.parse(operation.target), 'queued pull-request summary identity');
+    }
+    catch {
+        return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Queued pull-request summary identity is invalid', retryable: false } });
+    }
+    const resolved = await resolvePlatformProviderContext({ cwd, client });
+    if (!resolved.ok)
+        return resolved.context;
+    const listed = resolved.value.provider.comments?.list
+        ? await resolved.value.provider.comments.list({ context: providerOperationContext(resolved.value), parent: identity })
+        : unsupportedProviderOperation(resolved.value.provider, 'comments.list');
+    if (!listed.ok)
+        return platformResult(listed.error.retryable ? 'blocked' : 'failed', { error: providerError(listed.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') });
+    const marker = `<!-- sync-pr:${taskId}:summary -->`;
+    const summaries = listed.value.filter((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] === marker);
+    if (summaries.length > 1)
+        return platformResult('blocked', { error: {
+                code: 'PR_SUMMARY_MARKER_AMBIGUOUS', message: 'Multiple pull-request comments contain the queued summary marker', retryable: false
+            } });
+    if (summaries.length === 1 && createHash('sha256').update(normalizeCommentContent(summaries[0].body)).digest('hex') === operation.expectedDigest) {
+        return platformResult('no-op');
+    }
+    if (!operation.pullRequestSummary)
+        return platformResult('blocked', { error: {
+                code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Pull-request summary recovery content is missing', retryable: false
+            } });
+    const bound = await inspectPlatformPullRequest(taskId, { cwd, client });
+    if (!bound.pullRequest || !resourceIdentityEquals(bound.pullRequest.identity, identity))
+        return platformResult('blocked', { error: bound.error ?? {
+                code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Bound pull request differs from the queued summary target', retryable: false
+            } });
+    const replayed = await syncPullRequestSummary(taskId, {
+        agent,
+        cwd,
+        client,
+        body: operation.pullRequestSummary.body,
+        changeReportFile: operation.pullRequestSummary.changeReportFile,
+        primaryResult: 'no_op',
+        strict: true,
+        skipQueue: true,
+        lockAlreadyHeld: true
+    });
+    if ((replayed.status === 'applied' || replayed.status === 'no-op') && !replayed.error && replayed.warnings.length === 0) {
+        return platformResult(replayed.status, { changed: replayed.changed });
+    }
+    return platformResult('blocked', { error: replayed.error ?? {
+            code: 'PR_SUMMARY_RECOVERY_UNCONFIRMED', message: 'Pull-request summary replay did not confirm the requested remote state', retryable: true
+        } });
+}
+async function replayPullRequestReview(operation, agent, cwd, client) {
+    const intent = operation.pullRequestReview;
+    if (!intent)
+        return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Pull-request review recovery parameters are missing', retryable: false } });
+    let target;
+    try {
+        target = parseResourceIdentity(JSON.parse(operation.target), 'queued pull-request review identity');
+    }
+    catch {
+        return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Queued pull-request review identity is invalid', retryable: false } });
+    }
+    if (!intent.resource || !resourceIdentityEquals(target, intent.resource))
+        return platformResult('failed', { error: {
+                code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Pull-request review identity differs from the journal target', retryable: false
+            } });
+    let body;
+    try {
+        body = readReviewBodyFile(intent.scope, intent.round, intent.artifactFile, intent.bodyDigest, cwd);
+    }
+    catch {
+        return platformResult('failed', { error: {
+                code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Canonical pull-request review body is unavailable or does not match the queued digest', retryable: false
+            } });
+    }
+    return publishPrReview({
+        cwd,
+        client,
+        agent,
+        prNumber: intent.prNumber,
+        expectedResource: target,
+        expectedProviderScopeId: intent.providerScopeId,
+        identity: { scope: intent.scope, round: intent.round, commitSha: intent.commitSha, ...(intent.resource ? { resource: intent.resource } : {}) },
+        event: intent.event,
+        body,
+        recoveryArtifact: intent.artifactFile,
+        skipQueue: true
+    });
+}
+async function replayPullRequest(taskId, operation, agent, cwd) {
+    const intent = operation.pullRequest;
+    if (!intent)
+        return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Pull-request recovery parameters are missing', retryable: false } });
+    if (intent.action === 'bind') {
+        if (!intent.prToken)
+            return platformResult('failed', { error: { code: 'PLATFORM_OPERATION_PAYLOAD_INVALID', message: 'Pull-request bind identity is missing', retryable: false } });
+        return bindPlatformPullRequest(taskId, { agent, cwd, pr: intent.prToken, skipQueue: true });
+    }
+    if (intent.action === 'sync') {
+        const synced = await syncPlatformPullRequest(taskId, {
+            agent, cwd, metadata: intent.metadata === true, closingIssue: intent.closingIssue === true, primaryResult: 'no_op', skipQueue: true
+        });
+        if (synced.warnings.length > 0 || synced.result?.endsWith('_with_warnings')) {
+            return platformResult('blocked', { error: { code: 'PLATFORM_OPERATION_PR_SYNC_UNCONFIRMED', message: 'Pull-request metadata sync remains degraded', retryable: true } });
+        }
+        return synced;
+    }
+    return recoverCreatedPullRequest(taskId, { agent, cwd, base: intent.baseRef || '', head: intent.headRef || '', skipQueue: true });
+}
+async function recoverPlatformOperations(taskRef, selection, options) {
+    const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+    if (!resolved.ok)
+        return result('failed', [], [], { code: resolved.code, message: resolved.message, retryable: false });
+    let journal;
+    try {
+        journal = readPlatformOperationJournal(resolved.taskId, resolved.repoRoot);
+    }
+    catch (error) {
+        const value = error;
+        return result('failed', [], [], { code: value.code || 'PLATFORM_OPERATION_JOURNAL_INVALID', message: value.message || String(error), retryable: false });
+    }
+    const candidates = journal.operations.filter((operation) => operation.id !== options.excludeId
+        && (operation.state === 'queued' || operation.state === 'pending' || operation.state === 'unknown'
+            || (operation.state === 'failed' && operation.lastCode !== 'PLATFORM_OPERATION_SUPERSEDED')))
+        .filter((operation) => selection === 'all' || operation.dependency === selection)
+        .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+    if (!candidates.length)
+        return result('no-op', [], []);
+    const limit = options.limit === undefined ? candidates.length : Math.max(1, options.limit);
+    const recovered = [];
+    const pending = [];
+    const selected = candidates.slice(0, limit);
+    for (const [index, operation] of selected.entries()) {
+        if (operation.state === 'failed') {
+            pending.push(operation.id);
+            return result('blocked', recovered, pending, {
+                code: operation.lastCode || 'PLATFORM_OPERATION_FAILED',
+                message: 'A previous platform operation failed permanently; later writes remain queued',
+                retryable: false
+            });
+        }
+        if (operation.attempts >= operation.maxAttempts) {
+            pending.push(operation.id, ...selected.slice(index + 1).map((next) => next.id));
+            pending.push(...candidates.slice(limit).map((next) => next.id));
+            return result('blocked', recovered, pending, {
+                code: operation.lastCode || 'PLATFORM_OPERATION_RETRY_LIMIT_REACHED',
+                message: 'A previous platform operation exhausted its recovery attempts; later writes remain queued',
+                retryable: false
+            });
+        }
+        if (operation.kind !== 'issue-create') {
+            try {
+                recordPlatformOperation({
+                    taskRef: resolved.taskId, cwd: resolved.repoRoot, kind: operation.kind,
+                    target: operation.target, expectedDigest: operation.expectedDigest,
+                    dependency: operation.dependency, state: 'pending',
+                    ...(operation.issueMetadata ? { issueMetadata: operation.issueMetadata } : {}),
+                    ...(operation.issueCreate ? { issueCreate: operation.issueCreate } : {}),
+                    ...(operation.pullRequest ? { pullRequest: operation.pullRequest } : {}),
+                    ...(operation.pullRequestSummary ? { pullRequestSummary: operation.pullRequestSummary } : {}),
+                    ...(operation.pullRequestReview ? { pullRequestReview: operation.pullRequestReview } : {})
+                });
+            }
+            catch (error) {
+                const value = error;
+                return result('blocked', recovered, [...pending, operation.id], {
+                    code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED',
+                    message: value.message || String(error), retryable: true
+                });
+            }
+        }
+        let targetOperation = operation;
+        if (operation.kind === 'issue-metadata') {
+            const current = currentIssueMetadataOperation(resolved.taskId, resolved.taskMdPath, resolved.repoRoot, operation);
+            if (!current) {
+                pending.push(operation.id);
+                return result('blocked', recovered, pending, { code: 'PLATFORM_OPERATION_TARGET_UNAVAILABLE', message: 'Current Issue metadata target cannot be reconstructed safely', retryable: true });
+            }
+            if (current.target !== operation.target) {
+                return result('blocked', recovered, [...pending, operation.id], { code: 'PLATFORM_OPERATION_IDENTITY_MISMATCH', message: 'Bound Issue identity differs from the journal target', retryable: false });
+            }
+            if (current.id !== operation.id) {
+                try {
+                    recordPlatformOperation({ taskRef: resolved.taskId, cwd: resolved.repoRoot, kind: operation.kind, target: operation.target,
+                        expectedDigest: operation.expectedDigest, issueMetadata: operation.issueMetadata, dependency: operation.dependency,
+                        state: 'failed', lastCode: 'PLATFORM_OPERATION_SUPERSEDED' });
+                    targetOperation = { ...operation, expectedDigest: current.expectedDigest, issueMetadata: current.issueMetadata, id: current.id };
+                }
+                catch (error) {
+                    const value = error;
+                    return result('blocked', recovered, [...pending, operation.id], { code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED', message: value.message || String(error), retryable: true });
+                }
+            }
+        }
+        if (operation.kind === 'task-comment' || operation.kind === 'artifact-comment'
+            || operation.kind === 'summary-comment' || operation.kind === 'cancel-comment') {
+            const commentOptions = operation.kind === 'task-comment'
+                ? { kind: 'task', agent: options.agent, cwd: resolved.repoRoot, dependency: operation.dependency }
+                : operation.kind === 'artifact-comment'
+                    ? { kind: 'artifact', artifact: operation.target, agent: options.agent, cwd: resolved.repoRoot, dependency: operation.dependency }
+                    : operation.kind === 'summary-comment' ? (() => {
+                        const summary = summaryPayload(resolved.taskDir, resolved.taskId);
+                        return summary ? { kind: 'summary', body: summary.body, agent: options.agent, cwd: resolved.repoRoot, summaryAuthorization: { sha256: summary.sha256 }, dependency: operation.dependency } : null;
+                    })() : { kind: 'cancel', agent: options.agent, cwd: resolved.repoRoot, dependency: operation.dependency };
+            const current = commentOptions ? inspectPlatformCommentOperation(resolved.taskId, commentOptions) : null;
+            if (!current) {
+                pending.push(operation.id);
+                return result('blocked', recovered, pending, { code: 'PLATFORM_OPERATION_TARGET_UNAVAILABLE', message: 'Current comment target cannot be reconstructed safely', retryable: true });
+            }
+            if (current.id !== operation.id) {
+                try {
+                    recordPlatformOperation({ taskRef: resolved.taskId, cwd: resolved.repoRoot, kind: operation.kind, target: operation.target,
+                        expectedDigest: operation.expectedDigest, dependency: operation.dependency, state: 'failed', lastCode: 'PLATFORM_OPERATION_SUPERSEDED' });
+                    targetOperation = { ...operation, expectedDigest: current.expectedDigest, id: current.id };
+                }
+                catch (error) {
+                    const value = error;
+                    return result('blocked', recovered, [...pending, operation.id], { code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED', message: value.message || String(error), retryable: true });
+                }
+            }
+        }
+        let remote;
+        try {
+            remote = operation.kind === 'issue-create'
+                ? await verifyIssueCreate(resolved.taskId, operation, resolved.repoRoot)
+                : operation.kind === 'pull-request-summary'
+                    ? await replayPullRequestSummary(resolved.taskId, operation, options.agent, resolved.repoRoot, options.client)
+                    : operation.kind === 'pull-request-review'
+                        ? await replayPullRequestReview(operation, options.agent, resolved.repoRoot, options.client)
+                        : operation.kind === 'issue-metadata'
+                            ? await replayIssueMetadata(resolved.taskId, targetOperation, options.agent, resolved.repoRoot)
+                            : operation.kind === 'pull-request'
+                                ? await replayPullRequest(resolved.taskId, targetOperation, options.agent, resolved.repoRoot)
+                                : await replayComment(resolved.taskId, resolved.taskDir, operation, options.agent, resolved.repoRoot);
+        }
+        catch (error) {
+            const value = error;
+            remote = platformResult('blocked', { error: { code: value.code || 'PLATFORM_OPERATION_RECOVERY_FAILED', message: value.message || String(error), retryable: true } });
+        }
+        const succeeded = (remote.status === 'applied' || remote.status === 'no-op') && !remote.error;
+        try {
+            recordPlatformOperation({
+                taskRef: resolved.taskId,
+                cwd: resolved.repoRoot,
+                kind: operation.kind,
+                target: operation.target,
+                expectedDigest: targetOperation.expectedDigest,
+                ...(targetOperation.issueMetadata ? { issueMetadata: targetOperation.issueMetadata } : {}),
+                ...(operation.issueCreate ? { issueCreate: operation.issueCreate } : {}),
+                ...(operation.pullRequest ? { pullRequest: operation.pullRequest } : {}),
+                ...(operation.pullRequestSummary ? { pullRequestSummary: operation.pullRequestSummary } : {}),
+                ...(operation.pullRequestReview ? { pullRequestReview: operation.pullRequestReview } : {}),
+                dependency: operation.dependency,
+                state: succeeded ? 'succeeded' : remote.status === 'failed' && remote.error?.retryable === false ? 'failed' : 'unknown',
+                lastCode: remote.error?.code ?? null
+            });
+        }
+        catch (error) {
+            const value = error;
+            return result('blocked', recovered, [...pending, operation.id], { code: value.code || 'PLATFORM_OPERATION_JOURNAL_WRITE_FAILED', message: value.message || String(error), retryable: true });
+        }
+        if (!succeeded) {
+            pending.push(targetOperation.id);
+            return result(remote.status === 'failed' ? 'failed' : 'blocked', recovered, pending, remote.error ?? { code: 'PLATFORM_OPERATION_RECOVERY_UNKNOWN', message: 'Platform operation outcome remains unknown', retryable: true });
+        }
+        recovered.push(targetOperation.id);
+    }
+    const remaining = candidates.slice(limit).map((operation) => operation.id);
+    pending.push(...remaining);
+    return result(pending.length ? 'blocked' : recovered.length ? 'applied' : 'no-op', recovered, pending, pending.length ? { code: 'PLATFORM_OPERATION_RECOVERY_PENDING', message: 'Platform operations remain pending after the recovery budget', retryable: true } : null);
+}
+export { fieldsMatchExpected, labelsMatchOwnedPrefix, recoverPlatformOperations };
+//# sourceMappingURL=platform-operation-recovery.js.map

package/dist/lib/task/workflow-warning-intents.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { resolveTaskRef } from './resolve-ref.js';
 import { parseTaskFrontmatter } from './frontmatter.js';
 import { WORKFLOW_WARNING_COLUMNS, WORKFLOW_WARNING_HEADINGS, WORKFLOW_WARNING_SEVERITIES, WORKFLOW_WARNING_STATUSES, parseWorkflowWarnings } from './workflow-warnings.js';
@@ -120,7 +121,12 @@ function projectFinalizationWarning(taskRef, warning, options = {}) {
     let prepared = resolved.state === 'completed';
     if (!prepared && resolved.state === 'active') {
         try {
-            prepared = parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8')).status === 'completed';
+            const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+            prepared = parseTaskFrontmatter(taskContent).status === 'completed';
+            if (!prepared) {
+                const lifecycle = JSON.parse(fs.readFileSync(path.join(resolved.taskDir, '.task-lifecycle.json'), 'utf8'));
+                prepared = lifecycle.taskId === resolved.taskId && lifecycle.intent === 'complete';
+            }
         }
         catch {
             prepared = false;

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.11.7",
-  "sourceInputHash": "095f0cf30aa29fcd2dd45123dc755e5097d7a9f81de33420461fd943cff122b2",
-  "internalExecutableBuildHash": "a956f2ed366e025a111a87bc1f542b87d83d4025e068304f95b1aae704709d3f"
+  "packageVersion": "0.11.8",
+  "sourceInputHash": "6ddb72f8b50137d5148a47172bd7eb2628b17a937ae647ac38350e582ba08124",
+  "internalExecutableBuildHash": "c886e015506879620bb490f1ea5977d9952f2bbb4515d3a0b49e0ec184b48028"
 }

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

@@ -54,7 +54,7 @@ const codexAdapter = defineAgentClientAdapter({
       containerMount: '/home/devuser/.codex',
       versionCmd: 'codex --version',
       setupHint: 'Run codex once inside the container and choose Device Code login if needed.',
-      tmpfs: { size: '512m', seed: ['config.toml', 'model-catalogs'] },
+      tmpfs: { size: '512m', seed: ['config.toml', 'model-catalogs'], exec: true },
       hostLiveMounts: [
         {
           hostPath: hostJoin(home, '.codex', 'auth.json'),

package/lib/agent-clients/config.ts

@@ -167,10 +167,16 @@ function normalizeAgentClients(
   }
   if (hasOwn(input, 'tuis')) fail('INVALID_AGENT_CLIENTS', 'tuis');
   const sandbox = isRecord(input.sandbox) ? input.sandbox : undefined;
-  if (Array.isArray(sandbox?.tools)) {
-    for (const [index, tool] of sandbox.tools.entries()) {
+  if (sandbox && hasOwn(sandbox, 'customTools')) {
+    fail('INVALID_AGENT_CLIENTS', 'sandbox.customTools');
+  }
+  if (sandbox && hasOwn(sandbox, 'tools')) {
+    if (!isRecord(sandbox.tools)) fail('INVALID_AGENT_CLIENTS', 'sandbox.tools');
+    const tools = sandbox.tools;
+    if (!Array.isArray(tools.ids)) fail('INVALID_AGENT_CLIENTS', 'sandbox.tools.ids');
+    for (const [index, tool] of tools.ids.entries()) {
       if (isAgentClientId(tool)) {
-        fail('INVALID_AGENT_CLIENTS', `sandbox.tools[${index}]`);
+        fail('INVALID_AGENT_CLIENTS', `sandbox.tools.ids[${index}]`);
       }
     }
   }

package/lib/defaults.json

@@ -34,9 +34,12 @@
     "runtimes": [
       "node22"
     ],
-    "tools": [
-      "agent-infra"
-    ],
+    "tools": {
+      "ids": [
+        "agent-infra"
+      ],
+      "definitions": {}
+    },
     "refreshIntervalDays": 7,
     "dockerfile": null,
     "vm": {

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

@@ -63,6 +63,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'task-invalidation': ['reconcile'],
   'task-lifecycle': ['intent'],
   'task-finalization': ['complete'],
+  'task-platform-recovery': ['inspect', 'recover'],
   'task-short-id': ['list', 'list-verify', 'alloc', 'release', 'resolve'],
   'task-snapshot': ['snapshot'],
   'task-verify': ['event'],
@@ -89,6 +90,7 @@ export function internalRouteSelector(command: string, args: readonly string[]):
   if (command === 'task-qualification') return args[1] ?? '';
   if (command === 'task-lifecycle') return args[1] ? 'intent' : '';
   if (command === 'task-finalization') return args[1] === 'complete' ? 'complete' : '';
+  if (command === 'task-platform-recovery') return args[1] ?? '';
   if (command === 'task-event') return args[1] ? 'event' : '';
   if (command === 'task-verify') return args[0] && args[1] ? 'event' : '';
   if (command === 'task-snapshot') return 'snapshot';

package/lib/internal/platform-pr-review.ts

@@ -6,14 +6,15 @@ import { listPrReviews, publishPrReview } from '../platform/pr-review.ts';
 import type { PrReviewEvent } from '../platform/pr-review.ts';
 import type { PlatformResult } from '../platform/types.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-pr-review inspect --pr <token> [--cwd <path>]
        agent-infra-internal platform-pr-review list --pr <token> [--cwd <path>]
-       agent-infra-internal platform-pr-review publish --pr <token> --scope <taskId|pr{N}> --round <N> --commit <sha> --event <COMMENT|APPROVE|REQUEST_CHANGES> --body-file <path|-> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr-review publish --pr <token> --scope <taskId|pr{N}> --round <N> --commit <sha> --event <COMMENT|APPROVE|REQUEST_CHANGES> --body-file <path|-> [--artifact <pr-review-artifact>] [--agent <agent>] [--dry-run] [--cwd <path>]
 `;
 
 const BOOLEAN_FLAGS = new Set(['--dry-run']);
-const VALUE_FLAGS = new Set(['--cwd', '--pr', '--scope', '--round', '--commit', '--event', '--body-file']);
+const VALUE_FLAGS = new Set(['--cwd', '--pr', '--scope', '--round', '--commit', '--event', '--body-file', '--artifact', '--agent']);
 
 function key(flag: string): string {
   return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
@@ -67,7 +68,7 @@ async function platformPrReview(args: string[] = []): Promise<void> {
   const allowed: Record<string, string[]> = {
     inspect: ['cwd', 'pr'],
     list: ['cwd', 'pr'],
-    publish: ['cwd', 'pr', 'scope', 'round', 'commit', 'event', 'bodyFile', 'dryRun']
+    publish: ['cwd', 'pr', 'scope', 'round', 'commit', 'event', 'bodyFile', 'artifact', 'agent', 'dryRun']
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
@@ -86,6 +87,8 @@ async function platformPrReview(args: string[] = []): Promise<void> {
   const round = Number(values.round);
   const commit = typeof values.commit === 'string' ? values.commit : '';
   const event = values.event as string;
+  const rawAgent = typeof values.agent === 'string' ? values.agent : '';
+  const agent = rawAgent ? normalizeAgentToken(rawAgent) : null;
   if (!scope || !/^(?:pr\d+|TASK-\d{8}-\d{6})$/.test(scope)) { fail('publish requires --scope <taskId|pr{N}>'); return; }
   if (!internalHandlerRoute('platform-pr-review', 'publish-task', publishSelector)
     && !internalHandlerRoute('platform-pr-review', 'publish-pr', publishSelector)) {
@@ -95,6 +98,12 @@ async function platformPrReview(args: string[] = []): Promise<void> {
   if (!/^[0-9a-f]{7,40}$/i.test(commit)) { fail('publish requires --commit <sha>'); return; }
   if (!['COMMENT', 'APPROVE', 'REQUEST_CHANGES'].includes(event)) { fail('publish requires --event <COMMENT|APPROVE|REQUEST_CHANGES>'); return; }
   if (typeof values.bodyFile !== 'string') { fail('publish requires --body-file'); return; }
+  if (/^TASK-\d{8}-\d{6}$/u.test(scope) && typeof values.artifact !== 'string') { fail('task-scoped publish requires --artifact <pr-review-artifact>'); return; }
+  if (/^TASK-\d{8}-\d{6}$/u.test(scope) && !agent) {
+    fail(`task-scoped publish requires --agent <agent>${rawAgent ? `: invalid '${rawAgent}'` : ''}: ${AGENT_USAGE_HINT}`);
+    return;
+  }
+  if (rawAgent && !agent) { fail(`invalid --agent '${rawAgent}': ${AGENT_USAGE_HINT}`); return; }
   let body: string;
   try {
     body = readBodyFile(values.bodyFile, cwd);
@@ -108,6 +117,8 @@ async function platformPrReview(args: string[] = []): Promise<void> {
     identity: { scope, round, commitSha: commit },
     event: event as PrReviewEvent,
     body,
+    ...(typeof values.artifact === 'string' ? { recoveryArtifact: values.artifact } : {}),
+    ...(agent ? { agent } : {}),
     dryRun: values.dryRun === true
   }));
 }

package/lib/internal/task-operation-registry.ts

@@ -145,6 +145,8 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'task-invalidation', 'reconcile', 'task-bound', 'progress'),
     descriptor('internal', 'task-lifecycle', 'intent', 'task-bound', 'progress'),
     descriptor('internal', 'task-finalization', 'complete', 'task-bound', 'progress'),
+    descriptor('internal', 'task-platform-recovery', 'inspect', 'task-bound', 'diagnostic'),
+    descriptor('internal', 'task-platform-recovery', 'recover', 'task-bound', 'recovery'),
     descriptor('internal', 'task-short-id', 'list', 'conditional', 'diagnostic'),
     descriptor('internal', 'task-short-id', 'list-verify', 'conditional', 'diagnostic'),
     descriptor('internal', 'task-short-id', 'alloc', 'task-bound', 'progress'),
@@ -221,7 +223,7 @@ export const INTERNAL_DISPATCHER_ROUTES = Object.freeze([
   'platform-comment', 'platform-issue', 'platform-pr', 'platform-pr-review', 'pr-review-grade',
   'platform-checks', 'task-context', 'task-ledger', 'task-warning', 'task-activity', 'task-artifact',
   'task-orchestration', 'task-review', 'task-event', 'task-invalidation', 'task-lifecycle',
-  'task-finalization', 'task-short-id', 'task-snapshot', 'task-verify', 'task-validate', 'manual-validation'
+  'task-finalization', 'task-platform-recovery', 'task-short-id', 'task-snapshot', 'task-verify', 'task-validate', 'manual-validation'
 ]);
 export const PUBLIC_DISPATCHER_ROUTES = Object.freeze([
   'agent-client', 'cp', 'data', 'decide', 'help', 'init', 'merge', 'run', 'sandbox', 'server', 'task', 'sync', 'update', 'version'