@fitlab-ai/agent-infra 0.11.9 → 0.11.10

package/lib/internal/task-finalization.ts

@@ -3,12 +3,11 @@ import {
   dispatchTaskControlOperation,
   parseTaskControlOperation
 } from '../task/control-authority.ts';
-import { applyTaskFinalization, bindTaskFinalizationReceipt, prepareTaskFinalization } from '../task/finalization.ts';
-import { publishTaskFinalizationHandoff } from '../task/finalization-handoff.ts';
+import { applyTaskFinalization } from '../task/finalization.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
-import { verifyTaskEvent } from '../task/verification.ts';
 import { resolveSandboxControlTransport } from './task-operation-registry.ts';
 import { requestSandboxTaskFinalization, SandboxControlClientError } from '../sandbox/control/client.ts';
+import { serializeTaskFinalizationEnvelope } from '../task/finalization-envelope.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
@@ -17,12 +16,13 @@ type FinalizationError = Readonly<{ code: string; message: string; retryable: bo
 
 function envelope(
   status: 'completed' | 'failed' | 'blocked' | 'unknown',
-  changed: boolean,
+  changed: boolean | null,
   accepted: boolean,
   result: Awaited<ReturnType<typeof applyTaskFinalization>> | null,
-  error: FinalizationError | null
+  error: FinalizationError | null,
+  requestId: string | null = null
 ): string {
-  return `${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`;
+  return serializeTaskFinalizationEnvelope({ status, changed, accepted, requestId, result, error });
 }
 
 function exitCode(status: 'completed' | 'failed' | 'blocked' | 'unknown'): number {
@@ -79,33 +79,25 @@ async function taskFinalization(args: string[] = []): Promise<void> {
   };
   const transport = resolveSandboxControlTransport(process.env, { localWorkflow: true });
   if (transport.kind === 'sandbox-local') {
-    const prepared = await prepareTaskFinalization(boundOperation.request, {
-      repoRoot,
-      preflight: (request, options) => verifyTaskEvent({ ...request, event: 'complete-task.hard-preflight' }, options)
-    });
-    if (prepared.status !== 'prepared') {
-      process.stdout.write(envelope(prepared.status, prepared.changed, true, prepared, prepared.error));
-      process.exitCode = exitCode(prepared.status);
-      return;
-    }
     try {
       const response = requestSandboxTaskFinalization({
-        agent: boundOperation.request.agent,
-        prepareHandoff: (binding) => {
-          const receipt = bindTaskFinalizationReceipt(repoRoot, boundOperation.request.taskRef, binding);
-          return publishTaskFinalizationHandoff('/share/branch', receipt, binding);
-        }
+        agent: boundOperation.request.agent
       });
       process.stdout.write(response.stdout);
       process.stderr.write(response.stderr);
       process.exitCode = response.exitCode ?? 1;
       return;
     } catch (error) {
-      const detail = error instanceof SandboxControlClientError
-        ? error.detail
+      const clientError = error instanceof SandboxControlClientError ? error : null;
+      const detail = clientError
+        ? clientError.detail
         : { code: 'SANDBOX_CONTROL_CLIENT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false };
-      process.stdout.write(envelope(detail.retryable ? 'blocked' : 'failed', false, false, null, detail));
-      process.exitCode = detail.retryable ? 2 : 1;
+      const status = detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN'
+        ? 'unknown'
+        : detail.retryable ? 'blocked' : 'failed';
+      const changed = status === 'unknown' ? null : false;
+      process.stdout.write(envelope(status, changed, clientError?.accepted ?? false, null, detail, clientError?.requestId ?? null));
+      process.exitCode = exitCode(status);
       return;
     }
   }

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

@@ -142,9 +142,8 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'task-review', 'preflight', 'task-bound', 'artifact-write'),
     descriptor('internal', 'task-review', 'finalize-summary', 'task-bound', 'progress'),
     descriptor('internal', 'task-event', 'event', 'task-bound', 'progress'),
-    descriptor('internal', 'task-invalidation', 'reconcile', 'task-bound', 'progress'),
     descriptor('internal', 'task-lifecycle', 'intent', 'task-bound', 'progress'),
-    descriptor('internal', 'task-finalization', 'complete', 'task-bound', 'progress'),
+    descriptor('internal', 'task-finalization', 'complete', 'task-bound', 'recovery'),
     descriptor('internal', 'task-platform-recovery', 'inspect', 'task-bound', 'diagnostic'),
     descriptor('internal', 'task-platform-recovery', 'recover', 'task-bound', 'recovery'),
     descriptor('internal', 'task-short-id', 'list', 'conditional', 'diagnostic'),
@@ -222,7 +221,7 @@ export const INTERNAL_DISPATCHER_ROUTES = Object.freeze([
   'git-workflow', 'task-delivery', 'release-workflow', 'platform-release-notes', 'platform-security', 'platform-metadata', 'platform-context',
   'platform-comment', 'platform-issue', 'platform-pr', 'platform-pr-review', 'pr-review-grade',
   'platform-checks', 'task-context', 'task-ledger', 'task-warning', 'task-activity', 'task-artifact',
-  'task-orchestration', 'task-review', 'task-event', 'task-invalidation', 'task-lifecycle',
+  'task-orchestration', 'task-review', 'task-event', 'task-lifecycle',
   'task-finalization', 'task-platform-recovery', 'task-short-id', 'task-snapshot', 'task-verify', 'task-validate', 'manual-validation'
 ]);
 export const PUBLIC_DISPATCHER_ROUTES = Object.freeze([

package/lib/internal/task-platform-recovery.ts

@@ -3,7 +3,7 @@ import { readPlatformOperationJournal } from '../task/platform-operation-journal
 import { recoverPlatformOperations } from '../task/platform-operation-recovery.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = 'Usage: agent-infra-internal task-platform-recovery <N | TASK-id> <inspect | recover> [--agent <agent>] [--selection required|deferred|all]\n';
+const USAGE = 'Usage: agent-infra-internal task-platform-recovery <N | TASK-id> <inspect | recover> [--agent <agent>] [--selection required|deferred|all] [--attempts <positive-integer>]\n';
 
 function option(args: readonly string[], name: string): string | undefined {
   const index = args.indexOf(name);
@@ -38,14 +38,19 @@ async function taskPlatformRecovery(args: string[] = []): Promise<void> {
   }
   const agent = option(args, '--agent');
   const selection = option(args, '--selection') ?? 'all';
+  const attemptsInput = option(args, '--attempts');
+  const attempts = attemptsInput === undefined ? undefined : Number(attemptsInput);
+  const validAttempts = attemptsInput === undefined
+    || (attempts !== undefined && Number.isSafeInteger(attempts) && attempts > 0);
   if (!agent || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u.test(agent)
-    || !['required', 'deferred', 'all'].includes(selection)) {
-    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PLATFORM_OPERATION_RECOVERY_PAYLOAD_INVALID', message: 'recover requires a valid --agent and --selection' } })}\n`);
+    || !['required', 'deferred', 'all'].includes(selection)
+    || !validAttempts) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PLATFORM_OPERATION_RECOVERY_PAYLOAD_INVALID', message: 'recover requires a valid --agent, --selection, and positive --attempts when supplied' } })}\n`);
     process.stderr.write(USAGE);
     process.exitCode = 1;
     return;
   }
-  const result = await recoverPlatformOperations(task.taskId, selection as 'required' | 'deferred' | 'all', { agent, cwd: repoRoot });
+  const result = await recoverPlatformOperations(task.taskId, selection as 'required' | 'deferred' | 'all', { agent, cwd: repoRoot, ...(attempts === undefined ? {} : { attempts }) });
   process.stdout.write(`${JSON.stringify(result)}\n`);
   process.exitCode = result.status === 'applied' || result.status === 'no-op' ? 0 : result.status === 'blocked' ? 2 : 1;
 }

package/lib/platform/completion-backfill.ts

@@ -10,6 +10,7 @@ import { applyWorkflowWarningIntent } from '../task/workflow-warning-intents.ts'
 import { captureTaskWriteMetadata } from '../task/write.ts';
 import { syncPlatformComment } from './issue-comments.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 { taskIssueIdentity } from './task-identities.ts';
@@ -151,7 +152,7 @@ async function backfillCompletionComments(
     })));
     artifacts.push({ artifact: artifact.name, status: latest.status });
     if (latest.status === 'failed' || latest.status === 'blocked') return result({ ...latest, operations }, artifacts, []);
