@ixo/oracle-runtime-workers 0.15.0 → 0.16.0

package/README.md

@@ -91,7 +91,7 @@ Every variable, binding and migration is explained in
 | `POST/GET /sessions`, `POST/GET /messages/:id`        | The chat API                                          |
 | `GET /runs/:runId`, `GET /sessions/:id/messages`      | Re-join a durable run; one page of a transcript       |
 | `/delegation`, `/models`, `/socket.io/`, `/byo-llm/*` | Delegation, models, realtime channel, BYO LLM         |
-| `POST /channels/turn`                                 | IXO Channels ingress (its own channel UCAN policy)    |
+| `POST /channels/turn`                                 | IXO Channels ingress; refusals carry a `code`         |
 | `POST /messages/:sessionId/:messageId/feedback`       | Anonymous feedback on a reply (when configured)       |
 | `/topic-deliverables/:operationId`                    | Owner-only Topic deliverables (when enabled)          |
 | `GET /a/:id`, `GET /a/:id/data`                       | Artefact links opened from chat apps (public)         |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -57,8 +57,8 @@
     "yjs": "13.6.32",
     "zod": "^4.4.3",
     "@ixo/common": "1.6.0",
-    "@ixo/ixo-transaction": "0.1.0",
-    "@ixo/ucan": "2.2.1"
+    "@ixo/ucan": "2.2.1",
+    "@ixo/ixo-transaction": "0.1.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/channels/auth.ts

@@ -58,7 +58,11 @@ export async function authenticateChannel(
     token.length > 32_000 ||
     headers.get('x-auth-type')?.toLowerCase() !== 'ucan'
   )
