refactor(sandbox): normalize Daytona recovery errors (#184)

## Why

Daytona currently reports an unhealthy sandbox host with a structured
HTTP 503 body but no provider error code. The sandbox lifecycle should
not depend on provider message text.

## What changed

- validate the Daytona error projection at the adapter boundary
- normalize the specific host-recovery response to an internal
`daytona_host_recovering` code
- make lifecycle classification depend only on the internal code and
HTTP status
- document the normalized adapter-to-lifecycle contract

This preserves the guarded same-volume runtime replacement behavior
merged in #183 while keeping provider response details isolated to the
Daytona adapter.

## Verification

- `pnpm lint`
- `pnpm typecheck`
- `pnpm turbo build --force`
- `pnpm deadcode`
- `pnpm architecture:check`
- `pnpm turbo skills:build`
- captured the live Daytona 503 response shape for the affected sandbox
without exposing credentials

Production behavior will be exercised after merge and exact-SHA
Cloudflare deployment.

Author: iamjr15

apps/agent-worker/README.md

@@ -83,9 +83,10 @@ completed step instead of losing an in-memory coroutine. Transcript publication
 event keys and an atomic SQLite receipt, so Workflow step replay cannot duplicate visible parts.
 Preparation uses a multi-minute durable exponential-backoff window for transient provider
 failures. Daytona's explicit host-recovery start rejection is treated as a runtime failover signal:
-after the active-run lease and canonical volume mount are verified, the stopped container is
-replaced on the same isolated workspace-volume subpath. This preserves user files while avoiding
-an indefinite dependency on one unhealthy runner.
+the Daytona adapter normalizes the provider's structured `503` response to an internal error code,
+then the lifecycle verifies the active-run lease and canonical volume mount before replacing the
+stopped container on the same isolated workspace-volume subpath. This preserves user files while
+avoiding an indefinite dependency on one unhealthy runner.
 There is no application step, token, duration, or cost ceiling; semantic completion ends the loop,
 while per-operation timeouts and the platform Workflow limit remain operational safeguards.
 The Worker pins Cloudflare's paid-plan maximum subrequest allowance because external provider,

packages/agent-core/src/tools/code/daytona-client.ts

@@ -34,9 +34,18 @@ const DAYTONA_FILE_LIST_MAX_ITEMS = 1_000;
 const DAYTONA_SANDBOX_PAGE_MAX_ITEMS = 100;
 const DAYTONA_SESSION_COMMAND_MAX_ITEMS = 1_000;
 const DAYTONA_VOLUME_NAME_MAX_CHARACTERS = 100;
-const DAYTONA_HOST_RECOVERY_START_MESSAGE =
+const DAYTONA_HOST_RECOVERY_ERROR_CODE = "daytona_host_recovering";
+const DAYTONA_HOST_RECOVERY_MESSAGE_PREFIX =
   "sandbox start is temporarily unavailable while the sandbox's host recovers";
 
+const DaytonaErrorResponseSchema = z
+  .object({
+    error: z.string(),
+    message: z.string(),
+    statusCode: z.number().int(),
+  })
+  .strip();
+
 interface DaytonaClientConfig {
   apiKey: string;
   apiUrl: string;
@@ -75,7 +84,7 @@ export function isDaytonaHostRecoveryStartError(error: unknown): boolean {
     if (
       current instanceof DaytonaApiError &&
       current.status === 503 &&
-      current.message.toLowerCase().includes(DAYTONA_HOST_RECOVERY_START_MESSAGE)
+      current.code === DAYTONA_HOST_RECOVERY_ERROR_CODE
     ) {
       return true;
     }
@@ -655,13 +664,15 @@ export class DaytonaClient {
 }
 
 async function toApiError(res: Response, operation?: string): Promise<DaytonaApiError> {
+  let code: string | undefined;
   let details: unknown;
   let message = `Daytona request failed (HTTP ${res.status}${operation ? `; ${operation}` : ""})`;
   try {
     const text = await readBoundedResponseText(res, DAYTONA_ERROR_RESPONSE_MAX_BYTES);
     if (text.length > 0) {
       try {
         const parsed: unknown = JSON.parse(text);
+        code = providerErrorCode(parsed, res.status);
         details = parsed;
         message = providerErrorMessage(parsed) ?? message;
       } catch {
@@ -671,7 +682,25 @@ async function toApiError(res: Response, operation?: string): Promise<DaytonaApi
   } catch {
     // ignore body read failures
   }
-  return new DaytonaApiError(res.status, message, { details });
+  return new DaytonaApiError(res.status, message, {
+    ...(code ? { code } : {}),
+    details,
+  });
+}
+
+function providerErrorCode(value: unknown, responseStatus: number): string | undefined {
+  const result = DaytonaErrorResponseSchema.safeParse(value);
+  if (!result.success) return undefined;
+  const providerError = result.data;
+  if (
+    responseStatus === 503 &&
+    providerError.statusCode === 503 &&
+    providerError.error === "Service Unavailable" &&
+    providerError.message.toLowerCase().startsWith(DAYTONA_HOST_RECOVERY_MESSAGE_PREFIX)
+  ) {
+    return DAYTONA_HOST_RECOVERY_ERROR_CODE;
+  }
+  return undefined;
 }
 
 function providerErrorMessage(value: unknown): string | undefined {