@fitlab-ai/agent-infra 0.11.10 → 0.11.11

package/dist/lib/agent-clients/adapter.js

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import { AGENT_CLIENT_CAPABILITY_IDS, AGENT_CLIENT_SUPPORT_LEVELS, isAgentClientId } from './types.js';
 import { SANDBOX_HOOK_PHASES } from '../sandbox/tool-types.js';
 const PROJECT_ASSET_CATEGORIES = ['managed', 'merged', 'ejected'];
@@ -65,6 +66,24 @@ function freezeTool(tool) {
     if (!tool.containerMount.startsWith('/')) {
         throw new Error(`Sandbox tool '${tool.id}' containerMount must be absolute`);
     }
+    if (tool.hostStateMounts !== undefined && !Array.isArray(tool.hostStateMounts)) {
+        throw new Error(`Agent Client '${tool.id}' hostStateMounts must be an array`);
+    }
+    const hostStateMounts = tool.hostStateMounts?.map((entry) => {
+        if (!entry || typeof entry.hostSubdir !== 'string' || typeof entry.containerSubpath !== 'string') {
+            throw new Error(`Agent Client '${tool.id}' hostStateMounts must contain relative path pairs`);
+        }
+        for (const value of [entry.hostSubdir, entry.containerSubpath]) {
+            const normalized = path.posix.normalize(value);
+            if (value === ''
+                || path.posix.isAbsolute(value)
+                || normalized === '..'
+                || normalized.startsWith('../')) {
+                throw new Error(`Agent Client '${tool.id}' hostStateMounts must stay within the tool directories`);
+            }
+        }
+        return Object.freeze({ ...entry });
+    });
     if (!tool.versionCmd) {
         throw new Error(`Sandbox tool '${tool.id}' requires versionCmd`);
     }
@@ -82,6 +101,7 @@ function freezeTool(tool) {
         ...(tool.hostLiveMounts ? {
             hostLiveMounts: Object.freeze(tool.hostLiveMounts.map((entry) => Object.freeze({ ...entry })))
         } : {}),
+        ...(hostStateMounts ? { hostStateMounts: Object.freeze(hostStateMounts) } : {}),
         ...(tool.postSetupCmds ? { postSetupCmds: Object.freeze([...tool.postSetupCmds]) } : {}),
         ...(tool.tmpfs ? {
             tmpfs: Object.freeze({

package/dist/lib/agent-clients/adapters/codex-sandbox.js

@@ -241,6 +241,19 @@ const codexRecoveryChecks = [
             path: '/home/devuser/.codex'
         }
     },
+    {
+        id: 'app-server-package-writable',
+        probe: {
+            script: 'probe="$1/.agent-infra-app-server-package-$$"; trap \'rm -f -- "$probe"\' EXIT; : > "$probe"',
+            args: ['/home/devuser/.codex/packages/app-server-daemon'],
+            user: 'devuser'
+        },
+        finding: {
+            repairKind: 'hard-failure',
+            message: 'Codex app-server package directory is not writable by devuser.',
+            path: '/home/devuser/.codex/packages/app-server-daemon'
+        }
+    },
     {
         id: 'prompts-link',
         when: {

package/dist/lib/agent-clients/adapters/codex.js

@@ -51,6 +51,10 @@ const codexAdapter = defineAgentClientAdapter({
             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'], exec: true },
+            hostStateMounts: [{
+                    hostSubdir: 'packages/app-server-daemon',
+                    containerSubpath: 'packages/app-server-daemon'
+                }],
             hostLiveMounts: [
                 {
                     hostPath: hostJoin(home, '.codex', 'auth.json'),

package/dist/lib/internal/manual-validation.js

@@ -196,7 +196,7 @@ async function executeManualValidationTransactionLocked(taskRef, values, cwd, re
         if (transaction.phase === 'prepared') {
             const staged = await syncPullRequestSummary(taskRef, {
                 cwd, client: options.client, agent, body: pendingBody, changeReportFile: path.resolve(cwd, values.changeReportFile), primaryResult: primaryResult, strict: true,
-                manualValidation: { phase: 'pending' }, lockAlreadyHeld: true
+                manualValidation: { phase: 'pending', transactionId: transaction.transactionId }, lockAlreadyHeld: true
             });
             if (!['applied', 'no-op'].includes(staged.status))
                 transactionFailure(staged.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'pending summary staging failed' });
@@ -261,7 +261,7 @@ async function executeManualValidationTransactionLocked(taskRef, values, cwd, re
             try {
                 await syncPullRequestSummary(taskRef, {
                     cwd, client: options.client, agent, body: pendingBody, changeReportFile: path.resolve(cwd, values.changeReportFile), primaryResult: primaryResult, strict: true,
-                    manualValidation: { phase: 'pending' }, lockAlreadyHeld: true
+                    manualValidation: { phase: 'pending', transactionId: transaction.transactionId }, lockAlreadyHeld: true
                 });
             }
             catch {

package/dist/lib/internal/platform-pr.js

@@ -10,7 +10,7 @@ const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd
        agent-infra-internal platform-pr bind <task-ref> --pr <token> --agent <agent> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr skip <task-ref> --agent <agent> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] --result <pr_created|pr_reused|no_op> [--dry-run] [--cwd <path>]
-       agent-infra-internal platform-pr sync-in-labels --pr <N> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr sync-in-labels --pr <token> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr summary-context <task-ref> [--cwd <path>]
        agent-infra-internal platform-pr change-report <task-ref> --agent <agent> --mechanical-file <path> --precheck-file <path> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> --change-report-file <path> --result <pr_created|pr_reused|no_op> [--manual-phase pending|final ...] [--strict] [--dry-run] [--cwd <path>]
@@ -91,13 +91,12 @@ async function platformPr(args = []) {
             fail(`sync-in-labels does not accept --${unexpected}`);
             return;
         }
-        const pr = Number(values.pr);
-        if (!Number.isInteger(pr) || pr <= 0) {
-            fail('sync-in-labels requires a positive --pr');
+        if (typeof values.pr !== 'string' || !values.pr || values.pr.trim() !== values.pr) {
+            fail('sync-in-labels requires a non-empty --pr token');
             return;
         }
         const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
-        finish(await syncPlatformPullRequestInLabels(pr, { cwd, dryRun: values.dryRun === true }));
+        finish(await syncPlatformPullRequestInLabels(values.pr, { cwd, dryRun: values.dryRun === true }));
         return;
     }
     const taskRef = args[1];

package/dist/lib/internal/task-artifact.js

@@ -1,6 +1,6 @@
 import { parseArtifactCommand, executeArtifactCommand } from '../task/artifact-command.js';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.js';
-const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family> [--source-finding <id> --source-artifact <name> --source-sha256 <digest>]\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> preflight|finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, preflight, or finalize workflow artifact facts.\n`;
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family> [--reason-code <reason>] [--source-finding <id> --source-artifact <name> --source-sha256 <digest>]\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> preflight|finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, preflight, or finalize workflow artifact facts.\n`;
 function taskArtifact(args = []) {
     if (!ensureInternalHandlerRoute('task-artifact', args))
         return;

package/dist/lib/internal/task-create.js

@@ -54,7 +54,21 @@ async function taskCreate(args) {
             throw new Error('TASK_CREATE_INPUT_INVALID: input must be a regular file');
         if (stat.size > SANDBOX_CONTROL_MAX_BYTES)
             throw new Error('TASK_CREATE_INPUT_TOO_LARGE: input exceeds the control limit');
-        const candidate = validateTaskCreateCandidate(JSON.parse(fs.readFileSync(inputPath, 'utf8')));
+        const inputContent = fs.readFileSync(inputPath, 'utf8');
+        let candidate;
+        try {
+            candidate = validateTaskCreateCandidate(JSON.parse(inputContent));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'TASK_CREATE_INPUT_INVALID';
+            output(failed(code, message, false, {
+                requestId: null,
+                accepted: false,
+                recovery: 'new-request-id'
+            }));
+            return;
+        }
         const environment = resolveSandboxControlTransport();
         if (environment.kind === 'fail-closed') {
             output(failed(environment.reasonCode ?? 'TASK_CONTROL_TRANSPORT_INVALID', 'sandbox client control configuration is invalid'));

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

@@ -65,9 +65,7 @@ async function taskFinalization(args = []) {
     const transport = resolveSandboxControlTransport(process.env, { localWorkflow: true });
     if (transport.kind === 'sandbox-local') {
         try {
-            const response = requestSandboxTaskFinalization({
-                agent: boundOperation.request.agent
-            });
+            const response = requestSandboxTaskFinalization({ agent: boundOperation.request.agent });
             process.stdout.write(response.stdout);
             process.stderr.write(response.stderr);
             process.exitCode = response.exitCode ?? 1;

package/dist/lib/internal/task-operation-registry.js

@@ -3,7 +3,8 @@ import path from 'node:path';
 import { accessSandboxTaskView, parseSandboxTaskView, taskViewFromStatus } from '../sandbox/control/task-view.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { PUBLIC_CLI_COMMAND_ALIASES, PUBLIC_CLI_SELECTOR_ALIASES, internalRouteSelector } from './cli-route-inventory.js';
-import { readSandboxControlIdentitySentinel } from '../sandbox/control/identity-sentinel.js';
+import { hasSandboxControlMarker, resolveSandboxControlTransport, sandboxTaskMarkerState } from '../sandbox/environment.js';
+export { resolveSandboxControlTransport } from '../sandbox/environment.js';
 const descriptor = (dispatcher, command, selector, scope, effect, taskRefSource = scope === 'non-task' ? 'none' : 'argv') => ({ dispatcher, command, selector, scope, effect, taskRefSource, guardBeforeImport: true });
 function internalTaskRoutes() {
     return [
@@ -232,141 +233,6 @@ export function resolveDelegatedTaskOperation(args) {
         return null;
     return resolveTaskOperation('internal', rest[0], rest.slice(1));
 }
-const TASK_MARKER_KEYS = [
-    'AGENT_INFRA_TASK_ID',
-    'AGENT_INFRA_CONTROL_TOKEN',
-    'AGENT_INFRA_CONTROL_GENERATION',
-    'AGENT_INFRA_CONTROL_DIR',
-    'AGENT_INFRA_CONTROL_STATUS_DIR',
-    'AGENT_INFRA_RUNTIME_DIR'
-];
-const TASK_CONTROL_MARKER_KEYS = [
-    'AGENT_INFRA_CONTROL_TOKEN',
-    'AGENT_INFRA_CONTROL_GENERATION',
-    'AGENT_INFRA_CONTROL_DIR',
-    'AGENT_INFRA_CONTROL_STATUS_DIR'
-];
-const TASK_CONTROL_CONFIG_KEYS = [
-    'AGENT_INFRA_CONTROL_TOKEN',
-    'AGENT_INFRA_CONTROL_GENERATION',
-    'AGENT_INFRA_CONTROL_ROOT_ID',
-    'AGENT_INFRA_CONTROL_DIR',
-    'AGENT_INFRA_CONTROL_STATUS_DIR'
-];
-export const SANDBOX_CONTROL_STATUS_MOUNT = '/run/agent-infra/control-status';
-function nativeDirectoryProbe(candidate) {
-    try {
-        // The fixed mount is a trust anchor. Do not use a mutable node:fs export:
-        // a preload must not turn a mounted sandbox into the direct-host path by
-        // replacing the ordinary filesystem probe.
-        const binding = process.binding('fs');
-        if (!Function.prototype.toString.call(binding.internalModuleStat).includes('[native code]'))
-            return 'unknown';
-        const result = binding.internalModuleStat(candidate);
-        if (result === 1)
-            return 'present';
-        if (result === -2)
-            return 'absent';
-        return 'unknown';
-    }
-    catch {
-        return 'unknown';
-    }
-}
-function taskMarkerState(env) {
-    const present = (key) => Boolean(env[key]);
-    const taskId = present('AGENT_INFRA_TASK_ID');
-    const controls = TASK_CONTROL_MARKER_KEYS.every(present);
-    const runtime = present('AGENT_INFRA_RUNTIME_DIR');
-    const any = TASK_MARKER_KEYS.some(present);
-    if (!any)
-        return 'none';
-    if (taskId && controls && runtime)
-        return 'task-bound';
-    if (!taskId && controls && !runtime)
-        return 'branch-only';
-    return 'incomplete';
-}
-export function resolveSandboxControlTransport(env = process.env, options = {}) {
-    const hasAnyMarker = TASK_MARKER_KEYS.some((key) => Boolean(env[key]))
-        || Boolean(env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING)
-        || Boolean(env.AGENT_INFRA_EXECUTOR_MANIFEST);
-    const fixedStatusDir = options.statusMountPath
-        ?? SANDBOX_CONTROL_STATUS_MOUNT;
-    const fixedStatusProbe = path.isAbsolute(fixedStatusDir)
-        ? nativeDirectoryProbe(fixedStatusDir) : 'absent';
-    if (fixedStatusProbe === 'unknown') {
-        return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_UNAVAILABLE' };
-    }
-    const fixedStatusMounted = fixedStatusProbe === 'present';
-    // A fixed status mount is installed only in a task-bound sandbox. Its
-    // presence is not mutable by the sandbox process, so marker removal must
-    // never make that process look like a direct host invocation.
-    if (!hasAnyMarker) {
-        return fixedStatusMounted
-            ? { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' }
-            : { kind: 'direct-host', reasonCode: null };
-    }
-    const hasCompleteConfig = TASK_CONTROL_CONFIG_KEYS.every((key) => Boolean(env[key]));
-    if (!hasCompleteConfig) {
-        return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
-    }
-    const configuredStatusDir = env.AGENT_INFRA_CONTROL_STATUS_DIR;
-    const configuredStatusProbe = configuredStatusDir && path.isAbsolute(configuredStatusDir)
-        ? nativeDirectoryProbe(configuredStatusDir) : 'absent';
-    if (configuredStatusProbe === 'unknown') {
-        return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_UNAVAILABLE' };
-    }
-    const statusDir = configuredStatusDir && path.isAbsolute(configuredStatusDir)
-        ? configuredStatusProbe === 'present' ? configuredStatusDir : null
-        : fixedStatusMounted ? fixedStatusDir : null;
-    const statusMounted = statusDir !== null;
-    if (env.AGENT_INFRA_EXECUTOR_MANIFEST || env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING) {
-        return { kind: 'fail-closed', reasonCode: 'TASK_CONTROL_TRANSPORT_INVALID' };
-    }
-    const taskBound = Boolean(env.AGENT_INFRA_TASK_ID);
-    const runtime = Boolean(env.AGENT_INFRA_RUNTIME_DIR);
-    if (statusMounted) {
-        let sentinel;
-        try {
-            sentinel = readSandboxControlIdentitySentinel(statusDir);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : '';
-            return { kind: 'fail-closed', reasonCode: message.endsWith('MISSING')
-                    ? 'SANDBOX_CONTROL_IDENTITY_MISSING'
-                    : 'SANDBOX_CONTROL_IDENTITY_MALFORMED' };
-        }
-        if (sentinel.generation !== env.AGENT_INFRA_CONTROL_GENERATION) {
-            return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_GENERATION_MISMATCH' };
-        }
-        if (env.AGENT_INFRA_CONTROL_ROOT_ID && sentinel.controlRootId !== env.AGENT_INFRA_CONTROL_ROOT_ID) {
-            return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_ROOT_ID_MISMATCH' };
-        }
-        if (sentinel.mode === 'task-bound'
-            && (sentinel.taskId !== env.AGENT_INFRA_TASK_ID || !runtime)) {
-            return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH' };
-        }
-        if (sentinel.mode === 'branch-only' && (taskBound || runtime)) {
-            return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH' };
-        }
-        if (!hasCompleteConfig) {
-            return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
-        }
-        return { kind: options.localWorkflow ? 'sandbox-local' : 'broker-client', reasonCode: null };
-    }
-    if (!hasAnyMarker)
-        return { kind: 'direct-host', reasonCode: null };
-    if (!hasCompleteConfig || (taskBound && !runtime) || (!taskBound && runtime)) {
-        return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
-    }
-    return options.localWorkflow
-        ? { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_MISSING' }
-        : { kind: 'broker-client', reasonCode: null };
-}
-export function hasTaskBoundMarker(env = process.env) {
-    return taskMarkerState(env) === 'task-bound';
-}
 function explicitTaskRefForOperation(dispatcher, command, args, selected) {
     if (selected.taskRefSource === 'none' || selected.taskRefSource === 'environment')
         return null;
@@ -446,7 +312,7 @@ function isSandboxExecutorRoute(dispatcher, command, args, env) {
         && first(args) === 'execute'
         && Boolean(env.AGENT_INFRA_EXECUTOR_MANIFEST)
         && Boolean(env.AGENT_INFRA_RUNTIME_DIR)
-        && !TASK_CONTROL_MARKER_KEYS.some((key) => Boolean(env[key]));
+        && !hasSandboxControlMarker(env);
 }
 function viewFromEnvironment(env) {
     const statusDir = env.AGENT_INFRA_CONTROL_STATUS_DIR;
@@ -492,7 +358,7 @@ export function guardTaskOperation(dispatcher, command, args = [], options = {})
             taskView: null
         };
     }
-    const markerState = taskMarkerState(env);
+    const markerState = sandboxTaskMarkerState(env);
     if (markerState === 'incomplete' && !isSandboxExecutorRoute(dispatcher, command, args, env)) {
         throw new TaskViewOperationError('SANDBOX_TASK_VIEW_MARKER_INVALID', 'sandbox task markers are incomplete; refusing to infer host-direct authority');
     }

package/dist/lib/platform/pr-summary.js

@@ -16,6 +16,7 @@ import { resourceIdentityEquals } from './resource-identity.js';
 import { buildPrChangeReport, CANONICAL_REPORT_PLACEHOLDER, readPrChangeReport, replaceCanonicalReportPlaceholder, runMechanicalChangeReport, taskIntentDigest, validateMechanicalReport, validatePrecheckCandidate, writePrChangeReportAtomic } from './pr-change-report.js';
 import { MANUAL_VALIDATION_RECEIPT_PLACEHOLDER, manualValidationFinalSummaryProjectionMatches } from '../task/manual-validation-receipt.js';
 import { readManualValidationCompletion } from '../task/manual-validation-completion.js';
+import { readManualValidationTransaction } from '../task/manual-validation-transaction.js';
 function summaryMarker(taskId) {
     return `<!-- sync-pr:${taskId}:summary -->`;
 }
@@ -119,6 +120,20 @@ async function inspectBoundPullRequest(context, repoRoot, prIdentity, loadedCont
         return { ok: false, status: inspectionError(error), error };
     }
     const remote = inspected.value;
+    if (!remote.identity) {
+        return {
+            ok: false,
+            status: 'failed',
+            error: { code: 'PR_IDENTITY_MISSING', message: 'Provider pull-request inspection did not return a canonical identity', retryable: false }
+        };
+    }
+    if (!resourceIdentityEquals(remote.identity, prIdentity)) {
+        return {
+            ok: false,
+            status: 'failed',
+            error: { code: 'PR_IDENTITY_MISMATCH', message: 'Provider returned a different pull request identity than requested', retryable: false }
+        };
+    }
     const number = remote.number ?? resourceIdentityNumber(remote.identity) ?? resourceIdentityNumber(prIdentity) ?? 0;
     const head = remote.head || { repository: context.platform.repository, ref: '', sha: remote.headSha || '' };
     const base = remote.base || { repository: context.platform.repository, ref: '', sha: remote.baseSha || '' };
@@ -127,7 +142,7 @@ async function inspectBoundPullRequest(context, repoRoot, prIdentity, loadedCont
         value: {
             repository: context.platform.repository,
             number,
-            identity: remote.identity ?? prIdentity,
+            identity: remote.identity,
             nodeId: remote.id,
             url: remote.displayUrl || '',
             state: remote.state === 'closed' ? 'closed' : 'open',
@@ -261,14 +276,18 @@ async function summaryContext(taskRef, options = {}) {
             artifacts: []
         };
     const prIdentity = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.resource : null;
-    const prNumber = resourceIdentityNumber(prIdentity);
+    let prNumber = resourceIdentityNumber(prIdentity);
     const loaded = await resolvePlatformProviderContext({ cwd: resolved.repoRoot, client: options.client });
     const context = loaded.ok ? loaded.value.context : loaded.context;
     let pullRequest = null;
     if (loaded.ok && prIdentity && context.platform.repository && ['no-op', 'degraded'].includes(context.status)) {
         const inspected = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
-        if (inspected.ok)
+        if (inspected.ok) {
             pullRequest = inspected.value;
+            if (Number.isSafeInteger(inspected.value.number) && inspected.value.number > 0) {
+                prNumber = inspected.value.number;
+            }
+        }
     }
     const report = summaryReportStatus(reportPath, pullRequest, taskContent, resolved.repoRoot);
     return {
@@ -493,7 +512,7 @@ async function syncPullRequestSummary(taskRef, options) {
             const prIdentity = boundFact.identity.resource;
             const boundPrNumber = resourceIdentityNumber(prIdentity);
             knownPrNumber = boundPrNumber;
-            const prNumber = boundPrNumber;
+            let prNumber = boundPrNumber;
             const initial = await inspectBoundPullRequest(context, resolved.repoRoot, prIdentity, loaded.value);
             if (!initial.ok)
                 return fail(initial.status, context, initial.error);
@@ -505,9 +524,23 @@ async function syncPullRequestSummary(taskRef, options) {
             if (manual && (manual.phase === 'pending' ? hasFinalManualValidation : !hasFinalManualValidation))
                 return fail('failed', context, { code: 'MANUAL_VALIDATION_SUMMARY_PHASE_INVALID', message: 'manual-validation summary phase does not match the requested writer phase', retryable: false }, prNumber);
             if (manual) {
-                if (prNumber === null)
-                    return fail('failed', context, { code: 'MANUAL_VALIDATION_PR_NUMBER_REQUIRED', message: 'manual-validation summary requires a numeric pull-request identity', retryable: false }, prNumber);
-                if (manual.phase === 'final' && (!manual.transactionId || !manual.receiptDigest || !manual.prHeadSha || manual.prHeadSha !== initial.value.head.sha))
+                if (!Number.isSafeInteger(initial.value.number) || initial.value.number <= 0)
+                    return fail('failed', context, { code: 'MANUAL_VALIDATION_PR_NUMBER_REQUIRED', message: 'manual-validation summary requires a positive safe pull-request number from the authoritative snapshot', retryable: false }, prNumber);
+                prNumber = initial.value.number;
+                knownPrNumber = prNumber;
+                if (!manual.transactionId)
+                    return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'manual-validation summary requires a transaction ID', retryable: false }, prNumber);
+                if (manual.phase === 'pending') {
+                    const transaction = readManualValidationTransaction(resolved.taskDir, {
+                        transactionId: manual.transactionId,
+                        taskId: resolved.taskId,
+                        prNumber,
+                        prHeadSha: initial.value.head.sha
+                    });
+                    if (!transaction.ok)
+                        return fail('failed', context, platformError(transaction.error), prNumber);
+                }
+                if (manual.phase === 'final' && (!manual.receiptDigest || !manual.prHeadSha || manual.prHeadSha !== initial.value.head.sha))
                     return fail('failed', context, { code: 'MANUAL_VALIDATION_TRANSACTION_REQUIRED', message: 'final manual-validation summary requires transaction, receipt, and current head identity', retryable: false }, prNumber);
                 if (manual.phase === 'final') {
                     if (manual.authority !== 'coordinator')
@@ -688,7 +721,11 @@ async function syncPullRequestSummary(taskRef, options) {
                 target: JSON.stringify(prIdentity),
                 expectedDigest: createHash('sha256').update(desired).digest('hex'),
                 dependency: 'deferred',
-                pullRequestSummary: { body: options.body, changeReportFile: options.changeReportFile }
+                pullRequestSummary: {
+                    body: options.body,
+                    changeReportFile: options.changeReportFile,
+                    ...(manual?.transactionId ? { manualValidation: { ...manual, transactionId: manual.transactionId } } : {})
+                }
             };
             if (options.skipQueue)
                 return publish();

package/dist/lib/platform/pull-requests.js

@@ -317,6 +317,21 @@ function normalizeProviderPullRequest(remote, repository, fallbackNumber, fallba
     Object.defineProperty(snapshot, 'identity', { value: identity, enumerable: false, configurable: true });
     return snapshot;
 }
+function inspectedPullRequestIdentityError(remote, requested) {
+    if (!remote.identity)
+        return {
+            code: 'PR_IDENTITY_MISSING',
+            message: 'Provider pull-request inspection did not return a canonical identity',
+            retryable: false
+        };
+    if (!resourceIdentityEquals(remote.identity, requested))
+        return {
+            code: 'PR_IDENTITY_MISMATCH',
+            message: 'Provider returned a different pull request identity than requested',
+            retryable: false
+        };
+    return null;
+}
 function pullRequestIdentity(pullRequest) {
     return pullRequest.identity || { kind: 'number', value: pullRequest.number };
 }
@@ -339,6 +354,9 @@ async function inspectExternalPullRequest(base, prIdentity) {
         : unsupportedProviderOperation(base.provider, 'changeRequests.inspect');
     if (!inspected.ok)
         return providerPullRequestError(base, inspected.error, prNumber);
+    const identityError = inspectedPullRequestIdentityError(inspected.value, prIdentity);
+    if (identityError)
+        return providerPullRequestError(base, identityError, prNumber);
     const pullRequest = normalizeProviderPullRequest(inspected.value, base.context.platform.repository, prNumber || 0, fallback);
     return result('no-op', base.resolved.taskId, base.issueNumber, prNumber, {
         platform: base.context.platform,
@@ -392,6 +410,12 @@ async function inspectPlatformPullRequestByNumber(prNumber, options = {}) {
                 platform: context.platform, capabilities: context.capabilities,
                 resource: { kind: 'pull-request', number, identity }, error: providerError(inspected.error, 'PLATFORM_PROVIDER_OPERATION_FAILED')
             });
+        const identityError = inspectedPullRequestIdentityError(inspected.value, identity);
+        if (identityError)
+            return result('failed', null, null, number, {
+                platform: context.platform, capabilities: context.capabilities,
+                resource: { kind: 'pull-request', number, identity }, error: identityError
+            });
         return result('no-op', null, null, number, {
             platform: context.platform, capabilities: context.capabilities,
             resource: { kind: 'pull-request', number, identity },
@@ -448,27 +472,38 @@ function resourceIdentityLabel(identity) {
     const number = resourceIdentityNumber(identity);
     return number === null ? `${identity.kind} ${identity.value}` : `#${number}`;
 }
-function inLabelResource(kind, identity, before, expected, after, effect) {
-    return { kind, number: resourceIdentityNumber(identity), identity, before: [...before].sort(), expected: [...expected].sort(), after: after ? [...after].sort() : null, effect };
+function inLabelResource(kind, identity, before, expected, after, effect, displayNumber = resourceIdentityNumber(identity)) {
+    return { kind, number: displayNumber, identity, before: [...before].sort(), expected: [...expected].sort(), after: after ? [...after].sort() : null, effect };
 }
-async function syncPlatformPullRequestInLabels(prNumber, options = {}) {
+async function syncPlatformPullRequestInLabels(prToken, options = {}) {
     const cwd = path.resolve(options.cwd || process.cwd());
+    const token = String(prToken);
     const loaded = await resolvePlatformProviderContext({ cwd, client: options.client });
     const context = loaded.ok ? loaded.value.context : loaded.context;
     const usable = (context.status === 'no-op' || context.status === 'degraded') && context.platform.repository;
     if (!loaded.ok || !usable)
-        return result(context.status, null, null, prNumber, {
+        return result(context.status, null, null, null, {
             platform: context.platform, capabilities: context.capabilities, operations: context.operations, error: context.error
         });
-    if (!Number.isSafeInteger(prNumber) || prNumber <= 0)
-        return result('failed', null, null, prNumber, {
+    if (!token || token.trim() !== token)
+        return result('failed', null, null, null, {
             platform: context.platform, capabilities: context.capabilities,
-            error: { code: 'PR_NUMBER_INVALID', message: 'PR number must be positive', retryable: false }
+            error: { code: 'PR_IDENTITY_INVALID', message: 'PR identity token must be non-empty and trimmed', retryable: false }
         });
     const provider = loaded.value.provider;
     const operationContext = providerOperationContext(loaded.value);
     const repository = context.platform.repository;
-    const pullRequestIdentity = providerResourceToken(provider, 'pull-request', String(prNumber));
+    let pullRequestIdentity;
+    try {
+        pullRequestIdentity = providerResourceToken(provider, 'pull-request', token);
+    }
+    catch (error) {
+        return result('failed', null, null, null, {
+            platform: context.platform, capabilities: context.capabilities,
+            error: { code: 'PR_IDENTITY_INVALID', message: error instanceof Error ? error.message : String(error), retryable: false }
+        });
+    }
+    let prNumber = resourceIdentityNumber(pullRequestIdentity);
     const providerFailure = (error) => result(error.code === 'PLATFORM_CAPABILITY_UNSUPPORTED' ? 'degraded' : providerStatus(error), null, null, prNumber, {
         platform: context.platform,
         capabilities: context.capabilities,
@@ -480,7 +515,13 @@ async function syncPlatformPullRequestInLabels(prNumber, options = {}) {
         : unsupportedProviderOperation(provider, 'changeRequests.inspect');
     if (!inspected.ok)
         return providerFailure(inspected.error);
-    const fetched = normalizeProviderPullRequest(inspected.value, repository, prNumber);
+    const identityError = inspectedPullRequestIdentityError(inspected.value, pullRequestIdentity);
+    if (identityError)
+        return providerFailure(identityError);
+    if (Number.isSafeInteger(inspected.value.number) && inspected.value.number > 0) {
+        prNumber = inspected.value.number;
+    }
+    const fetched = normalizeProviderPullRequest(inspected.value, repository, prNumber ?? 0);
     const files = provider.changeRequests?.listFiles
         ? await provider.changeRequests.listFiles({ context: operationContext, target: pullRequestIdentity })
         : unsupportedProviderOperation(provider, 'changeRequests.listFiles');
@@ -549,7 +590,7 @@ async function syncPlatformPullRequestInLabels(prNumber, options = {}) {
         }))
     ];
     const willWrite = context.capabilities.triage && !options.dryRun;
-    const resourcesState = plans.map((item) => inLabelResource(item.kind, item.identity, item.snapshot.labels, item.plan.target, item.plan.changed && willWrite ? null : item.snapshot.labels, item.plan.changed && willWrite ? 'unknown' : 'no-op'));
+    const resourcesState = plans.map((item) => inLabelResource(item.kind, item.identity, item.snapshot.labels, item.plan.target, item.plan.changed && willWrite ? null : item.snapshot.labels, item.plan.changed && willWrite ? 'unknown' : 'no-op', item.number));
     if (options.dryRun || !context.capabilities.triage)
         return result(!context.capabilities.triage || association.value.length !== 1 ? 'degraded' : plans.some((item) => item.plan.changed) ? 'planned' : 'no-op', null, issueNumber, prNumber, {
             platform: context.platform, capabilities: context.capabilities, pullRequest: fetched,
@@ -611,6 +652,16 @@ async function syncPlatformPullRequestInLabels(prNumber, options = {}) {
                 evidence: { kind: 'pull-request-files', pullRequestFiles: files.value, closingIssues: closingIssueIdentities },
                 error: { ...providerError(reread.error, 'PLATFORM_PROVIDER_OPERATION_FAILED'), code: 'IN_LABEL_SYNC_PARTIAL', message: `In-label synchronization is partial or unknown: ${reread.error.message}` }
             });
+        if (item.kind === 'pull-request') {
+            const identityError = inspectedPullRequestIdentityError(reread.value, item.identity);
+            if (identityError)
+                return result('blocked', null, issueNumber, prNumber, {
+                    changed: true, platform: context.platform, capabilities: context.capabilities,
+                    pullRequest: currentPullRequest, resource: { kind: 'pull-request', number: prNumber, identity: pullRequestIdentity }, operations, resources: resourcesState,
+                    evidence: { kind: 'pull-request-files', pullRequestFiles: files.value, closingIssues: closingIssueIdentities },
+                    error: { ...identityError, code: 'IN_LABEL_SYNC_PARTIAL', message: `In-label synchronization is partial or unknown: ${identityError.message}` }
+                });
+        }
         const after = reread.value.labels || [];
         const state = resourcesState.find((resource) => resource.kind === item.kind && resourceIdentityEquals(resource.identity, item.identity));
         state.after = after;
@@ -623,7 +674,7 @@ async function syncPlatformPullRequestInLabels(prNumber, options = {}) {
                 error: { code: 'IN_LABEL_SYNC_PARTIAL', message: `${item.kind} ${resourceIdentityLabel(item.identity)} did not converge to the expected in: labels`, retryable: true }
             });
         if (item.kind === 'pull-request')
-            currentPullRequest = normalizeProviderPullRequest(reread.value, repository, prNumber, currentPullRequest);
+            currentPullRequest = normalizeProviderPullRequest(reread.value, repository, prNumber ?? currentPullRequest.number, currentPullRequest);
     }
     return result(association.value.length !== 1 ? 'degraded' : successfulWrites > 0 ? 'applied' : 'no-op', null, issueNumber, prNumber, {
         changed: successfulWrites > 0, platform: context.platform, capabilities: context.capabilities,
@@ -856,9 +907,13 @@ async function resolveExternalPullRequest(taskRef, options) {
         ? await base.provider.changeRequests.inspect({
             context: providerOperationContext(base.loadedContext),
             target: pullRequestIdentity(selected.selected)
-        }).then((response) => response.ok
-            ? { ok: true, value: normalizeProviderPullRequest(response.value, base.context.platform.repository, selected.selected.number, selected.selected) }
-            : response)
+        }).then((response) => {
+            if (!response.ok)
+                return response;
+            const identityError = inspectedPullRequestIdentityError(response.value, pullRequestIdentity(selected.selected));
+            return identityError ? { ok: false, error: identityError }
+                : { ok: true, value: normalizeProviderPullRequest(response.value, base.context.platform.repository, selected.selected.number, selected.selected) };
+        })
         : unsupportedProviderOperation(base.provider, 'changeRequests.inspect');
     if (!rechecked.ok || !rechecked.value)
         return externalResult(result(rechecked.ok ? 'failed' : rechecked.error.retryable ? 'blocked' : 'failed', base.resolved.taskId, base.issueNumber, base.prNumber, {
@@ -1152,6 +1207,9 @@ async function createExternalPullRequest(taskRef, options, base) {
         : unsupportedProviderOperation(base.provider, 'changeRequests.inspect');
     if (!inspected.ok)
         return withCreation(providerPullRequestError(base, inspected.error, number), { kind: 'created', createdByCurrentOperation: true });
+    const identityError = inspectedPullRequestIdentityError(inspected.value, createdIdentity);
+    if (identityError)
+        return withCreation(providerPullRequestError(base, identityError, number), { kind: 'created', createdByCurrentOperation: true });
     const pullRequest = normalizeProviderPullRequest(inspected.value, base.context.platform.repository, inspected.value.number ?? fallback.number, fallback);
     if (!pullRequest.nodeId || !isUsableResourceIdentity(pullRequestIdentity(pullRequest)))
         return withCreation(result('failed', base.resolved.taskId, base.issueNumber, null, {
@@ -1354,6 +1412,13 @@ async function syncPlatformPullRequestImpl(taskRef, options) {
                     code: 'IN_LABEL_SYNC_PARTIAL',
                     message: `In-label synchronization is partial or unknown: ${reread.error.message}`
                 }, base.prNumber));
+            const identityError = inspectedPullRequestIdentityError(reread.value, base.prIdentity);
+            if (identityError)
+                return softenFailure(providerPullRequestError(base, {
+                    ...identityError,
+                    code: 'IN_LABEL_SYNC_PARTIAL',
+                    message: `Pull-request metadata synchronization is partial or unknown: ${identityError.message}`
+                }, base.prNumber));
             finalPullRequest = normalizeProviderPullRequest(reread.value, base.context.platform.repository, base.prNumber || 0, inspected.pullRequest);
             const expected = ((planned.find((operation) => operation.name === 'labels')?.value || [])
                 .filter((label) => label.startsWith('in:') || label.startsWith('type:'))).sort();