@bitkyc08/opencodex 2.60.0 → 2.61.0

package/src/update/runtime-ownership.mjs

@@ -0,0 +1,122 @@
+/**
+ * Does an update own the runtime it is about to stop and restart?
+ *
+ * Both updaters ask this: `src/update/index.ts` on the Bun path and `bin/ocx.mjs` on the
+ * npm and pnpm path. It lives here as plain ESM for the same reason `stop-decision.mjs`
+ * does — the Node launcher has to be able to import it, and two lanes deciding the same
+ * situation separately is how a fix ships on one side only.
+ */
+
+/**
+ * Decide how an update treats a runtime it may not own.
+ *
+ * `ocx update` replaces the package's files and then puts the proxy back: it stops the
+ * running server first, and afterwards runs `ocx service repair` to re-register and restart
+ * the background service. Under a desktop owner both halves are wrong. The running server is
+ * the app's own bundled sidecar rather than anything this package installed, so stopping it
+ * takes down a runtime the update has no way to bring back; and the repair would re-enable
+ * the npm launcher the takeover superseded, which is the exact reactivation the ownership
+ * marker exists to prevent. Neither half is needed either — the app updates its own runtime.
+ *
+ * The service registration itself is untouched in every case. It is kept by decision, not by
+ * accident, so a user who later runs `ocx service install` gets their npm service back.
+ *
+ * THE COST OF A STALE MARKER. This reads the recorded claim, not liveness. An app deleted
+ * without releasing ownership leaves a marker behind, and an update then declines to stop or
+ * refresh a runtime no app is managing any more. That is the orphan-recovery cost the
+ * two-record ownership design accepted; `ocx service install` clears the marker and restores
+ * the ordinary path.
+ *
+ * The three returned flags are separate authorities, not commands. In particular, leaving
+ * a runtime running is not permission to replace the package it may be executing from.
+ *
+ * A recorded desktop claim does not prove which binary is live. Until the bundled resolver
+ * carries installation identity, it therefore blocks package replacement as well as stop and
+ * restoration; the notice tells a stale-marker user how to take ownership back explicitly.
+ *
+ * @param {{ ownership: { owner: string, installId: string, consentGeneration: number } | null, ownershipUnknown?: boolean, serviceInstalled: boolean }} input
+ * @returns {{ mayReplacePackage: boolean, mayStopRuntime: boolean, mayRestoreService: boolean, notice: string | null }}
+ */
+export function planUpdateRuntimeHandling({ ownership, ownershipUnknown = false, serviceInstalled }) {
+  // Unreadable, malformed or contradictory is not "nobody owns it". Reading it that way is
+  // how a permissions error reactivates the npm launcher over a consented takeover.
+  if (ownershipUnknown) {
+    return {
+      mayReplacePackage: false,
+      mayStopRuntime: false,
+      mayRestoreService: false,
+      notice: "⚠️  The background runtime's recorded owner could not be determined, so it was "
+        + "left running and the service registration was not touched. "
+        + "Run 'ocx service install' to re-register the service and take the runtime back.",
+    };
+  }
+  // Any owner that is not this CLI. Reading it this way rather than testing for "desktop"
+  // keeps a third kind of owner from silently falling into the branch that touches the npm
+  // registration.
+  if (ownership && ownership.owner !== "cli") {
+    return {
+      // A claim does not prove which binary is live. A stale desktop marker beside a
+      // manually started npm proxy would otherwise replace that proxy's executing files.
+      mayReplacePackage: false,
+      mayStopRuntime: false,
+      mayRestoreService: false,
+      notice: `🖥️  The desktop app owns the background runtime (install ${ownership.installId}, `
+        + `consent generation ${ownership.consentGeneration}). It and the npm package were left unchanged, and the `
+        + "service registration was neither re-enabled nor restarted. "
+        + "If the desktop app is gone, run 'ocx service install' to take the runtime back.",
+    };
+  }
+  return {
+    mayReplacePackage: true,
+    mayStopRuntime: true,
+    mayRestoreService: serviceInstalled,
+    notice: null,
+  };
+}
+
+/** Decide recovery after this updater already stopped the prior CLI-owned runtime. */
+export function planStoppedRuntimeRecovery({
+  stopAttempted,
+  ownership,
+  ownershipUnknown = false,
+  sameOwner,
+  liveness,
+  serviceInstalled,
+  launcherUsable,
+  hadRuntimeState,
+}) {
+  if (!stopAttempted) return { action: "none", reason: "not-stopped" };
+  if (ownershipUnknown) return { action: "manual", reason: "ownership-unknown" };
+  if (!sameOwner || (ownership && ownership.owner !== "cli")) {
+    return { action: "none", reason: "ownership-transferred" };
+  }
+  if (liveness !== "dead") return { action: "manual", reason: `runtime-${liveness}` };
+  if (!launcherUsable) return { action: "manual", reason: "launcher-unavailable" };
+  if (serviceInstalled) return { action: "service", reason: "same-cli-owner" };
+  if (hadRuntimeState) return { action: "direct", reason: "same-cli-owner" };
+  return { action: "none", reason: "nothing-to-restore" };
+}
+
+/**
+ * Re-read the current package runtime before probing. The result keeps an absent current
+ * record distinct from a dead captured endpoint while still projecting one fail-closed
+ * liveness verdict for replacement and recovery decisions.
+ */
+export function inspectPackageRuntimeLiveness({ capturedTarget, readCurrentTarget, probe }) {
+  const currentTarget = readCurrentTarget();
+  const observations = new Map();
+  const inspect = target => {
+    const key = `${target.hostname}:${target.port}`;
+    if (!observations.has(key)) observations.set(key, probe(target));
+    return observations.get(key);
+  };
+  // Probe the fresh record first. It is the address a replacement runtime may have
+  // published while the updater was waiting on the ownership lease.
+  const current = currentTarget.kind === "target" ? inspect(currentTarget.target) : currentTarget.kind;
+  const captured = inspect(capturedTarget);
+  const verdicts = current === "absent" ? [captured] : [current, captured];
+  const overall = verdicts.includes("live")
+    ? "live"
+    : verdicts.includes("unknown") ? "unknown" : "dead";
+  return { current, captured, overall };
+}

