cartethyia 2.7.7 → 2.7.9

package/src/providers/operations/cooldown-rules.ts

@@ -0,0 +1,61 @@
+/**
+ * Static in-code registry of provider × category × tier cooldown rules (D19).
+ *
+ * The registry ships empty by default: before a rule is filled in, behavior is
+ * byte-identical to the old hardcoded constants. Rules are keyed by
+ * `(providerId, category, tier)` and, when present, replace the provider's old
+ * cooldown constant for that combination — they sit between the provider-stated
+ * window (which always wins, D18) and the old constant/env fallback.
+ *
+ * The initial content is the example from the approved proposal (part 03):
+ * Trae's daily-quota verdict (`model_unreachable`, upstream 4008) cools a free
+ * account for a full day and a paid/pro account for 15 minutes (D17 — `paid`
+ * never gets `0`, which would hammer the upstream on a wrong verdict).
+ */
+import type { AccountErrorCategory } from "./account-error-classification";
+import type { AccountTier } from "./account-tier";
+
+export type CooldownRuleKey = {
+  readonly providerId: string;
+  readonly category: AccountErrorCategory;
+  readonly tier: AccountTier;
+};
+
+type TierRules = Partial<Record<NonNullable<AccountTier>, number>>;
+type CategoryRules = Partial<Record<AccountErrorCategory, TierRules>>;
+type ProviderRules = Record<string, CategoryRules>;
+
+const DAY = 24 * 60 * 60 * 1000;
+const MINUTE = 60 * 1000;
+
+const COOLDOWN_RULES: ProviderRules = {
+  trae: {
+    model_unreachable: {
+      free: DAY,
+      paid: 15 * MINUTE,
+      pro: 15 * MINUTE,
+    },
+  },
+  // Trae CN is the same upstream product under a second realm id — the
+  // classifier already treats the two identically (trae-region-unavailable,
+  // trae-quota-exhausted), so the rules mirror.
+  traecn: {
+    model_unreachable: {
+      free: DAY,
+      paid: 15 * MINUTE,
+      pro: 15 * MINUTE,
+    },
+  },
+};
+
+/**
+ * Resolves a cooldown rule for `(providerId, category, tier)`.
+ *
+ * Returns `undefined` when no rule exists — for an unknown provider, an
+ * unstored category, or an unknown tier — which is the signal to keep the old
+ * constant/fallback behavior.
+ */
+export function resolveCooldownRule(key: CooldownRuleKey): number | undefined {
+  if (key.tier === null || key.tier === undefined) return undefined;
+  return COOLDOWN_RULES[key.providerId.toLowerCase()]?.[key.category]?.[key.tier];
+}

package/src/providers/operations/provider-catalog-seeder.ts