-    if (latest.error) return result(platformResult(latest.error.retryable ? 'blocked' : 'failed', {
+    if (latest.error) return result(platformResult(latest.error.retryable || providerErrorRetryable(latest.error.code) ? 'blocked' : 'failed', {
       platform: latest.platform,
       resource: latest.resource,
       capabilities: latest.capabilities,

package/lib/platform/context.ts

@@ -2,9 +2,12 @@ import path from 'node:path';
 
 import { loadPlatformProvider } from './provider-loader.ts';
 import { defaultGitRemote, parseGitHubRemote } from './github-provider.ts';
+import { providerErrorRetryable } from './provider-validation.ts';
 import { platformResult } from './types.ts';
 import type { PlatformResult } from './types.ts';
-import type { PlatformProvider, PlatformContextSnapshot, PlatformError } from './provider-contract.ts';
+import type { PlatformContextSnapshot } from './provider-contract.ts';
+import type { PlatformError } from './types.ts';
+import type { LoadedRuntimeProvider } from './provider-validation.ts';
 
 type PlatformClientResult<T> =
   | { ok: true; value: T }
@@ -23,7 +26,7 @@ type ContextOptions = {
 };
 
 type LoadedContext = {
-  provider: PlatformProvider;
+  provider: LoadedRuntimeProvider;
   providerType: string;
   repositoryRoot: string;
   workingDirectory: string;
@@ -33,7 +36,7 @@ type LoadedContext = {
 };
 
 function errorStatus(error: PlatformError): PlatformResult['status'] {
-  if (error.retryable || error.code === 'AUTH_REQUIRED' || error.code === 'PLATFORM_DEPENDENCY_MISSING') return 'blocked';
+  if (error.retryable || providerErrorRetryable(error.code) || error.code === 'AUTH_REQUIRED' || error.code === 'PLATFORM_DEPENDENCY_MISSING') return 'blocked';
   if (error.code === 'REMOTE_MISSING' || error.code === 'PLATFORM_UNSUPPORTED') return 'no-op';
   return 'failed';
 }
@@ -43,9 +46,10 @@ function contextError(
   error: PlatformError,
   repository: string | null = null
 ): PlatformResult {
+  const retryable = error.retryable ?? providerErrorRetryable(error.code);
   return platformResult(errorStatus(error), {
     platform: { type: providerType || null, repository, currentUser: null },
-    error: { code: error.code, message: error.message, retryable: error.retryable }
+    error: { code: error.code, message: error.message, retryable }
   });
 }
 

package/lib/platform/github-client.ts

@@ -3,13 +3,13 @@ import spawn from 'cross-spawn';
 
 import semver from 'semver';
 
-import type { PlatformError } from './types.ts';
-
 type RunResult = { status: number | null; stdout: string; stderr: string; error?: Error };
 type RunOptions = { cwd?: string; input?: string };
 type Runner = (args: string[], options: RunOptions) => RunResult;
 type RequestOptions = RunOptions & { method?: 'GET' | 'PATCH' | 'POST' | 'PUT' | 'DELETE' };
-type ClientResult<T> = { ok: true; value: T } | { ok: false; error: PlatformError };
+type GitHubError = { code: string; message: string };
+type ClientResult<T> = { ok: true; value: T } | { ok: false; error: GitHubError };
+type GitHubRequestFailure = GitHubError & { requestRetryable: boolean };
 type ResponseMetadata = {
   status: number;
   requestUrl: string;
@@ -86,36 +86,40 @@ function defaultSleep(delayMs: number): void {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delayMs);
 }
 
-function classifyGitHubFailure(result: RunResult): PlatformError {
+function classifyGitHubFailure(result: RunResult): GitHubRequestFailure {
   const errorCode = result.error && 'code' in result.error ? (result.error as NodeJS.ErrnoException).code : undefined;
   if (errorCode === 'ENOBUFS') {
     return {
       code: 'PLATFORM_OUTPUT_TOO_LARGE',
       message: 'GitHub CLI output exceeded the configured limit',
-      retryable: false
+      requestRetryable: false
     };
   }
   const detail = boundedFailureDetail(result);
   const lower = detail.toLowerCase();
   if (/\b401\b|bad credentials|authentication required|not logged into/.test(lower)) {
-    return { code: 'AUTH_REQUIRED', message: detail || 'GitHub authentication is required', retryable: false };
+    return { code: 'AUTH_REQUIRED', message: detail || 'GitHub authentication is required', requestRetryable: false };
   }
   if (/\b429\b|rate limit|secondary rate|\b5\d\d\b|timeout|timed out|econnreset|enotfound|dns|tls|socket|network/.test(lower)) {
-    return { code: 'NETWORK_TRANSIENT', message: detail || 'GitHub request failed temporarily', retryable: true };
+    return { code: 'NETWORK_TRANSIENT', message: detail || 'GitHub request failed temporarily', requestRetryable: true };
   }
   if (/\b403\b|resource not accessible|permission denied/.test(lower)) {
-    return { code: 'PERMISSION_DENIED', message: detail || 'GitHub permission denied', retryable: false };
+    return { code: 'PERMISSION_DENIED', message: detail || 'GitHub permission denied', requestRetryable: false };
   }
   if (/\b404\b/.test(lower)) {
-    return { code: 'RESOURCE_NOT_FOUND', message: detail || 'GitHub resource not found', retryable: false };
+    return { code: 'RESOURCE_NOT_FOUND', message: detail || 'GitHub resource not found', requestRetryable: false };
   }
   if (/\b422\b|validation failed/.test(lower)) {
-    return { code: 'PLATFORM_REQUEST_INVALID', message: detail || 'GitHub rejected the request', retryable: false };
+    return { code: 'PLATFORM_REQUEST_INVALID', message: detail || 'GitHub rejected the request', requestRetryable: false };
   }
   if (errorCode === 'ENOENT') {
-    return { code: 'PLATFORM_DEPENDENCY_MISSING', message: detail || 'GitHub CLI is unavailable', retryable: false };
+    return { code: 'PLATFORM_DEPENDENCY_MISSING', message: detail || 'GitHub CLI is unavailable', requestRetryable: false };
   }
-  return { code: 'PLATFORM_REQUEST_FAILED', message: detail || 'GitHub request failed', retryable: false };
+  return { code: 'PLATFORM_REQUEST_FAILED', message: detail || 'GitHub request failed', requestRetryable: false };
+}
+
+function clientError(error: GitHubError): GitHubError {
+  return { code: error.code, message: error.message };
 }
 
 function responseUrl(args: string[]): string {
@@ -164,13 +168,13 @@ function createGitHubClient(options: ClientOptions = {}): GitHubClient {
       const result = runner(args, request);
       if (result.status === 0) return { ok: true, value: result.stdout };
       const error = classifyGitHubFailure(result);
-      if (!retryableMethod || !error.retryable) return { ok: false, error };
+      if (!retryableMethod || !error.requestRetryable) return { ok: false, error: clientError(error) };
       if (attempt >= delays.length) {
         return {
           ok: false,
           error: error.code === 'NETWORK_TRANSIENT'
-            ? { ...error, code: 'NETWORK_RETRY_EXHAUSTED', message: `${error.message} (retry exhausted)` }
-            : error
+            ? { ...clientError(error), code: 'NETWORK_RETRY_EXHAUSTED', message: `${error.message} (retry exhausted)` }
+            : clientError(error)
         };
       }
       sleep(delays[attempt]!);
@@ -181,12 +185,12 @@ function createGitHubClient(options: ClientOptions = {}): GitHubClient {
   return {
     version(request = {}) {
       const result = runner(['--version'], request);
-      if (result.status !== 0) return { ok: false, error: classifyGitHubFailure(result) };
+      if (result.status !== 0) return { ok: false, error: clientError(classifyGitHubFailure(result)) };
       const version = result.stdout.match(/^gh version (\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\s|$)/m)?.[1];
       if (!version || !semver.valid(version)) {
         return {
           ok: false,
-          error: { code: 'GH_CLI_VERSION_INVALID', message: 'GitHub CLI returned an invalid version', retryable: false }
+          error: { code: 'GH_CLI_VERSION_INVALID', message: 'GitHub CLI returned an invalid version' }
         };
       }
       return { ok: true, value: version };
@@ -203,7 +207,7 @@ function createGitHubClient(options: ClientOptions = {}): GitHubClient {
       } catch {
         return {
           ok: false,
-          error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'GitHub returned invalid JSON', retryable: true }
+          error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'GitHub returned invalid JSON' }
         };
       }
     },
@@ -217,7 +221,7 @@ function createGitHubClient(options: ClientOptions = {}): GitHubClient {
       if (!parsed) {
         return {
           ok: false,
-          error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'GitHub response metadata or JSON is invalid', retryable: true }
+          error: { code: 'INVALID_PLATFORM_RESPONSE', message: 'GitHub response metadata or JSON is invalid' }
         };
       }
       return { ok: true, value: parsed };
@@ -225,5 +229,5 @@ function createGitHubClient(options: ClientOptions = {}): GitHubClient {
   };
 }
 
-export { classifyGitHubFailure, createGitHubClient, MINIMUM_GITHUB_CLI_VERSION, parseIncludedResponse };
+export { createGitHubClient, MINIMUM_GITHUB_CLI_VERSION, parseIncludedResponse };
 export type { ClientResult, GitHubClient, JsonResponse, RequestOptions, ResponseMetadata, RunOptions, RunResult, Runner };

package/lib/platform/github-provider.ts

@@ -21,7 +21,7 @@ import type {
   MutationReceipt,
   MilestoneInitialization,
   PlatformContextSnapshot,
-  PlatformError,
+  ProviderError,
   ProviderOperationContext,
   PlatformProvider,
   PlatformProviderFactoryInput,
@@ -38,6 +38,33 @@ import type {
 } from './provider-contract.ts';
 import { resourceIdentityNumber, resourceIdentityString } from './resource-identity.ts';
 import { extractPullRequestFileNames, syncLabelDelta } from './in-label-sync.ts';
+import type { PlatformError } from './types.ts';
+
+function providerError(error: PlatformError | ProviderError): ProviderError {
+  return { code: error.code, message: error.message };
+}
+
+function publicProviderErrors(provider: PlatformProvider): PlatformProvider {
+  const sanitize = async (call: () => Promise<unknown>): Promise<unknown> => {
+    const result = await call();
+    if (!result || typeof result !== 'object' || (result as { ok?: unknown }).ok !== false) return result;
+    const envelope = result as { error?: PlatformError | ProviderError };
+    return envelope.error ? { ...(result as Record<string, unknown>), error: providerError(envelope.error) } : result;
+  };
+  const wrapped: PlatformProvider = { ...provider, context: { ...provider.context } };
+  wrapped.context.resolve = (input) => sanitize(() => provider.context.resolve(input)) as ReturnType<PlatformProvider['context']['resolve']>;
+  for (const groupName of ['issues', 'comments', 'changeRequests', 'checks', 'reviews', 'releases', 'securityAlerts', 'repositoryMetadata', 'verification'] as const) {
+    const group = provider[groupName];
+    if (!group) continue;
+    const target: Record<string, unknown> = { ...group };
+    for (const method of Object.keys(group)) {
+      const original = group[method as keyof typeof group] as (...args: never[]) => Promise<unknown>;
+      target[method] = (input: unknown) => sanitize(() => original(input as never));
+    }
+    (wrapped as unknown as Record<string, unknown>)[groupName] = target;
+  }
+  return wrapped;
+}
 
 const CURRENT_USER_QUERY = 'query { viewer { login } }';
 const ISSUE_TYPES_QUERY = `query($owner:String!){organization(login:$owner){issueTypes(first:20){nodes{id name pinnedFields{__typename ... on IssueFieldSingleSelect{id name options{id name}} ... on IssueFieldDate{id name} ... on IssueFieldText{id name} ... on IssueFieldNumber{id name}}}}}}`;
@@ -105,7 +132,6 @@ function resolveGitHubChangeRequestGitEvidence({
       error: {
         code: 'PR_MERGE_EVIDENCE_SOURCE_UNAVAILABLE',
         message: 'Pull request repository identity is inconsistent',
-        retryable: false
       }
     };
   }
@@ -127,7 +153,6 @@ function resolveGitHubChangeRequestGitEvidence({
       error: {
         code: 'PR_MERGE_EVIDENCE_SOURCE_UNAVAILABLE',
         message: 'Pull request Git refs are invalid',
-        retryable: false
       }
     };
   }
@@ -145,7 +170,6 @@ function resolveGitHubChangeRequestGitEvidence({
       error: {
         code: 'PR_MERGE_EVIDENCE_SOURCE_UNAVAILABLE',
         message: `No GitHub remote can provide evidence for ${repository}`,
-        retryable: false
       }
     };
   }
@@ -155,8 +179,8 @@ function resolveGitHubChangeRequestGitEvidence({
   };
 }
 
-function failure(error: { code: string; message: string; retryable: boolean }): ProviderResult<PlatformContextSnapshot> {
-  return { ok: false, error };
+function failure(error: PlatformError | ProviderError): ProviderResult<PlatformContextSnapshot> {
+  return { ok: false, error: providerError(error) };
 }
 
 function resolveContext(
@@ -170,19 +194,17 @@ function resolveContext(
     return failure({
       code: 'GH_CLI_VERSION_UNSUPPORTED',
       message: 'GitHub CLI ' + version.value + ' is unsupported; install gh >= ' + MINIMUM_GITHUB_CLI_VERSION,
-      retryable: false
     });
   }
   const remote = input.gitRemote || defaultGitRemote(cwd);
   if (!remote) {
-    return failure({ code: 'REMOTE_MISSING', message: 'Git origin remote is not configured', retryable: false });
+    return failure({ code: 'REMOTE_MISSING', message: 'Git origin remote is not configured' });
   }
   const ownerRepo = parseGitHubRemote(remote);
   if (!ownerRepo) {
     return failure({
       code: /github\.com/i.test(remote) ? 'REMOTE_INVALID' : 'PLATFORM_UNSUPPORTED',
       message: 'Unable to parse GitHub owner/repo from configured remote',
-      retryable: false
     });
   }
   const repository = client.json(['api', 'repos/' + ownerRepo], { cwd });
@@ -192,7 +214,6 @@ function resolveContext(
   if (!upstream) return failure({
     code: 'UPSTREAM_UNRESOLVED',
     message: 'Unable to resolve the upstream repository',
-    retryable: false
   });
   const user = client.json(['api', 'graphql', '-f', 'query=' + CURRENT_USER_QUERY], { cwd });
   if (!user.ok) return failure(user.error);
@@ -241,18 +262,18 @@ function repositoryHead(cwd: string): string {
 
 function verifyRemoteBranch(cwd: string, repositoryName: string, head: string):
   | { ok: true; value: string }
-  | { ok: false; error: { code: string; message: string; retryable: boolean } } {
+  | { ok: false; error: ProviderError } {
   const wanted = expectedHeadRepository(repositoryName, head);
   if (!wanted.ref || !/^[A-Za-z0-9._/-]+$/.test(wanted.ref)) return {
     ok: false,
-    error: { code: 'PR_HEAD_INVALID', message: 'Pull request head ref is invalid', retryable: false }
+    error: { code: 'PR_HEAD_INVALID', message: 'Pull request head ref is invalid' }
   };
   const remotes = configuredGitRemotes(cwd);
   const remote = remotes.find((item) => item.repository.toLowerCase() === wanted.repository.toLowerCase())
     ?? remotes.find((item) => item.name === 'origin');
   if (!remote) return {
     ok: false,
-    error: { code: 'PR_REMOTE_BRANCH_MISSING', message: `No configured remote can verify ${wanted.repository}:${wanted.ref}`, retryable: false }
+    error: { code: 'PR_REMOTE_BRANCH_MISSING', message: `No configured remote can verify ${wanted.repository}:${wanted.ref}` }
   };
   try {
     const output = execFileSync('git', ['ls-remote', '--refs', remote.name, `refs/heads/${wanted.ref}`], {
@@ -262,19 +283,19 @@ function verifyRemoteBranch(cwd: string, repositoryName: string, head: string):
     const sha = match?.split(/\s+/)[0] || null;
     if (!sha || !/^[a-f0-9]{40}$/i.test(sha)) return {
       ok: false,
-      error: { code: 'PR_REMOTE_BRANCH_MISSING', message: `Remote branch ${wanted.repository}:${wanted.ref} does not exist`, retryable: false }
+      error: { code: 'PR_REMOTE_BRANCH_MISSING', message: `Remote branch ${wanted.repository}:${wanted.ref} does not exist` }
     };
     return { ok: true, value: sha };
   } catch (error) {
     return {
       ok: false,
-      error: { code: 'PR_REMOTE_BRANCH_UNAVAILABLE', message: error instanceof Error ? error.message : String(error), retryable: true }
+      error: { code: 'PR_REMOTE_BRANCH_UNAVAILABLE', message: error instanceof Error ? error.message : String(error) }
     };
   }
 }
 
 function invalid(code: string, message: string): ProviderResult<never> {
-  return { ok: false, error: { code, message, retryable: false } };
+  return { ok: false, error: { code, message } };
 }
 
 function changeRequestSnapshot(value: any): ChangeRequestSnapshot {
@@ -346,8 +367,8 @@ function createReceipt(remoteId: string): ProviderResult<MutationReceipt> {
   return { ok: true, value: { changed: true, remoteId } };
 }
 
-function partialFailure<T>(response: { ok: false; error: PlatformError }, value: T): ProviderResult<T> {
-  return { ok: false, error: response.error, value };
+function partialFailure<T>(response: { ok: false; error: PlatformError | ProviderError }, value: T): ProviderResult<T> {
+  return { ok: false, error: providerError(response.error), value };
 }
 
 function labelReconciliation(
@@ -390,8 +411,8 @@ function syncLabels(
         status: 'blocked' as const,
         changed: true,
         error: synced.error
-          ? { ...synced.error, code: 'IN_LABEL_SYNC_PARTIAL', message: `In-label synchronization is partial or unknown: ${synced.error.message}` }
-          : { code: 'IN_LABEL_SYNC_PARTIAL', message: 'In-label synchronization is partial or unknown', retryable: true }
+          ? { ...providerError(synced.error), code: 'IN_LABEL_SYNC_PARTIAL', message: `In-label synchronization is partial or unknown: ${synced.error.message}` }
+          : { code: 'IN_LABEL_SYNC_PARTIAL', message: 'In-label synchronization is partial or unknown' }
       };
       return synced;
     }
@@ -642,13 +663,13 @@ function createGitHubOperations(client: GitHubClient): Pick<PlatformProvider, 'i
       try {
         localHead = repositoryHead(context.workingDirectory);
       } catch (error) {
-        return { ok: false, error: { code: 'PR_LOCAL_HEAD_UNAVAILABLE', message: error instanceof Error ? error.message : String(error), retryable: false } };
+        return { ok: false, error: { code: 'PR_LOCAL_HEAD_UNAVAILABLE', message: error instanceof Error ? error.message : String(error) } };
       }
       const remote = verifyRemoteBranch(context.workingDirectory, repository(context), head);
       if (!remote.ok) return remote;
       if (remote.value !== localHead) return {
         ok: false,
-        error: { code: 'PR_REMOTE_HEAD_MISMATCH', message: `Remote head ${remote.value} does not match local HEAD ${localHead}`, retryable: false }
+        error: { code: 'PR_REMOTE_HEAD_MISMATCH', message: `Remote head ${remote.value} does not match local HEAD ${localHead}` }
       };
       return { ok: true, value: { sha: localHead } };
     },
@@ -909,7 +930,7 @@ function createGitHubOperations(client: GitHubClient): Pick<PlatformProvider, 'i
       try {
         const tag = resourceIdentityString(release) || '';
         const result = module.publishGitHubReleaseNotes({ repository: repository(context), tag, title, notesFile }, { cwd: context.workingDirectory, client });
-        if (result.status === 'failed' || result.status === 'blocked') return { ok: false, error: result.error || { code: 'RELEASE_NOTES_PUBLISH_FAILED', message: 'Release notes publish failed', retryable: false } };
+        if (result.status === 'failed' || result.status === 'blocked') return { ok: false, error: result.error ? providerError(result.error) : { code: 'RELEASE_NOTES_PUBLISH_FAILED', message: 'Release notes publish failed' } };
         return { ok: true, value: { changed: result.changed, remoteId: tag } };
       } finally {
         fs.rmSync(temporaryRoot, { recursive: true, force: true });
@@ -921,7 +942,7 @@ function createGitHubOperations(client: GitHubClient): Pick<PlatformProvider, 'i
         repository: repository(context), commitOids, branch, historyLimit, fromTime, toTime
       }, { cwd: context.workingDirectory, client });
       if (collected.status === 'failed' || collected.status === 'blocked' || !('pullRequests' in collected)) {
-        return { ok: false, error: collected.error || { code: 'RELEASE_NOTES_COLLECTION_FAILED', message: 'Release notes could not be collected', retryable: false } };
+        return { ok: false, error: collected.error ? providerError(collected.error) : { code: 'RELEASE_NOTES_COLLECTION_FAILED', message: 'Release notes could not be collected' } };
       }
       const mergedPullRequests = collected.pullRequests.map((item: any) => ({
         id: String(item.number), identity: { kind: 'number' as const, value: Number(item.number) }, number: Number(item.number),
@@ -1107,7 +1128,7 @@ function createGitHubProvider(
   input: PlatformProviderFactoryInput,
   client: GitHubClient = createGitHubClient()
 ): PlatformProvider {
-  return {
+  return publicProviderErrors({
     type: input.providerType,
     contractVersion: 2,
     identity: { issue: 'number', 'pull-request': 'number', comment: 'number', release: 'key' },
@@ -1117,7 +1138,7 @@ function createGitHubProvider(
         return resolveContext(client, contextInput);
       }
     }
-  };
+  });
 }
 
 export {

package/lib/platform/github-release-notes.ts

@@ -1,5 +1,6 @@
 import type { GitHubClient } from './github-client.ts';
 import { createGitHubClient } from './github-client.ts';
+import { providerErrorRetryable } from './provider-validation.ts';
 
 type GitHubActorInput = {
   name?: string | null;
@@ -43,13 +44,14 @@ function normalizePlatformAuthor(author: { login?: string | null } | null | unde
   };
 }
 
-function failure(error: { code: string; message: string; retryable: boolean }) {
+function failure(error: { code: string; message: string; retryable?: boolean }) {
+  const retryable = error.retryable ?? providerErrorRetryable(error.code);
   return {
-    status: error.retryable ? 'blocked' as const : 'failed' as const,
+    status: retryable ? 'blocked' as const : 'failed' as const,
     changed: false,
     operation: null,
     url: null,
-    error
+    error: { code: error.code, message: error.message }
   };
 }
 

package/lib/platform/in-label-sync.ts

@@ -1,5 +1,6 @@
 import { computeInLabels } from './metadata-labels.ts';
 import { createHash } from 'node:crypto';
+import { providerErrorRetryable } from './provider-validation.ts';
 import type { PlatformError } from './types.ts';
 
 type InLabelPlan = {
@@ -150,7 +151,7 @@ function syncLabelDelta(
   const delta = labelDelta(current, target, prefix);
   let changed = false;
   const failure = (error: PlatformError): LabelDeltaResult => {
-    if (changed || error.retryable) {
+    if (changed || error.retryable || providerErrorRetryable(error.code)) {
       return {
         status: 'blocked',
         changed,