package/src/usage/attempt-delivery.ts

@@ -0,0 +1,198 @@
+/**
+ * Counting what an attempt delivered, without recording what it said.
+ *
+ * The recorder below is bound to a request-scoped object and reaches the CURRENT attempt through
+ * a callback rather than holding one. An attempt can be rotated mid-request -- a key-account
+ * change seals the old one and starts a fresh one -- and a recorder holding a reference would
+ * keep crediting frames to an attempt that had already been finalized and snapshotted.
+ *
+ * Nothing here reads a payload's content. `semanticBytes` is a length; the event classification
+ * reads only a frame's type name and an item's type name, both of which are protocol constants.
+ */
+import type { AttemptDeliverySummary } from "./telemetry-contract";
+
+export interface AttemptDeliveryTarget {
+  deliverySummary?: AttemptDeliverySummary;
+}
+
+export interface RelayedEventObservation {
+  semanticBytes?: number;
+  sideEffect?: boolean;
+  terminal?: boolean;
+}
+
+export interface AttemptDeliveryRecorder {
+  noteAdapterEvent(): void;
+  noteRelayedEvent(observation?: RelayedEventObservation): void;
+  noteBufferedDelivery(body: Record<string, unknown>): void;
+}
+
+export function createAttemptDeliverySummary(): AttemptDeliverySummary {
+  return { adapterEvents: 0, relayedEvents: 0, semanticBytes: 0, sideEffectEvents: 0, terminalEvents: 0 };
+}
+
+/**
+ * Saturating addition.
+ *
+ * A counter that wraps or drifts into a non-integer is worse than one that stops: the row would
+ * be dropped by the normalizer and the whole summary lost. A long-lived stream that somehow
+ * reaches the safe-integer ceiling keeps a readable, if pinned, number.
+ */
+function bump(current: number, by: number): number {
+  if (!Number.isFinite(by) || by <= 0) return current;
+  return Math.min(Number.MAX_SAFE_INTEGER, current + Math.floor(by));
+}
+
+const SEMANTIC_DELTA_EVENTS: ReadonlySet<string> = new Set([
+  "response.output_text.delta",
+  "response.reasoning_summary_text.delta",
+  "response.reasoning_text.delta",
+  "response.function_call_arguments.delta",
+  "response.custom_tool_call_input.delta",
+]);
+
+const TERMINAL_EVENTS: ReadonlySet<string> = new Set([
+  "response.completed",
+  "response.incomplete",
+  "response.failed",
+]);
+
+const SIDE_EFFECT_ITEM_TYPES: ReadonlySet<string> = new Set([
+  "function_call",
+  "custom_tool_call",
+  "web_search_call",
+]);
+
+/**
+ * What one relayed frame contributes, read from its type name alone.
+ *
+ * A side effect is counted when the item STARTS, not on its argument fragments and not again on
+ * the matching done frame, so one tool call is one effect however many deltas carried its
+ * arguments.
+ */
+export function classifyRelayedResponseEvent(
+  name: string,
+  data: Record<string, unknown>,
+): RelayedEventObservation {
+  const observation: RelayedEventObservation = {};
+  if (SEMANTIC_DELTA_EVENTS.has(name) && typeof data.delta === "string") {
+    observation.semanticBytes = Buffer.byteLength(data.delta, "utf8");
+  }
+  if (name === "response.output_item.added") {
+    const item = data.item;
+    const type = item !== null && typeof item === "object"
+      ? (item as Record<string, unknown>).type
+      : undefined;
+    if (typeof type === "string" && SIDE_EFFECT_ITEM_TYPES.has(type)) observation.sideEffect = true;
+  }
+  if (TERMINAL_EVENTS.has(name)) observation.terminal = true;
+  return observation;
+}
+
+/**
+ * What one buffered response body delivered.
+ *
+ * A non-streaming turn has no frames: the whole answer reaches the client as one JSON body. Read
+ * naively that looks like total relay loss -- adapter events counted, nothing relayed -- which is
+ * precisely the signal these counters exist to raise, so a buffered response would raise it on
+ * every request and make it worthless. Everything the adapter produced DID reach the client here;
+ * it arrived in one piece. So the relayed total is set to the adapter total rather than left at
+ * zero, and the semantic facts are read from the body that was built.
+ *
+ * Fields are read defensively and by name. Keying this on the adapter event union would make a
+ * member added later a merge-time exhaustiveness failure in a counter that does not need one.
+ */
+function observeBufferedBody(body: Record<string, unknown>): { semanticBytes: number; sideEffects: number } {
+  const output = Array.isArray(body.output) ? body.output : [];
+  let semanticBytes = 0;
+  let sideEffects = 0;
+  for (const entry of output) {
+    if (entry === null || typeof entry !== "object") continue;
+    const item = entry as Record<string, unknown>;
+    if (typeof item.type === "string" && SIDE_EFFECT_ITEM_TYPES.has(item.type)) sideEffects += 1;
+    if (typeof item.arguments === "string") semanticBytes += Buffer.byteLength(item.arguments, "utf8");
+    const content = Array.isArray(item.content) ? item.content : [];
+    for (const part of content) {
+      if (part === null || typeof part !== "object") continue;
+      const text = (part as Record<string, unknown>).text;
+      if (typeof text === "string") semanticBytes += Buffer.byteLength(text, "utf8");
+    }
+  }
+  return { semanticBytes, sideEffects };
+}
+
+const recordersByScope = new WeakMap<object, AttemptDeliveryRecorder>();
+
+/**
+ * Bind a recorder to a request-scoped object.
+ *
+ * The scope is the request's translator budget, which every bridge on the delivery path already
+ * receives. Reusing it avoids threading a new parameter through six call sites where any one of
+ * them silently defaulting would leave a transport uncounted -- the failure mode that made
+ * `locallyAnswered` travel on the attempt instead of as an argument.
+ */
+export function bindAttemptDeliveryRecorder(
+  scope: object,
+  currentAttempt: () => AttemptDeliveryTarget | undefined,
+): AttemptDeliveryRecorder {
+  const summaryFor = (): AttemptDeliverySummary | undefined => {
+    const attempt = currentAttempt();
+    if (!attempt) return undefined;
+    return attempt.deliverySummary ??= createAttemptDeliverySummary();
+  };
+  const recorder: AttemptDeliveryRecorder = {
+    noteAdapterEvent(): void {
+      const summary = summaryFor();
+      if (summary) summary.adapterEvents = bump(summary.adapterEvents, 1);
+    },
+    noteRelayedEvent(observation): void {
+      const summary = summaryFor();
+      if (!summary) return;
+      summary.relayedEvents = bump(summary.relayedEvents, 1);
+      if (observation?.semanticBytes) summary.semanticBytes = bump(summary.semanticBytes, observation.semanticBytes);
+      if (observation?.sideEffect) summary.sideEffectEvents = bump(summary.sideEffectEvents, 1);
+      if (observation?.terminal) summary.terminalEvents = bump(summary.terminalEvents, 1);
+    },
+    noteBufferedDelivery(body): void {
+      const summary = summaryFor();
+      if (!summary) return;
+      const observed = observeBufferedBody(body);
+      summary.relayedEvents = Math.max(summary.relayedEvents, summary.adapterEvents);
+      summary.semanticBytes = bump(summary.semanticBytes, observed.semanticBytes);
+      summary.sideEffectEvents = bump(summary.sideEffectEvents, observed.sideEffects);
+      summary.terminalEvents = bump(summary.terminalEvents, 1);
+    },
+  };
+  recordersByScope.set(scope, recorder);
+  return recorder;
+}
+
+export function attemptDeliveryRecorder(scope: object | undefined): AttemptDeliveryRecorder | undefined {
+  return scope ? recordersByScope.get(scope) : undefined;
+}
+
+/**
+ * A persisted summary is trusted only when all five counts are non-negative safe integers.
+ *
+ * The whole record is dropped rather than repaired: a partially trusted count is a number an
+ * operator would compare against another number, and half a summary is how a loss signal turns
+ * into a false one.
+ */
+export function normalizeAttemptDeliverySummary(value: unknown): AttemptDeliverySummary | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const raw = value as Record<string, unknown>;
+  const counts = createAttemptDeliverySummary();
+  for (const key of Object.keys(counts) as Array<keyof AttemptDeliverySummary>) {
+    const count = raw[key];
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) return undefined;
+    counts[key] = count;
+  }
+  return counts;
+}
+
+/** A detached copy, so a snapshotted attempt cannot keep counting after it was finalized. */
+export function cloneAttemptDeliverySummary(
+  summary: AttemptDeliverySummary | undefined,
+): AttemptDeliverySummary | undefined {
+  return summary ? { ...summary } : undefined;
+}

