@fitlab-ai/agent-infra 0.11.10 → 0.11.12

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();

package/dist/lib/platform/verification-sync.js

@@ -457,7 +457,7 @@ function checkTaskCommentContent(context, remoteData, shared) {
     return shared.failResult(CHECK_TYPE, buildCommentContentMismatchMessage("task", context.issueNumber, expectedBody, commentBody), "check_failed");
 }
 function checkPrTypeLabel(context, remoteData, shared) {
-    if (!context.audit.enabled || !context.hasTriage || !context.prNumber || !remoteData.prLabels) {
+    if (!context.audit.enabled || !context.hasTriage || !context.prIdentity || remoteData.prLabels === undefined || remoteData.prLabels === null) {
         return infoResult('PR type-label audit is not applicable because the required PR metadata or capability is unavailable');
     }
     const expectedLabel = mapTaskTypeToLabel(context.task.metadata.type);
@@ -465,12 +465,12 @@ function checkPrTypeLabel(context, remoteData, shared) {
         return infoResult('PR type-label audit is not applicable because the task type has no label mapping');
     }
     if (remoteData.prLabels.includes(expectedLabel)) {
-        return shared.passResult(CHECK_TYPE, `PR #${context.prNumber} has expected type label '${expectedLabel}'`);
+        return shared.passResult(CHECK_TYPE, `${pullRequestLabel(context)} has expected type label '${expectedLabel}'`);
     }
-    return shared.failResult(CHECK_TYPE, `Expected type label '${expectedLabel}' not found on PR #${context.prNumber}`, "check_failed");
+    return shared.failResult(CHECK_TYPE, `Expected type label '${expectedLabel}' not found on ${pullRequestLabel(context)}`, "check_failed");
 }
 function checkInLabelsMatchPr(context, remoteData, shared) {
-    if (!context.audit.enabled || !context.hasTriage || !context.prNumber || !remoteData.prLabels) {
+    if (!context.audit.enabled || !context.hasTriage || !context.prIdentity || remoteData.prLabels === undefined || remoteData.prLabels === null) {
         return infoResult('PR in: label audit is not applicable because the required PR metadata or capability is unavailable');
     }
     const issueInLabels = extractLabelNames(remoteData.issue.labels)
@@ -480,9 +480,12 @@ function checkInLabelsMatchPr(context, remoteData, shared) {
         .filter((label) => label.startsWith("in:"))
         .sort();
     if (arraysEqual(issueInLabels, prInLabels)) {
-        return shared.passResult(CHECK_TYPE, `PR #${context.prNumber} in: labels match Issue #${context.issueNumber}`);
+        return shared.passResult(CHECK_TYPE, `${pullRequestLabel(context)} in: labels match Issue #${context.issueNumber}`);
     }
-    return shared.failResult(CHECK_TYPE, `in: labels mismatch — PR #${context.prNumber} has [${formatLabelList(prInLabels)}], Issue #${context.issueNumber} has [${formatLabelList(issueInLabels)}]`, "check_failed");
+    return shared.failResult(CHECK_TYPE, `in: labels mismatch — ${pullRequestLabel(context)} has [${formatLabelList(prInLabels)}], Issue #${context.issueNumber} has [${formatLabelList(issueInLabels)}]`, "check_failed");
+}
+function pullRequestLabel(context) {
+    return context.prNumber ? `PR #${context.prNumber}` : 'Pull request';
 }
 function checkInLabelsComputed(context, remoteData, shared) {
     if (!context.audit.enabled || !context.hasTriage) {
@@ -574,13 +577,13 @@ function checkIssueFields(context, remoteData, shared) {
     return shared.passResult(CHECK_TYPE, `Issue #${context.issueNumber} fields match task metadata`);
 }
 function checkPrAssignee(context, remoteData, shared) {
-    if (!context.audit.enabled || !context.hasPush || !context.prNumber) {
+    if (!context.audit.enabled || !context.hasPush || !context.prIdentity || remoteData.prAssignees === undefined || remoteData.prAssignees === null) {
         return infoResult('PR assignee audit is not applicable because it is disabled or required PR metadata/capability is unavailable');
     }
-    if (!remoteData.prAssignees || remoteData.prAssignees.length === 0) {
-        return shared.failResult(CHECK_TYPE, `PR #${context.prNumber} has no assignee`, "check_failed");
+    if (remoteData.prAssignees.length === 0) {
+        return shared.failResult(CHECK_TYPE, `${pullRequestLabel(context)} has no assignee`, "check_failed");
     }
-    return shared.passResult(CHECK_TYPE, `PR #${context.prNumber} has an assignee`);
+    return shared.passResult(CHECK_TYPE, `${pullRequestLabel(context)} has an assignee`);
 }
 function checkMilestone(context, remoteData, shared) {
     if (!context.hasTriage) {
@@ -589,16 +592,16 @@ function checkMilestone(context, remoteData, shared) {
     if (!remoteData.issue?.milestone?.title) {
         return shared.failResult(CHECK_TYPE, `Issue #${context.issueNumber} has no milestone set`, "check_failed");
     }
-    if (context.prNumber && remoteData.prMilestone !== undefined && !remoteData.prMilestone?.title) {
-        return shared.failResult(CHECK_TYPE, `PR #${context.prNumber} has no milestone set`, "check_failed");
+    if (context.prIdentity && remoteData.prMilestone !== undefined && !remoteData.prMilestone?.title) {
+        return shared.failResult(CHECK_TYPE, `${pullRequestLabel(context)} has no milestone set`, "check_failed");
     }
     if (context.audit.requireSpecificMilestone) {
         const issueTitle = remoteData.issue.milestone.title;
         if (VERSION_LINE_REGEX.test(issueTitle)) {
             return shared.failResult(CHECK_TYPE, `Issue #${context.issueNumber} milestone '${issueTitle}' is a release line; narrow to a specific version (e.g. ${issueTitle.replace(/\.x$/, ".N")}) before continuing`, "check_failed");
         }
-        if (context.prNumber && remoteData.prMilestone?.title && VERSION_LINE_REGEX.test(remoteData.prMilestone.title)) {
-            return shared.failResult(CHECK_TYPE, `PR #${context.prNumber} milestone '${remoteData.prMilestone.title}' is a release line; narrow to a specific version before continuing`, "check_failed");
+        if (context.prIdentity && remoteData.prMilestone?.title && VERSION_LINE_REGEX.test(remoteData.prMilestone.title)) {
+            return shared.failResult(CHECK_TYPE, `${pullRequestLabel(context)} milestone '${remoteData.prMilestone.title}' is a release line; narrow to a specific version before continuing`, "check_failed");
         }
     }
     return shared.passResult(CHECK_TYPE, `Issue #${context.issueNumber} milestone satisfies the configured policy`);

package/dist/lib/runtime/agent-runtime.js

@@ -1,5 +1,5 @@
 import path from 'node:path';
-const CLIENT_NAMESPACE = /^[a-z][a-z0-9-]{0,31}$/u;
+import { resolveTaskRuntimeRoot } from '../task/runtime-paths.js';
 function runtimeError(code, message) {
     const error = new Error(`${code}: ${message}`);
     error.name = code;
@@ -9,16 +9,9 @@ function boundControlContext(env) {
     return [
         'AGENT_INFRA_CONTROL_TOKEN',
         'AGENT_INFRA_CONTROL_GENERATION',
-        'AGENT_INFRA_EXECUTOR_MANIFEST',
-        'AGENT_INFRA_CODEX_CONTROLLER_CONTEXT'
+        'AGENT_INFRA_EXECUTOR_MANIFEST'
     ].some((key) => typeof env[key] === 'string' && env[key].length > 0);
 }
-function clientNamespace(client) {
-    if (!CLIENT_NAMESPACE.test(client)) {
-        throw runtimeError('AGENT_INFRA_RUNTIME_CLIENT_INVALID', `invalid runtime client namespace '${client}'`);
-    }
-    return client;
-}
 export function resolveAgentRuntimeRoot(options = {}) {
     const env = options.env ?? process.env;
     const configured = env.AGENT_INFRA_RUNTIME_DIR;
@@ -28,29 +21,13 @@ export function resolveAgentRuntimeRoot(options = {}) {
         }
         return path.resolve(configured);
     }
+    const taskId = env.AGENT_INFRA_TASK_ID;
+    if (taskId) {
+        return resolveTaskRuntimeRoot(taskId, { repoRoot: options.repoRoot });
+    }
     if (boundControlContext(env)) {
         throw runtimeError('AGENT_INFRA_RUNTIME_DIR_REQUIRED', 'task-bound control context requires AGENT_INFRA_RUNTIME_DIR');
     }
     return path.join(path.resolve(options.repoRoot ?? process.cwd()), '.agents', 'workspace', '.runtime');
 }
-export function resolveAgentRuntimeStoreRoot(options = {}) {
-    const client = clientNamespace(options.client ?? 'codex');
-    if (options.explicitRoot)
-        return path.resolve(options.explicitRoot);
-    const env = options.env ?? process.env;
-    const runtimeRoot = resolveAgentRuntimeRoot({ repoRoot: options.repoRoot, env });
-    if (env.AGENT_INFRA_RUNTIME_DIR) {
-        if (!options.store) {
-            throw runtimeError('AGENT_INFRA_RUNTIME_STORE_INVALID', 'store kind is required for task-bound runtime');
-        }
-        return path.join(runtimeRoot, 'clients', client, options.store);
-    }
-    if (client === 'codex' && options.store) {
-        return path.join(runtimeRoot, `codex-${options.store}`);
-    }
-    if (!options.store) {
-        throw runtimeError('AGENT_INFRA_RUNTIME_STORE_INVALID', 'store kind is required');
-    }
-    return path.join(runtimeRoot, 'clients', client, options.store);
-}
 //# sourceMappingURL=agent-runtime.js.map

package/dist/lib/sandbox/commands/control-status.js

@@ -8,6 +8,7 @@ export function readSandboxControlStatusForRow(config, row) {
         : { mode: 'branch-only' };
     const control = sandboxControlPaths({
         base: config.controlBase,
+        repoRoot: config.repoRoot,
         project: config.project,
         container: row.name,
         identity

package/dist/lib/sandbox/commands/create.js

@@ -672,7 +672,7 @@ function readProjectInitCommandDigest(controlRoot) {
 function writeProjectInitCommandDigest(controlRoot, commandSha256) {
     atomicWriteJson(path.join(controlRoot, 'project-init.json'), { version: 1, commandSha256 });
 }
-export async function create(args, { runProjectInitCommand = true } = {}) {
+export async function create(args, { runProjectInitCommand = true, workspace: workspaceOverride } = {}) {
     const { values, positionals } = parseArgs({
         args,
         allowPositionals: true,
@@ -696,7 +696,13 @@ export async function create(args, { runProjectInitCommand = true } = {}) {
     validateSelinuxDisableEnv();
     const config = loadConfig();
     const [branchOrTaskId = '', base] = positionals;
-    const target = resolveSandboxTarget(branchOrTaskId, config.repoRoot);
+    const resolvedTarget = resolveSandboxTarget(branchOrTaskId, config.repoRoot);
+    const workspace = workspaceOverride?.mode === 'task-bound'
+        && resolvedTarget.workspace.mode === 'task-bound'
+        && workspaceOverride.taskId === resolvedTarget.workspace.taskId
+        ? resolvedTarget.workspace
+        : workspaceOverride ?? resolvedTarget.workspace;
+    const target = { ...resolvedTarget, workspace };
     const branch = target.branch;
     assertValidBranchName(branch);
     const effectiveConfig = {
@@ -735,6 +741,7 @@ export async function create(args, { runProjectInitCommand = true } = {}) {
     const container = containerName(effectiveConfig, branch);
     const controlPaths = sandboxControlPaths({
         base: effectiveConfig.controlBase,
+        repoRoot: effectiveConfig.repoRoot,
         project: effectiveConfig.project,
         container,
         identity: target.workspace
@@ -866,6 +873,9 @@ export async function create(args, { runProjectInitCommand = true } = {}) {
                 task: async () => {
                     for (const { tool, dir } of effectiveResolvedTools) {
                         fs.mkdirSync(dir, { recursive: true });
+                        for (const { hostSubdir } of tool.hostStateMounts ?? []) {
+                            fs.mkdirSync(path.join(dir, hostSubdir), { recursive: true });
+                        }
                         for (const { hostPath, sandboxName } of tool.hostPreSeedFiles ?? []) {
                             const destination = path.join(dir, sandboxName);
                             if (fs.existsSync(hostPath) && !fs.existsSync(destination)) {
@@ -1105,6 +1115,10 @@ export async function create(args, { runProjectInitCommand = true } = {}) {
                                 '-v',
                                 volumeArg(engine, hostPath, path.posix.join(tool.containerMount, containerSubpath))
                             ]));
+                            const hostStateMountVolumes = effectiveResolvedTools.flatMap(({ tool, dir }) => (tool.hostStateMounts ?? []).flatMap(({ hostSubdir, containerSubpath }) => [
+                                '-v',
+                                volumeArg(engine, path.join(dir, hostSubdir), path.posix.join(tool.containerMount, containerSubpath))
+                            ]));
                             fs.mkdirSync(shareCommon, { recursive: true });
                             fs.mkdirSync(shareBranch, { recursive: true });
                             fs.mkdirSync(clipboardHostDir(effectiveConfig.home), { recursive: true, mode: 0o700 });
@@ -1133,6 +1147,8 @@ export async function create(args, { runProjectInitCommand = true } = {}) {
                                     `${sandboxBranchLabel(effectiveConfig)}=${branch}`,
                                     '--label',
                                     `${sandboxWorkspaceModeLabel(effectiveConfig)}=${target.workspace.mode}`,
+                                    '-e',
+                                    'AGENT_INFRA_SANDBOX=1',
                                     ...(target.workspace.mode === 'task-bound'
                                         ? [
                                             '--label',
@@ -1163,6 +1179,7 @@ export async function create(args, { runProjectInitCommand = true } = {}) {
                                     ...tmpfsArgs,
                                     ...tmpfsSeedPlan.flatMap(({ volumeArgs }) => volumeArgs),
                                     ...liveMountVolumes,
+                                    ...hostStateMountVolumes,
                                     ...envFile.dockerArgs,
                                     ...tzFlags,
                                     '-w',

package/dist/lib/sandbox/commands/enter.js

@@ -8,15 +8,16 @@ import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.js';
 import { redactCommandError } from '../redaction.js';
 import { runInteractiveWithClipboardBridge } from '../clipboard/bridge.js';
 import { detectHostTimezone } from '../host-timezone.js';
-import { fetchSandboxRows, selectSandboxContainer, } from './list-running.js';
-import { resolveSandboxReentryContext, resolveSandboxTarget } from '../workspace-identity.js';
+import { fetchSandboxRows, selectSandboxContainer, startSandboxContainer, } from './list-running.js';
+import { resolveSandboxTarget } from '../workspace-identity.js';
 const USAGE = `Usage: ai sandbox exec [--recreate] <branch | TASK-id | N> [cmd...]
 
 N references an active task short id from
 .agents/workspace/active/.short-ids.json. They resolve only via that
 registry — they do not reference a container's row position in
-'ai sandbox ls' output. --recreate is a host recovery flag only before the
-target; the same token after the target is passed to the container command.`;
+'ai sandbox ls' output. --recreate rebuilds the matched container while
+preserving its task or branch identity. The same token after the target is
+passed to the container command.`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
 // Terminal-detection variables that interactive TUIs (e.g. claude-code)
 // inspect to enable progressive enhancements such as the kitty keyboard
@@ -78,41 +79,54 @@ export async function enter(args) {
     const config = loadConfig();
     const engine = detectEngine(config);
     const parsed = parseEnterArgs(args);
-    const target = resolveSandboxTarget(parsed.target, config.repoRoot);
-    const branch = target.branch;
-    assertValidBranchName(branch);
+    const fullTaskId = /^TASK-\d{8}-\d{6}$/.test(parsed.target);
+    const target = fullTaskId ? null : resolveSandboxTarget(parsed.target, config.repoRoot);
+    const branch = target?.branch ?? '';
+    if (branch)
+        assertValidBranchName(branch);
     const { running, nonRunning } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config), {
         mode: sandboxWorkspaceModeLabel(config),
         taskId: sandboxTaskIdLabel(config)
     });
-    const found = selectSandboxContainer([...running, ...nonRunning], containerNameCandidates(config, branch));
-    if (!found) {
-        throw new Error(`No sandbox found for branch '${branch}'. Run 'ai sandbox create ${branch}' to create one.`);
+    const rows = [...running, ...nonRunning];
+    const found = fullTaskId
+        ? rows.find((row) => row.taskId === parsed.target)
+        : rows.find((row) => row.branch === branch)
+            ?? selectSandboxContainer(rows, containerNameCandidates(config, branch));
+    if (!found)
+        throw new Error(`No sandbox found for '${parsed.target}'.`);
+    const sandboxBranch = found.branch || branch;
+    if (sandboxBranch)
+        assertValidBranchName(sandboxBranch);
+    if (target?.workspace.mode === 'task-bound' && found.taskId !== target.workspace.taskId) {
+        throw new Error(`Sandbox task mismatch for short id '${parsed.target}'.`);
     }
-    const containerWorkspace = found.workspaceMode === 'task-bound' && found.taskId
+    const workspace = found.workspaceMode === 'task-bound' && found.taskId
         ? { mode: 'task-bound', taskId: found.taskId }
-        : found.workspaceMode === 'branch-only'
-            ? { mode: 'branch-only' }
-            : { mode: 'legacy-invalid' };
-    const reentry = resolveSandboxReentryContext({
-        target,
-        containerWorkspace,
-        repoRoot: config.repoRoot
-    });
-    const ready = await ensureSandboxReady({
-        config,
-        engine,
-        branch,
-        workspace: reentry.workspace,
-        reentry: reentry.reentry,
-        row: found,
-        allowRecreate: parsed.recreate,
-        recreate: async () => {
-            const { create } = await import('./create.js');
-            await create([target.requestedRef, '--no-refresh'], { runProjectInitCommand: false });
-        }
-    });
-    const container = ready.container;
+        : { mode: 'branch-only' };
+    let container = found.name;
+    if (parsed.recreate) {
+        const ready = await ensureSandboxReady({
+            config,
+            engine,
+            branch: sandboxBranch,
+            workspace,
+            row: found,
+            allowRecreate: true,
+            forceRecreate: true,
+            recreate: async () => {
+                const { create } = await import('./create.js');
+                await create([sandboxBranch, '--no-refresh'], {
+                    runProjectInitCommand: false,
+                    workspace
+                });
+            }
+        });
+        container = ready.container;
+    }
+    else if (!found.running) {
+        startSandboxContainer(engine, found.name);
+    }
     const cmd = parsed.command;
     const capabilityPlan = createSandboxCapabilityPlan(config);
     const enterHookResults = await runSandboxHooks({