@bitkyc08/opencodex 2.59.0 → 2.60.0

package/src/integrations/writer.ts

@@ -11,12 +11,14 @@
  */
 import { homedir } from "node:os";
 import { createClineIO, ClineTransactionError } from "./cline-io";
-import { parseClineDocument, serializeClineDocument, preserveClineSelection } from "./cline-document";
+import { serializeClineDocument, preserveClineSelection } from "./cline-document";
 import { dirname } from "node:path";
 import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
+import { detachedConfigSnapshot } from "../config/admitted-identity";
+import { copyPlainData } from "../lib/plain-data";
 import type { OcxConfig } from "../types";
-import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
+import { defaultIntegrationIO, loadTarget, type IntegrationIO } from "./config-io";
 import {
   fingerprint,
   canonicalContribution,
@@ -31,11 +33,12 @@ import {
 } from "./ownership-policy";
 import { AmbiguousSelectorError, createdContainerPaths, mergeContribution, removeFragments } from "./merge";
 import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
-import { classifyIntegration, exportContextOf } from "./state";
+import { exportContextOf } from "./state";
 import type { IntegrationState } from "./state";
 import { serializeDocument, UnserializableValueError } from "./serialize";
 import { ClientPathError } from "../clients/config-export";
 import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
+import { observeIntegration, type IntegrationWriteInput, type RefusalReason } from "./mutation-plan";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 import {
   patchYamlFragmentSource,
@@ -62,14 +65,12 @@ function yamlRefusalReason(
 }
 import { withIntegrationWriterLock, type IntegrationWriterLockSeams } from "./writer-lock";
 
-export type RefusalReason =
-  | "not_installed"
-  | "conflict"
-  | "unsafe"
-  | "non_loopback"
-  | "drift_requires_confirm"
-  | "snapshot_expired"
-  | "write_failed";
+/**
+ * Owned by the planner so a plan can report a refusal without depending on the writer, and
+ * re-exported here because this module was its original home and every caller imports it from
+ * the writer.
+ */
+export type { IntegrationWriteInput, RefusalReason };
 
 export interface WriteOk {
   ok: true;
@@ -94,19 +95,6 @@ export interface WriteRefused {
 
 export type WriteOutcome = WriteOk | WriteRefused;
 
-export interface IntegrationWriteInput {
-  clientId: IntegrationClientId;
-  models: readonly ExportModel[];
-  config: OcxConfig;
-  port: number;
-  env?: NodeJS.ProcessEnv;
-  home?: string;
-  store?: IntegrationStateStore;
-  io?: IntegrationIO;
-  /** Frozen once by the async coordinator; synchronous callers may omit it. */
-  resolvedPaths?: { configPath: string; detectDir: string };
-}
-
 export interface IntegrationRestoreInput extends IntegrationWriteInput {
   opId: string;
   confirmDrift?: boolean;
@@ -227,76 +215,20 @@ function sourcePreservingFragmentValue(
   return fragment?.value;
 }
 
-/** Shared preflight: detect, gate, read, parse and classify. */
+/**
+ * Mutation's view of the shared observation.
+ *
+ * The read, parse and classify live in the planner so a preview and the mutation it authorizes
+ * cannot disagree. Mutation keeps the effects a preview must not have: pending-prune maintenance
+ * and Cline transaction recovery both write. Translating the planner's refusal into WriteRefused
+ * here keeps the planner free of any dependency on this module's result type.
+ */
 function preflight(input: IntegrationWriteInput) {
-  const store = input.store ?? createIntegrationStateStore();
-  let io = input.io ?? defaultIntegrationIO(store);
-  const clientId = input.clientId;
-  const spec = INTEGRATION_CLIENTS[clientId];
-  const exportSpec = EXPORT_CLIENTS[clientId];
-  /*
-   * Resolution itself can refuse: a relative OPENCLAW_* selector is rejected
-   * because we cannot know the gateway's working directory. That is a refusal
-   * about the user's configuration, not an internal fault, so it must not
-   * escape as an exception — the collection route would answer 500 for the
-   * whole Integrations page because one client is misconfigured.
-   */
-  let configPath: string;
-  let detectDir: string;
-  try {
-    /*
-     * Resolve the PAIR, never one half.
-     *
-     * The coordinated path hands us a frozen pair, but applyIntegration,
-     * refreshIntegration and disableIntegration are public and may be called
-     * without one. Resolving configPath here and detectDir separately later let
-     * an Aside account switch land between the two, so a direct apply could
-     * verify account 1 was installed and then write account 0's catalog.
-     */
-    const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
-    configPath = resolved.configPath;
-    detectDir = resolved.detectDir;
-    if (clientId === "cline") io = createClineIO(io, configPath, store, true);
-  } catch (error) {
-    if (error instanceof ClineTransactionError) {
-      return { failed: { ...refuse(clientId, "unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;
-    }
-    if (!(error instanceof ClientPathError)) throw error;
-    return { failed: refuse(clientId, "unsafe", "unsafe", error.message) } as const;
-  }
-  store.retryPendingPrunes();
-
-  const target = loadTarget(io, configPath);
-  if (!target.ok) {
-    return {
-      failed: refuse(clientId, "unsafe", "unsafe",
-        target.why === "read-failed"
-          ? `${configPath} exists but could not be read`
-          : `${configPath} is not a regular file`),
-    } as const;
-  }
-  const before = target.before;
-  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, exportSpec.format);
-  if (parsed === PARSE_FAILED) {
-    return { failed: refuse(clientId, "unsafe", "unsafe",
-      `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
-  }
-  const contribution = exportSpec.buildContribution(exportContextOf(input));
-  // A record proves ownership of the file it was written FOR. Matching only by
-  // client id let a record for one home authorize a write to another whose
-  // bytes happened to hash the same — which deleted a config we never touched.
-  const stored = store.readRecords()[clientId] ?? null;
-  const record = stored && stored.clientId === clientId && stored.configPath === configPath
-    ? stored
-    : null;
-  // `configPath`/`clientId` are load-bearing, not decoration: a record proves
-  // ownership of ONE file, and the writer mutates whatever path resolves NOW.
-  // Without them a record written for another home directory would grant
-  // ownership here and disable would delete fragments it never wrote.
-  const classified = classifyIntegration({
-    fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
-  });
-  return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } as const;
+  const observed = observeIntegration(input, { maintenance: true, recover: true });
+  if (!observed.failed) return observed;
+  const { reason, state, message, snapshotPath, residual } = observed.failed;
+  const refused = refuse(input.clientId, reason, state, message, snapshotPath);
+  return { failed: residual ? { ...refused, residual: true } : refused } as const;
 }
 
 /**
@@ -748,6 +680,15 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
 
 export interface CoordinatedIntegrationOptions {
   lockSeams?: IntegrationWriterLockSeams;
+  /**
+   * Checked after the input is frozen and the writer lock is held, before any side effect.
+   *
+   * A confirmation is a statement about state the operator was shown. Checking it out here, where
+   * the lock already excludes cooperating writers, is what makes it a decision about the same
+   * state the mutation is about to change rather than about state from a moment earlier. A
+   * non-null result refuses without writing anything.
+   */
+  revalidate?: (frozen: IntegrationWriteInput) => Promise<WriteOutcome | null>;
 }
 
 /** Freeze all mutable resolution seams before the first lock await. */
@@ -759,6 +700,16 @@ type FrozenIntegrationInput = IntegrationWriteInput & {
   resolvedPaths: { configPath: string; detectDir: string };
 };
 
+/**
+ * An input this write cannot hold still.
+ *
+ * A coordinated write checks a plan and then writes a document from the same input, with an await
+ * in between. Anything it cannot copy would have to be read from the caller's object twice, and
+ * the second read is not the one that was checked. Refusing is bounded and says so; carrying the
+ * reference and calling it a frozen input would not be.
+ */
+class UncopyableIntegrationInputError extends Error {}
+
 function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegrationInput {
   const env = { ...(input.env ?? process.env) };
   const home = input.home ?? homedir();
@@ -773,7 +724,23 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
   const resolvedPaths = input.resolvedPaths
     ? { ...input.resolvedPaths }
     : resolveIntegrationPaths(input.clientId, env, home);
-  return { ...input, env, home, store, io, resolvedPaths };
+  /*
+   * The configuration and the roster are seams like the others, and they were the two still held
+   * by reference. A coordinated write plans from this input, awaits the writer lock and a
+   * revalidation, and only then serializes the document from it. A management route editing the
+   * live configuration, or a caller editing the model objects it passed in, would have been
+   * checked in one state and written from another, which is the substitution the fingerprint
+   * exists to prevent. Copying both here gives the plan and the document one input.
+   */
+  const config = detachedConfigSnapshot(input.config);
+  if (config === null) {
+    throw new UncopyableIntegrationInputError("the proxy configuration could not be captured for this write");
+  }
+  const models = copyPlainData(input.models);
+  if (!models.ok) {
+    throw new UncopyableIntegrationInputError("the model roster could not be captured for this write");
+  }
+  return { ...input, config, models: models.value, env, home, store, io, resolvedPaths };
 }
 
 function tryFreezeIntegrationInput(input: IntegrationWriteInput):
@@ -782,6 +749,9 @@ function tryFreezeIntegrationInput(input: IntegrationWriteInput):
   try {
     return { ok: true, value: freezeIntegrationInput(input) };
   } catch (error) {
+    if (error instanceof UncopyableIntegrationInputError) {
+      return { ok: false, refusal: refuse(input.clientId, "unsafe", "unsafe", error.message) };
+    }
     if (!(error instanceof ClientPathError)) throw error;
     return {
       ok: false,
@@ -799,15 +769,22 @@ async function coordinatedWrite(
   if (!prepared.ok) return prepared.refusal;
   const frozen = prepared.value;
   const spec = INTEGRATION_CLIENTS[frozen.clientId];
-  if (!spec.writerLock) return operation(frozen);
+  if (!spec.writerLock) {
+    const refused = await options?.revalidate?.(frozen);
+    return refused ?? operation(frozen);
+  }
 
   // An absent client home is not created merely to acquire a sibling lock.
   if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
-    return operation(frozen);
+    const refused = await options?.revalidate?.(frozen);
+    return refused ?? operation(frozen);
   }
   return withIntegrationWriterLock(
     frozen.resolvedPaths.configPath,
-    async () => operation(frozen),
+    async () => {
+      const refused = await options?.revalidate?.(frozen);
+      return refused ?? operation(frozen);
+    },
     options?.lockSeams,
     spec.writerLock.suffix,
   );
@@ -849,7 +826,11 @@ export async function restoreIntegrationCoordinated(
   if (!prepared.ok) return prepared.refusal;
   const frozen = prepared.value;
   const spec = INTEGRATION_CLIENTS[frozen.clientId];
-  if (!spec.writerLock) return restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift });
+  const run = () => restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift });
+  if (!spec.writerLock) {
+    const refused = await options?.revalidate?.(frozen);
+    return refused ?? run();
+  }
   if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
     return refuse(
       frozen.clientId,
@@ -860,7 +841,12 @@ export async function restoreIntegrationCoordinated(
   }
   return withIntegrationWriterLock(
     frozen.resolvedPaths.configPath,
-    async () => restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift }),
+    async () => {
+      // An undo is bound like any other confirmation, and this is the only place where that check
+      // happens with the lock held and before the snapshot, the write and the journal row.
+      const refused = await options?.revalidate?.(frozen);
+      return refused ?? run();
+    },
     options?.lockSeams,
     spec.writerLock.suffix,
   );

package/src/lab/live/transport.ts

@@ -104,6 +104,10 @@ export function classifyTransportError(error: unknown): { classification: Failur
     case "network_blocked": return { classification: "network_failure", secondaryCode: code };
     case "region_blocked": return { classification: "region_blocked", secondaryCode: code };
     case "provider_transient": return { classification: "provider_transient", secondaryCode: code };
+    // A response this transport cannot read is an upstream protocol failure. It is deterministic
+    // rather than transient, and attributing it to the harness would blame the runner for what
+    // the peer sent.
+    case "unreadable_response": return { classification: "protocol_failure", secondaryCode: code };
     case "connect_timeout": case "first_byte_timeout": case "total_timeout":
       return { classification: "timeout", secondaryCode: code };
     case "inactivity_timeout":

package/src/lab/live/types.ts

@@ -89,6 +89,11 @@ export type TransportErrorCode =
   | "output_byte_limit"
   | "output_token_limit"
   | "tool_call_limit"
+  // The peer answered, and the answer cannot be read: a content coding this transport cannot
+  // undo, or coded bytes that did not decode. Neither is a timeout, a budget, or a fault of
+  // the harness, so none of those codes describes it and every one of them would send an
+  // operator looking in the wrong place.
+  | "unreadable_response"
   | "artifact_byte_limit"
   | "memory_limit"
   | "child_process_limit"

package/src/lab/subject/behavior-fingerprint.ts

@@ -9,7 +9,7 @@ const CLOSED_KEYS = new Set([
   "limits.contextWindow", "limits.maxInputTokens", "limits.maxOutputTokens",
   "modalities.input",
   "sampling.omitTemperature", "sampling.omitTopP", "sampling.omitPenalties",
-  "reasoning.supported", "reasoning.efforts", "reasoning.defaultEffort", "reasoning.effortMap", "reasoning.wireFormat",
+  "reasoning.supported", "reasoning.efforts", "reasoning.effortsAuthoritative", "reasoning.defaultEffort", "reasoning.effortMap", "reasoning.wireFormat",
   "reasoning.summaryMode", "reasoning.replayMode", "reasoning.splitMode", "reasoning.toggleMode", "reasoning.budgetMode",
   "tools.choiceRestrictions", "tools.parallel", "tools.hostedPreference", "tools.customFreeform", "tools.builtinNameEscaping",
   "cache.forwarding", "cache.retention", "anthropic.eofPolicy", "openai-chat.eofPolicy",

package/src/lib/admin-secrets.ts

@@ -1,4 +1,4 @@
-import { timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
@@ -27,6 +27,14 @@ export function configuredAdminToken(configDir = getConfigDir(), env: NodeJS.Pro
 
 export const ADMIN_TOKEN_PREFIX = "ocx_admin_";
 
+/**
+ * Derive the bearer used by the OpenCode launcher for its one management read.
+ * A listener that captures this value cannot recover or replay the administrator token.
+ */
+export function opencodeCatalogToken(adminToken: string): string {
+  return `ocx_catalog_${createHmac("sha256", adminToken).update("opencode:/api/models:v1").digest("base64url")}`;
+}
+
 function secretTextEquals(left: string, right: string): boolean {
   const a = Buffer.from(left);
   const b = Buffer.from(right);

package/src/lib/debug-log-buffer.ts

@@ -9,7 +9,12 @@ export interface DebugLogEntry {
 
 const MAX_LINES = 2_000;
 const MAX_DEBUG_SUBSCRIBERS = 64;
-const MAX_DEBUG_LINE_BYTES = 16 * 1024;
+/**
+ * Per-line retention cap. Exported because a producer of a long structured line has to budget
+ * BELOW it: this buffer truncates at a byte boundary, so a JSON line cut here stops being
+ * parseable while its retained prefix still reads as complete.
+ */
+export const MAX_DEBUG_LINE_BYTES = 16 * 1024;
 const buffer: DebugLogEntry[] = [];
 interface DebugSubscriberRegistration { lease: AdmissionLease }
 const listeners = new Map<(entry: DebugLogEntry) => void, DebugSubscriberRegistration>();

package/src/lib/debug.ts

@@ -29,3 +29,26 @@ export function debugProviderDiagnostic(adapter: string, event: string, details:
     /* diagnostics must never affect request handling */
   }
 }
+
+/**
+ * The same diagnostic for details that are expensive to compute or read live request state.
+ *
+ * The eager form takes an already-built object, so the build runs in ARGUMENT position: outside
+ * this module's gate, and outside its try/catch. For a projection that walks a whole request
+ * that is wrong twice over — it pays the walk while debug is off, and a throw inside it reaches
+ * the caller, which for an adapter means a built request becomes a rejected one and a send that
+ * would have happened does not. Pass the builder instead: it runs only when debug is on, and a
+ * throw inside it is swallowed exactly like a throw in the emit.
+ */
+export function debugProviderDiagnosticLazy(
+  adapter: string,
+  event: string,
+  details: () => Record<string, unknown>,
+): void {
+  if (!isDebugEnabled()) return;
+  try {
+    emitDebugLine(`[ocx:${adapter}:${event}] ${JSON.stringify(redactSecrets(details()))}`);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}

package/src/lib/errors.ts

@@ -74,6 +74,75 @@ export function isCyberPolicyMessage(text: string): boolean {
   return false;
 }
 
+/**
+ * Refusal codes Codex ends a turn on.
+ *
+ * Its Responses parser classifies a `response.failed` terminal by `error.code`
+ * alone (codex-rs/codex-api/src/sse/responses.rs:423-462). These four become a
+ * fatal `ApiError` the client reports instead of reconnecting. A code outside
+ * this set is never read as a refusal: `server_is_overloaded` and `slow_down`
+ * take the overload arm, `rate_limit_exceeded` takes the rate-limit arm, and
+ * everything else falls through to `ApiError::Retryable` and is reconnected up
+ * to `stream_max_retries`.
+ *
+ * Deliberately scoped to content refusals. `insufficient_quota` and
+ * `context_length_exceeded` are terminal for Codex too, but they are separate
+ * failure families this proxy already classifies through its own quota and
+ * context paths, and pulling them in here would change their retry behavior
+ * with no evidence asking for it.
+ */
+const TERMINAL_REFUSAL_CODES = new Set<string>([
+  CYBER_POLICY_ERROR_CODE,
+  "misalignment_policy_violation",
+  "invalid_prompt",
+  "bio_policy",
+]);
+
+/** True when an upstream error code is a refusal the client must not retry. */
+export function isTerminalRefusalCode(code: string | null | undefined): boolean {
+  return typeof code === "string" && TERMINAL_REFUSAL_CODES.has(code);
+}
+
+/** Stand-in copy for a refusal the upstream sent without a message of its own. */
+export const TERMINAL_REFUSAL_FALLBACK_MESSAGE = "The upstream refused this request.";
+
+/** Readable copy for a refusal code, used when the upstream carried no message. */
+export function terminalRefusalFallbackMessage(code: string): string {
+  return code === CYBER_POLICY_ERROR_CODE
+    ? CYBER_POLICY_FALLBACK_MESSAGE
+    : TERMINAL_REFUSAL_FALLBACK_MESSAGE;
+}
+
+/**
+ * Name the refusal code behind upstream safety copy when the structured code
+ * was not carried on the wire.
+ *
+ * Same discipline as {@link isCyberPolicyMessage}: whole distinctive phrases
+ * only. A loose match here is the mirror-image defect — it would end a turn
+ * that a genuine transient failure would have retried successfully — so a
+ * message that merely mentions safety or blocking does not qualify. Callers
+ * must consult this only when the upstream carried no structured code at all,
+ * so that a transport failure quoting a refusal in its diagnostic text cannot
+ * be promoted past the verdict the upstream actually gave.
+ *
+ * Copy provenance: "limited access to this content for safety reasons" is the
+ * prefix Codex itself matches (tui/src/chatwidget/turn_runtime.rs:8-15) and
+ * pairs with `invalid_prompt` in its parser fixture (sse/responses.rs:1358-1366),
+ * which also pairs "flagged for possible biological risk" with `bio_policy`.
+ * "blocked by our safety systems" is the copy reported in #5176; pairing it
+ * with `invalid_prompt` is an inference from the two verified pairings above,
+ * not something the upstream source states.
+ */
+export function safetyRefusalCodeFromMessage(text: string): string | undefined {
+  const lower = String(text ?? "").toLowerCase();
+  if (lower.includes("flagged for possible biological risk")) return "bio_policy";
+  if (
+    lower.includes("blocked by our safety systems")
+    || lower.includes("limited access to this content for safety reasons")
+  ) return "invalid_prompt";
+  return undefined;
+}
+
 function isSubscriptionGateMessage(text: string): boolean {
   return (
     text.includes("requires a subscription") ||
@@ -187,6 +256,16 @@ export function isClientClosedMessage(text: string): boolean {
   );
 }
 
+/**
+ * Ambiguous-reset refusal wording owned by this proxy (src/lib/upstream-retry.ts):
+ * the upstream connection closed before any response arrived, so the request may
+ * already have been processed and automatic replay was stopped. Matched narrowly
+ * so a provider-sent message is never relabeled by it.
+ */
+export function isUpstreamResetReplayRefusedMessage(text: string): boolean {
+  return text.toLowerCase().includes("connection closed before a response was received");
+}
+
 export function classifyError(status: number, type: string, message: string): OcxErrorPayload {
   const text = message.toLowerCase();
   if (type === "previous_response_not_found") {

package/src/lib/http-response-semantics.ts

@@ -0,0 +1,57 @@
+/**
+ * Response rules both raw outbound transports have to apply themselves.
+ *
+ * `fetch` applies them below the Response constructor. `src/lib/pinned-http.ts` and
+ * `src/lib/socks5-fetch.ts` assemble a Response from a socket instead, so each one answers the
+ * same questions on its own — and a rule written twice is a rule that drifts. It already had:
+ * the SOCKS helper excluded 204 and the pinned helper excluded nothing, so the same no-content
+ * upstream answer behaved differently depending on which transport carried the request.
+ */
+
+/**
+ * Statuses the Fetch specification defines as null-body.
+ *
+ * `new Response(body, { status })` throws a TypeError for a non-null body on any of these, so a
+ * transport that attaches its stream unconditionally converts a valid no-content answer into a
+ * construction failure. There are no body bytes to wait for either, so a transport that streams
+ * one of these holds the caller until the peer closes a connection it is entitled to keep alive.
+ *
+ * 101 and 103 are null-body statuses too, but neither is a final Response status these helpers
+ * support. 103 and every other informational head is consumed while looking for the final one,
+ * and 101 hands the connection to a protocol neither helper speaks, which is outside what they
+ * construct a Response for at all. The three below are the statuses these transports actually
+ * have to answer for.
+ *
+ * https://fetch.spec.whatwg.org/#null-body-status
+ */
+export function isNullBodyStatus(status: number): boolean {
+  return status === 204 || status === 205 || status === 304;
+}
+
+/** What a transport must do with the coding a response declares. */
+export type ContentCoding =
+  | { kind: "identity" }
+  | { kind: "decodable"; format: "gzip" | "deflate" }
+  | { kind: "unsupported"; coding: string };
+
+/**
+ * Classify the `content-encoding` a raw transport received.
+ *
+ * `fetch` undoes a content-coding below the Response constructor. A transport that assembles a
+ * body from a socket hands the coded bytes to whatever reads them instead: `response.json()`
+ * throws a SyntaxError on the gzip magic number and an SSE reader sees noise rather than frames.
+ * Only `gzip` and `deflate` can be undone with `DecompressionStream`, so anything else is
+ * reported as unsupported and each transport refuses it under its own error type rather than
+ * surfacing bytes no caller can parse.
+ *
+ * This reads the coding the response actually carries and nothing else. A caller whose
+ * `accept-encoding` names a coding this code cannot undo is not the problem; what the peer
+ * chose to send is.
+ */
+export function classifyContentCoding(headers: Headers): ContentCoding {
+  const coding = (headers.get("content-encoding") ?? "").trim().toLowerCase();
+  if (coding === "" || coding === "identity") return { kind: "identity" };
+  if (coding === "gzip" || coding === "x-gzip") return { kind: "decodable", format: "gzip" };
+  if (coding === "deflate") return { kind: "decodable", format: "deflate" };
+  return { kind: "unsupported", coding };
+}

package/src/lib/lab-live-pinned-sender.ts

@@ -1,10 +1,32 @@
-import { PinnedHttpError, pinnedHttpGet, pinnedHttpPost } from "./pinned-http";
+import { PinnedHttpError, pinnedHttpGet, pinnedHttpPost, type PinnedHttpErrorCode } from "./pinned-http";
 import { TransportError } from "../lab/live/transport";
-import type { LabCredentialLeaseV1, LabPinnedSender } from "../lab/live/types";
+import type { LabCredentialLeaseV1, LabPinnedSender, TransportErrorCode } from "../lab/live/types";
 
 /** Only response metadata required by current live assertions crosses into Lab. */
 const LAB_RESPONSE_HEADER_ALLOWLIST = ["content-type"] as const;
 
+/**
+ * Every pinned-transport failure code, mapped to the Lab transport taxonomy or to nothing.
+ *
+ * A switch over the codes that existed when it was written silently let later ones fall through
+ * to a raw rethrow. That is not the same as leaving them unclassified: Lab's executor turns an
+ * unrecognized error into `harness_failure` / `execution_error`, so a response the peer coded
+ * in a format this transport cannot undo was reported as a fault of the runner. Both unreadable
+ * answers therefore carry `unreadable_response`, which Lab classifies as a protocol failure.
+ * A total map keeps a future code from acquiring that misattribution by default.
+ */
+const LAB_TRANSPORT_FAILURES = {
+  connect_timeout: { code: "connect_timeout", message: "pinned provider connection timed out" },
+  first_byte_timeout: { code: "first_byte_timeout", message: "pinned provider first byte timed out" },
+  inactivity_timeout: { code: "inactivity_timeout", message: "pinned provider response stalled" },
+  output_byte_limit: { code: "output_byte_limit", message: "pinned provider response exceeded byte budget" },
+  content_decode_failed: { code: "unreadable_response", message: "pinned provider response did not decode" },
+  unsupported_content_encoding: {
+    code: "unreadable_response",
+    message: "pinned provider used a content-encoding this transport cannot decode",
+  },
+} satisfies Record<PinnedHttpErrorCode, { code: TransportErrorCode; message: string }>;
+
 /**
  * Trusted credential/transport owner. Secret headers exist only in this non-Lab module and are
  * consumed directly by the pinned HTTP primitive; they are never returned to Lab code.
@@ -33,16 +55,8 @@ export function createLabAuthorizedPinnedSender(
       body = await response.text();
     } catch (error) {
       if (error instanceof PinnedHttpError) {
-        switch (error.code) {
-          case "connect_timeout":
-            throw new TransportError("connect_timeout", "pinned provider connection timed out");
-          case "first_byte_timeout":
-            throw new TransportError("first_byte_timeout", "pinned provider first byte timed out");
-          case "inactivity_timeout":
-            throw new TransportError("inactivity_timeout", "pinned provider response stalled");
-          case "output_byte_limit":
-            throw new TransportError("output_byte_limit", "pinned provider response exceeded byte budget");
-        }
+        const mapped = LAB_TRANSPORT_FAILURES[error.code];
+        throw new TransportError(mapped.code, mapped.message);
       }
       throw error;
     }