@bitkyc08/opencodex 2.67.0 → 2.68.0

package/src/plugins/loader.ts

@@ -0,0 +1,350 @@
+/**
+ * Local plugin loader.
+ *
+ * `ocx start` imports every `*.ts`, `*.js` and `*.mjs` file in `$OPENCODEX_HOME/plugins/`
+ * before the server binds, so a plugin's hooks are in place for the first request. A missing
+ * directory means no plugins and no work. `OCX_PLUGINS=0` disables loading for one start.
+ *
+ * A plugin is a module whose default export is `{ name?, setup(ctx) }`. It runs in the proxy
+ * process with the operator's credentials, so the loader accepts only files owned by the
+ * current user that no other user can write — the same trust boundary as `config.json`.
+ * Windows auto-loading stays disabled until this trust check is backed by an ACL check.
+ * Plugins cannot import ocx internals (a compiled binary keeps them inside `$bunfs`); they
+ * receive everything they may use through `OcxPluginContext`.
+ *
+ * Failures are contained: a plugin that throws, times out or has the wrong shape is reported
+ * and skipped, its context stops accepting registrations, and the remaining plugins and the
+ * proxy start normally. The setup deadline bounds setup that yields to the event loop; plugins
+ * run in the proxy's own thread, so synchronous work that never yields cannot be interrupted.
+ */
+
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+import { userInfo } from "node:os";
+import { getConfigDir } from "../config/paths";
+import { registerOptionalShutdownHook } from "../lib/optional-shutdown-hooks";
+import { registerUpstreamRewriter, type UpstreamRewriter } from "./upstream-hooks";
+
+export type { UpstreamRewriter, UpstreamTarget, UpstreamTransport } from "./upstream-hooks";
+
+export interface OcxPluginContext {
+  /** The plugin's own name, as reported in logs. */
+  readonly name: string;
+  /** `$OPENCODEX_HOME`, for plugins that keep state next to the proxy's. */
+  readonly configDir: string;
+  /** `$OPENCODEX_HOME/plugins`. */
+  readonly pluginDir: string;
+  log(message: string): void;
+  /** See `src/plugins/upstream-hooks.ts`. Called synchronously on every provider send. */
+  registerUpstreamRewriter(rewrite: UpstreamRewriter): void;
+  /** Runs once when the proxy shuts down. Must not throw or block. */
+  onShutdown(teardown: () => void): void;
+}
+
+export interface OcxPlugin {
+  name?: string;
+  setup(context: OcxPluginContext): void | Promise<void>;
+}
+
+export interface PluginLoadResult {
+  file: string;
+  name: string;
+  loaded: boolean;
+  error?: "windows_auto_load_disabled" | "directory_read_failed" | "directory_resolution_failed"
+    | "directory_untrusted" | "ancestor_untrusted" | "file_untrusted"
+    | "import_failed" | "invalid_export" | "setup_failed" | "setup_timeout";
+}
+
+const PLUGIN_EXTENSIONS = [".ts", ".js", ".mjs"];
+const SETUP_TIMEOUT_MS = 5_000;
+const ACL_PROBE_TIMEOUT_MS = 2_000;
+
+const MAC_ACL_BENIGN_TOKENS = new Set([
+  "read", "list", "search", "execute", "readattr", "readextattr", "readsecurity",
+  "file_inherit", "directory_inherit", "limit_inherit", "only_inherit",
+]);
+
+/**
+ * A deny, trusted-user grant, or read-only ACL does not let another user replace a checked path.
+ * `only_inherit` is not effective on this object; inherited grants on descendants are checked
+ * when those descendants are visited. Unknown allow rights and malformed entries fail closed.
+ */
+export function macAclListingTrustError(listing: string, currentUser = userInfo().username): string | null {
+  const [header, ...lines] = listing.split("\n");
+  const owner = /^\S+\s+\d+\s+(\S+)\s+/.exec(header ?? "")?.[1];
+  let unparseable = !owner;
+  for (const line of lines) {
+    if (!/^\s*\d+:/.test(line)) continue;
+    const entry = /^\s*\d+:\s+(.+?)\s+(?:inherited\s+)?(allow|deny)\s+([a-z_,]+)\s*$/.exec(line);
+    if (!entry) { unparseable = true; continue; }
+    if (entry[2] === "deny") continue;
+    const principal = entry[1]!;
+    // The file owner, this process's user, and root already control the path without an ACE.
+    // Require the `user:` prefix: a bare or group principal might include other users.
+    if (principal.startsWith("user:")
+      && [owner, currentUser, "root", "0"].includes(principal.slice(5))) continue;
+    const rights = entry[3]!.split(",");
+    if (rights.includes("only_inherit")) continue;
+    if (rights.some(right => !MAC_ACL_BENIGN_TOKENS.has(right))) return "has an access control list";
+  }
+  return unparseable ? "access control list inspection failed" : null;
+}
+
+interface MacAclProbeResult {
+  status: number | null;
+  stdout: string;
+  error?: Error;
+}
+
+/** A failed inspection never grants trust, even if a subsequent probe is attempted. */
+export function macAclProbeTrustError(probe: () => MacAclProbeResult): string | null {
+  try {
+    const first = probe();
+    // A timeout may carry partial stdout. Its unsafe ACEs are authoritative even if a retry
+    // would be clean; any other partial listing is incomplete and therefore also refused.
+    // Retry only when the first probe produced no ACL evidence at all.
+    let result = first;
+    if ((first.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT") {
+      if (first.stdout.trim()) {
+        return macAclListingTrustError(first.stdout) ?? "access control list inspection failed";
+      }
+      result = probe();
+    }
+    if (result.error || result.status !== 0) return "access control list inspection failed";
+    return macAclListingTrustError(result.stdout);
+  } catch {
+    return "access control list inspection failed";
+  }
+}
+
+/** Refuse extended ACLs: mode bits alone cannot prove who can rewrite a plugin path. */
+function aclTrustError(path: string): string | null {
+  if (process.platform !== "darwin" && process.platform !== "linux") return null;
+  const mac = process.platform === "darwin";
+  // CI and operator PATHs may put GNU coreutils ahead of the macOS tool.
+  // GNU ls does not support -e, so pin the OS ACL inspector.
+  const probe = () => spawnSync(mac ? "/bin/ls" : "getfacl", mac
+    ? ["-lebd", "--", path] : ["-cp", "--", path], {
+    encoding: "utf8",
+    timeout: ACL_PROBE_TIMEOUT_MS,
+    maxBuffer: 64 * 1024,
+    env: { ...process.env, LC_ALL: "C" },
+  });
+  if (mac) return macAclProbeTrustError(probe);
+  const result = probe();
+  // getfacl is optional on Linux. Without it, the POSIX owner/mode checks below remain;
+  // the documented Linux ACL limitation must be visible to operators.
+  if ((result.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return null;
+  if (result.error || result.status !== 0) return "access control list inspection failed";
+  return result.stdout.split("\n").some(line => /^(?:user:[^:]+:|group:[^:]+:|mask::|default:)/.test(line))
+    ? "has an access control list" : null;
+}
+
+export function pluginDirectory(): string {
+  return join(getConfigDir(), "plugins");
+}
+
+/** A missing directory is "no plugins"; any other read failure propagates to be reported. */
+function listPluginFiles(dir: string): string[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+  return entries
+    .filter(entry => !entry.startsWith(".") && !entry.startsWith("_") && !entry.endsWith(".d.ts"))
+    .filter(entry => PLUGIN_EXTENSIONS.some(extension => entry.endsWith(extension)))
+    .sort()
+    .map(entry => join(dir, entry));
+}
+
+/**
+ * Null when `path` is safe to trust, otherwise the reason it is refused. `lstat` is used so a
+ * symbolic link is judged as a link — and refused — rather than as the file it points to: a
+ * link to a file you own would otherwise pass the owner and mode checks. Windows has no
+ * POSIX owner or mode bits; the loader refuses execution on that platform.
+ */
+function trustError(path: string, kind: "file" | "directory"): string | null {
+  let stats: ReturnType<typeof lstatSync>;
+  try {
+    stats = lstatSync(path);
+  } catch {
+    return "filesystem inspection failed";
+  }
+  if (stats.isSymbolicLink()) return "is a symbolic link";
+  if (kind === "file" ? !stats.isFile() : !stats.isDirectory()) return `not a regular ${kind}`;
+  if (process.platform === "win32") return null;
+  const uid = process.getuid?.();
+  if (uid !== undefined && stats.uid !== uid) return "owned by another user";
+  // A POSIX ACL write mask may also set group-write mode bits. Inspect the ACL first so
+  // the extended grant is explicitly refused even when the mode check would also refuse it.
+  const aclError = aclTrustError(path);
+  if (aclError) return aclError;
+  if ((stats.mode & 0o022) !== 0) return "writable by group or others (chmod go-w)";
+  return null;
+}
+
+/** Null when the file is safe to execute, otherwise the reason it is refused. */
+export function pluginFileTrustError(file: string): string | null {
+  return trustError(file, "file");
+}
+
+/**
+ * A directory another user can write lets them add or swap plugin files, so its owner and
+ * mode are checked like each file's.
+ */
+export function pluginDirectoryTrustError(dir: string): string | null {
+  return trustError(dir, "directory");
+}
+
+/**
+ * Every directory above the (resolved) plugin directory, up to `/`, must be owned by the user
+ * or root and not writable by group or others unless it is sticky (like `/tmp`), where others
+ * cannot rename or replace entries they do not own. With no writable component on the path, no
+ * other user can swap what the loader checked for something else before it is imported
+ * (OpenSSH StrictModes applies the same rule). POSIX only.
+ */
+export function pluginAncestorsTrustError(realDir: string): string | null {
+  if (process.platform === "win32") return null;
+  const uid = process.getuid?.();
+  let current = dirname(realDir);
+  for (;;) {
+    let stats: ReturnType<typeof lstatSync>;
+    try {
+      stats = lstatSync(current);
+    } catch {
+      return "ancestor inspection failed";
+    }
+    if (uid !== undefined && stats.uid !== uid && stats.uid !== 0) return `${current} is owned by another user`;
+    const aclError = aclTrustError(current);
+    if (aclError) return aclError;
+    if ((stats.mode & 0o022) !== 0 && (stats.mode & 0o1000) === 0) {
+      return `${current} is writable by group or others`;
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function isPlugin(value: unknown): value is OcxPlugin {
+  return typeof value === "object" && value !== null && typeof (value as OcxPlugin).setup === "function";
+}
+
+async function withTimeout<T>(work: Promise<T>, ms: number): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new PluginSetupTimeoutError()), ms);
+  });
+  try {
+    return await Promise.race([work, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+class PluginSetupTimeoutError extends Error {}
+
+export interface LoadOcxPluginsOptions {
+  /** Deadline for a setup that yields; see the module comment. */
+  setupTimeoutMs?: number;
+}
+
+export async function loadOcxPlugins(
+  dir = pluginDirectory(),
+  options: LoadOcxPluginsOptions = {},
+): Promise<PluginLoadResult[]> {
+  if (process.env["OCX_PLUGINS"] === "0") return [];
+  if (process.platform === "win32") {
+    return [{ file: dir, name: "plugins directory", loaded: false, error: "windows_auto_load_disabled" }];
+  }
+  let files: string[];
+  try {
+    files = listPluginFiles(dir);
+  } catch {
+    return [{ file: dir, name: "plugins directory", loaded: false, error: "directory_read_failed" }];
+  }
+  if (files.length === 0) return [];
+  const dirRefused = pluginDirectoryTrustError(dir);
+  if (dirRefused) return [{ file: dir, name: "plugins directory", loaded: false, error: "directory_untrusted" }];
+  // Check and import through the resolved path, so both refer to the same components.
+  let realDir: string;
+  try {
+    realDir = realpathSync(dir);
+  } catch {
+    return [{ file: dir, name: "plugins directory", loaded: false, error: "directory_resolution_failed" }];
+  }
+  const ancestorRefused = pluginAncestorsTrustError(realDir);
+  if (ancestorRefused) return [{ file: dir, name: "plugins directory", loaded: false, error: "ancestor_untrusted" }];
+  const results: PluginLoadResult[] = [];
+  for (const file of files.map(listed => join(realDir, basename(listed)))) {
+    const fallbackName = basename(file).replace(/\.(ts|js|mjs)$/, "");
+    const refused = pluginFileTrustError(file);
+    if (refused) {
+      results.push({ file, name: fallbackName, loaded: false, error: "file_untrusted" });
+      continue;
+    }
+    const unregister: Array<() => void> = [];
+    // Closed when setup fails or times out: a setup that resumes later must not register.
+    let active = true;
+    let shutdownCount = 0;
+    const whileActive = (name: string, register: () => () => void): void => {
+      if (!active) {
+        console.error("[opencodex] plugin registration ignored: setup_failed");
+        return;
+      }
+      unregister.push(register());
+    };
+    let phase: "import" | "export" | "setup" = "import";
+    try {
+      const module = await import(pathToFileURL(file).href) as { default?: unknown; plugin?: unknown };
+      const plugin = module.default ?? module.plugin;
+      phase = "export";
+      if (!isPlugin(plugin)) throw new Error("default export must be { name?, setup(context) }");
+      const name = typeof plugin.name === "string" && plugin.name.trim() ? plugin.name.trim() : fallbackName;
+      const context: OcxPluginContext = {
+        name,
+        configDir: getConfigDir(),
+        pluginDir: dir,
+        log: message => console.log(`[plugin:${name}] ${message}`),
+        registerUpstreamRewriter: rewrite => whileActive(name, () => registerUpstreamRewriter(name, rewrite)),
+        // Keyed by file and registration, not name: two plugins may share a display name, and
+        // one plugin may register several teardowns.
+        onShutdown: teardown => whileActive(name, () => registerOptionalShutdownHook(`plugin:${file}#${++shutdownCount}`, teardown)),
+      };
+      const timeoutMs = options.setupTimeoutMs ?? SETUP_TIMEOUT_MS;
+      phase = "setup";
+      await withTimeout(Promise.resolve(plugin.setup(context)), timeoutMs);
+      results.push({ file, name, loaded: true });
+    } catch (error) {
+      // A half-initialised plugin must not leave hooks behind, now or later.
+      active = false;
+      for (const undo of unregister) undo();
+      results.push({
+        file,
+        name: fallbackName,
+        loaded: false,
+        error: error instanceof PluginSetupTimeoutError ? "setup_timeout"
+          : phase === "import" ? "import_failed"
+          : phase === "export" ? "invalid_export" : "setup_failed",
+      });
+    }
+  }
+  return results;
+}
+
+/** `ocx start` entry: load and print one line per plugin. Never throws. */
+export async function loadAndReportOcxPlugins(): Promise<void> {
+  try {
+    for (const result of await loadOcxPlugins()) {
+      if (result.loaded) console.log(`🔌 Plugin loaded: ${result.name}`);
+      else console.error(`⚠️  Plugin skipped: ${result.error}`);
+    }
+  } catch {
+    console.error("⚠️  Plugin loading failed: internal_error");
+  }
+}

package/src/plugins/upstream-hooks.ts

@@ -0,0 +1,119 @@
+/**
+ * Upstream rewrite slot for local plugins.
+ *
+ * A plugin loaded by `src/plugins/loader.ts` may register a rewriter that sees every
+ * provider send at the physical boundary, after the transport was chosen: HTTP in
+ * `sendWithConnectionPolicy` and the Codex WebSocket dial in `CodexWsSession`. The rewriter
+ * may replace the URL and add or change headers — enough to put a local sidecar (a
+ * compression proxy, a recorder) in front of the provider without the core knowing it exists.
+ *
+ * This module imports nothing, so the request path pays one array-length check when no
+ * plugin is installed. A rewriter that throws is disabled for the rest of the process and
+ * the send continues unmodified: a broken plugin must never take the proxy down with it.
+ */
+
+export type UpstreamTransport = "http" | "websocket";
+
+export interface UpstreamTarget {
+  /** Absolute upstream URL. A rewriter may assign a new one. */
+  url: string;
+  /** Mutable outbound headers. Credentials are present; a rewriter must not log them. */
+  headers: Headers;
+  readonly transport: UpstreamTransport;
+}
+
+export type UpstreamRewriter = (target: UpstreamTarget) => void;
+
+interface Registration {
+  readonly name: string;
+  readonly rewrite: UpstreamRewriter;
+  disabled: boolean;
+}
+
+const registrations: Registration[] = [];
+
+export function registerUpstreamRewriter(name: string, rewrite: UpstreamRewriter): () => void {
+  const registration: Registration = { name, rewrite, disabled: false };
+  registrations.push(registration);
+  return () => {
+    const index = registrations.indexOf(registration);
+    if (index >= 0) registrations.splice(index, 1);
+  };
+}
+
+export function hasUpstreamRewriters(): boolean {
+  return registrations.length > 0;
+}
+
+/**
+ * Run every active rewriter over one send. Returns the input untouched (same objects) when
+ * no rewriter is registered, so the common path allocates nothing.
+ */
+export function rewriteUpstream<H extends HeadersInit | undefined>(
+  url: string,
+  headers: H,
+  transport: UpstreamTransport,
+): { url: string; headers: H | Headers } {
+  if (registrations.length === 0) return { url, headers };
+  const target: UpstreamTarget = { url, headers: new Headers(headers), transport };
+  for (const registration of registrations) {
+    if (registration.disabled) continue;
+    // A rewriter that edits the target and then throws must not leave a half-rewritten send
+    // for the next rewriter or the network.
+    const urlBefore = target.url;
+    const headersBefore = new Headers(target.headers);
+    try {
+      registration.rewrite(target);
+    } catch {
+      target.url = urlBefore;
+      target.headers = headersBefore;
+      registration.disabled = true;
+      console.error("[opencodex] plugin upstream rewriter disabled: plugin_exception");
+    }
+  }
+  return { url: target.url, headers: target.headers };
+}
+
+/** Plain-record variant for callers that hold headers as `Record<string, string>` (WebSocket dial). */
+export function rewriteUpstreamRecord(
+  url: string,
+  headers: Record<string, string>,
+  transport: UpstreamTransport,
+): { url: string; headers: Record<string, string> } {
+  if (registrations.length === 0) return { url, headers };
+  const result = rewriteUpstream(url, headers, transport);
+  const record: Record<string, string> = {};
+  new Headers(result.headers).forEach((value, key) => { record[key] = value; });
+  return { url: result.url, headers: record };
+}
+
+export function isLoopbackUrl(raw: string): boolean {
+  let host: string;
+  try {
+    host = new URL(raw).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  } catch {
+    return false;
+  }
+  return host === "localhost" || host.endsWith(".localhost") || host === "::1" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+
+/**
+ * WebSocket dial variant, run for every exchange before a pooled socket is chosen so the pool
+ * identity can include the rewritten destination. The caller chose `proxy` for the original
+ * destination; a proxy elsewhere on the network cannot reach this machine's loopback, so a
+ * rewrite onto a loopback sidecar dials directly. Any other rewrite keeps the caller's proxy.
+ */
+export function rewriteWebSocketDial(
+  url: string,
+  headers: Record<string, string>,
+  proxy: string | undefined,
+): { url: string; headers: Record<string, string>; proxy: string | undefined } {
+  if (registrations.length === 0) return { url, headers, proxy };
+  const target = rewriteUpstreamRecord(url, headers, "websocket");
+  const redirectedToLoopback = target.url !== url && isLoopbackUrl(target.url);
+  return { ...target, proxy: redirectedToLoopback ? undefined : proxy };
+}
+
+export function resetUpstreamRewritersForTests(): void {
+  registrations.length = 0;
+}

package/src/protocols/encoders/adapter-events.ts

@@ -142,6 +142,11 @@ export interface AdapterEventEncodeOptions {
   freeformToolNames?: ReadonlySet<string>;
   toolSearchToolNames?: ReadonlySet<string>;
   stallTimeoutSec?: number;
+  /**
+   * Operator-trusted local upstream (loopback / private / `.local` / `.lan`): an unset budget
+   * resolves to disabled there instead of the 300 s default, matching the bridge (#5876).
+   */
+  localUpstream?: boolean;
   /** Wire-silence heartbeat and stall tick; the bridge's 2 s default. */
   heartbeatMs?: number;
   hooks?: ClientEncodeHooks;
@@ -165,7 +170,9 @@ export function encodeAdapterEventStream(
   const heartbeatMs = options.heartbeatMs ?? 2_000;
   const setTimer = options.timers?.setInterval ?? ((handler: () => void, ms: number) => setInterval(handler, ms));
   const clearTimer = options.timers?.clearInterval ?? ((id: unknown) => clearInterval(id as ReturnType<typeof setInterval>));
-  const maxStallTicks = Math.ceil((resolveStallTimeoutSec(options.stallTimeoutSec) * 1000) / heartbeatMs);
+  const maxStallTicks = Math.ceil(
+    (resolveStallTimeoutSec(options.stallTimeoutSec, { localUpstream: options.localUpstream }) * 1000) / heartbeatMs,
+  );
   const textEncoder = new TextEncoder();
 
   let controller!: ReadableStreamDefaultController<Uint8Array>;
@@ -836,7 +843,7 @@ export function encodeAdapterEventStream(
         if (upstreamActivity) {
           upstreamActivity = false;
           stallTicks = 0;
-        } else if (++stallTicks >= maxStallTicks) {
+        } else if (maxStallTicks > 0 && ++stallTicks >= maxStallTicks) {
           stall();
           return;
         }

package/src/providers/account-quota-disk.ts

@@ -14,6 +14,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile, getConfigDir } from "../config";
 import type { ProviderQuota } from "./quota-types";
+import type { KiroPersistedQuota, KiroPersistedVerdict } from "./kiro-account-state-disk";
+import { ACCOUNT_QUOTA_TTL_MS } from "./quota-wire";
 
 const FILENAME = "provider-account-quota-cache.json";
 
@@ -31,7 +33,8 @@ const PERSIST_DEBOUNCE_MS = 250;
 type DiskFile = {
   version: 1;
   /** provider\u0000accountId -> quota, the same key the in-memory cache uses. */
-  rows: Record<string, ProviderQuota>;
+  rows: Record<string, ProviderQuota | KiroPersistedQuota>;
+  kiroVerdicts?: Record<string, KiroPersistedVerdict>;
 };
 
 let persistTimer: ReturnType<typeof setTimeout> | null = null;
@@ -45,8 +48,12 @@ export function readPersistedAccountQuotas(now = Date.now()): Map<string, Provid
     const parsed = JSON.parse(readFileSync(path, "utf8")) as DiskFile;
     if (!parsed || parsed.version !== 1 || !parsed.rows || typeof parsed.rows !== "object") return rows;
     for (const [key, quota] of Object.entries(parsed.rows)) {
-      if (!quota || typeof quota !== "object" || typeof quota.updatedAt !== "number") continue;
+      if (!quota || typeof quota !== "object" || typeof quota.updatedAt !== "number"
+        || !Number.isFinite(quota.updatedAt)) continue;
       if (now - quota.updatedAt > DISK_MAX_AGE_MS) continue;
+      if (key.startsWith("kiro\0") && (quota.updatedAt > now
+        || typeof (quota as KiroPersistedQuota).identity !== "string"
+        || !/^[a-f0-9]{64}$/.test((quota as KiroPersistedQuota).identity))) continue;
       rows.set(key, quota);
     }
   } catch {
@@ -55,15 +62,46 @@ export function readPersistedAccountQuotas(now = Date.now()): Map<string, Provid
   return rows;
 }
 
+export function readPersistedKiroVerdicts(now = Date.now()): Map<string, KiroPersistedVerdict> {
+  const result = new Map<string, KiroPersistedVerdict>();
+  try {
+    const file: unknown = JSON.parse(readFileSync(join(getConfigDir(), FILENAME), "utf8"));
+    if (!file || typeof file !== "object" || Array.isArray(file)) return result;
+    const parsed = file as Partial<DiskFile>;
+    if (parsed.version !== 1 || !parsed.kiroVerdicts || typeof parsed.kiroVerdicts !== "object"
+      || Array.isArray(parsed.kiroVerdicts)) return result;
+    for (const [key, value] of Object.entries(parsed.kiroVerdicts)) {
+      if (!key.startsWith("kiro\0") || !value || typeof value !== "object") continue;
+      const row = value as Partial<KiroPersistedVerdict>;
+      if (typeof row.exhausted !== "boolean" || typeof row.identity !== "string"
+        || !/^[a-f0-9]{64}$/.test(row.identity) || typeof row.observedAt !== "number"
+        || !Number.isFinite(row.observedAt) || row.observedAt > now
+        || now - row.observedAt >= ACCOUNT_QUOTA_TTL_MS
+        || (row.resetAt !== undefined && (typeof row.resetAt !== "number"
+          || !Number.isFinite(row.resetAt) || row.resetAt <= now
+          || !Number.isFinite(new Date(row.resetAt).getTime())))) continue;
+      result.set(key, row as KiroPersistedVerdict);
+    }
+  } catch { /* Missing or malformed evidence is unknown. */ }
+  return result;
+}
+
 /** Write the snapshot, debounced. Best-effort: a failed write is not an error. */
-export function schedulePersistAccountQuotas(rows: () => Iterable<[string, ProviderQuota]>): void {
+export function schedulePersistAccountQuotas(
+  rows: () => Iterable<[string, ProviderQuota | KiroPersistedQuota]>,
+  verdicts: () => Iterable<[string, KiroPersistedVerdict]> = () => [],
+): void {
   if (persistTimer) clearTimeout(persistTimer);
   persistTimer = setTimeout(() => {
     persistTimer = null;
     try {
       const out: Record<string, ProviderQuota> = {};
       for (const [key, quota] of rows()) out[key] = quota;
-      const body: DiskFile = { version: 1, rows: out };
+      const kiroVerdicts: Record<string, KiroPersistedVerdict> = {};
+      for (const [key, verdict] of verdicts()) {
+        if (key.startsWith("kiro\0") && /^[a-f0-9]{64}$/.test(verdict.identity)) kiroVerdicts[key] = verdict;
+      }
+      const body: DiskFile = { version: 1, rows: out, kiroVerdicts };
       atomicWriteFile(join(getConfigDir(), FILENAME), `${JSON.stringify(body)}\n`);
     } catch {
       // Best-effort persistence only.

package/src/providers/codebuddy-models.ts

@@ -7,8 +7,12 @@
  * Global and CN are deliberately NOT the same roster (§八). Context windows, output caps, vision
  * and reasoning ladders are filled ONLY where the official manifest states them; a model with no
  * published figure is omitted rather than guessed (§二十八/§二十九). CodeBuddy exposes no documented
- * third-party live `/v1/models` endpoint, so these providers seed a static catalog
- * (`liveModels: false`) exactly like the Kiro and Command Code entries.
+ * third-party live `/v1/models` endpoint, so live discovery instead reads the key-authenticated
+ * product configuration roster (src/adapters/codebuddy/live-models.ts) and this static catalog is
+ * only the degraded seed for keys that fail to authenticate or requests that fail. The
+ * server-side roster can list models the manifest does not know — an account's entitlement can
+ * be newer than the bundled manifest — so a mismatch between this file and a live roster is
+ * expected, not a catalog bug.
  */
 
 /** Global (`public`) session models accepted by `codebuddy --model`. */