@@ -60,6 +60,9 @@ export async function seedBundledModels(
           // states the tier, so the flag is carried rather than derived.
           freeTier: definition.freeTier ?? null,
           dialect: definition.dialect ?? null,
+          // Display-only: a static catalog that declares no warnings clears any
+          // stale value on the next boot rather than leaving an old banner.
+          warningMetadata: definition.warnings ?? null,
           source: "builtin",
           sourceUpdatedAt: now,
           enabled: true,
@@ -90,6 +93,7 @@ export async function seedBundledModels(
       proOnly: sql`excluded.pro_only`,
       freeTier: sql`excluded.free_tier`,
       dialect: sql`excluded.dialect`,
+      warningMetadata: sql`excluded.warning_metadata`,
       source: sql`'builtin'`,
       sourceUpdatedAt: sql`excluded.source_updated_at`,
     },

package/src/providers/provider-contracts.ts

@@ -187,6 +187,13 @@ export interface ProviderDispatchContext {
   readonly outbound_attachment_fetch?: ValidatedOutboundFetch | undefined;
   /** Validated bidirectional HTTP/2 egress bound to the same selected network pool. */
   readonly outbound_http2?: ValidatedOutboundHttp2Bidi | undefined;
+  /**
+   * Capture sink for one attempt's provider exchange, filled by HTTP fetch
+   * wrapping. Adapters whose real upstream transport is not a `fetch`
+   * (Qoder's gRPC) write it directly so Request Detail shows the actual
+   * conversation call rather than an auth exchange or an empty panel.
+   */
+  readonly provider_capture?: ProviderCaptureExchange | undefined;
   /**
    * Route-selected fallback User-Agent from Routing Strategy; set when the
    * operator configured one (bundled API-key providers default to the Claude
@@ -261,6 +268,20 @@ export function applyRouteUserAgent(
 }
 
 /** ProviderDispatchTarget identity already resolved by routing before credential leasing. */
+/**
+ * Capture sink for one attempt's provider exchange.
+ *
+ * HTTP transports fill this automatically by wrapping `outbound_fetch` (see
+ * `captureProviderExchange` in `transport/dispatch/attempt-finalize.ts`).
+ * Adapters whose real upstream call is not a fetch — Qoder's gRPC surface —
+ * write it directly so Request Detail shows the actual conversation call
+ * instead of an auth exchange or nothing.
+ */
+export interface ProviderCaptureExchange {
+  request: unknown;
+  response: Promise<unknown>;
+}
+
 export interface ProviderDispatchTarget {
   readonly provider_id: ProviderId;
   readonly model_id: string;
@@ -287,6 +308,14 @@ export interface ProviderAdapter {
     candidate: ProviderDispatchTarget,
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent>;
+  /**
+   * Optional provider-mandated system prompt, returned for probes and any
+   * caller that needs the upstream's required identity prompt. A provider
+   * whose wire refuses requests without a specific system prompt (Perch's
+   * Saffron fingerprint) declares it here so the probe path can carry it —
+   * the probe builder otherwise sends only the user message.
+   */
+  systemPrompt?(): string | undefined;
   /**
    * Optional native-protocol capability for the public `POST /v1/systemone`
    * route (the dispatch leg of the System One service, alongside the probing

package/src/providers/provider-metadata.ts

@@ -32,6 +32,14 @@ export interface CompatibilityProfile {
    * bundled specs declare it on `ApiKeyProviderSpec.gatewayUserAgent`.
    */
   readonly gateway_user_agent?: boolean;
+  /**
+   * Which service surfaces this custom provider may serve. Absent means every
+   * kind is enabled (the historical default). The operator narrows this by
+   * checking only the capabilities their upstream actually answers — agentic
+   * (LLM) is always on when the list is present, and a kind the upstream
+   * cannot serve stays out of the provider's tab set.
+   */
+  readonly service_kinds?: readonly ServiceKind[];
 }
 
 /** Identity and routing defaults for every builtin provider. */
@@ -144,6 +152,20 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     credentialUrl: "https://cursor.com",
     credentialHint: "Sign in with Cursor or import a Cursor API key.",
   },
+  {
+    id: "devin",
+    displayName: "Devin",
+    baseUrl: "https://server.codeium.com",
+    wireFamilyDefault: "chat",
+    requiresAccount: true,
+    bespokeWire: true,
+    hasAdapterUserAgent: true,
+    // Devin's upstream is a Connect-RPC protobuf service with its own framing;
+    // an egress proxy in front of it breaks the stream shape. Direct only.
+    defaultSkipProxy: true,
+    credentialUrl: "https://devin.ai",
+    credentialHint: "Sign in with Devin, Windsurf Enterprise, or import a Devin session token / Windsurf seat key.",
+  },
   { id: "kimi", displayName: "Kimi Code", baseUrl: "https://api.kimi.com/coding", credentialUrl: "https://platform.moonshot.ai/console/api-keys" },
   { id: "opencode", displayName: "OpenCode Free", baseUrl: "https://opencode.ai", requiresAccount: false, ipScopedRateLimit: true, hasAdapterUserAgent: true },
   { id: "opencode-zen", displayName: "OpenCode Zen", baseUrl: "https://opencode.ai", hasAdapterUserAgent: true, credentialUrl: "https://opencode.ai/auth" },
@@ -344,6 +366,7 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     // User-Agent. Letting the operator overwrite it would let them break the
     // provider, so the console locks the control.
     hasAdapterUserAgent: true,
+    credentialHint: "Paste a Nous Portal API key (portal.nousresearch.com → API keys), or sign in with the Nous Portal device code (OAuth) for the subscription route.",
   },
   { id: "bai", displayName: "B.AI", baseUrl: "https://api.b.ai/v1", credentialUrl: "https://b.ai" },
   {
@@ -367,8 +390,6 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
   { id: "cline", displayName: "Cline", baseUrl: "https://api.cline.bot/api/v1", hasAdapterUserAgent: true, defaultSkipProxy: true, credentialUrl: "https://app.cline.bot" },
   { id: "cb", displayName: "CodeBuddy", baseUrl: "https://www.codebuddy.ai/v2", hasAdapterUserAgent: true, serviceKinds: ["llm", "imageGeneration", "videoGeneration"], credentialUrl: "https://www.codebuddy.ai", credentialHint: "Sign in with the same CodeBuddy account you use in the desktop app." },
   { id: "cbcn", displayName: "CodeBuddy CN", baseUrl: "https://copilot.tencent.com/v2", hasAdapterUserAgent: true, credentialUrl: "https://copilot.tencent.com", credentialHint: "Sign in with the same CodeBuddy China account you use in the desktop app." },
-  { id: "workbuddy", displayName: "WorkBuddy", baseUrl: "https://www.workbuddy.ai", hasAdapterUserAgent: true, serviceKinds: ["llm", "imageGeneration", "videoGeneration"], credentialUrl: "https://www.workbuddy.ai", credentialHint: "Sign in with the same WorkBuddy account you use in the desktop app." },
-  { id: "workbuddycn", displayName: "WorkBuddy CN", baseUrl: "https://www.workbuddy.cn", hasAdapterUserAgent: true, serviceKinds: ["llm", "imageGeneration", "videoGeneration"], credentialUrl: "https://www.workbuddy.cn", credentialHint: "Sign in with the same WorkBuddy China account you use in the desktop app." },
   {
     // Kilo Code resells the OpenRouter catalog. The base URL carries the API's
     // path prefix (`/api/openrouter`) and every model row carries only the wire
@@ -432,6 +453,22 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     credentialUrl: "https://www.trae.com.cn/",
     credentialHint: "Paste a Trae CN account export (accessToken + refreshToken) or the raw access token from a Trae China account.",
   },
+  {
+    id: "freepi",
+    displayName: "Free-pi",
+    baseUrl: "https://api.freepi.ai/v1/chat/completions",
+    defaultSkipProxy: true,
+    credentialUrl: "https://freepi.ai",
+    credentialHint: "Sign in with a GitHub device code (free-pi login), or paste a free-pi JWT issued by the backend.",
+  },
+  {
+    id: "perch",
+    displayName: "Perch",
+    baseUrl: "https://app.perchai.app",
+    defaultSkipProxy: true,
+    credentialUrl: "https://chat.perchai.app",
+    credentialHint: "Sign in with Google or GitHub (Perch account). Starter includes Roost Standard and Standard 1M.",
+  },
   { id: "ollamacloud", displayName: "Ollama Cloud", baseUrl: "https://ollama.com/v1", credentialUrl: "https://ollama.com/settings/keys" },
   { id: "gemini", displayName: "Google Gemini", baseUrl: "https://generativelanguage.googleapis.com/v1beta", serviceKinds: ["llm", "websearch", "imageGeneration"], credentialUrl: "https://aistudio.google.com/app/apikey" },
   { id: "xiaomipg", displayName: "Xiaomi MiMo (PAYG)", baseUrl: "https://api.xiaomimimo.com/v1", credentialUrl: "https://platform.xiaomimimo.com" },
@@ -472,7 +509,7 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
 export type BundledProviderId = (typeof RAW_BUNDLED_PROVIDER_METADATA)[number]["id"];
 
 /**
- * The Buddy family: CodeBuddy, its China tenant, and WorkBuddy.
+ * The Buddy family: CodeBuddy and its China tenant.
  *
  * They share one billing and credit system, so several layers need to ask "is
  * this a Buddy provider" — the health recorder, the request preparer, and the
@@ -480,7 +517,7 @@ export type BundledProviderId = (typeof RAW_BUNDLED_PROVIDER_METADATA)[number]["
  * get added in one place and silently missed in the others. Declared here
  * beside the identities it names; the layers keep their own *policies*.
  */
-export const BUDDY_PROVIDER_IDS: ReadonlySet<string> = new Set(["cb", "cbcn", "workbuddy", "workbuddycn"]);
+export const BUDDY_PROVIDER_IDS: ReadonlySet<string> = new Set(["cb", "cbcn"]);
 
 /**
  * Per-provider JWT verification defaults for issued OAuth access tokens. An
@@ -650,6 +687,24 @@ export function providerServiceKinds(providerId: string): readonly ServiceKind[]
   return SERVICE_KINDS;
 }
 
+/**
+ * Resolves the service kinds for a custom (BYOK) provider row.
+ *
+ * The operator may narrow the surface set via `compatibilityProfile.service_kinds`
+ * (the Advanced Capabilities checkboxes in the Add Custom Provider modal). Absent,
+ * every kind is allowed — the historical default. A present list never drops
+ * `llm` (agentic is the floor of a custom provider).
+ */
+export function customProviderServiceKinds(
+  compatibilityProfile: CompatibilityProfile | null | undefined,
+): readonly ServiceKind[] {
+  const kinds = compatibilityProfile?.service_kinds;
+  if (kinds === undefined || kinds.length === 0) return SERVICE_KINDS;
+  const set = new Set<ServiceKind>(SERVICE_KINDS.filter((kind) => kinds.includes(kind)));
+  set.add("llm");
+  return SERVICE_KINDS.filter((kind) => set.has(kind));
+}
+
 
 /** Canonical builtin base URL used by adapters, discovery, and quota clients. */
 export function providerBaseUrl(providerId: string): string {

package/src/providers/provider-model-definition.ts

@@ -33,6 +33,37 @@ export const FREE_TIER_COST: ModelCostDefinition = {
   pricing_model: "pay-per-use",
 };
 
+/**
+ * Severity of one display-only model warning. `warn` is the default so a
+ * catalog that omits severity does not silently render a critical banner.
+ */
+export type ModelWarningSeverity = "info" | "warn" | "critical";
+
+/** Severity values accepted on the wire, as a runtime tuple. */
+export const MODEL_WARNING_SEVERITIES = ["info", "warn", "critical"] as const;
+
+/** Longest accepted warning `kind` / `message`, in UTF-16 code units. */
+export const MODEL_WARNING_KIND_MAX_LENGTH = 64;
+export const MODEL_WARNING_MESSAGE_MAX_LENGTH = 500;
+
+/**
+ * One display-only warning attached to a model row. `kind` is an open string
+ * with three defined values (`fallback_model`, `cache_reliability`,
+ * `model_refusal`) so a new category needs no migration. Persisted as
+ * `{ warnings: ModelWarning[] }` in `models.warning_metadata`; never read by
+ * routing.
+ */
+export interface ModelWarning {
+  /** Stable machine-readable category; open vocabulary. */
+  readonly kind: string;
+  /** Operator-facing text. Provider-level claims use "may". */
+  readonly message: string;
+  /** Defaults to `warn` when absent. */
+  readonly severity?: ModelWarningSeverity;
+  /** ISO timestamp of the last edit, when known. */
+  readonly updatedAt?: string;
+}
+
 /** Canonical static metadata for one provider model. */
 export interface ModelDefinition {
   readonly modelId: string;
@@ -118,6 +149,8 @@ export interface ModelDefinition {
    * turns a gap in our catalog into a claim about someone else's model.
    */
   readonly limitsEstimated?: boolean;
+  /** Display-only warnings carried from a static catalog into the seeded row. */
+  readonly warnings?: readonly ModelWarning[];
 }
 
 /**
@@ -205,6 +238,8 @@ export interface ModelHelperRow {
   readonly proOnly?: boolean;
   /** Explicit wire dialect override for this row. See `ModelDefinition.dialect`. */
   readonly dialect?: DialectId;
+  /** Display-only warnings to carry onto the built row. */
+  readonly warnings?: readonly ModelWarning[];
 }
 
 function defaultEndpoint(wireFamily: ModelDefinition["wireFamily"]): string {
@@ -309,6 +344,7 @@ export function defineModel(row: ModelHelperRow): ModelDefinition {
     ...(row.proOnly === undefined ? {} : { proOnly: row.proOnly }),
     ...(row.dialect === undefined ? {} : { dialect: row.dialect }),
     ...(limitsEstimated ? { limitsEstimated: true } : {}),
+    ...(row.warnings === undefined ? {} : { warnings: row.warnings }),
   };
 }
 

package/src/providers/quota/refresh.ts

@@ -11,6 +11,7 @@ import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { providerAccounts } from "../../persistence/schema";
 import type { RedisClient } from "../../persistence/redis";
 import { log } from "../../observability/logger";
+import { pushStructuredConsoleLog } from "../../observability/log-ring";
 import { fetchProviderQuota } from "./quota-support";
 import { type FetchLike, type ProviderQuotaResult } from "./quota-contracts";
 import type { ProviderId } from "../provider-contracts";
@@ -261,6 +262,12 @@ const TARGET_COLUMNS = {
  * disabled account is not necessarily revoked — it may have been parked for a
  * reason unrelated to its credential — and skipping it would let a credential
  * die silently while the row still reads healthy.
+ *
+ * Invariant (area 04, D21): this sweep **never flips status**. The refresh it
+ * kicks off rewrites only credential/expiry columns; `recordAccountCheck` is
+ * active-only, so `disabled` rows are identical after the pass to before. The
+ * `origin: "sweep:quota"` tag on the token-refresh log lines (D26) is what
+ * lets an operator verify that in the Console Log.
  */
 export async function listQuotaRefreshTargets(
   db: CartethyiaDatabase,
@@ -343,6 +350,20 @@ async function runQuotaRefresh(
   let resolveError: string | undefined;
   try {
     credential = await deps.resolveCredential(target.providerId as ProviderId, target.accountId);
+    // D26: every OAuth credential this sweep resolves may have been refreshed
+    // inside the refresh-aware resolver. Label that refresh with its origin so
+    // the Console Log can prove the sweep touches disabled accounts without
+    // ever flipping their status. The refresh service itself also logs the
+    // actual token refresh under the `sweep` origin family; this line names
+    // the sweep here, at the source of the trigger.
+    if (credential !== "" && target.credentialKind === "oauth") {
+      pushStructuredConsoleLog("debug", "Quota sweep resolved OAuth credential; token may have been refreshed", {
+        event: "token_refresh",
+        accountId: target.accountId,
+        providerId: target.providerId,
+        details: { origin: "sweep:quota" },
+      });
+    }
   } catch (error) {
     resolveError = error instanceof Error ? error.message : "Failed to resolve credential";
   }

package/src/security/abuse.ts

@@ -113,6 +113,15 @@ export interface IpAbuseStore {
    * bounded `admission_unavailable` with zero dispatches.
    */
   checkAndRecord(attempt: IpAbuseAttempt): Promise<IpAbuseOutcome>;
+  /**
+   * Manually bans an identity for `durationMs` (0/negative = permanent).
+   * Throws when the store is unreachable.
+   */
+  ban(identity: string, durationMs: number): Promise<void>;
+  /** Lifts a manual (or any) ban on an identity. No-op when not banned. */
+  unban(identity: string): Promise<void>;
+  /** Lists currently active bans with their expiry (`null` = permanent). */
+  listBans(): Promise<readonly { identity: string; bannedUntil: number | null }[]>;
 }
 
 interface IpAbuseProtectionServiceOptions {
@@ -293,6 +302,34 @@ export class InMemoryIpAbuseStore implements IpAbuseStore {
     return true;
   }
 
+  async ban(identity: string, durationMs: number): Promise<void> {
+    this.assertAvailable();
+    this.evictOldest(this.bans);
+    this.bans.set(identity, durationMs > 0 ? this.clock() + durationMs : Number.POSITIVE_INFINITY);
+  }
+
+  async unban(identity: string): Promise<void> {
+    this.assertAvailable();
+    this.bans.delete(identity);
+  }
+
+  async listBans(): Promise<readonly { identity: string; bannedUntil: number | null }[]> {
+    this.assertAvailable();
+    const now = this.clock();
+    const out: { identity: string; bannedUntil: number | null }[] = [];
+    for (const [identity, until] of this.bans) {
+      if (until <= now) {
+        this.bans.delete(identity);
+        continue;
+      }
+      out.push({
+        identity,
+        bannedUntil: Number.isFinite(until) ? until : null,
+      });
+    }
+    return out;
+  }
+
   async checkAndRecord(attempt: IpAbuseAttempt): Promise<IpAbuseOutcome> {
     this.assertAvailable();
     const { identity, route, now, limit, banThreshold, banDurationMs } = attempt;
@@ -582,5 +619,39 @@ export class RedisIpAbuseStore implements IpAbuseStore {
     );
     return decodeAbuseOutcome(raw);
   }
+
+  async ban(identity: string, durationMs: number): Promise<void> {
+    const marker = this.banMarkerKey(identity);
+    const now = Date.now();
+    if (durationMs > 0) {
+      await this.redis.set(marker, String(now + durationMs), "PX", durationMs);
+    } else {
+      // Permanent: no TTL; a large sentinel far in the future.
+      await this.redis.set(marker, String(Number.MAX_SAFE_INTEGER));
+    }
+  }
+
+  async unban(identity: string): Promise<void> {
+    await this.redis.del(this.banMarkerKey(identity));
+  }
+
+  async listBans(): Promise<readonly { identity: string; bannedUntil: number | null }[]> {
+    const keys = await this.redis.keys("cartethyia:ip:ban:*");
+    const now = Date.now();
+    const out: { identity: string; bannedUntil: number | null }[] = [];
+    for (const key of keys) {
+      const value = await this.redis.get(key);
+      const until = Number(value ?? 0);
+      if (!Number.isFinite(until) || until <= now) {
+        await this.redis.del(key);
+        continue;
+      }
+      out.push({
+        identity: key.slice("cartethyia:ip:ban:".length),
+        bannedUntil: until >= Number.MAX_SAFE_INTEGER - 1 ? null : until,
+      });
+    }
+    return out;
+  }
 }
 

package/src/transport/dispatch/proxy-request.ts

@@ -263,6 +263,7 @@ export async function handleProviderProxyRequest(
         ...(conversationAffinity ? { conversationAffinity } : {}),
         ...(tenantSystemPromptText === undefined ? {} : { tenantSystemPrompt: tenantSystemPromptText }),
         ...(candidate.user_agent === undefined ? {} : { userAgent: candidate.user_agent }),
+        ...(providerCapture ? { providerCapture } : {}),
         ...(deps.networkBindingFactory
           ? {
               outboundFetch: captureProviderExchange(

package/src/transport/dispatch/streaming/stream.ts

@@ -249,6 +249,7 @@ export async function dispatchStreamingAttempt(input: StreamingDispatchInput): P
       : {}),
     ...(leaseOwnership === undefined ? {} : { leaseOwnership }),
     ...(continuationScope === undefined ? {} : { continuationScope }),
+    ...(providerCapture ? { providerCapture } : {}),
   });
   // `ProviderAdapter.dispatch` is declared to return a non-nullable
   // `AsyncIterable`, so an adapter that returned `undefined` would be a

package/src/transport/dispatch/upstream.ts

@@ -1,6 +1,6 @@
 import type { CanonicalEvent } from "../../protocol/canonical-model";
 import type { AttemptLeaseOwnership, ValidatedOutboundFetch, ValidatedOutboundHttp2Bidi } from "../../providers/provider-contracts";
-import type { ProviderContinuationScope } from "../../providers/provider-contracts";
+import type { ProviderCaptureExchange, ProviderContinuationScope } from "../../providers/provider-contracts";
 import { GATEWAY_SECURITY_HEADERS } from "../../security/outbound-headers";
 
 const FORWARDED_REQUEST_HEADERS = new Set([
@@ -42,6 +42,8 @@ export function buildUpstreamDispatchContext(input: {
   readonly requestId?: string;
   readonly userAgent?: string;
   readonly outboundFetch?: ValidatedOutboundFetch;
+  /** Capture sink for provider exchanges not visible to the HTTP fetch wrapper. */
+  readonly providerCapture?: ProviderCaptureExchange;
   /** Validated attachment egress that must not be wrapped by provider payload capture. */
   readonly outboundAttachmentFetch?: ValidatedOutboundFetch;
   /** Validated bidirectional HTTP/2 egress bound to the same selected pool. */
@@ -100,6 +102,7 @@ export function buildUpstreamDispatchContext(input: {
     ...(userAgent ? { user_agent: userAgent } : {}),
     ...(Object.keys(input.headers).length > 0 ? { request_headers: input.headers } : {}),
     ...(outboundFetch ? { outbound_fetch: outboundFetch } : {}),
+    ...(input.providerCapture ? { provider_capture: input.providerCapture } : {}),
     ...(input.outboundAttachmentFetch
       ? { outbound_attachment_fetch: input.outboundAttachmentFetch }
       : {}),

package/src/transport/failure-policy.ts

@@ -14,6 +14,7 @@ import { resolveAccountQuotaCooldownMs } from "../config/cooldowns";
  * runs a few KB; 4000 keeps the whole thing while bounding a hostile body.
  */
 const MAX_UPSTREAM_ERROR_BYTES = 4000;
+export { MAX_UPSTREAM_ERROR_BYTES };
 export {
   parseRetryAfter,
   parseRateLimitReset,
@@ -22,6 +23,32 @@ export {
   parseProviderResetDuration,
   parseAbsoluteResetTimestamp,
 } from "../protocol/upstream-parsing";
+/**
+ * Extracts only the human-readable text from an upstream error body —
+ * `message`/`msg`/`error` fields — deliberately skipping `code`/identifier
+ * values. Used by `upstreamMessageAsIs` to decide whether the upstream
+ * actually supplied a message: a symbolic code like `"permission_error"` is
+ * an identifier, not prose, so it must not count as passthrough text.
+ */
+export function extractUpstreamMessageText(body: unknown): string {
+  let raw = "";
+  if (typeof body === "string") raw = body;
+  else if (isRecord(body)) {
+    if (typeof body.error === "string" && body.error.trim()) raw = body.error;
+    else {
+      const envelope = isRecord(body.error) ? body.error : body;
+      const message = (envelope as Record<string, unknown>).message;
+      if (typeof message === "string" && message.trim()) raw = message;
+      else if (typeof body.msg === "string" && body.msg.trim()) raw = body.msg;
+      else if (typeof (envelope as Record<string, unknown>).msg === "string" && String((envelope as Record<string, unknown>).msg).trim())
+        raw = String((envelope as Record<string, unknown>).msg);
+      else if (typeof (envelope as Record<string, unknown>).error === "string" && String((envelope as Record<string, unknown>).error).trim())
+        raw = String((envelope as Record<string, unknown>).error);
+    }
+  }
+  return raw.replace(/[\r\n]+/g, " ").trim();
+}
+
 /** Extracts a bounded, newline-free provider message from any error envelope. */
 export function extractUpstreamMessage(body: unknown): string {
   let raw = "";
@@ -696,6 +723,25 @@ const AUTH_ERROR_IDENTIFIERS: ReadonlySet<string> = new Set([
   "insufficient_key_scope",
   "model_not_allowed_for_key",
 ]);
+
+/**
+ * Qoder job-token verdicts that are NOT credential evidence.
+ *
+ * A PAT (`pt-…`) is exchanged for a short-lived job token (`jt-…`). When the
+ * job token expires mid-flight the upstream answers `{"code":"105","message":
+ * "Login expired"}` (403). The PAT is still valid — re-exchanging it mints a
+ * fresh job token — so treating this as `auth_invalidated` parked a healthy
+ * account as "Re-login required". It stays `authentication_failed` (retryable;
+ * the next attempt re-runs the PAT exchange) but without `credentialEvidence`,
+ * so the account is never disabled or cooled on it.
+ */
+const QODER_JOB_TOKEN_EXPIRED: ReadonlySet<string> = new Set([
+  "105",
+  "login expired",
+  "login_expired",
+  "job token expired",
+  "jobtoken expired",
+]);
 const PLATFORM_ERROR_IDENTIFIERS: ReadonlySet<string> = new Set([
   "server_error",
   "internal_error",
@@ -809,6 +855,16 @@ export function classifyUpstreamError(
       origin: "upstream",
       rateLimitScope: "provider",
     };
+  // Qoder job-token expiry (`105` / "Login expired") is recoverable by
+  // re-exchanging the PAT — never credential evidence (see
+  // `QODER_JOB_TOKEN_EXPIRED`).
+  if (normalized !== undefined && QODER_JOB_TOKEN_EXPIRED.has(normalized)) {
+    return {
+      code: "authentication_failed",
+      status: status === 403 || status === 401 ? status : 403,
+      origin: "upstream",
+    };
+  }
   if (normalized !== undefined && AUTH_ERROR_IDENTIFIERS.has(normalized)) {
     let authStatus: number;
     if (status === 401 || status === 403) authStatus = status;
@@ -919,17 +975,15 @@ export async function mapUpstreamHttpError(response: Response, providerId: strin
     : isContextLengthFailure(parsedBody)
       ? { code: "context_length_exceeded" as const, status: 413, origin: "upstream" as const }
       : classifyUpstreamError(response.status, identifier);
-  const extracted = extractUpstreamMessage(parsedBody ?? text);
-  let message =
-    extracted.length > 0
-      ? extracted
-      : text.trim() || `Provider returned HTTP ${response.status}.`;
+  const upstreamText = upstreamMessageAsIs(parsedBody ?? text, "");
+  let message = upstreamText.message || `Provider returned HTTP ${response.status}.`;
   // A bare "Provider returned HTTP <5xx>" tells the operator nothing actionable;
   // platform-unavailable fallbacks get the same human sign-off every other
-  // gateway error carries. The raw upstream body stays in `details.raw` for
-  // diagnostics either way.
+  // gateway error carries — but only when the upstream supplied no text of its
+  // own. The raw upstream body stays in `details.raw` for diagnostics either way.
   if (
     classification.code === "platform_unavailable" &&
+    !upstreamText.hadUpstreamText &&
     message === `Provider returned HTTP ${response.status}.`
   ) {
     message = `The provider's service is temporarily unavailable (HTTP ${response.status}) (request {requestId}). Your request did not go through — wait a moment and try again. Hold tight ☁️`;
@@ -949,6 +1003,7 @@ export async function mapUpstreamHttpError(response: Response, providerId: strin
     ...(reportedProviderCode ? { providerCode: reportedProviderCode } : {}),
     ...(requestId ? { upstreamRequestId: requestId } : {}),
     raw: text.slice(0, MAX_UPSTREAM_ERROR_BYTES),
+    ...(upstreamText.hadUpstreamText ? { upstreamMessageAsIs: true } : {}),
     ...(retryAfterMs === null || retryAfterMs === undefined ? {} : { retryAfterMs }),
     ...(queuedWaitMs !== undefined
       ? { reason: "upstream-queued", cooldownMs: queuedWaitMs }
@@ -971,6 +1026,57 @@ export function extractHtmlTitle(html: string): string {
   return html.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().slice(0, 160);
 }
 
+/** The public bound on an upstream message surface. */
+export const MAX_UPSTREAM_MESSAGE_LENGTH = 500;
+
+/**
+ * Extracts the upstream's own text from an error body, "as-is".
+ *
+ * The upstream error passthrough contract: when a failure is unknown or
+ * unparseable, the client should see whatever the upstream actually said,
+ * not a generalized 502 sentence. Structured JSON envelopes already flow
+ * through `extractUpstreamMessage`; this helper extends the same idea to the
+ * shapes that used to lose the text entirely — HTML error pages (their
+ * `<title>` is often the only readable thing) and plain-text bodies.
+ *
+ * The returned message is bounded to 500 chars (D44) and newline-collapsed,
+ * matching `sanitizePublicDetail` per-string bound; `details.raw` keeps the
+ * full 4000. `hadUpstreamText` distinguishes "the upstream said something"
+ * from "we synthesized a fallback", so callers can keep their human sign-off
+ * only when there is genuinely no upstream text.
+ */
+export function upstreamMessageAsIs(
+  body: unknown,
+  fallback: string,
+): { message: string; hadUpstreamText: boolean } {
+  const raw = typeof body === "string" ? body : "";
+  const looksLikeHtml = raw.includes("<") && raw.includes(">");
+  // HTML error pages first: the structured extractor passes a string through
+  // verbatim, which would surface raw markup instead of the readable `<title>`
+  // (or a tag-stripped excerpt when the page has no title).
+  if (looksLikeHtml) {
+    const title = extractHtmlTitle(raw);
+    if (title.length > 0) {
+      return {
+        message: title.replace(/[\r\n]+/g, " ").trim().slice(0, MAX_UPSTREAM_MESSAGE_LENGTH),
+        hadUpstreamText: true,
+      };
+    }
+  }
+  const structured = extractUpstreamMessageText(body);
+  if (structured.length > 0) {
+    return { message: structured.slice(0, MAX_UPSTREAM_MESSAGE_LENGTH), hadUpstreamText: true };
+  }
+  const text = raw.trim();
+  if (text.length > 0) {
+    return {
+      message: text.replace(/[\r\n]+/g, " ").trim().slice(0, MAX_UPSTREAM_MESSAGE_LENGTH),
+      hadUpstreamText: true,
+    };
+  }
+  return { message: fallback, hadUpstreamText: false };
+}
+
 /** Throws a typed transport error when an upstream returns an HTML error page. */
 export async function throwIfHtmlResponse(response: Response): Promise<void> {
   const contentType = response.headers.get("content-type") ?? "";