@fitlab-ai/agent-infra 0.11.8 → 0.11.10

package/lib/agent-clients/schema.ts

@@ -43,16 +43,24 @@ const AGENT_CLIENTS_SCHEMA = {
         }
       }))
     },
-    customTUIs: {
-      type: 'array',
-      items: {
-        type: 'object',
-        additionalProperties: true,
-        required: ['name', 'dir', 'invoke'],
-        properties: {
-          name: { type: 'string' },
-          dir: { type: 'string' },
-          invoke: { type: 'string' }
+    sandbox: {
+      type: 'object',
+      properties: {
+        tools: {
+          type: 'object',
+          properties: {
+            ids: { type: 'array', items: { type: 'string' } },
+            definitions: {
+              type: 'object',
+              additionalProperties: {
+                type: 'object',
+                properties: {
+                  name: { type: 'string' },
+                  invoke: { type: 'string' }
+                }
+              }
+            }
+          }
         }
       }
     }

package/lib/git/workflow.ts

@@ -100,7 +100,7 @@ function commitExplicitPaths(input: { cwd: string; paths: readonly string[]; mes
     const tree = value(runner, input.cwd, ['write-tree']);
     if (tree !== input.expectedTree) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'applied' as const }], error: { code: 'GIT_TREE_MISMATCH', message: `Expected staged tree ${input.expectedTree}, received ${tree ?? 'unavailable'}` } };
   }
-  const commit = run(runner, input.cwd, ['commit', '-m', input.message]);
+  const commit = run(runner, input.cwd, ['commit', '--cleanup=verbatim', '-m', input.message]);
   const after = inspectGitWorkflow(input.cwd, runner);
   if (commit.status !== 0) return { status: 'failed' as const, changed: false, snapshot: after.snapshot, operations: [{ name: 'commit', status: 'failed' as const, message: commit.stderr.trim() }], error: { code: 'GIT_COMMIT_FAILED', message: commit.stderr.trim() } };
   return { status: 'applied' as const, changed: true, snapshot: after.snapshot, operations: [{ name: 'stage', status: 'applied' as const }, { name: 'commit', status: 'applied' as const }], error: null };

package/lib/init.ts

@@ -314,8 +314,8 @@ async function cmdInit(): Promise<void> {
   console.log('    npm install -g @fitlab-ai/agent-infra');
   console.log('');
   if (workflowPlan.nextSteps.length === 0) {
-    console.log('  No Agent Client project integration enabled.');
-    console.log(`  Configure "customTUIs" in ${configPath} before running update-agent-infra.`);
+    console.log('  No Agent Client or sandbox custom tool integration enabled.');
+    console.log(`  Configure a custom tool in "sandbox.tools.definitions" and select it in "sandbox.tools.ids" in ${configPath}.`);
     console.log('');
   } else {
     console.log('  Next step: open this project in any AI TUI and run:');

package/lib/internal/agent-client.ts

@@ -5,7 +5,7 @@ import {
   AgentClientConfigError,
   normalizeAgentClients
 } from '../agent-clients/config.ts';
-import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.ts';
+import { normalizeCustomToolInvocations } from '../agent-clients/custom-tool-invocations.ts';
 import { renderNextStepCommands } from '../agent-clients/next-steps.ts';
 import { getAgentClientModelSelection } from '../agent-clients/registry.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
@@ -148,11 +148,11 @@ function agentClient(args: string[] = []): void {
 
   try {
     const clients = normalizeAgentClients(config);
-    const custom = normalizeCustomTUIs(process.cwd(), config.customTUIs ?? []);
+    const custom = normalizeCustomToolInvocations(config);
     const commands = renderNextStepCommands({
       projectName: String(config.project ?? ''),
       state: clients.state,
-      customTUIs: custom.items,
+      customToolInvocations: custom.items,
       skillName: parsed.skillName,
       ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {}),
       ...(parsed.version ? { version: parsed.version } : {})

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

@@ -60,7 +60,6 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'task-orchestration': ['status', 'progress'],
   'task-review': ['preflight', 'finalize-summary'],
   'task-event': ['event'],
-  'task-invalidation': ['reconcile'],
   'task-lifecycle': ['intent'],
   'task-finalization': ['complete'],
   'task-platform-recovery': ['inspect', 'recover'],
@@ -98,7 +97,6 @@ export function internalRouteSelector(command: string, args: readonly string[]):
   if (command === 'task-short-id') return first(args) === 'list' && args.includes('--verify') ? 'list-verify' : first(args);
   if (command === 'task-orchestration') return args[1] === 'status' ? 'status' : args[1] ? 'progress' : '';
   if (command === 'task-review') return args[1] ?? '';
-  if (command === 'task-invalidation') return args[1] ?? '';
   if (command === 'task-artifact') return args[1] ?? '';
   if (command === 'platform-pr-review' && first(args) === 'publish') {
     const scope = optionValue(args, '--scope') ?? '';

package/lib/internal/sandbox-control.ts

@@ -9,6 +9,7 @@ import { serveSandboxControl } from '../sandbox/control/server.ts';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 import { parseTaskCreateResult, taskCreateExitCode } from '../task/create-service.ts';
+import { serializeTaskFinalizationEnvelope, type TaskFinalizationEnvelope } from '../task/finalization-envelope.ts';
 
 type FinalizationStatus = 'completed' | 'failed' | 'blocked' | 'unknown';
 
@@ -16,10 +17,11 @@ function writeFinalizationEnvelope(
   status: FinalizationStatus,
   accepted: boolean,
   error: { code: string; message: string; retryable: boolean },
-  changed = false,
-  result: unknown = null
+  changed: boolean | null = false,
+  result: unknown = null,
+  requestId: string | null = null
 ): void {
-  process.stdout.write(`${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`);
+  process.stdout.write(serializeTaskFinalizationEnvelope({ status, changed, accepted, requestId, result, error }));
 }
 
 function finalizationErrorStatus(error: { retryable: boolean; code: string }): FinalizationStatus {
@@ -43,6 +45,28 @@ function recoveredExitCode(response: Awaited<ReturnType<typeof recoverSandboxCon
   return response.exitCode ?? 1;
 }
 
+function finalizationResponseOutput(response: Awaited<ReturnType<typeof requestSandboxTaskFinalization>>): string {
+  try {
+    const value = JSON.parse(response.stdout) as Partial<TaskFinalizationEnvelope>;
+    if (value.version === 2
+      && value.status
+      && ['completed', 'failed', 'blocked', 'unknown'].includes(value.status)
+      && (typeof value.changed === 'boolean' || value.changed === null)) {
+      return serializeTaskFinalizationEnvelope({
+        status: value.status,
+        changed: value.changed,
+        accepted: true,
+        requestId: response.id,
+        result: value.result ?? null,
+        error: value.error ?? null
+      });
+    }
+  } catch {
+    // Preserve non-envelope output for diagnostics from the executor.
+  }
+  return response.stdout;
+}
+
 function sandboxFinalizationClient(args: string[]): void {
   if (args.length !== 4 || !args[0] || args[1] !== 'complete' || args[2] !== '--agent' || !args[3]) {
     const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'task ref, complete intent, and --agent are required', retryable: false };
@@ -63,7 +87,8 @@ function sandboxFinalizationClient(args: string[]): void {
     response = requestSandboxTaskFinalization({ agent });
   } catch (error) {
     if (!(error instanceof SandboxControlClientError)) throw error;
-    writeFinalizationEnvelope(finalizationErrorStatus(error.detail), error.accepted, error.detail);
+    const status = finalizationErrorStatus(error.detail);
+    writeFinalizationEnvelope(status, error.accepted, error.detail, status === 'unknown' ? null : false, null, error.requestId);
     writeClientError(error);
     process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.detail.retryable ? 2 : 1;
     return;
@@ -74,12 +99,20 @@ function sandboxFinalizationClient(args: string[]): void {
       message: 'sandbox control rejected the finalization request',
       retryable: false
     };
-    writeFinalizationEnvelope(finalizationErrorStatus(error), error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN', error);
+    const status = finalizationErrorStatus(error);
+    writeFinalizationEnvelope(
+      status,
+      error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN',
+      error,
+      status === 'unknown' ? null : false,
+      null,
+      response.id
+    );
     process.stderr.write(`${error.message}\n`);
     process.exitCode = error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.retryable ? 2 : 1;
     return;
   }
-  process.stdout.write(response.stdout);
+  process.stdout.write(finalizationResponseOutput(response));
   process.stderr.write(response.stderr);
   process.exitCode = response.exitCode ?? 1;
 }

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 };