@chorus-aidlc/chorus 0.19.0 → 0.20.0

package/cli/codex-app-server-client.mjs

@@ -0,0 +1,402 @@
+// Versioned wire contract and integration responsibilities:
+// docs/verification/codex-app-server-protocol.md
+import { TextDecoder } from "node:util";
+
+export const APP_SERVER_DEFAULTS = Object.freeze({
+  initializeTimeoutMs: 30_000,
+  threadSetupTimeoutMs: 60_000,
+  turnStartTimeoutMs: 60_000,
+  requestTimeoutMs: 60_000,
+  writeTimeoutMs: 60_000,
+  maxFrameBytes: 32 * 1024 * 1024,
+  maxQueuedBytes: 32 * 1024 * 1024,
+  maxPendingRequests: 1024,
+  stderrTailBytes: 8192,
+});
+
+export class CodexAppServerError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "CodexAppServerError";
+    this.code = code;
+    Object.assign(this, details);
+  }
+}
+
+const fault = (code) => new CodexAppServerError(code, `Codex App Server: ${code}`);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const has = (value, key) => Object.hasOwn(value, key);
+const validId = (id) => typeof id === "string" || Number.isSafeInteger(id);
+const positive = (value) => Number.isSafeInteger(value) && value > 0;
+
+/** Deliberately narrower than "invalid request" or generic "not found". */
+export function isHistoryUnavailableError(error, threadId) {
+  return error instanceof CodexAppServerError
+    && error.code === "RPC_ERROR"
+    && error.method === "thread/resume"
+    && error.rpcCode === -32600
+    && typeof threadId === "string" && threadId.length > 0
+    && error.rpcMessage === `no rollout found for thread id ${threadId}`;
+}
+
+/** No user answers or positive approvals are ever synthesized. */
+export function headlessResponseFor(method) {
+  switch (method) {
+    case "item/commandExecution/requestApproval":
+    case "item/fileChange/requestApproval":
+      return { result: { decision: "cancel" } };
+    case "item/permissions/requestApproval":
+      return { result: { permissions: {}, scope: "turn" } };
+    case "mcpServer/elicitation/request":
+      return { result: { action: "cancel", content: null } };
+    case "execCommandApproval":
+    case "applyPatchApproval":
+      return { result: { decision: "abort" } };
+    case "item/tool/call":
+      return { result: { contentItems: [], success: false } };
+    case "item/tool/requestUserInput":
+    case "account/chatgptAuthTokens/refresh":
+    case "attestation/generate":
+      return { error: { code: -32603, message: "Unavailable in headless mode" }, fatal: true };
+    default:
+      return { error: { code: -32601, message: "Method not supported" }, fatal: true };
+  }
+}
+
+// A write callback can schedule a later error event, even after client teardown.
+// Keep only this payload-blind guard until the actual stream/process closes.
+function guardLateErrors(emitter) {
+  const ignore = () => {};
+  emitter.on("error", ignore);
+  emitter.once("close", () => emitter.removeListener("error", ignore));
+}
+
+/**
+ * Execution-scoped, bounded stdio RPC transport. Does not spawn, kill, retry,
+ * interpret turn success, or call Chorus. Subscribe before sending requests.
+ */
+export class CodexAppServerClient {
+  #child;
+  #limits;
+  #diagnostic;
+  #error = null;
+  #pending = new Map();
+  #subscribers = new Set();
+  #listeners = [];
+  #closedEmitters = new WeakSet();
+  #nextId = 1n;
+  #frame = Buffer.alloc(0);
+  #frameLength = 0;
+  #stderr = Buffer.alloc(0);
+  #queue = [];
+  #queuedBytes = 0;
+  #writing = false;
+  #fatalReply = false;
+  #resolveFailure;
+
+  constructor(child, { limits = {}, onDiagnostic = () => {} } = {}) {
+    this.#limits = { ...APP_SERVER_DEFAULTS, ...limits };
+    if (Object.values(this.#limits).some((value) => !positive(value))
+      || !child?.stdin?.write || !child?.stdout?.on || !child?.stderr?.on) {
+      throw fault("INVALID_OPTIONS");
+    }
+    this.#child = child;
+    this.#diagnostic = onDiagnostic;
+    this.failure = new Promise((resolve) => { this.#resolveFailure = resolve; });
+    for (const emitter of [child, child.stdin, child.stdout, child.stderr]) {
+      this.#listen(emitter, "close", () => this.#closedEmitters.add(emitter));
+    }
+    this.#listen(child.stdout, "data", (chunk) => this.#read(chunk));
+    this.#listen(child.stderr, "data", (chunk) => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const limit = this.#limits.stderrTailBytes;
+      // Copy so a tiny tail does not retain a huge input backing buffer.
+      this.#stderr = bytes.length >= limit
+        ? Buffer.from(bytes.subarray(bytes.length - limit))
+        : Buffer.from(Buffer.concat([this.#stderr, bytes]).subarray(-limit));
+    });
+    this.#listen(child.stdout, "end", () => this.#stop(fault(
+      this.#frameLength ? "TRUNCATED_FRAME" : "EOF",
+    )));
+    this.#listen(child.stdout, "close", () => this.#stop(fault("EOF")));
+    this.#listen(child.stdin, "close", () => this.#stop(fault("IO_CLOSED")));
+    this.#listen(child, "close", () => this.#stop(fault("PROCESS_CLOSED")));
+    // Do not settle on exit: the shared spawner settlement drains trailing IO.
+    for (const emitter of [child, child.stdin, child.stdout, child.stderr]) {
+      this.#listen(emitter, "error", () => this.#stop(fault("IO_ERROR")));
+    }
+  }
+
+  get error() { return this.#error; }
+  get closed() { return this.#error !== null; }
+  get pendingCount() { return this.#pending.size; }
+  get stderrBytes() { return this.#stderr.length; }
+
+  subscribe(listener) {
+    if (typeof listener !== "function") throw fault("INVALID_SUBSCRIBER");
+    if (!this.closed) this.#subscribers.add(listener);
+    return () => this.#subscribers.delete(listener);
+  }
+
+  request(method, params, { timeoutMs = this.#timeout(method), signal } = {}) {
+    if (this.closed) return Promise.reject(this.#error);
+    if (this.#fatalReply) return Promise.reject(fault("HEADLESS_REQUEST_UNSUPPORTED"));
+    if (!positive(timeoutMs) || typeof method !== "string" || !method
+      || (signal && (typeof signal.addEventListener !== "function"
+        || typeof signal.removeEventListener !== "function"))) {
+      return Promise.reject(fault("INVALID_REQUEST"));
+    }
+    if (signal?.aborted) {
+      this.#stop(fault("CANCELLED"));
+      return Promise.reject(this.#error);
+    }
+    if (this.#pending.size >= this.#limits.maxPendingRequests) {
+      this.#stop(fault("PENDING_LIMIT"));
+      return Promise.reject(this.#error);
+    }
+    // String IDs avoid collisions/precision loss and preserve numeric server IDs.
+    const id = `chorus-${this.#nextId++}`;
+    return new Promise((resolve, reject) => {
+      const abort = () => this.#stop(fault("CANCELLED"));
+      const timer = setTimeout(() => this.#stop(fault("RESPONSE_TIMEOUT")), timeoutMs);
+      const cleanup = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", abort);
+      };
+      this.#pending.set(id, { resolve, reject, cleanup, method });
+      signal?.addEventListener("abort", abort, { once: true });
+      this.#send({ id, method, ...(params === undefined ? {} : { params }) })
+        .catch((error) => {
+          // A fatal reverse request discards unsent application frames before
+          // flushing its negative response. Do not close that response early.
+          if (!(this.#fatalReply && error.code === "HEADLESS_REQUEST_UNSUPPORTED")) this.#stop(error);
+        });
+    });
+  }
+
+  notify(method, params) {
+    if (typeof method !== "string" || !method) return Promise.reject(fault("INVALID_REQUEST"));
+    return this.#send({ method, ...(params === undefined ? {} : { params }) });
+  }
+
+  respond(id, response) {
+    if (!validId(id) || !object(response) || has(response, "result") === has(response, "error")
+      || (has(response, "result") && response.result === undefined)
+      || (has(response, "error") && !this.#validRpcError(response.error))) {
+      return Promise.reject(fault("INVALID_RESPONSE"));
+    }
+    return this.#send({ id, ...(has(response, "error")
+      ? { error: response.error } : { result: response.result }) });
+  }
+
+  close() { this.#stop(fault("CLOSED")); }
+
+  #timeout(method) {
+    if (method === "initialize") return this.#limits.initializeTimeoutMs;
+    if (method === "thread/start" || method === "thread/resume") return this.#limits.threadSetupTimeoutMs;
+    if (method === "turn/start") return this.#limits.turnStartTimeoutMs;
+    return this.#limits.requestTimeoutMs;
+  }
+
+  #listen(emitter, name, fn) {
+    emitter.on(name, fn);
+    this.#listeners.push(() => emitter.removeListener(name, fn));
+  }
+
+  #send(message) {
+    if (this.closed) return Promise.reject(this.#error);
+    if (this.#fatalReply && has(message, "method")) return Promise.reject(fault("HEADLESS_REQUEST_UNSUPPORTED"));
+    let bytes;
+    try {
+      bytes = Buffer.from(`${JSON.stringify(message)}\n`);
+    } catch {
+      this.#stop(fault("INVALID_OUTBOUND_FRAME"));
+      return Promise.reject(this.#error);
+    }
+    if (bytes.length - 1 > this.#limits.maxFrameBytes
+      || this.#queuedBytes + bytes.length > this.#limits.maxQueuedBytes) {
+      this.#stop(fault("WRITE_BUFFER_LIMIT"));
+      return Promise.reject(this.#error);
+    }
+    return new Promise((resolve, reject) => {
+      const entry = { bytes, resolve, reject, cleanup: () => {} };
+      // Covers time spent queued as well as the actual backpressured write.
+      const timer = setTimeout(() => this.#stop(fault("WRITE_TIMEOUT")), this.#limits.writeTimeoutMs);
+      entry.cleanup = () => clearTimeout(timer);
+      this.#queue.push(entry);
+      this.#queuedBytes += bytes.length;
+      this.#pump();
+    });
+  }
+
+  #pump() {
+    if (this.closed || this.#writing || !this.#queue.length) return;
+    this.#writing = true;
+    const entry = this.#queue[0];
+    const stdin = this.#child.stdin;
+    let returned = false;
+    let callbackDone = false;
+    let drained = false;
+    let needsDrain = false;
+    const done = () => {
+      if (this.closed || !returned || !callbackDone || (needsDrain && !drained)) return;
+      entry.cleanup();
+      this.#queue.shift();
+      this.#queuedBytes -= entry.bytes.length;
+      this.#writing = false;
+      entry.resolve();
+      this.#pump();
+    };
+    const onDrain = () => { drained = true; done(); };
+    const clearTimer = entry.cleanup;
+    entry.cleanup = () => { clearTimer(); stdin.removeListener("drain", onDrain); };
+    stdin.on("drain", onDrain);
+    try {
+      needsDrain = stdin.write(entry.bytes, (error) => {
+        if (error) { this.#stop(fault("IO_ERROR")); return; }
+        callbackDone = true;
+        done();
+      }) === false;
+      returned = true;
+      done();
+    } catch {
+      this.#stop(fault("IO_ERROR"));
+    }
+  }
+
+  #read(chunk) {
+    if (this.closed) return;
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    let offset = 0;
+    while (offset < bytes.length && !this.closed) {
+      const newline = bytes.indexOf(10, offset);
+      const end = newline < 0 ? bytes.length : newline;
+      const length = end - offset;
+      if (this.#frameLength + length > this.#limits.maxFrameBytes) {
+        this.#stop(fault("FRAME_LIMIT"));
+        return;
+      }
+      const required = this.#frameLength + length;
+      if (required > this.#frame.length) {
+        const capacity = Math.min(this.#limits.maxFrameBytes, Math.max(required, 1024, this.#frame.length * 2));
+        const next = Buffer.allocUnsafe(capacity);
+        this.#frame.copy(next, 0, 0, this.#frameLength);
+        this.#frame = next;
+      }
+      bytes.copy(this.#frame, this.#frameLength, offset, end);
+      this.#frameLength = required;
+      if (newline < 0) return;
+      const frame = this.#frame.subarray(0, this.#frameLength);
+      this.#frameLength = 0;
+      try {
+        // Fatal decoding detects malformed UTF-8; buffering preserves split code points.
+        this.#message(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(frame)));
+      } catch {
+        this.#stop(fault("MALFORMED_FRAME"));
+      }
+      offset = end + 1;
+    }
+  }
+
+  #validRpcError(error) {
+    return object(error) && Number.isSafeInteger(error.code) && typeof error.message === "string";
+  }
+
+  #message(message) {
+    if (this.#fatalReply) return; // Only the bounded negative-response write remains.
+    if (!object(message) || (has(message, "jsonrpc") && message.jsonrpc !== "2.0")) {
+      throw fault("MALFORMED_FRAME");
+    }
+    if (has(message, "method")) {
+      if (typeof message.method !== "string" || !message.method
+        || has(message, "result") || has(message, "error")
+        || (has(message, "id") && !validId(message.id))) throw fault("MALFORMED_FRAME");
+      if (has(message, "id")) {
+        const { fatal, ...response } = headlessResponseFor(message.method);
+        this.#diagnose(fatal ? "HEADLESS_REQUEST_UNSUPPORTED" : "HEADLESS_REQUEST_DENIED");
+        if (fatal) {
+          this.#fatalReply = true;
+          const error = fault("HEADLESS_REQUEST_UNSUPPORTED");
+          for (const pending of this.#pending.values()) {
+            pending.cleanup();
+            pending.reject(error);
+          }
+          this.#pending.clear();
+          // The active write has already reached stdin and cannot be recalled.
+          // Keep its callback/drain and deadline, but remove everything unsent.
+          const unsent = this.#queue.splice(this.#writing ? 1 : 0);
+          for (const entry of unsent) {
+            entry.cleanup();
+            this.#queuedBytes -= entry.bytes.length;
+            entry.reject(error);
+          }
+        }
+        this.respond(message.id, response).then(() => {
+          if (fatal) this.#stop(fault("HEADLESS_REQUEST_UNSUPPORTED"));
+        }).catch((error) => this.#stop(error));
+      }
+    } else {
+      if (!has(message, "id") || !validId(message.id)
+        || has(message, "result") === has(message, "error")
+        || (has(message, "error") && !this.#validRpcError(message.error))) throw fault("MALFORMED_FRAME");
+      const pending = this.#pending.get(message.id);
+      if (pending) {
+        this.#pending.delete(message.id);
+        pending.cleanup();
+        if (has(message, "error")) {
+          const error = new CodexAppServerError("RPC_ERROR", "Codex App Server RPC request failed", {
+            method: pending.method, rpcCode: message.error.code,
+          });
+          // Needed for the exact verified fallback; excluded from serialization/logging.
+          Object.defineProperty(error, "rpcMessage", { value: message.error.message });
+          pending.reject(error);
+        } else pending.resolve(message.result);
+      }
+    }
+    for (const listener of this.#subscribers) {
+      try {
+        const result = listener(message);
+        // Do not allow an accidental async subscriber rejection to escape.
+        if (result?.then) Promise.resolve(result).catch(() => this.#stop(fault("SUBSCRIBER_ERROR")));
+      } catch {
+        this.#stop(fault("SUBSCRIBER_ERROR"));
+        return;
+      }
+    }
+  }
+
+  #diagnose(code) {
+    try {
+      const result = this.#diagnostic(`Codex App Server: ${code}`);
+      if (result?.then) Promise.resolve(result).catch(() => {});
+    } catch { /* Diagnostic callbacks cannot strand transport cleanup. */ }
+  }
+
+  #stop(error) {
+    if (this.closed) return;
+    this.#error = error instanceof CodexAppServerError ? error : fault("IO_ERROR");
+    for (const remove of this.#listeners.splice(0)) remove();
+    for (const emitter of [this.#child, this.#child.stdin, this.#child.stdout, this.#child.stderr]) {
+      if (!emitter.closed && !emitter.destroyed && !this.#closedEmitters.has(emitter)) guardLateErrors(emitter);
+    }
+    for (const pending of this.#pending.values()) {
+      pending.cleanup();
+      pending.reject(this.#error);
+    }
+    this.#pending.clear();
+    for (const entry of this.#queue) {
+      entry.cleanup();
+      entry.reject(this.#error);
+    }
+    this.#queue = [];
+    this.#queuedBytes = 0;
+    this.#writing = false;
+    this.#frame = Buffer.alloc(0);
+    this.#frameLength = 0;
+    this.#stderr = Buffer.alloc(0);
+    this.#subscribers.clear();
+    this.#resolveFailure(this.#error);
+    this.#diagnose(this.#error.code);
+    try { this.#child.stdin.end(); } catch { /* Tree cleanup belongs to spawner. */ }
+  }
+}

package/cli/codex-app-server-events.mjs

@@ -0,0 +1,176 @@
+// App Server notifications -> existing Chorus transcript/usage envelopes.
+// Transport, process lifecycle and persistence belong to the spawner.
+import { CodexAppServerError } from "./codex-app-server-client.mjs";
+import { normalizeCodexUsageEvent } from "./codex-usage-map.mjs";
+
+const COUNTERS = {
+  inputTokens: "input_tokens",
+  cachedInputTokens: "cached_input_tokens",
+  cacheWriteInputTokens: "cache_write_input_tokens",
+  outputTokens: "output_tokens",
+  reasoningOutputTokens: "reasoning_output_tokens",
+};
+const validCount = (v) => Number.isSafeInteger(v) && v >= 0;
+const nonempty = (v) => typeof v === "string" && v.trim().length > 0;
+const fail = (code) => new CodexAppServerError(code, `Codex App Server: ${code}`);
+const ZERO = Object.fromEntries(Object.values(COUNTERS).map((k) => [k, 0]));
+
+export class CodexAppServerEvents {
+  #threadId;
+  #turnId = null;
+  #observedTurnId = null;
+  #baseline;
+  #isNew;
+  #onMessage;
+  #onUsageSnapshot;
+  #buffer = [];
+  #bufferBytes = 0;
+  #maxBufferedBytes;
+  #maxItems;
+  #seen = new Set();
+  #snapshot = null;
+  #lastObserved = {};
+  #tainted = new Set();
+  #outcome = null;
+  #finished = false;
+  #noticeSent = false;
+  #resolveCompletion;
+
+  constructor({
+    threadId, isNew = false, previousUsage = null,
+    onMessage = () => {}, onUsageSnapshot = () => {},
+    maxBufferedBytes = 32 * 1024 * 1024, maxItems = 100_000,
+  }) {
+    if (!nonempty(threadId) || !Number.isSafeInteger(maxBufferedBytes) || maxBufferedBytes <= 0
+      || !Number.isSafeInteger(maxItems) || maxItems <= 0) throw fail("INVALID_EVENT_OPTIONS");
+    this.#threadId = threadId;
+    this.#isNew = isNew;
+    this.#baseline = previousUsage ? { ...previousUsage } : null;
+    this.#lastObserved = isNew ? {} : { ...this.#baseline };
+    this.#onMessage = onMessage;
+    this.#onUsageSnapshot = onUsageSnapshot;
+    this.#maxBufferedBytes = maxBufferedBytes;
+    this.#maxItems = maxItems;
+    this.completion = new Promise((resolve) => { this.#resolveCompletion = resolve; });
+  }
+
+  get turnId() { return this.#turnId; }
+  get observedTurnId() { return this.#observedTurnId; }
+  get outcome() { return this.#outcome; }
+  get usageSnapshot() { return this.#snapshot ? { ...this.#snapshot } : null; }
+
+  /** Authoritative turn/start response; buffered events cannot settle before it. */
+  confirmTurn(turnId) {
+    if (!nonempty(turnId) || (this.#turnId && this.#turnId !== turnId)) throw fail("INVALID_TURN_ID");
+    if (this.#finished) throw fail("EVENT_ADAPTER_CLOSED");
+    this.#turnId = turnId;
+    const buffered = this.#buffer;
+    this.#buffer = [];
+    this.#bufferBytes = 0;
+    for (const message of buffered) this.accept(message);
+  }
+
+  /** Returns whether the frame is relevant semantic progress for this wake. */
+  accept(message) {
+    if (this.#finished || !message || Object.hasOwn(message, "id")) return false;
+    const { method, params } = message;
+    if (typeof method !== "string" || !params || params.threadId !== this.#threadId) return false;
+    const turnId = method === "turn/started" || method === "turn/completed"
+      ? params.turn?.id : params.turnId;
+    if (!nonempty(turnId)) return false;
+    if (!(method.startsWith("item/") || method === "turn/started"
+      || method === "turn/completed" || method === "thread/tokenUsage/updated")) return false;
+    if (!this.#turnId) {
+      if (method === "turn/started") this.#observedTurnId = turnId;
+      // Only completed snapshots and totals are needed after confirmation.
+      if (method !== "turn/started" && method !== "turn/completed"
+        && method !== "item/completed" && method !== "thread/tokenUsage/updated") return true;
+      const bytes = Buffer.byteLength(JSON.stringify(message));
+      if (this.#bufferBytes + bytes > this.#maxBufferedBytes || this.#buffer.length >= this.#maxItems) {
+        throw fail("EVENT_BUFFER_LIMIT");
+      }
+      this.#buffer.push(message);
+      this.#bufferBytes += bytes;
+      return true;
+    }
+    if (turnId !== this.#turnId) return false;
+    if (method === "item/completed") this.#item(params.item);
+    if (method === "thread/tokenUsage/updated") this.#usage(params.tokenUsage?.total);
+    if (method === "turn/completed") {
+      if (!["completed", "failed", "interrupted"].includes(params.turn?.status)) throw fail("INVALID_TURN_OUTCOME");
+      // Some transports deliver the terminal snapshot without every item event.
+      for (const item of Array.isArray(params.turn.items) ? params.turn.items : []) this.#item(item);
+      this.#outcome = { status: params.turn.status, turnId: this.#turnId };
+      this.finish();
+      this.#resolveCompletion(this.#outcome);
+    }
+    return true;
+  }
+
+  #item(item) {
+    if (item?.type !== "agentMessage" || !nonempty(item.id) || !nonempty(item.text) || this.#seen.has(item.id)) return;
+    if (this.#seen.size >= this.#maxItems) throw fail("ITEM_LIMIT");
+    this.#seen.add(item.id);
+    this.#onMessage({
+      type: "item.completed",
+      item: { id: item.id, type: "agent_message", text: item.text, phase: item.phase ?? null },
+    });
+  }
+
+  #usage(total) {
+    if (!total || typeof total !== "object" || Array.isArray(total)) return;
+    const snapshot = {};
+    for (const [from, to] of Object.entries(COUNTERS)) {
+      if (!validCount(total[from])) continue;
+      snapshot[to] = total[from];
+      // Never turn a counter reset into a historical charge, including resets
+      // between two notifications inside this wake.
+      const before = this.#lastObserved[to];
+      if (validCount(before) && snapshot[to] < before) this.#tainted.add(to);
+      this.#lastObserved[to] = snapshot[to];
+    }
+    if (!Object.keys(snapshot).length) return;
+    if (this.#tainted.has("cached_input_tokens") || this.#tainted.has("cache_write_input_tokens")) {
+      this.#tainted.add("input_tokens"); // Exclusive input depends on both cache deltas.
+    }
+    if (JSON.stringify(snapshot) === JSON.stringify(this.#snapshot)) return;
+    this.#snapshot = snapshot;
+    this.#onUsageSnapshot({ ...snapshot });
+  }
+
+  /** One notice per fallback, through the same transcript consumer as replies. */
+  notice(text) {
+    if (this.#finished || this.#noticeSent || !nonempty(text)) return;
+    this.#noticeSent = true;
+    this.#onMessage({
+      type: "item.completed",
+      item: { id: `chorus-continuity-${this.#threadId}`, type: "agent_message", text },
+    });
+  }
+
+  /**
+   * Flush at most one usage frame, including partial valid totals on crash.
+   * The spawner owns persistence; snapshot callbacks also seed interrupted turns.
+   */
+  finish() {
+    if (this.#finished) return this.usageSnapshot;
+    this.#finished = true;
+    this.#buffer = [];
+    this.#bufferBytes = 0;
+    let usage = null;
+    if (this.#snapshot && (this.#isNew || this.#baseline)) {
+      const delta = {};
+      for (const key of Object.values(COUNTERS)) {
+        const now = this.#snapshot[key];
+        const before = this.#isNew ? 0 : this.#baseline?.[key];
+        delta[key] = validCount(now) && validCount(before) && now >= before && !this.#tainted.has(key)
+          ? now - before : null;
+      }
+      // Shared normalization excludes cache reads/writes from input exactly once.
+      usage = normalizeCodexUsageEvent({ type: "turn.completed", usage: delta }, ZERO).usage;
+    }
+    this.#onMessage({ type: "turn.completed", usage });
+    this.#seen.clear();
+    return this.usageSnapshot;
+  }
+}

package/cli/codex-session-map.mjs

@@ -3,7 +3,7 @@
 // its own thread id (unlike Claude, which accepts a client-supplied --session-id),
 // so to make a wake resumable across daemon restarts we record the generated id
 // keyed by the Chorus session anchor (direct idea uuid, or the entity uuid for an
-// ad-hoc session) and `codex exec resume <thread_id>` on the next wake.
+// ad-hoc session) and call App Server `thread/resume` on the next wake.
 //
 // Thin wrapper over the generic `createSessionMap` factory (shared with the Kiro
 // backend); the store is ~/.chorus/codex-sessions.json. The public API