@fitlab-ai/agent-infra 0.11.9 → 0.11.10

package/lib/platform/issue-comments.ts

@@ -7,6 +7,7 @@ import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { coordinatePlatformWrite } from './operation-coordinator.ts';
 import { resolvePlatformProviderContext } from './context.ts';
 import type { PlatformClient } from './context.ts';
+import { providerErrorRetryable } from './provider-validation.ts';
 import { platformResult } from './types.ts';
 import type { PlatformOperation, PlatformResult } from './types.ts';
 import {
@@ -34,6 +35,10 @@ import {
 } from './comment-safety.ts';
 import type { FenceRange } from './comment-safety.ts';
 
+function isRetryable(error: { code: string; retryable?: boolean }): boolean {
+  return error.retryable ?? providerErrorRetryable(error.code);
+}
+
 type RemoteComment = {
   id: number | string;
   body: string;
@@ -578,7 +583,7 @@ async function syncPlatformCommentImpl(taskRef: string, options: SyncOptions): P
   const issue = resourceIdentityNumber(issueIdentityFromTask);
   const listed = await listedComments(loaded.value.provider, loaded.value, issueIdentityFromTask);
   if (!listed.ok) {
-    return platformResult(listed.error.retryable ? 'blocked' : 'failed', {
+    return platformResult(isRetryable(listed.error) ? 'blocked' : 'failed', {
       ...contextFields(context), resource: { kind: 'issue', number: issue }, error: listed.error
     });
   }
@@ -648,10 +653,10 @@ async function syncPlatformCommentImpl(taskRef: string, options: SyncOptions): P
         })
         : unsupportedProviderOperation(loaded.value.provider, 'comments.write');
     if (!written.ok) {
-      if (!current && written.error.retryable) {
+      if (!current && isRetryable(written.error)) {
         // A provider owns reconciliation because only it knows how to address the resource.
       }
-      return platformResult(written.error.retryable ? 'blocked' : 'failed', {
+      return platformResult(isRetryable(written.error) ? 'blocked' : 'failed', {
         ...contextFields(context),
         resource: { kind: 'issue', number: issue },
         operations,
@@ -674,7 +679,7 @@ async function syncPlatformCommentImpl(taskRef: string, options: SyncOptions): P
         })
         : unsupportedProviderOperation(loaded.value.provider, 'comments.delete');
     if (!deleted.ok) {
-      return platformResult(deleted.error.retryable ? 'blocked' : 'failed', {
+      return platformResult(isRetryable(deleted.error) ? 'blocked' : 'failed', {
         ...contextFields(context),
         resource: { kind: 'issue', number: issue },
         operations,
@@ -686,7 +691,7 @@ async function syncPlatformCommentImpl(taskRef: string, options: SyncOptions): P
   if (options.kind === 'summary') {
     const refreshed = await listedComments(loaded.value.provider, loaded.value, issueIdentityFromTask);
     if (!refreshed.ok) {
-      return platformResult(refreshed.error.retryable ? 'blocked' : 'failed', {
+      return platformResult(isRetryable(refreshed.error) ? 'blocked' : 'failed', {
         ...contextFields(context), resource: { kind: 'issue', number: issue }, operations, error: refreshed.error
       });
     }
@@ -714,7 +719,7 @@ async function syncPlatformCommentImpl(taskRef: string, options: SyncOptions): P
         })
         : unsupportedProviderOperation(loaded.value.provider, 'comments.delete');
       if (!deleted.ok) {
-        return platformResult(deleted.error.retryable ? 'blocked' : 'failed', {
+        return platformResult(isRetryable(deleted.error) ? 'blocked' : 'failed', {
           ...contextFields(context), resource: { kind: 'issue', number: issue }, operations, error: deleted.error
         });
       }
@@ -725,7 +730,7 @@ async function syncPlatformCommentImpl(taskRef: string, options: SyncOptions): P
         })
         : unsupportedProviderOperation(loaded.value.provider, 'comments.write');
       if (!written.ok) {
-        return platformResult(written.error.retryable ? 'blocked' : 'failed', {
+        return platformResult(isRetryable(written.error) ? 'blocked' : 'failed', {
           ...contextFields(context), resource: { kind: 'issue', number: issue }, operations, error: written.error
         });
       }
@@ -736,7 +741,7 @@ async function syncPlatformCommentImpl(taskRef: string, options: SyncOptions): P
         const error = reconciled.ok
           ? { code: 'SUMMARY_POSITION_UNVERIFIED', message: 'Summary comment is not provably last among task-managed comments', retryable: true }
           : reconciled.error;
-        return platformResult(error.retryable ? 'blocked' : 'failed', {
+        return platformResult(isRetryable(error) ? 'blocked' : 'failed', {
           ...contextFields(context), resource: { kind: 'issue', number: issue }, operations, error
         });
       }
@@ -837,7 +842,7 @@ async function checkPlatformCommentOwner(taskRef: string, options: { cwd?: strin
         ? { ok: true as const, value: response.value.map((comment) => ({ id: comment.id, body: comment.body, user: comment.author?.name ? { login: comment.author.name } : undefined })) }
         : response)
       : unsupportedProviderOperation(loaded.value.provider, 'comments.list');
-  if (!listed.ok) return platformResult(listed.error.retryable ? 'blocked' : 'failed', { ...contextFields(context), error: listed.error });
+  if (!listed.ok) return platformResult(isRetryable(listed.error) ? 'blocked' : 'failed', { ...contextFields(context), error: listed.error });
   const matches = findMarkerComments(listed.value, MARKERS.task(resolved.taskId));
   if (matches.length > 1) return platformResult('failed', { ...contextFields(context), error: { code: 'COMMENT_MARKER_CONFLICT', message: 'Multiple task comments use the registered marker', retryable: false } });
   const owner = matches[0]?.user?.login;

package/lib/platform/operation-coordinator.ts

@@ -48,7 +48,7 @@ async function coordinatePlatformWrite<T extends OperationResult>(input: Coordin
       excludeId: operationId
     });
   if (drained.status !== 'applied' && drained.status !== 'no-op') {
-    return input.block(drained.error ?? {
+    return input.block(drained.error ? { ...drained.error, retryable: true } : {
       code: 'PLATFORM_OPERATION_QUEUE_BLOCKED',
       message: 'A previous platform operation is still unresolved; the current write remains queued',
       retryable: true

package/lib/platform/pr-review.ts

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { coordinatePlatformWrite } from './operation-coordinator.ts';
 import { resolvePlatformProviderContext } from './context.ts';
 import type { PlatformClient } from './context.ts';
+import { providerErrorRetryable } from './provider-validation.ts';
 import { platformResult } from './types.ts';
 import type { PlatformOperation, PlatformResult } from './types.ts';
 import {
@@ -283,7 +284,7 @@ export async function publishPrReview(options: {
       })
       : unsupportedProviderOperation(loaded.value.provider, 'reviews.publish');
     if (!published.ok) {
-      if (published.error.retryable) {
+      if (published.error.retryable || providerErrorRetryable(published.error.code)) {
         const reconciled = await listPrReviews(options.prNumber, { cwd: options.cwd, client: options.client });
         const found = reconciled.reviews.find((review) => firstLine(review.body) === marker);
         if (found) return platformResult('applied', {

package/lib/platform/provider-bridge.ts

@@ -1,7 +1,7 @@
 import path from 'node:path';
 
 import type {
-  PlatformError,
+  ProviderError,
   ProviderOperationContext,
   PlatformProvider,
   ProviderResult,
@@ -15,6 +15,9 @@ import {
 } from './resource-identity.ts';
 import type { LoadedContext } from './context.ts';
 import type { PlatformResult } from './types.ts';
+import type { PlatformError } from './types.ts';
+import { providerErrorRetryable } from './provider-validation.ts';
+import type { NormalizedProviderResult } from './provider-validation.ts';
 
 function providerOperationContext(
   loaded: LoadedContext,
@@ -29,30 +32,28 @@ function providerOperationContext(
   };
 }
 
-function providerError(error: PlatformError, fallbackCode: string): PlatformError {
+function providerError(error: ProviderError | PlatformError, fallbackCode: string): PlatformError {
   return {
     code: error.code || fallbackCode,
     message: error.message || 'Platform provider operation failed',
-    retryable: error.retryable
+    retryable: 'retryable' in error ? error.retryable : providerErrorRetryable(error.code)
   };
 }
 
-function providerStatus(error: PlatformError): PlatformResult['status'] {
-  return error.retryable ? 'blocked' : 'failed';
+function providerStatus(error: ProviderError | PlatformError): PlatformResult['status'] {
+  return ('retryable' in error ? error.retryable : providerErrorRetryable(error.code)) ? 'blocked' : 'failed';
 }
 
 function unsupportedProviderOperation(
   provider: PlatformProvider,
   operation: string
-): ProviderResult<never> {
+): NormalizedProviderResult<never> {
   return {
     ok: false,
     error: {
       code: 'PLATFORM_CAPABILITY_UNSUPPORTED',
       message: `Platform '${provider.type}' does not provide ${operation}`,
-      retryable: false,
-      providerType: provider.type,
-      phase: 'operation'
+      retryable: false
     }
   };
 }

package/lib/platform/provider-contract.ts

@@ -12,17 +12,14 @@ type JsonValue =
   | JsonValue[]
   | { [key: string]: JsonValue };
 
-type PlatformError = {
+type ProviderError = {
   code: string;
   message: string;
-  retryable: boolean;
-  providerType?: string;
-  phase?: string;
 };
 
 type ProviderResult<T> =
   | { ok: true; value: T }
-  | { ok: false; error: PlatformError; value?: T };
+  | { ok: false; error: ProviderError; value?: T };
 
 type ProviderOperationContext = {
   repositoryRoot: string;
@@ -534,10 +531,7 @@ function validatePlatformProvider(
       ok: false,
       error: {
         code: 'PLATFORM_PROVIDER_CONTRACT_INVALID',
-        message: 'Provider must expose matching type, contractVersion, and context.resolve',
-        retryable: false,
-        providerType,
-        phase: 'provider-validation'
+        message: 'Provider must expose matching type, contractVersion, and context.resolve'
       }
     };
   }
@@ -550,10 +544,7 @@ function validatePlatformProvider(
         ok: false,
         error: {
           code: 'PLATFORM_PROVIDER_CONTRACT_INVALID',
-          message: 'Provider identity declaration is invalid',
-          retryable: false,
-          providerType,
-          phase: 'provider-validation'
+          message: 'Provider identity declaration is invalid'
         }
       };
     }
@@ -567,10 +558,7 @@ function validatePlatformProvider(
         ok: false,
         error: {
           code: 'PLATFORM_PROVIDER_CONTRACT_INVALID',
-          message: `Provider operation group ${groupName} is incomplete`,
-          retryable: false,
-          providerType,
-          phase: 'provider-validation'
+          message: `Provider operation group ${groupName} is incomplete`
         }
       };
     }
@@ -583,9 +571,6 @@ function validatePlatformProvider(
             error: {
               code: 'PLATFORM_PROVIDER_CONTRACT_INVALID',
               message: `Provider operation group ${groupName} requires an identity declaration for ${resourceKind}`,
-              retryable: false,
-              providerType,
-              phase: 'provider-validation'
             }
           };
         }
@@ -617,7 +602,7 @@ export type {
   MutationReceipt,
   PlatformCapabilities,
   PlatformContextSnapshot,
-  PlatformError,
+  ProviderError,
   PlatformProvider,
   PlatformProviderFactory,
   PlatformProviderFactoryInput,

package/lib/platform/provider-loader.ts

@@ -12,13 +12,14 @@ import {
 } from './provider-contract.ts';
 import type {
   JsonValue,
-  PlatformError,
   PlatformProvider,
   PlatformProviderFactoryInput
 } from './provider-contract.ts';
 import { createGitHubProvider } from './github-provider.ts';
 import { createNoneProvider } from './none-provider.ts';
 import { wrapProviderOperations } from './provider-validation.ts';
+import type { LoadedRuntimeProvider, RuntimePlatformProvider } from './provider-validation.ts';
+import type { PlatformError } from './types.ts';
 import type { PlatformClient } from './context.ts';
 
 type ProviderLoaderOptions = {
@@ -28,7 +29,7 @@ type ProviderLoaderOptions = {
 };
 
 type LoadedPlatformProvider = {
-  provider: PlatformProvider;
+  provider: LoadedRuntimeProvider;
   providerType: string;
   repositoryRoot: string;
   workingDirectory: string;
@@ -44,7 +45,7 @@ type ResolvedExternalSource = {
   importUrl: string;
 };
 
-const sessions = new Map<string, Promise<PlatformProvider>>();
+const sessions = new Map<string, Promise<LoadedRuntimeProvider>>();
 
 function findRepositoryRoot(cwd: string): string {
   try {
@@ -151,15 +152,15 @@ async function instantiateProvider(
   importUrl: string | null,
   config: Readonly<Record<string, JsonValue>>,
   client?: PlatformClient
-): Promise<PlatformProvider> {
+): Promise<LoadedRuntimeProvider> {
   const input: PlatformProviderFactoryInput = {
     providerType,
     contractVersion: PLATFORM_PROVIDER_CONTRACT_VERSION,
     repositoryRoot,
     config
   };
-  if (providerType === 'github') return createGitHubProvider(input, client as never);
-  if (providerType === 'none') return createNoneProvider(input);
+  if (providerType === 'github') return createGitHubProvider(input, client as never) as unknown as RuntimePlatformProvider;
+  if (providerType === 'none') return createNoneProvider(input) as unknown as RuntimePlatformProvider;
 
   let moduleValue: Record<string, unknown>;
   try {

package/lib/platform/provider-validation.ts

@@ -13,7 +13,7 @@ import type {
   MilestoneReconciliation,
   MutationReceipt,
   PlatformContextSnapshot,
-  PlatformError,
+  ProviderError,
   PlatformProvider,
   ProviderResult,
   ReleaseNoteAuthor,
@@ -29,8 +29,23 @@ import type {
   VerificationRemoteFacts
 } from './provider-contract.ts';
 import type { JsonValue } from './provider-contract.ts';
+import type { PlatformError } from './types.ts';
 
 type ResultValidator<T> = (value: unknown) => T;
+type NormalizedProviderResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: PlatformError; value?: T };
+type RuntimeResult<T> = T extends { ok: true; value: infer V }
+  ? { ok: true; value: V }
+  : T extends { ok: false; error: ProviderError; value?: infer V }
+    ? { ok: false; error: PlatformError; value?: V }
+    : T;
+type RuntimeMethod<T> = T extends (...args: infer A) => Promise<infer R>
+  ? (...args: A) => Promise<RuntimeResult<R>>
+  : T;
+type RuntimeProviderValue<T> = T extends object ? { [K in keyof T]: RuntimeMethod<T[K]> } : T;
+type RuntimePlatformProvider = { [K in keyof PlatformProvider]: RuntimeProviderValue<PlatformProvider[K]> };
+type LoadedRuntimeProvider = RuntimePlatformProvider;
 
 function validationError(providerType: string, phase: string, message: string, code = 'PLATFORM_PROVIDER_RESULT_INVALID'): PlatformError {
   return {
@@ -494,9 +509,11 @@ const PROVIDER_ERROR_CATALOG: Readonly<Record<string, { message: string; retryab
   REMOTE_INVALID: { message: 'The platform remote is invalid', retryable: false },
   UPSTREAM_UNRESOLVED: { message: 'The platform upstream repository could not be resolved', retryable: false },
   RESOURCE_NOT_FOUND: { message: 'The platform resource was not found', retryable: false },
+  COMMENT_LIST_FAILED: { message: 'Comments could not be listed', retryable: true },
   PR_NOT_FOUND: { message: 'The pull request was not found', retryable: false },
   ISSUE_NOT_FOUND: { message: 'The issue was not found', retryable: false },
   REMOTE_BUSY: { message: 'Platform provider is temporarily busy', retryable: true },
+  IN_LABEL_SYNC_PARTIAL: { message: 'In-label synchronization is partial or unknown', retryable: true },
   NETWORK_TRANSIENT: { message: 'The platform request failed temporarily', retryable: true },
   NETWORK_RETRY: { message: 'The platform request failed temporarily', retryable: true },
   NETWORK_RETRY_EXHAUSTED: { message: 'The platform request retries were exhausted', retryable: true },
@@ -538,12 +555,16 @@ function safeProviderError(providerType: string, operation: string, value: unkno
   return {
     code: definition ? item.code as string : 'PLATFORM_PROVIDER_OPERATION_FAILED',
     message: definition?.message || PROVIDER_ERROR_CATALOG.PLATFORM_PROVIDER_OPERATION_FAILED!.message,
-    retryable: definition?.retryable || false,
+    retryable: definition?.retryable ?? false,
     providerType,
     phase: operation
   };
 }
 
+function providerErrorRetryable(code: string): boolean {
+  return PROVIDER_ERROR_CATALOG[code]?.retryable ?? false;
+}
+
 function validators(providerType: string, declaration?: ProviderIdentityDeclaration): Record<string, ResultValidator<unknown>> {
   return {
     'context.resolve': (value) => validateContext(value, providerType),
@@ -629,7 +650,7 @@ async function invokeProviderOperation<T>(
   operation: string,
   call: () => Promise<unknown>,
   validate: ResultValidator<T>
-): Promise<ProviderResult<T>> {
+): Promise<NormalizedProviderResult<T>> {
   try {
     const raw = await call();
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, error: validationError(providerType, operation, 'Provider operation returned an invalid result envelope') };
@@ -646,8 +667,8 @@ async function invokeProviderOperation<T>(
       try {
         exactKeys(envelope, Object.hasOwn(envelope, 'value') ? ['ok', 'error', 'value'] : ['ok', 'error'], `${operation} result`);
         const error = envelope.error as Record<string, unknown>;
-        exactKeys(error, ['code', 'message', 'retryable'], `${operation} error`);
-        if (typeof error.code !== 'string' || !error.code || typeof error.message !== 'string' || !error.message || typeof error.retryable !== 'boolean') throw new Error('invalid provider error');
+        exactKeys(error, ['code', 'message'], `${operation} error`);
+        if (typeof error.code !== 'string' || !error.code || typeof error.message !== 'string' || !error.message) throw new Error('invalid provider error');
         return {
           ok: false,
           error: safeProviderError(providerType, operation, error),
@@ -663,7 +684,7 @@ async function invokeProviderOperation<T>(
   }
 }
 
-function wrapProviderOperations(provider: PlatformProvider): PlatformProvider {
+function wrapProviderOperations(provider: PlatformProvider): RuntimePlatformProvider {
   const map = validators(provider.type, provider.identity);
   const wrapped: PlatformProvider = { ...provider, context: { ...provider.context } };
   wrapped.context.resolve = (input) => invokeProviderOperation(provider.type, 'context.resolve', () => provider.context.resolve(input), map['context.resolve']! as ResultValidator<PlatformContextSnapshot>);
@@ -680,7 +701,8 @@ function wrapProviderOperations(provider: PlatformProvider): PlatformProvider {
     }
     (wrapped as unknown as Record<string, unknown>)[groupName] = target;
   }
-  return wrapped;
+  return wrapped as RuntimePlatformProvider;
 }
 
-export { invokeProviderOperation, validationError, wrapProviderOperations };
+export { invokeProviderOperation, providerErrorRetryable, validationError, wrapProviderOperations };
+export type { LoadedRuntimeProvider, NormalizedProviderResult, RuntimePlatformProvider };

package/lib/platform/pull-requests.ts

@@ -12,6 +12,7 @@ import type { PlatformChangeRequestSnapshot } from './snapshots.ts';
 import { resolvePlatformProviderContext } from './context.ts';
 import type { PlatformClient } from './context.ts';
 import { inspectPlatformIssue } from './issues.ts';
+import { providerErrorRetryable } from './provider-validation.ts';
 import { planPullRequestMetadata } from './pull-request-metadata.ts';
 import {
   planInLabelUpdate,
@@ -741,9 +742,10 @@ async function syncPlatformPullRequestInLabels(prNumber: number, options: Shared
         : unsupportedProviderOperation(provider, 'changeRequests.update');
     if (!synced.ok) {
       const state = resourcesState.find((resource) => resource.kind === item.kind && resourceIdentityEquals(resource.identity, item.identity))!;
-      state.effect = synced.error.retryable ? 'unknown' : 'no-op';
+      const retryable = synced.error.retryable || providerErrorRetryable(synced.error.code);
+      state.effect = retryable ? 'unknown' : 'no-op';
       state.after = state.effect === 'unknown' ? null : item.snapshot.labels;
-      const partial = successfulWrites > 0 || synced.error.retryable;
+      const partial = successfulWrites > 0 || retryable;
       const error = partial
         ? { ...synced.error, code: 'IN_LABEL_SYNC_PARTIAL', message: `In-label synchronization is partial or unknown: ${synced.error.message}` }
         : synced.error;

package/lib/platform/repository-metadata.ts

@@ -14,9 +14,10 @@ import type {
   LabelReconciliation,
   MilestoneDefinition,
   MilestoneInitialization,
-  PlatformError,
+  ProviderError,
   ProviderResult
 } from './provider-contract.ts';
+import type { PlatformError } from './types.ts';
 import { platformResult } from './types.ts';
 import type { PlatformResult } from './types.ts';
 
@@ -288,7 +289,7 @@ function operationStatus(changed: boolean): 'applied' | 'no-op' {
   return changed ? 'applied' : 'no-op';
 }
 
-function errorStatus(error: PlatformError): PlatformResult['status'] {
+function errorStatus(error: PlatformError | ProviderError): PlatformResult['status'] {
   return error.code === 'PLATFORM_CAPABILITY_UNSUPPORTED' ? 'degraded' : providerStatus(error);
 }
 

package/lib/platform/security-alerts.ts

@@ -9,10 +9,10 @@ import {
   providerStatus
 } from './provider-bridge.ts';
 import type {
-  PlatformError,
   SecurityAlertKind,
   SecurityAlertSnapshot
 } from './provider-contract.ts';
+import type { PlatformError } from './types.ts';
 import { platformResult } from './types.ts';
 import type { PlatformResult } from './types.ts';
 

package/lib/platform/types.ts

@@ -4,6 +4,8 @@ type PlatformError = {
   code: string;
   message: string;
   retryable: boolean;
+  providerType?: string;
+  phase?: string;
 };
 
 type PlatformCapabilities = {

package/lib/sandbox/control/client.ts

@@ -27,6 +27,7 @@ import { readSandboxControlIdentitySentinel } from './identity-sentinel.ts';
 import { configuredShortIdLength, resolveShortIdReadOnly } from '../../task/short-id.ts';
 
 const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
+const SANDBOX_TASK_FINALIZATION_RECOVERY_BUDGET_MS = 5 * 60_000;
 
 export class SandboxControlClientError extends Error {
   readonly detail: SandboxControlError;
@@ -114,7 +115,8 @@ function preflight(
 }
 
 function taskViewEffectForRequest(request: SandboxControlRequest): TaskViewAccessEffect | null {
-  if (request.family === 'task-lifecycle' || request.family === 'task-finalization') return 'progress';
+  if (request.family === 'task-lifecycle') return 'progress';
+  if (request.family === 'task-finalization') return 'recovery';
   return null;
 }
 
@@ -347,13 +349,20 @@ export function recoverSandboxControl(requestId: string, params: Readonly<{
         } else if (now - malformedResponseObservedAt >= SANDBOX_CONTROL_RESPONSE_SETTLE_MS) {
           clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response remained malformed', false, accepted, requestId);
         }
-        sleep(25);
+        const remainingMs = deadline - Date.now();
+        if (remainingMs > 0) sleep(Math.min(25, Math.ceil(remainingMs)));
         continue;
       }
-      if (response.phase === 'accepted') accepted = true;
-      else return response;
+      if (response.phase === 'accepted') {
+        accepted = true;
+      } else if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') {
+        accepted = true;
+      } else {
+        return response;
+      }
     }
-    sleep(25);
+    const remainingMs = deadline - Date.now();
+    if (remainingMs > 0) sleep(Math.min(25, Math.ceil(remainingMs)));
   }
   clientError(
     'SANDBOX_CONTROL_RESULT_UNKNOWN',
@@ -399,6 +408,7 @@ export function requestSandboxTaskFinalization(params: Readonly<{
   token?: string;
   generation?: string;
   timeoutMs?: number;
+  recoveryBudgetMs?: number;
 }>): SandboxControlResponse {
   const agent = normalizeAgentToken(params.agent);
   if (!agent) clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization agent is invalid', false);
@@ -420,7 +430,48 @@ export function requestSandboxTaskFinalization(params: Readonly<{
     controllerProcess: null,
     controllerProof: null
   };
-  return exchangeSandboxControl(request, params);
+  let response: SandboxControlResponse;
+  try {
+    response = exchangeSandboxControl(request, params);
+  } catch (error) {
+    if (!(error instanceof SandboxControlClientError)
+      || error.detail.code !== 'SANDBOX_CONTROL_RESULT_UNKNOWN'
+      || !error.accepted || !error.requestId) throw error;
+    return recoverAcceptedTaskFinalization(error.requestId, params);
+  }
+  if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') {
+    return recoverAcceptedTaskFinalization(response.id, params);
+  }
+  return response;
+}
+
+export function recoverAcceptedTaskFinalization(
+  requestId: string,
+  params: Readonly<{ channelDir?: string; recoveryBudgetMs?: number }>,
+  recover: typeof recoverSandboxControl = recoverSandboxControl
+): SandboxControlResponse {
+  const deadline = Date.now() + (params.recoveryBudgetMs ?? SANDBOX_TASK_FINALIZATION_RECOVERY_BUDGET_MS);
+  while (Date.now() < deadline) {
+    const timeoutMs = Math.min(30_000, deadline - Date.now());
+    if (timeoutMs <= 0) break;
+    try {
+      const response = recover(requestId, { channelDir: params.channelDir, timeoutMs });
+      if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') continue;
+      return response;
+    } catch (error) {
+      if (error instanceof SandboxControlClientError
+        && error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN'
+        && error.requestId === requestId) continue;
+      throw error;
+    }
+  }
+  clientError(
+    'SANDBOX_CONTROL_RESULT_UNKNOWN',
+    'accepted finalization request remained unknown after the automatic recovery budget; inspect the receipt and resume by request id',
+    false,
+    true,
+    requestId
+  );
 }
 
 type CodexControllerClosed = Readonly<{

package/lib/sandbox/control/executor.ts

@@ -12,6 +12,7 @@ import {
   type TaskCreateResult
 } from '../../task/create-service.ts';
 import { applyTaskFinalization } from '../../task/finalization.ts';
+import { serializeTaskFinalizationEnvelope } from '../../task/finalization-envelope.ts';
 import {
   bindSandboxControlTask,
   validateSandboxControlRequest,
@@ -535,10 +536,14 @@ export async function runSandboxControlExecutor(requestPath: string, nonce: stri
     result = request.family === 'task-finalization'
       ? {
         exitCode: 1,
-        stdout: `${JSON.stringify({
-          version: 1, status: 'failed', changed: false, accepted: true, result: null,
+        stdout: serializeTaskFinalizationEnvelope({
+          status: code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 'unknown' : 'failed',
+          changed: code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? null : false,
+          accepted: true,
+          requestId: request.id,
+          result: null,
           error: { code, message: detail, retryable: false }
-        })}\n`,
+        }),
         stderr: ''
       }
       : request.family === 'task-create'

package/lib/sandbox/removal.ts

@@ -50,14 +50,6 @@ import { getProcessStartTime } from '../server/process-state.ts';
 import { releaseStaleShortIdRegistry } from '../task/short-id.ts';
 import { withRepositoryMutationLock } from '../task/task-execution-lock.ts';
 import { fetchSandboxRows, type SandboxRow } from './commands/list-running.ts';
-import {
-  formatIntermediateCleanupReport,
-  cleanupIntermediateUnderRemovalCoordinator,
-  protectIntermediateCleanupReport,
-  mergeIntermediateCleanupReports,
-  type IntermediateCleanupReport,
-  scanIntermediateCleanup
-} from '../task/intermediate-cleanup.ts';
 import { createSandboxControlBindingEvidence } from './task-cleanup.ts';
 import {
   createCleanPermit,
@@ -946,7 +938,7 @@ async function runRmOneUnderRepositoryLock(
   tools: SandboxTool[],
   branch: string,
   options: RmOneOptions = {}
-): Promise<IntermediateCleanupReport | null> {
+): Promise<null> {
   const target = options.target ?? resolveRmTarget(
     config,
     tools,
@@ -1048,7 +1040,7 @@ async function rmOneCore(
   tools: SandboxTool[],
   branch: string,
   options: RmOneOptions = {}
-): Promise<IntermediateCleanupReport | null> {
+): Promise<null> {
   const target = options.target ?? resolveRmTarget(
     config,
     tools,

package/lib/task/artifact-command.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 
 import { resolveArtifactContext, hasOpenArtifactRound } from './artifact-lifecycle.ts';
 import { parseArtifactName } from './artifact-name.ts';
@@ -83,7 +84,15 @@ export function executeArtifactCommand(
   const input = { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskDir, family: schema.family, artifact };
   if (operation === 'init') {
     const context = resolveArtifactContext(taskRef, family, { repoRoot: resolved.repoRoot });
-    if (context.status !== 'ready' || (context.next?.name !== artifact && !hasOpenArtifactRound(fs.readFileSync(resolved.taskMdPath, 'utf8'), family, parsed.round))) {
+    const existingCandidate = path.join(taskDir, artifact);
+    let matchingInitializedSkeleton = false;
+    try {
+      const existing = fs.readFileSync(existingCandidate, 'utf8');
+      matchingInitializedSkeleton = existing.includes(`<!-- artifact-context:${resolved.taskId}:${family}:${parsed.round} -->`);
+    } catch { /* an absent candidate is created only for the selected identity */ }
+    if ((context.status !== 'ready' && !matchingInitializedSkeleton) || (context.next?.name !== artifact
+      && !hasOpenArtifactRound(fs.readFileSync(resolved.taskMdPath, 'utf8'), family, parsed.round)
+      && !matchingInitializedSkeleton)) {
       return fail('ARTIFACT_INIT_CONTEXT_INVALID', context.error?.message ?? `artifact '${artifact}' is not the next ${family} artifact`);
     }
     return { ...initializeArtifactSkeleton({ ...input, ...(locale ? { locale } : {}) }), ...identity };