package/src/usage/cache-diagnostic.ts

@@ -0,0 +1,305 @@
+/** Privacy-bounded, process-local cache diagnostics. Enable with OPENCODEX_CACHE_DEBUG=1. */
+import { createHmac, randomBytes } from "node:crypto";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CODEX_AFFINITY_DEBUG_SAFE_HEADERS } from "../codex/affinity-debug";
+import { getConfigDir } from "../config";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+import type { CacheTelemetryProvenance } from "./log";
+
+const CACHE_DEBUG_KEY = randomBytes(32);
+const MAX_BLOCKS = 128;
+const MAX_DRAFTS = 512;
+export const CACHE_DEBUG_MAX_LINES = 200;
+export const CACHE_DEBUG_KEEP_LINES = 100;
+
+export type PromptCacheKeySource = "caller" | "metadata-derived" | "system-derived" | "proxy-synthesized";
+export interface TaggedPresence { present: boolean; tag?: string; source?: PromptCacheKeySource }
+export interface TaggedSequence { present: boolean; count: number; tags: string[]; truncated?: true }
+export interface PrefixFingerprint {
+  instructions: TaggedSequence;
+  tools: TaggedSequence;
+  messages: TaggedSequence;
+}
+export interface CacheDiagnosticDraft {
+  promptCacheKey?: { inbound?: TaggedPresence; outbound?: TaggedPresence };
+  session?: { inboundHeader?: TaggedPresence; outboundHeader?: TaggedPresence };
+  prefix?: { inbound?: PrefixFingerprint; outbound?: PrefixFingerprint };
+}
+
+export interface CacheDiagnosticFinalFacts {
+  requestId: string;
+  logicalRequestId?: string;
+  protocol: "responses" | "chat" | "messages";
+  provider: string;
+  model: string;
+  accountLogLabel?: string;
+  affinityMove?: string;
+  affinityReason?: string;
+  /**
+   * The cache counter exactly as the upstream usage object carried it, read before any
+   * client-wire defaulting. Undefined means the upstream object had no cache counter at
+   * all, which keeps a measured zero distinct from an absent-then-defaulted zero.
+   */
+  rawCacheCounterValue?: number;
+  normalizedCacheValue?: number;
+  cacheProvenance: CacheTelemetryProvenance;
+  draft?: CacheDiagnosticDraft;
+}
+
+const drafts = new Map<string, CacheDiagnosticDraft>();
+const bodyDrafts = new WeakMap<object, CacheDiagnosticDraft>();
+
+export function isCacheDiagnosticEnabled(): boolean {
+  return process.env.OPENCODEX_CACHE_DEBUG === "1";
+}
+
+export function cacheDiagnosticPath(): string {
+  return join(getConfigDir(), "cache-debug.jsonl");
+}
+
+function tag(domain: string, value: string): string {
+  return createHmac("sha256", CACHE_DEBUG_KEY)
+    .update(domain).update("\0").update(value).digest("hex").slice(0, 12);
+}
+
+export function tagCacheDiagnosticValue(domain: string, value: string): string {
+  return tag(`cache-debug:${domain}`, value);
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const record = value as Record<string, unknown>;
+  return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+
+function taggedPresence(value: unknown, domain: string, source?: PromptCacheKeySource): TaggedPresence {
+  if (typeof value !== "string" || value.length === 0) return { present: false };
+  return { present: true, tag: tag(domain, value), ...(source ? { source } : {}) };
+}
+
+function sessionPresence(headers: Headers | HeadersInit): TaggedPresence {
+  const normalized = headers instanceof Headers ? headers : new Headers(headers);
+  const values = CODEX_AFFINITY_DEBUG_SAFE_HEADERS.flatMap(name => {
+    const value = normalized.get(name);
+    return value === null ? [] : [[name, value] as const];
+  });
+  return values.length === 0
+    ? { present: false }
+    : { present: true, tag: tag("cache-debug:session-headers", canonicalJson(values)) };
+}
+
+function sequence(blocks: unknown[], domain: string): TaggedSequence {
+  const bounded = blocks.slice(0, MAX_BLOCKS);
+  return {
+    present: blocks.length > 0,
+    count: blocks.length,
+    tags: bounded.map(block => tag(domain, canonicalJson(block))),
+    ...(blocks.length > MAX_BLOCKS ? { truncated: true as const } : {}),
+  };
+}
+
+function requestBlocks(body: Record<string, unknown>): { instructions: unknown[]; messages: unknown[] } {
+  const instructions = body.instructions;
+  // The spread is load-bearing: an array-valued instructions field must be copied, never
+  // aliased, because the pushes below would otherwise mutate the live request body that
+  // the adapter is about to serialize upstream.
+  const instructionRows = instructions === undefined || instructions === null
+    ? [] : Array.isArray(instructions) ? [...instructions] : [instructions];
+  const input = Array.isArray(body.input) ? body.input : Array.isArray(body.messages) ? body.messages : [];
+  const messages: unknown[] = [];
+  for (const block of input) {
+    if (block && typeof block === "object" && !Array.isArray(block)) {
+      const row = block as Record<string, unknown>;
+      if (row.role === "system" || row.role === "developer") {
+        const content = row.content;
+        instructionRows.push(...(Array.isArray(content) ? content : [content]));
+        continue;
+      }
+    }
+    messages.push(block);
+  }
+  return { instructions: instructionRows, messages };
+}
+
+export function prefixFingerprint(body: unknown): PrefixFingerprint {
+  const record = body && typeof body === "object" && !Array.isArray(body)
+    ? body as Record<string, unknown> : {};
+  const tools = Array.isArray(record.tools) ? record.tools : [];
+  const blocks = requestBlocks(record);
+  return {
+    instructions: sequence(blocks.instructions, "cache-debug:prefix:instructions"),
+    tools: sequence(tools, "cache-debug:prefix:tools"),
+    messages: sequence(blocks.messages, "cache-debug:prefix:messages"),
+  };
+}
+
+function firstDivergence(inbound: PrefixFingerprint, outbound: PrefixFingerprint):
+  { section: "instructions" | "tools" | "messages"; index: number } | undefined {
+  for (const section of ["instructions", "tools", "messages"] as const) {
+    const before = inbound[section].tags;
+    const after = outbound[section].tags;
+    const compared = Math.min(before.length, after.length);
+    for (let index = 0; index < compared; index += 1) {
+      if (before[index] !== after[index]) return { section, index };
+    }
+    if (inbound[section].count !== outbound[section].count) return { section, index: compared };
+  }
+  return undefined;
+}
+
+export function observe(requestId: string, observation: Partial<CacheDiagnosticDraft>): CacheDiagnosticDraft {
+  const draft = drafts.get(requestId) ?? {};
+  Object.assign(draft, observation);
+  drafts.delete(requestId);
+  drafts.set(requestId, draft);
+  while (drafts.size > MAX_DRAFTS) drafts.delete(drafts.keys().next().value!);
+  return draft;
+}
+
+export function observeInbound(
+  body: unknown,
+  headers: Headers,
+  source: PromptCacheKeySource = "caller",
+): CacheDiagnosticDraft {
+  if (!isCacheDiagnosticEnabled()) return {};
+  try {
+    const record = body && typeof body === "object" && !Array.isArray(body)
+      ? body as Record<string, unknown> : {};
+    const draft: CacheDiagnosticDraft = {
+      promptCacheKey: { inbound: taggedPresence(record.prompt_cache_key, "cache-debug:prompt-cache-key", source) },
+      session: { inboundHeader: sessionPresence(headers) },
+      prefix: { inbound: prefixFingerprint(body) },
+    };
+    if (body && typeof body === "object") bodyDrafts.set(body, draft);
+    return draft;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Alias a later form of the same request body (for example after previous-response
+ * expansion) to an existing draft, so the outbound observation at the adapter seam can
+ * find it. The inbound fingerprint intentionally stays the literal pre-expansion body.
+ */
+export function rebindCacheDiagnosticBodyAlias(body: unknown, draft: CacheDiagnosticDraft | undefined): void {
+  if (!isCacheDiagnosticEnabled() || !draft) return;
+  if (body && typeof body === "object") bodyDrafts.set(body, draft);
+}
+
+export function observeOutbound(
+  inboundBody: unknown,
+  outboundBody: unknown,
+  headers: HeadersInit,
+  source: PromptCacheKeySource = "proxy-synthesized",
+): void {
+  if (!isCacheDiagnosticEnabled()) return;
+  try {
+    if (!inboundBody || typeof inboundBody !== "object") return;
+    const draft = bodyDrafts.get(inboundBody);
+    if (!draft) return;
+    const record = outboundBody && typeof outboundBody === "object" && !Array.isArray(outboundBody)
+      ? outboundBody as Record<string, unknown> : {};
+    const outbound = taggedPresence(record.prompt_cache_key, "cache-debug:prompt-cache-key", source);
+    const inboundKey = draft.promptCacheKey?.inbound;
+    if (outbound.present && inboundKey && outbound.tag === inboundKey.tag) {
+      outbound.source = inboundKey.source;
+    }
+    (draft.promptCacheKey ??= {}).outbound = outbound;
+    (draft.session ??= {}).outboundHeader = sessionPresence(headers);
+    (draft.prefix ??= {}).outbound = prefixFingerprint(outboundBody);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}
+
+function ensureDir(): void {
+  const dir = getConfigDir();
+  recordOwnedConfigPath(dir, cacheDiagnosticPath());
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { chmodSync(dir, 0o700); } catch { /* best-effort */ }
+}
+
+function trimRollingFile(path: string): void {
+  const lines = readFileSync(path, "utf8").split(/\r?\n/).filter(Boolean);
+  if (lines.length <= CACHE_DEBUG_MAX_LINES) return;
+  writeFileSync(path, `${lines.slice(-CACHE_DEBUG_KEEP_LINES).join("\n")}\n`, { encoding: "utf8", mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+}
+
+export function appendFinalCacheDiagnostic(facts: CacheDiagnosticFinalFacts): void {
+  if (!isCacheDiagnosticEnabled()) return;
+  try {
+    const draft = facts.draft ? observe(facts.requestId, facts.draft) : drafts.get(facts.requestId) ?? {};
+    drafts.delete(facts.requestId);
+    const inboundKey = draft.promptCacheKey?.inbound;
+    const outboundKey = draft.promptCacheKey?.outbound;
+    const inboundPrefix = draft.prefix?.inbound ?? prefixFingerprint(undefined);
+    const outboundPrefix = draft.prefix?.outbound ?? prefixFingerprint(undefined);
+    const record = {
+      version: 1 as const,
+      ts: Date.now(),
+      requestId: facts.requestId,
+      ...(facts.logicalRequestId ? { logicalRequestId: facts.logicalRequestId } : {}),
+      protocol: facts.protocol,
+      provider: facts.provider,
+      model: facts.model,
+      promptCacheKey: {
+        inbound: inboundKey ?? { present: false },
+        outbound: outboundKey ?? { present: false },
+        ...(inboundKey?.present && outboundKey?.present ? { equal: inboundKey.tag === outboundKey.tag } : {}),
+      },
+      session: {
+        inboundHeader: draft.session?.inboundHeader ?? { present: false },
+        outboundHeader: draft.session?.outboundHeader ?? { present: false },
+      },
+      prefix: {
+        inbound: inboundPrefix,
+        outbound: outboundPrefix,
+        ...(firstDivergence(inboundPrefix, outboundPrefix)
+          ? { firstDivergentBlock: firstDivergence(inboundPrefix, outboundPrefix) }
+          : {}),
+      },
+      route: {
+        provider: facts.provider,
+        model: facts.model,
+        ...(facts.accountLogLabel
+          ? { accountTag: tag("cache-debug:account-log-label", facts.accountLogLabel) }
+          : {}),
+        ...(facts.affinityMove ? { affinityMove: facts.affinityMove } : {}),
+        ...(facts.affinityReason ? { affinityReason: facts.affinityReason } : {}),
+      },
+      cache: {
+        rawUpstream: facts.rawCacheCounterValue !== undefined
+          ? { present: true, value: facts.rawCacheCounterValue }
+          : { present: false },
+        normalized: {
+          present: facts.normalizedCacheValue !== undefined,
+          ...(facts.normalizedCacheValue !== undefined ? { value: facts.normalizedCacheValue } : {}),
+          provenance: facts.cacheProvenance,
+        },
+      },
+    };
+    ensureDir();
+    const path = cacheDiagnosticPath();
+    appendFileSync(path, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+    if (existsSync(path)) trimRollingFile(path);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}
+
+const CACHE_DIAGNOSTIC_HOOK = Symbol.for("opencodex.cache-diagnostic.v1");
+interface CacheDiagnosticHooks {
+  observeInbound(body: unknown, headers: Headers, source: PromptCacheKeySource): CacheDiagnosticDraft;
+  rebind(body: unknown, draft: CacheDiagnosticDraft | undefined): void;
+  finalize(facts: CacheDiagnosticFinalFacts): void;
+}
+(globalThis as Record<symbol, CacheDiagnosticHooks | undefined>)[CACHE_DIAGNOSTIC_HOOK] = {
+  observeInbound,
+  rebind: rebindCacheDiagnosticBodyAlias,
+  finalize: appendFinalCacheDiagnostic,
+};