-    throw new ChannelError(401, 'A channel UCAN invocation is required');
+    throw new ChannelError(
+      401,
+      'A channel UCAN invocation is required',
+      'unauthorized',
+    );
   const validator = await createUCANValidator({
     serverDid: config.oracleDid,
     rootIssuers: ['*'],
@@ -88,7 +92,11 @@ export async function authenticateChannel(
     chain[1] !== config.channelDid ||
     result.invoker !== config.channelDid
   )
-    throw new ChannelError(401, 'Invalid user-rooted channel invocation');
+    throw new ChannelError(
+      401,
+      'Invalid user-rooted channel invocation',
+      'unauthorized',
+    );
   const now = Math.floor(Date.now() / 1000);
   const invocation = await parseDelegation(token);
   const proof = invocation.proofs[0];
@@ -109,6 +117,7 @@ export async function authenticateChannel(
     throw new ChannelError(
       401,
       'A bounded, direct user channel grant is required',
+      'unauthorized',
     );
   if (
     !result.expiration ||
@@ -121,6 +130,7 @@ export async function authenticateChannel(
     throw new ChannelError(
       401,
       'Channel invocations must expire within 60 seconds',
+      'unauthorized',
     );
   const nb = result.capability?.nb;
   if (
@@ -130,7 +140,11 @@ export async function authenticateChannel(
     nb.bindingRevision !== input.bindingRevision ||
     nb.oracleDid !== config.oracleDid
   )
-    throw new ChannelError(403, 'Channel scope does not match this request');
+    throw new ChannelError(
+      403,
+      'Channel scope does not match this request',
+      'scope_mismatch',
+    );
   const hash = await channelRequestHash(raw);
   if (
     result.facts?.length !== 1 ||
@@ -140,6 +154,7 @@ export async function authenticateChannel(
     throw new ChannelError(
       403,
       'Invocation does not authorize this request body',
+      'scope_mismatch',
     );
   return {
     userDid,
@@ -168,7 +183,11 @@ export function channelAuthConfig(
   >,
 ): ChannelAuthConfig {
   if (!env.CHANNEL_SERVICE_DID)
-    throw new ChannelError(503, 'Channels are not configured');
+    throw new ChannelError(
+      503,
+      'Channels are not configured',
+      'not_configured',
+    );
   const resolver = createCompositeDIDResolver([
     sharedIxoDIDResolver(env.BLOCKSYNC_GRAPHQL_URL),
     channelWebResolver,
@@ -204,15 +223,23 @@ export async function assertActiveChannelBinding(
   >,
 ): Promise<void> {
   if (!identity.channel)
-    throw new ChannelError(403, 'Channel identity is required');
+    throw new ChannelError(
+      403,
+      'Channel identity is required',
+      'identity_required',
+    );
   if (!env.AUTH_HUB_CHANNEL_SERVICE_KEY || (!env.AUTH_HUB && !env.AUTH_HUB_URL))
-    throw new ChannelError(503, 'Channel binding validation is not configured');
+    throw new ChannelError(
+      503,
+      'Channel binding validation is not configured',
+      'not_configured',
+    );
   const url = new URL(
     '/api/internal/channels/validate-binding',
     env.AUTH_HUB_URL ?? 'https://auth-hub.internal',
   );
   if (url.protocol !== 'https:')
-    throw new ChannelError(503, 'Auth Hub requires HTTPS');
+    throw new ChannelError(503, 'Auth Hub requires HTTPS', 'not_configured');
   const request = new Request(url, {
     method: 'POST',
     headers: {
@@ -235,15 +262,31 @@ export async function assertActiveChannelBinding(
       ? env.AUTH_HUB.fetch(request)
       : fetch(request));
   } catch {
-    throw new ChannelError(503, 'Channel binding validation is unavailable');
+    throw new ChannelError(
+      503,
+      'Channel binding validation is unavailable',
+      'binding_check_unavailable',
+    );
   }
   if (!response.ok)
-    throw new ChannelError(503, 'Channel binding validation is unavailable');
+    throw new ChannelError(
+      503,
+      'Channel binding validation is unavailable',
+      'binding_check_unavailable',
+    );
   const parsed = BindingVerdict.safeParse(await response.json());
   if (!parsed.success)
-    throw new ChannelError(503, 'Invalid channel binding validation response');
+    throw new ChannelError(
+      503,
+      'Invalid channel binding validation response',
+      'binding_check_unavailable',
+    );
   if (!parsed.data.active)
-    throw new ChannelError(403, 'Channel binding is inactive');
+    throw new ChannelError(
+      403,
+      'Channel binding is inactive',
+      'binding_inactive',
+    );
 }
 
 /**

package/src/channels/contract.ts

@@ -66,34 +66,130 @@ export interface ChannelTurnResponse {
   plan?: ReplyPlan;
 }
 
+export type ChannelErrorStatus =
+  | 400
+  | 401
+  | 403
+  | 404
+  | 409
+  | 410
+  | 413
+  | 428
+  | 429
+  | 503;
+
+/**
+ * The machine-readable reason a channel turn was refused. The gateway maps
+ * a refusal by `code` first and by HTTP status second. 428 (Precondition
+ * Required) means a precondition on the user's side is missing: fix it
+ * (authorize the oracle again, finish setting up the Companion room) and
+ * retry; it is never a transient outage.
+ *
+ * | code                              | status | meaning                                               |
+ * | --------------------------------- | ------ | ----------------------------------------------------- |
+ * | `invalid_request`                 | 400    | body missing, not UTF-8, not JSON, or the wrong shape |
+ * | `unauthorized`                    | 401    | no valid user-rooted channel invocation               |
+ * | `scope_mismatch`                  | 403    | the invocation does not cover this binding or body    |
+ * | `identity_mismatch`               | 403    | the channel identity does not match the request       |
+ * | `identity_required`               | 403    | the binding check got no channel identity             |
+ * | `binding_inactive`                | 403    | the Auth Hub reports the binding inactive             |
+ * | `channel_grant_not_tool_authority`| 403    | a channel request carried a delegation header         |
+ * | `session_not_found`               | 404    | the session is not the user's Companion session       |
+ * | `request_conflict`                | 409    | the request id already belongs to another message     |
+ * | `session_conflict`                | 409    | the channel is already bound to another session       |
+ * | `room_not_encrypted`              | 409    | the Companion room is not end-to-end encrypted        |
+ * | `response_expired`                | 410    | the run was pruned; the request cannot run again      |
+ * | `request_too_large`               | 413    | the body is over 64 kB                                |
+ * | `room_not_ready`                  | 428    | the user has no Companion room yet                    |
+ * | `delegation_required`             | 428    | no usable delegation to this oracle (see below)       |
+ * | `rate_limited`                    | 429    | too many requests for this user                       |
+ * | `not_configured`                  | 503    | channels or binding validation are not configured     |
+ * | `binding_check_unavailable`       | 503    | the Auth Hub binding check failed or answered badly   |
+ * | `unavailable`                     | 503    | any other failure (the shell logs it)                 |
+ */
+export type ChannelErrorCode =
+  | 'invalid_request'
+  | 'unauthorized'
+  | 'scope_mismatch'
+  | 'identity_mismatch'
+  | 'identity_required'
+  | 'binding_inactive'
+  | 'channel_grant_not_tool_authority'
+  | 'session_not_found'
+  | 'request_conflict'
+  | 'session_conflict'
+  | 'room_not_encrypted'
+  | 'response_expired'
+  | 'request_too_large'
+  | 'room_not_ready'
+  | 'delegation_required'
+  | 'rate_limited'
+  | 'not_configured'
+  | 'binding_check_unavailable'
+  | 'unavailable';
+
 export type ChannelTurnOutcome =
   | { ok: true; result: ChannelTurnResponse }
   | {
       ok: false;
-      status: 400 | 401 | 403 | 404 | 409 | 410 | 413 | 429 | 503;
+      status: ChannelErrorStatus;
+      code: ChannelErrorCode;
       message: string;
     };
 
 export class ChannelError extends Error {
   constructor(
-    readonly status: 400 | 401 | 403 | 404 | 409 | 410 | 413 | 429 | 503,
+    readonly status: ChannelErrorStatus,
     message: string,
+    readonly code: ChannelErrorCode,
   ) {
     super(message);
+    this.name = 'ChannelError';
   }
 }
 
+/**
+ * The least lifetime a delegation must have left for a channel turn to be
+ * admitted (seconds): a turn, its tool calls and its owner-copy flush must
+ * not outlive the delegation they run under.
+ */
+export const CHANNEL_DELEGATION_MIN_REMAINING_SECONDS = 900;
+
+/** The user's delegation to this oracle as the user object holds it. */
+export interface ChannelDelegation {
+  raw?: string;
+  /** Unix seconds: the delegation's effective expiry; absent = unknown. */
+  expiration?: number;
+}
+
+export function delegationRequiredError(): ChannelError {
+  return new ChannelError(
+    428,
+    'Companion delegation required: the user must authorize this oracle again',
+    'delegation_required',
+  );
+}
+
 /**
  * A channel turn runs under the user's stored delegation to this oracle,
- * like a Matrix turn. Without one there is no tool authority to run under;
- * the turn is refused with an explicit error instead of running degraded.
+ * like a Matrix turn. Without one, with an unknown expiry, or with less than
+ * `CHANNEL_DELEGATION_MIN_REMAINING_SECONDS` left, there is no tool
+ * authority to run under: the turn is refused with an explicit 428
+ * `delegation_required` instead of running degraded (memory, files and the
+ * sandbox would fail silently).
  */
-export function requireChannelDelegation(present: boolean): void {
-  if (!present)
-    throw new ChannelError(
-      409,
-      'Companion delegation required: the user must authorize this oracle again',
-    );
+export function requireChannelDelegation(
+  delegation: ChannelDelegation | undefined,
+  nowSeconds: number,
+): void {
+  if (
+    !delegation?.raw ||
+    typeof delegation.expiration !== 'number' ||
+    !Number.isFinite(delegation.expiration) ||
+    delegation.expiration <=
+      nowSeconds + CHANNEL_DELEGATION_MIN_REMAINING_SECONDS
+  )
+    throw delegationRequiredError();
 }
 
 export async function channelRequestHash(raw: string): Promise<string> {
@@ -108,7 +204,12 @@ export async function channelRequestHash(raw: string): Promise<string> {
 
 export async function readChannelBody(request: Request): Promise<string> {
   const reader = request.body?.getReader();
-  if (!reader) throw new ChannelError(400, 'A channel turn is required');
+  if (!reader)
+    throw new ChannelError(
+      400,
+      'A channel turn is required',
+      'invalid_request',
+    );
   const chunks: Uint8Array[] = [];
   let size = 0;
   while (true) {
@@ -117,7 +218,11 @@ export async function readChannelBody(request: Request): Promise<string> {
     size += chunk.value.byteLength;
     if (size > 64_000) {
       await reader.cancel();
-      throw new ChannelError(413, 'Channel request is too large');
+      throw new ChannelError(
+        413,
+        'Channel request is too large',
+        'request_too_large',
+      );
     }
     chunks.push(chunk.value);
   }
@@ -132,6 +237,10 @@ export async function readChannelBody(request: Request): Promise<string> {
       bytes,
     );
   } catch {
-    throw new ChannelError(400, 'Channel request must be UTF-8');
+    throw new ChannelError(
+      400,
+      'Channel request must be UTF-8',
+      'invalid_request',
+    );
   }
 }

package/src/channels/turns.ts

@@ -23,7 +23,10 @@ interface ReceiptRow extends Record<string, string | number | null> {
 export interface ChannelTurnsHost {
   createSession(identity: TurnIdentity, markerTxnId: string): Promise<string>;
   assertSession(identity: TurnIdentity, sessionId: string): Promise<void>;
-  /** Throws a `ChannelError` when the user has no stored delegation for this oracle. */
+  /**
+   * Throws a `ChannelError` (428 `delegation_required`) when the user has no
+   * usable delegation for this oracle: none, or one too close to expiry.
+   */
   requireDelegation(identity: TurnIdentity): Promise<void>;
   getRun(runId: string): Promise<RunRecord | undefined>;
   /** The Reply Plan (JSON) a finished run was built into, if any. */
@@ -167,6 +170,7 @@ export class ChannelTurns {
       throw new ChannelError(
         403,
         'Channel identity does not match this request',
+        'identity_mismatch',
       );
     const runId = `channel_${await channelRequestHash(JSON.stringify([input.bindingId, input.requestId]))}`;
     // Checked before a receipt is written: the receipt of a pruned run is
@@ -175,6 +179,7 @@ export class ChannelTurns {
       throw new ChannelError(
         410,
         'Channel response has expired; this request cannot execute again',
+        'response_expired',
       );
     const admitted = await this.db.run(
       `INSERT OR IGNORE INTO channel_requests
@@ -191,6 +196,7 @@ export class ChannelTurns {
       throw new ChannelError(
         409,
         'This request ID already belongs to another message',
+        'request_conflict',
       );
     let sessionId = receipt.session_id;
     // The session is checked when this request is bound to it, and again
@@ -203,7 +209,11 @@ export class ChannelTurns {
         [input.bindingId],
       );
       if (binding && input.sessionId && binding.session_id !== input.sessionId)
-        throw new ChannelError(409, 'This channel already has another session');
+        throw new ChannelError(
+          409,
+          'This channel already has another session',
+          'session_conflict',
+        );
       sessionId =
         binding?.session_id ??
         input.sessionId ??

package/src/do/user-oracle-do.ts

@@ -4,6 +4,7 @@ import {
   ChannelError,
   channelRequestHash,
   channelOrigin,
+  delegationRequiredError,
   requireChannelDelegation,
   type ChannelTurnInput,
   type ChannelTurnOutcome,
@@ -311,7 +312,11 @@ import type {
   FeedbackSettlement,
   FeedbackTarget,
 } from '../feedback/contract';
-import { resolveTurnDelegation, WorkersUcanService } from './ucan-service';
+import {
+  readDelegation,
+  resolveTurnDelegation,
+  WorkersUcanService,
+} from './ucan-service';
 import type { UcanDelegation } from '../plugin-api/types';
 
 /** What one attempt's agent build reads from the request body. */
@@ -540,6 +545,17 @@ interface StoredDelegation {
   at: number;
 }
 
+/** The user's delegation as the object holds it in memory. */
+interface CachedDelegation {
+  raw: string;
+  /**
+   * Unix seconds: the delegation's effective expiry. Taken from where the
+   * delegation arrived (the shell's validation, the deposit record) or read
+   * off the token itself; absent only when the token cannot be parsed.
+   */
+  expiration?: number;
+}
+
 interface FlushResult {
   uploaded: boolean;
   /** Raw file size (skips) or bytes sent upstream (uploads). */
@@ -761,7 +777,7 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
      * events of one request (a soft then a hard prune) never race.
      */
     private contextStatsWrites: Promise<void> = Promise.resolve();
-    private readonly delegations = new Map<string, { raw: string }>();
+    private readonly delegations = new Map<string, CachedDelegation>();
     /** Epoch-ms until which a room-state delegation lookup is not retried. */
     private delegationMissUntil = 0;
     private dirty = false;
@@ -977,9 +993,18 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           this.delegations.get(identity.userDid)?.raw ??
           (await this.ctx.storage.get<StoredDelegation>(META_DELEGATION))?.raw;
         delegationReplaced = known !== identity.ucanDelegation;
-        this.delegations.set(identity.userDid, {
-          raw: identity.ucanDelegation,
-        });
+        const cached = this.delegations.get(identity.userDid);
+        if (
+          cached?.raw !== identity.ucanDelegation ||
+          typeof cached.expiration !== 'number'
+        )
+          this.delegations.set(
+            identity.userDid,
+            await this.delegationRecord(
+              identity.ucanDelegation,
+              identity.ucanDelegationExpiration,
+            ),
+          );
         // Remember a new one for turns that arrive without the header.
         if (delegationReplaced)
           await this.ctx.storage.put(META_DELEGATION, {
@@ -1125,7 +1150,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       const cached =
         await this.ctx.storage.get<StoredDelegation>(META_DELEGATION);
       if (live(cached)) {
-        this.delegations.set(userDid, { raw: cached.raw });
+        this.delegations.set(
+          userDid,
+          await this.delegationRecord(cached.raw, cached.expiration),
+        );
         return;
       }
       if (Date.now() < this.delegationMissUntil) return;
@@ -1156,7 +1184,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             }
           : null;
         if (live(deposited)) {
-          this.delegations.set(userDid, { raw: deposited.raw });
+          this.delegations.set(
+            userDid,
+            await this.delegationRecord(deposited.raw, deposited.expiration),
+          );
           await this.ctx.storage.put(META_DELEGATION, deposited);
           console.log(
             `[user-do] delegation for ${userDid} loaded from the deposited room state (header-less turn)`,
@@ -1171,6 +1202,31 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       this.delegationMissUntil = Date.now() + DELEGATION_MISS_TTL_MS;
     }
 
+    /**
+     * The in-memory record of a delegation: the expiry where it arrived
+     * stated one (the shell validated the token and read it off the chain),
+     * else the token's own effective expiry along its proof chain. A token
+     * that cannot be parsed keeps no expiry; channel turns refuse it.
+     */
+    private async delegationRecord(
+      raw: string,
+      expiration: number | undefined,
+    ): Promise<CachedDelegation> {
+      if (typeof expiration === 'number' && Number.isFinite(expiration))
+        return { raw, expiration };
+      try {
+        const grant = await readDelegation(raw);
+        return typeof grant.expiration === 'number'
+          ? { raw, expiration: grant.expiration }
+          : { raw };
+      } catch (err) {
+        console.warn(
+          `[user-do] could not read the expiry of a delegation: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        return { raw };
+      }
+    }
+
     private async boot(userDid: string): Promise<void> {
       const stored = await this.ctx.storage.get<string>(META_USER_DID);
       if (stored && stored !== userDid)
@@ -1616,7 +1672,12 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       this.channelTurns = new ChannelTurns(liveDb, {
         createSession: async (identity, markerTxnId) => {
           const room = await this.gateway.resolveUserRoom(identity.userDid);
-          if (!room) throw new ChannelError(409, 'Companion room is not ready');
+          if (!room)
+            throw new ChannelError(
+              428,
+              'Companion room is not ready',
+              'room_not_ready',
+            );
           return (
             await this.createSession(identity, {
               roomId: room.roomId,
@@ -1633,7 +1694,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             !room ||
             session.roomId !== room.roomId
           )
-            throw new ChannelError(404, 'Companion session not found');
+            throw new ChannelError(
+              404,
+              'Companion session not found',
+              'session_not_found',
+            );
           const encryption = await this.gateway.getRoomStateEvent(
             room.roomId,
             'm.room.encryption',
@@ -1645,11 +1710,17 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
             !('algorithm' in parsed) ||
             parsed.algorithm !== 'm.megolm.v1.aes-sha2'
           )
-            throw new ChannelError(409, 'Companion room must be encrypted');
+            throw new ChannelError(
+              409,
+              'Companion room must be encrypted',
+              'room_not_encrypted',
+            );
         },
+        // Checked again as the run starts: admission may have waited.
         requireDelegation: async (identity) =>
           requireChannelDelegation(
-            !!this.delegations.get(identity.userDid)?.raw,
+            this.delegations.get(identity.userDid),
+            Math.floor(Date.now() / 1000),
           ),
         getRun: (runId) => this.runStore!.get(runId),
         getPlan: (runId) => this.runStore!.getPlan(runId),
@@ -2558,16 +2629,52 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
           throw new ChannelError(
             403,
             'Channel grants cannot become tool authority',
+            'channel_grant_not_tool_authority',
           );
         // The shell (the only caller) checked the binding just before.
-        await this.ready(identity);
+        // The delegation is checked BEFORE the object boots: a cold boot
+        // loads the owner copy under it, and a user without a usable one
+        // must get `delegation_required`, not a boot failure. Hydration
+        // reads the cached copy, then the deposited room state (throttled
+        // after a miss); an in-memory one that no longer passes is
+        // re-read too, in case a newer deposit did not reach this object.
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        try {
+          requireChannelDelegation(
+            this.delegations.get(identity.userDid),
+            nowSeconds,
+          );
+        } catch {
+          await this.hydrateDelegation(identity.userDid);
+          requireChannelDelegation(
+            this.delegations.get(identity.userDid),
+            nowSeconds,
+          );
+        }
+        try {
+          await this.ready(identity);
+        } catch (error) {
+          // A delegation that lacks the file-storage grant over
+          // `/.oracles` cannot load the owner copy: the user must
+          // authorize again, exactly as without a delegation. (Boot throws
+          // the failure as its RPC envelope, so it is parsed, not matched
+          // by class.)
+          if (parseOwnerCopyFailure(error)?.code === 'NO_VFS_DELEGATION')
+            throw delegationRequiredError();
+          throw error;
+        }
         return {
           ok: true,
           result: await this.channelTurns!.submit(identity, input, requestHash),
         };
       } catch (error) {
         if (error instanceof ChannelError)
-          return { ok: false, status: error.status, message: error.message };
+          return {
+            ok: false,
+            status: error.status,
+            code: error.code,
+            message: error.message,
+          };
         throw error;
       }
     }
@@ -2891,7 +2998,10 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
       raw: string,
       expiration?: number,
     ): Promise<void> {
-      this.delegations.set(userDid, { raw });
+      this.delegations.set(
+        userDid,
+        await this.delegationRecord(raw, expiration),
+      );
       this.delegationMissUntil = 0;
       await this.ctx.storage.put(META_DELEGATION, {
         raw,
@@ -3001,12 +3111,11 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         await this.ctx.storage.get<StoredDelegation>(META_DELEGATION);
       const inMemory = this.delegations.get(userDid);
       if (inMemory) {
+        const expiration = inMemory.expiration ?? stored?.expiration;
         return {
           present: true,
           source: 'memory',
-          ...(typeof stored?.expiration === 'number'
-            ? { expiration: stored.expiration }
-            : {}),
+          ...(typeof expiration === 'number' ? { expiration } : {}),
         };
       }
       if (stored?.raw) {
@@ -4076,7 +4185,8 @@ export function createUserOracleDO(opts: UserOracleDOOptions) {
         if (live.attemptSource !== 'begin')
           await assertChannelAttemptAllowed(req.identity, this.env);
         requireChannelDelegation(
-          !!this.delegations.get(req.identity.userDid)?.raw,
+          this.delegations.get(req.identity.userDid),
+          Math.floor(Date.now() / 1000),
         );
       }
       // An attempt that starts from `admitting` never reached the agent (the

package/src/shell/app.ts

@@ -139,6 +139,20 @@ function errorText(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+/** Longest error message an unexpected channel failure logs. */
+const CHANNEL_FAILURE_LOG_CHARS = 300;
+
+/** `<name>: <message>` of an unexpected channel failure, the message bounded. */
+function describeChannelFailure(err: unknown): string {
+  const name = err instanceof Error ? err.name : typeof err;
+  const message = errorText(err);
+  return `${name}: ${
+    message.length > CHANNEL_FAILURE_LOG_CHARS
+      ? `${message.slice(0, CHANNEL_FAILURE_LOG_CHARS)}…`
+      : message
+  }`;
+}
+
 /** The rejection an in-flight RPC gets when `ctx.abort()` resets its object. */
 function isAbortRejection(err: unknown): boolean {
   return /debug reset requested|reset requested by the debug route|durable object reset|no longer active|aborted/i.test(
@@ -405,16 +419,21 @@ export function createShell(
   app.post('/channels/turn', async (c) => {
     try {
       if (!c.env.CHANNEL_SERVICE_DID)
-        return c.json({ message: 'Channels are not configured' }, 503);
+        throw new ChannelError(
+          503,
+          'Channels are not configured',
+          'not_configured',
+        );
       const raw = await readChannelBody(c.req.raw);
       let json: unknown;
       try {
         json = JSON.parse(raw);
       } catch {
-        throw new ChannelError(400, 'Invalid JSON request');
+        throw new ChannelError(400, 'Invalid JSON request', 'invalid_request');
       }
       const parsed = ChannelTurnBody.safeParse(json);
-      if (!parsed.success) throw new ChannelError(400, 'Invalid channel turn');
+      if (!parsed.success)
+        throw new ChannelError(400, 'Invalid channel turn', 'invalid_request');
       const identity = await authenticateChannel(
         c.req.raw.headers,
         raw,
@@ -431,7 +450,7 @@ export function createShell(
           })
         ).success
       )
-        throw new ChannelError(429, 'Too many requests');
+        throw new ChannelError(429, 'Too many requests', 'rate_limited');
       await assertActiveChannelBinding(identity, c.env);
       const outcome = await userStub(c.env, identity.userDid).channelTurn(
         identity,
@@ -439,7 +458,10 @@ export function createShell(
         await channelRequestHash(raw),
       );
       if (!outcome.ok)
-        return c.json({ message: outcome.message }, outcome.status);
+        return c.json(
+          { code: outcome.code, message: outcome.message },
+          outcome.status,
+        );
       const result = outcome.result;
       return c.json(
         result,
@@ -447,9 +469,20 @@ export function createShell(
       );
     } catch (error) {
       if (error instanceof ChannelError)
-        return c.json({ message: error.message }, error.status);
+        return c.json(
+          { code: error.code, message: error.message },
+          error.status,
+        );
+      // The cause only, never the request or its tokens: a 503 the gateway
+      // retries must leave a trace of why it happened.
+      console.error(
+        `[channels] turn failed unexpectedly: ${describeChannelFailure(error)}`,
+      );
       return c.json(
-        { message: 'Channel turn is temporarily unavailable' },
+        {
+          code: 'unavailable',
+          message: 'Channel turn is temporarily unavailable',
+        },
         503,
       );
     }
@@ -1084,7 +1117,7 @@ export function createShell(
     // Thrown on purpose with a status and a message meant for the client.
     if (err instanceof HTTPException) return err.getResponse();
     if (err instanceof ChannelError)
-      return c.json({ message: err.message }, err.status);
+      return c.json({ code: err.code, message: err.message }, err.status);
     const requestId = errorRequestId(c.req.header('x-request-id'));
     console.error(
       `[shell] ${c.req.method} ${loggedRoute(c)} failed (request ${requestId}):`,