@bitkyc08/opencodex 2.82.0 → 2.84.0

package/src/integrations/registry.ts

@@ -12,6 +12,7 @@ import { homedir } from "node:os";
 import { assertDroidSettingsUnambiguous } from "./droid-settings";
 import { readPath } from "./merge";
 import type { OwnershipRecord } from "./ownership";
+import type { IntegrationIO } from "./config-io";
 import { dirname, join } from "node:path";
 import {
   ClientPathError,
@@ -49,6 +50,8 @@ import {
   raycastConfigPath,
   zcodeConfigPath,
   zcodeHomeDir,
+  zcodeLegacyHomeDir,
+  ZcodeSettingsPathError,
   zcodeProviderStorePath,
   buildZcodeStoreContribution,
   zcodeStoreSchemaEstablished,
@@ -75,12 +78,21 @@ import {
  */
 export type IntegrationClientId = ExportClientId;
 
+export interface ResolvedIntegrationPaths {
+  configPath: string;
+  detectDir: string;
+  /** Snapshot of a mutable store resolution from the same bootstrap read. */
+  storePath?: string;
+  /** The default config path is only a recovery hint when the active root is unknown. */
+  pathError?: string;
+}
+
 export interface IntegrationClientSpec {
   id: IntegrationClientId;
   /** The client's config file, honoring that client's own environment override. */
-  configPath: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  configPath: (env?: NodeJS.ProcessEnv, home?: string, io?: Pick<IntegrationIO, "readText">) => string;
   /** Directory whose existence is the cheap "is it installed?" signal. */
-  detectDir: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  detectDir: (env?: NodeJS.ProcessEnv, home?: string, io?: Pick<IntegrationIO, "readText">) => string;
   /**
    * The provider store this client reads INSTEAD of `configPath`.
    *
@@ -98,7 +110,7 @@ export interface IntegrationClientSpec {
    * client, never merged into on a guess.
    */
   currentStore?: {
-    path: (env?: NodeJS.ProcessEnv, home?: string) => string;
+    path: (env?: NodeJS.ProcessEnv, home?: string, io?: Pick<IntegrationIO, "readText">) => string;
     format: ConfigFormat;
     establishes: (parsed: unknown) => boolean;
     buildContribution: BuildContribution;
@@ -139,7 +151,7 @@ export interface IntegrationClientSpec {
    * Droid uses the same seam to check competing settings against the export
    * context before status, preview, or mutation proceeds.
    */
-  resolvePaths?: (env?: NodeJS.ProcessEnv, home?: string, exportContext?: ExportContext) => { configPath: string; detectDir: string };
+  resolvePaths?: (env?: NodeJS.ProcessEnv, home?: string, exportContext?: ExportContext, io?: Pick<IntegrationIO, "readText">) => ResolvedIntegrationPaths;
   /**
    * Where the client's config WOULD live, for a client whose real path cannot
    * be resolved yet.
@@ -183,10 +195,11 @@ export function resolveIntegrationPaths(
   env: NodeJS.ProcessEnv = process.env,
   home: string = homedir(),
   exportContext?: ExportContext,
-): { configPath: string; detectDir: string } {
+  io?: Pick<IntegrationIO, "readText">,
+): ResolvedIntegrationPaths {
   const spec = INTEGRATION_CLIENTS[clientId];
-  if (spec.resolvePaths) return spec.resolvePaths(env, home, exportContext);
-  return { configPath: spec.configPath(env, home), detectDir: spec.detectDir(env, home) };
+  if (spec.resolvePaths) return spec.resolvePaths(env, home, exportContext, io);
+  return { configPath: spec.configPath(env, home, io), detectDir: spec.detectDir(env, home, io) };
 }
 
 export function assertDroidPathsUnambiguous(root: string, exportContext?: ExportContext): void {
@@ -357,15 +370,31 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
   },
   zcode: {
     id: "zcode",
-    configPath: (env = process.env, home = homedir()) => zcodeConfigPath(env, home),
-    detectDir: (env = process.env, home = homedir()) => zcodeHomeDir(env, home),
+    configPath: (env = process.env, home = homedir(), io) => zcodeConfigPath(env, home, io),
+    detectDir: (env = process.env, home = homedir(), io) => zcodeHomeDir(env, home, io),
+    resolvePaths: (env = process.env, home = homedir(), _context, io) => {
+      let root: string;
+      let pathError: string | undefined;
+      try { root = zcodeHomeDir(env, home, io); }
+      catch (error) {
+        if (!(error instanceof ZcodeSettingsPathError)) throw error;
+        root = zcodeLegacyHomeDir(env, home);
+        pathError = error.message;
+      }
+      // Passing the resolved root prevents a second bootstrap read. An explicit
+      // provider-file override outranks both the setting and ZCODE_DATA_DIR.
+      const storePath = zcodeProviderStorePath({ ...env, ZCODE_DATA_DIR: root }, home, io);
+      return { configPath: join(root, "v2", "config.json"), detectDir: root, storePath, ...(pathError ? { pathError } : {}) };
+    },
+    bindsDriftedRecord: (path, env = process.env, home = homedir()) =>
+      path === join(zcodeLegacyHomeDir(env, home), "v2", "config.json"),
     /*
      * ZCode 3.14 reads its providers from `v2/provider_config.json` and reaches
      * `v2/config.json` only through the import that seeded it. Where the new
      * file exists the import is spent, so our write is read by nobody (#5348).
      */
     currentStore: {
-      path: (env = process.env, home = homedir()) => zcodeProviderStorePath(env, home),
+      path: (env = process.env, home = homedir(), io) => zcodeProviderStorePath(env, home, io),
       format: "json",
       establishes: zcodeStoreSchemaEstablished,
       buildContribution: buildZcodeStoreContribution,
@@ -496,7 +525,7 @@ export function boundIntegrationConfigPath(input: {
   if (
     record && record.clientId === input.clientId &&
     record.configPath !== input.resolvedPath &&
-    input.statKind(record.configPath) === "file" &&
+    (input.clientId === "zcode" ? input.statKind(record.configPath) !== "missing" : input.statKind(record.configPath) === "file") &&
     INTEGRATION_CLIENTS[input.clientId].bindsDriftedRecord?.(record.configPath, input.env, input.home) === true
   ) {
     return record.configPath;
@@ -529,6 +558,11 @@ export function restoreOwnershipCollision(input: {
 }): string | null {
   const currentPath = input.currentPath;
   if (currentPath === null || currentPath === input.journaledPath) return null;
+  // A relocated ZCode store must not lose its single record to an older
+  // legacy undo, even when both journaled locations are legal for this home.
+  if (input.clientId === "zcode") {
+    return `that operation was recorded for ${input.journaledPath}, but ${currentPath} currently owns this integration`;
+  }
   const binds = INTEGRATION_CLIENTS[input.clientId].bindsDriftedRecord;
   if (!binds) return null;
   if (binds(input.journaledPath, input.env, input.home) !== true) return null;

package/src/integrations/state.ts

@@ -39,6 +39,7 @@ import {
   assertDroidPathsUnambiguous,
   assertDroidRecordedSettingsUnambiguous,
   resolveIntegrationPaths,
+  type ResolvedIntegrationPaths,
   unresolvedPathHintFor,
   type IntegrationClientId,
 } from "./registry";
@@ -482,7 +483,7 @@ export interface IntegrationStateInput {
   store?: IntegrationStateStore;
   io?: IntegrationIO;
   /** Internal explicit profile target; never accepted as a caller-provided path. */
-  resolvedPaths?: { configPath: string; detectDir: string };
+  resolvedPaths?: ResolvedIntegrationPaths;
 }
 
 export function exportContextOf(input: {
@@ -592,11 +593,11 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
    */
   let installed: boolean;
   let effective: IntegrationTarget;
-  let record: OwnershipRecord | null;
+  let record: OwnershipRecord | null = null;
   try {
     // One resolution for both, so a client whose paths come from mutable state
     // cannot report one account's install beside another account's config path.
-    const paths = resolveStatePaths(input);
+    const paths = resolveStatePaths(input, io);
     installed = io.statKind(paths.detectDir) === "dir";
     if (input.clientId === "cline") io = createClineIO(io, paths.configPath, store);
     /*
@@ -611,7 +612,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
       statKind: io.statKind, env: input.env, home: input.home,
     });
     effective = resolveIntegrationTarget({
-      clientId: input.clientId, configPath: recordedPath, io, record, env: input.env, home: input.home,
+      clientId: input.clientId, configPath: recordedPath, io, record, env: input.env, home: input.home, resolvedPaths: paths,
     });
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
@@ -626,6 +627,10 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
      * yet. A client that can name where its config would go gets `installed:
      * false` and that location, which reads as "not installed" in the UI.
      */
+    if (input.clientId === "zcode" && record) return {
+      clientId: input.clientId, state: "unsafe", installed: false, configPath: record.configPath,
+      reason: "unresolvable-path", appliedAt: record.appliedAt, lastOpId: record.opId, ...retention,
+    };
     const hint = unresolvedPathHintFor(input.clientId, input.env, input.home);
     return {
       clientId: input.clientId,
@@ -638,6 +643,12 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   }
 
   const configPath = effective.configPath;
+  if (effective.pathError) return {
+    clientId: input.clientId, state: "unsafe", installed, configPath,
+    reason: "unresolvable-path",
+    ...(record?.configPath === configPath ? { appliedAt: record.appliedAt, lastOpId: record.opId } : {}),
+    ...retention,
+  };
   if (input.clientId === "kilo") {
     const candidates = inspectKiloCandidates({ io, selectedPath: configPath, env: input.env, home: input.home });
     if (candidates.kind !== "ok") return {
@@ -715,9 +726,10 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   };
 }
 
-function resolveStatePaths(input: IntegrationStateInput): { configPath: string; detectDir: string } {
+function resolveStatePaths(input: IntegrationStateInput, io: IntegrationIO): ResolvedIntegrationPaths {
   const context = exportContextOf(input);
-  const paths = input.resolvedPaths ?? resolveIntegrationPaths(input.clientId, input.env, input.home, context);
+  const paths = input.clientId === "zcode" || !input.resolvedPaths
+    ? resolveIntegrationPaths(input.clientId, input.env, input.home, context, io) : input.resolvedPaths;
   if (input.clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(paths.detectDir, context);
   return paths;
 }
@@ -727,7 +739,7 @@ export function readOwnedDroidReasoningDefaults(input: IntegrationStateInput): R
   const store = input.store ?? createIntegrationStateStore();
   const io = input.io ?? store.io();
   try {
-    const paths = resolveStatePaths(input);
+    const paths = resolveStatePaths(input, io);
     const record = store.readRecords().droid;
     if (!record || record.clientId !== "droid" || record.configPath !== paths.configPath) return {};
     const effective = resolveIntegrationTarget({

package/src/integrations/target.ts

@@ -23,11 +23,11 @@
  *    nesting into a file holding the user's other providers would trade a
  *    silent no-op for a silent loss.
  */
-import { EXPORT_CLIENTS, ClientPathError, type BuildContribution, type ConfigFormat } from "../clients/config-export";
+import { EXPORT_CLIENTS, ClientPathError, zcodeLegacyHomeDir, zcodeProviderStorePath, type BuildContribution, type ConfigFormat } from "../clients/config-export";
 import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import { AmbiguousSelectorError, InvalidSelectorError, readPath } from "./merge";
 import type { OwnershipRecord } from "./ownership";
-import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
+import { INTEGRATION_CLIENTS, resolveIntegrationPaths, type ResolvedIntegrationPaths, type IntegrationClientId } from "./registry";
 
 export interface IntegrationTarget {
   /** The file this operation reads, writes, journals and records ownership for. */
@@ -51,6 +51,8 @@ export interface IntegrationTarget {
    * to is as effective as it ever was.
    */
   readonly ineffective: IneffectiveWrite | null;
+  /** Active root unknown; the named config is only a historical removal target. */
+  readonly pathError?: string;
 }
 
 export interface IneffectiveWrite {
@@ -153,12 +155,44 @@ export function resolveIntegrationTarget(args: {
   record: OwnershipRecord | null;
   env?: NodeJS.ProcessEnv;
   home?: string;
+  resolvedPaths?: ResolvedIntegrationPaths;
 }): IntegrationTarget {
   const { clientId, configPath, io, record } = args;
   const declared = INTEGRATION_CLIENTS[clientId].currentStore;
   if (!declared) return configFileTarget(clientId, configPath, null);
-  const storePath = declared.path(args.env, args.home);
+  const paths = clientId === "zcode"
+    ? args.resolvedPaths ?? resolveIntegrationPaths(clientId, args.env, args.home, undefined, io)
+    : undefined;
+  const storePath = paths?.storePath ?? declared.path(args.env, args.home, io);
   const kind = io.statKind(storePath);
+  const owned = record !== null && record.clientId === clientId ? record : null;
+  const historicalStore = clientId === "zcode"
+    ? zcodeProviderStorePath({ ...(args.env ?? process.env), ZCODE_DATA_DIR: zcodeLegacyHomeDir(args.env, args.home) }, args.home, io)
+    : null;
+  if (clientId === "zcode" && owned && owned.configPath !== configPath && owned.configPath !== storePath
+    && owned.configPath !== historicalStore
+    && INTEGRATION_CLIENTS[clientId].bindsDriftedRecord?.(owned.configPath, args.env, args.home) !== true
+    && io.statKind(owned.configPath) !== "missing") {
+    throw new ClientPathError(`ZCode ownership remains at ${owned.configPath}. Its location cannot be bound to the current home or selectors; restore the original selectors and disable it before enabling a different data root. Ownership and recovery evidence are retained.`);
+  }
+  // An explicit provider-file selector can establish the active target even
+  // when the bootstrap is unreadable, but absence cannot justify a legacy write.
+  if (paths?.pathError && (!(args.env ?? process.env).ZCODE_PERSONAL_PROVIDER_CONFIG_FILE?.trim() || kind !== "file")) {
+    const removal = owned?.configPath === historicalStore
+      ? storeTarget(declared, historicalStore)
+      : configFileTarget(clientId, configPath, null);
+    return { ...removal, pathError: paths.pathError };
+  }
+  if (historicalStore && owned?.configPath === historicalStore && historicalStore !== storePath
+    && recordedBlockStillPresent(io, declared.format, historicalStore, owned)) {
+    return storeTarget(declared, historicalStore, { store: storePath, why: "owned-config-file" });
+  }
+  // Relocation must not orphan a block at the default historical path, even
+  // when the relocated store has not been created yet.
+  if (clientId === "zcode" && owned?.configPath === configPath && configPath !== paths?.configPath
+    && recordedBlockStillPresent(io, EXPORT_CLIENTS[clientId].format, configPath, owned)) {
+    return configFileTarget(clientId, configPath, { store: storePath, why: "owned-config-file" });
+  }
   if (kind === "missing") {
     const missing = declared.missingStore;
     return missing?.readsStore(storePath, path => io.statKind(path)) === true
@@ -182,7 +216,6 @@ export function resolveIntegrationTarget(args: {
    * file holds it. Disable has to remove what we wrote from where we wrote it,
    * and an apply must never leave a block in one file while writing another.
    */
-  const owned = record !== null && record.clientId === clientId ? record : null;
   if (owned?.configPath === storePath && recordedBlockStillPresent(io, declared.format, storePath, owned)) {
     return storeTarget(declared, storePath, established ? null : unestablished);
   }
@@ -214,6 +247,7 @@ export function declaredIntegrationTarget(args: {
   resolvedConfigPath: string;
   env?: NodeJS.ProcessEnv;
   home?: string;
+  io?: Pick<IntegrationIO, "readText">;
 }): IntegrationTarget | null {
   const { clientId, configPath, resolvedConfigPath } = args;
   if (configPath === resolvedConfigPath) return configFileTarget(clientId, configPath, null);
@@ -222,8 +256,11 @@ export function declaredIntegrationTarget(args: {
   }
   const declared = INTEGRATION_CLIENTS[clientId].currentStore;
   if (!declared) return null;
+  if (clientId === "zcode" && configPath === zcodeProviderStorePath(
+    { ...(args.env ?? process.env), ZCODE_DATA_DIR: zcodeLegacyHomeDir(args.env, args.home) }, args.home, args.io,
+  )) return storeTarget(declared, configPath);
   try {
-    if (declared.path(args.env, args.home) !== configPath) return null;
+    if (declared.path(args.env, args.home, args.io) !== configPath) return null;
   } catch (error) {
     // A store the operator relocated with a path we cannot resolve proves
     // nothing about the row, so the row is not a legal target.

package/src/integrations/writer.ts

@@ -39,6 +39,7 @@ import {
   assertDroidPathsUnambiguous,
   isLoopbackOnly,
   resolveIntegrationPaths,
+  type ResolvedIntegrationPaths,
   restoreOwnershipCollision,
   type IntegrationClientId,
 } from "./registry";
@@ -643,8 +644,15 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   if (entry.clientId !== input.clientId) throw new Error("restore input names a different client than the operation");
 
   const clientId = entry.clientId;
-  const resolvedPath = input.resolvedPaths?.configPath
-    ?? INTEGRATION_CLIENTS[clientId].configPath(input.env, input.home);
+  let resolvedPath: string;
+  try {
+    resolvedPath = clientId === "zcode" || !input.resolvedPaths
+      ? resolveIntegrationPaths(clientId, input.env, input.home, undefined, io).configPath
+      : input.resolvedPaths.configPath;
+  } catch (error) {
+    if (!(error instanceof ClientPathError)) throw error;
+    return refuse(clientId, "unsafe", "unsafe", error.message);
+  }
   const configPath = entry.configPath;
   /*
    * Restore acts on the path the operation was journaled against. Resolving a
@@ -655,7 +663,7 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
    * shape those bytes are in, which is what the state below is measured against.
    */
   const rowTarget = declaredIntegrationTarget({
-    clientId, configPath, resolvedConfigPath: resolvedPath, env: input.env, home: input.home,
+    clientId, configPath, resolvedConfigPath: resolvedPath, env: input.env, home: input.home, io,
   });
   if (rowTarget === null) {
     return refuse(clientId, "conflict", "conflict",
@@ -814,7 +822,7 @@ type FrozenIntegrationInput = IntegrationWriteInput & {
   io: IntegrationIO;
   env: NodeJS.ProcessEnv;
   home: string;
-  resolvedPaths: { configPath: string; detectDir: string };
+  resolvedPaths: ResolvedIntegrationPaths;
 };
 
 /**
@@ -854,7 +862,7 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
    */
   const resolvedPaths = input.resolvedPaths
     ? { ...input.resolvedPaths }
-    : resolveIntegrationPaths(input.clientId, env, home, exportContextOf({ ...input, config, models: models.value }));
+    : resolveIntegrationPaths(input.clientId, env, home, exportContextOf({ ...input, config, models: models.value }), io);
   /*
    * 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
@@ -899,7 +907,7 @@ function storeLockFile(frozen: FrozenIntegrationInput): string | null {
   if (!declared?.lockFile) return null;
   let storePath: string;
   try {
-    storePath = declared.path(frozen.env, frozen.home);
+    storePath = declared.path(frozen.env, frozen.home, frozen.io);
   } catch (error) {
     if (error instanceof ClientPathError) return null;
     throw error;

package/src/lib/app-owned-memory-stores.ts

@@ -169,12 +169,16 @@ export const APP_OWNED_RETAINED_STORE_REGISTRATIONS = [
     category: "caches",
     snapshot: usageSummaryRetainedStoreSnapshot,
     evictOldest: evictOldestUsageSummaryForBudget,
+    // Deletes one in-memory summary entry.
+    passiveEvictable: true,
   },
   {
     id: "usage_snapshot",
     category: "caches",
     snapshot: usageSnapshotRetainedStoreSnapshot,
     evictOldest: evictOldestUsageSnapshot,
+    // Drops the retained ledger snapshot or one unpinned aggregate, both in memory.
+    passiveEvictable: true,
   },
   {
     id: "cursor_blobs",

package/src/lib/app-owned-memory.ts

@@ -1,3 +1,5 @@
+import { isPassiveRead } from "./passive-read";
+
 export type AppOwnedRetainedCategory = "logs" | "caches" | "blobs" | "continuation";
 export type AppOwnedObservedCategory = "translator" | "serialized_tails";
 
@@ -14,6 +16,11 @@ export interface RetainedStoreRegistration {
   category: AppOwnedRetainedCategory;
   snapshot(): RetainedStoreSnapshot;
   evictOldest(): number;
+  /**
+   * Eviction only releases memory: no spill, snapshot or other write. Only such stores are
+   * demoted inside a passive read (#6959); the rest wait for this process's own next enforcement.
+   */
+  passiveEvictable?: true;
 }
 
 export interface ObservedBufferRegistration {
@@ -168,11 +175,15 @@ function nextCandidate(
   snapshots: ReadonlyMap<string, RetainedStoreSnapshot>,
   ineligible: Set<string>,
 ): RetainedStoreRegistration | undefined {
+  // A passive read (a Remote Link Child's, #6959) demotes only stores whose eviction is memory-only:
+  // a continuation spills to disk and a replay cache rewrites its snapshot.
+  const passive = isPassiveRead();
   for (const category of CATEGORY_ORDER) {
     let candidate: RetainedStoreRegistration | undefined;
     let candidateAt = Number.POSITIVE_INFINITY;
     for (const registration of retainedStores.values()) {
       if (registration.category !== category || ineligible.has(registration.id)) continue;
+      if (passive && registration.passiveEvictable !== true) continue;
       const snapshot = snapshots.get(registration.id);
       if (!snapshot || snapshot.evictableBytes <= 0) continue;
       const oldestAt = snapshot.oldestAt;

package/src/lib/errors.ts

@@ -17,6 +17,7 @@ export const ENCRYPTED_FUNCTION_OUTPUT_REJECTION =
  * string for a client to be able to tell this apart from a provider rate limit.
  */
 export const SEND_BUDGET_EXHAUSTED_CODE = "request_send_budget_exhausted";
+export const SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE = "spend_ledger_storage_unavailable";
 
 /** First nonblank string across the canonical upstream error paths, in priority order. */
 export function upstreamErrorMessageFromPayload(payload: unknown): string | undefined {
@@ -357,6 +358,9 @@ export function isUpstreamResetReplayRefusedMessage(text: string): boolean {
 
 export function classifyError(status: number, type: string, message: string): OcxErrorPayload {
   const text = message.toLowerCase();
+  if (type === SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE) {
+    return { message, type: "server_error", code: SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE };
+  }
   if (type === "previous_response_not_found") {
     return { message, type: "invalid_request_error", code: "previous_response_not_found" };
   }
@@ -639,6 +643,24 @@ export function adapterFailureFromMessage(message: string): { httpStatus: number
   return { httpStatus, error };
 }
 
+/** Narrow structured classes carried through a synthesized bare-error terminal. */
+export function recognizedUpstreamError(error: { type?: unknown; code?: unknown }):
+  { type: string; code: string; httpStatus: 429 | 503 } | undefined {
+  const code = typeof error.code === "string" ? error.code : undefined;
+  // An explicit unknown code must not gain a recognized class from its type or copy.
+  if (code !== undefined && !["rate_limit_exceeded", "rate_limit_error", "server_is_overloaded", "overloaded_error"].includes(code)) return undefined;
+  if (code === "rate_limit_exceeded" || code === "rate_limit_error"
+    || (code === undefined && error.type === "rate_limit_error")) {
+    return { type: "rate_limit_error", code: code ?? "rate_limit_exceeded", httpStatus: 429 };
+  }
+  if (code === "server_is_overloaded" || code === "overloaded_error"
+    || (code === undefined && error.type === "overloaded_error")) {
+    return { type: error.type === "overloaded_error" ? "overloaded_error" : "server_error",
+      code: code ?? "server_is_overloaded", httpStatus: 503 };
+  }
+  return undefined;
+}
+
 /** Map a terminal Responses error object to the HTTP status we record in /api/logs. */
 export function httpStatusFromTerminalError(error: {
   type?: string;
@@ -646,10 +668,13 @@ export function httpStatusFromTerminalError(error: {
   message?: string;
 } | undefined): number {
   if (!error) return 502;
+  if (error.code === SPEND_LEDGER_STORAGE_UNAVAILABLE_CODE) return 503;
   if (error.code === "client_closed_request" || error.code === "client_cancelled") return 499;
   if (isCyberPolicyCode(error.code) || (error.message ? isCyberPolicyMessage(error.message) : false)) {
     return 400;
   }
+  const recognized = recognizedUpstreamError(error);
+  if (recognized) return recognized.httpStatus;
   if (error.type === "rate_limit_error" || error.code === "rate_limit_exceeded") return 429;
   if (error.type === "authentication_error" || error.code === "invalid_api_key") return 401;
   if (

package/src/lib/json-byte-size.ts

@@ -1,5 +1,36 @@
 import { TRANSLATOR_MAX_TURN_BYTES, TranslatorBudgetExceededError } from "./translator-budget";
 
+/** Count one JSON string formed from parts without joining, serializing or encoding it. */
+export function jsonStringPartsUtf8Bytes(parts: readonly string[], limit = TRANSLATOR_MAX_TURN_BYTES): number {
+  let bytes = 0;
+  let highSurrogate = false;
+  const add = (count: number) => {
+    if (count > limit - bytes) throw new TranslatorBudgetExceededError("request_copies", limit);
+    bytes += count;
+  };
+  add(2); // The joined string has one pair of JSON quotes.
+  for (const text of parts) {
+    if (text.length > limit - bytes) throw new TranslatorBudgetExceededError("request_copies", limit);
+    for (let i = 0; i < text.length; i++) {
+      const code = text.charCodeAt(i);
+      if (highSurrogate) {
+        highSurrogate = false;
+        if (code >= 0xdc00 && code <= 0xdfff) { add(4); continue; }
+        add(6);
+      }
+      if (code >= 0xd800 && code <= 0xdbff) highSurrogate = true;
+      else if (code === 0x22 || code === 0x5c || code === 8 || code === 9 || code === 10 || code === 12 || code === 13) add(2);
+      else if (code < 0x20) add(6);
+      else if (code < 0x80) add(1);
+      else if (code < 0x800) add(2);
+      else if (code >= 0xdc00 && code <= 0xdfff) add(6);
+      else add(3);
+    }
+  }
+  if (highSurrogate) add(6);
+  return bytes;
+}
+
 /** Measure plain JSON data without allocating its serialized string or UTF-8 copy. */
 export function jsonUtf8Bytes(value: unknown, limit = TRANSLATOR_MAX_TURN_BYTES): number {
   let bytes = 0;

package/src/lib/optional-shutdown-hooks.ts

@@ -70,5 +70,40 @@ export function runOptionalShutdownHooks(): void {
 /** Test-only reset so an isolated lifecycle test does not inherit registrations. */
 export function resetOptionalShutdownHooksForTests(): void {
   hooks.clear();
+  drainStartHooks.clear();
+  drainStartHooksRan = false;
   hooksRan = false;
 }
+
+const drainStartHooks = new Map<string, ShutdownHook>();
+let drainStartHooksRan = false;
+
+/**
+ * Register work that must run the moment a drain begins, before in-flight turns are awaited.
+ * The service health sentinel (#6671) uses it: a deliberate stop whose drain stalls must stay a
+ * stop, so the sentinel is withdrawn before the drain can look unresponsive. Same contract as
+ * {@link registerOptionalShutdownHook}: keyed, synchronous, best-effort, detachable.
+ */
+export function registerDrainStartHook(key: string, hook: ShutdownHook): () => void {
+  drainStartHooks.set(key, hook);
+  return () => {
+    if (drainStartHooks.get(key) === hook) drainStartHooks.delete(key);
+  };
+}
+
+/** Run every drain-start hook. Never throws. */
+export function runDrainStartHooks(): void {
+  drainStartHooksRan = true;
+  for (const [key, hook] of [...drainStartHooks]) {
+    try {
+      hook();
+    } catch (err) {
+      console.warn(`[shutdown] drain-start hook "${key}" failed:`, err instanceof Error ? err.message : err);
+    }
+  }
+}
+
+/** Whether a drain has begun in this process; work that must not start mid-drain checks this. */
+export function didRunDrainStartHooks(): boolean {
+  return drainStartHooksRan;
+}