@hienlh/ppm 0.19.1 → 0.19.3

package/src/providers/codex-app-server/codex-event-mapper.ts

@@ -27,6 +27,35 @@ function asObj(v: unknown): Record<string, unknown> {
   return (v && typeof v === "object") ? (v as Record<string, unknown>) : {};
 }
 
+/**
+ * The command text to SHOW for a commandExecution item.
+ *
+ * A commandExecution carries the same command twice. `command` is what codex
+ * hands its exec layer: the interpreter wrapped around the script, with every
+ * backslash in the interpreter path doubled (`C:\\Windows\\System32\\…`), so
+ * rendering it puts `\\` in front of the user. `commandActions[].command` is
+ * the unwrapped script — single backslashes, no interpreter prefix — which is
+ * the part a reader actually cares about.
+ *
+ * Un-escaping `command` instead would be wrong: a legitimate bash script can
+ * contain a real `\\` (regex, escaped path), and rewriting that corrupts the
+ * command the user is being shown.
+ *
+ * Multiple actions are joined by newline; an item with none (or with blank
+ * ones) falls back to the wrapped form, because showing the doubled path still
+ * beats showing an empty card.
+ */
+export function commandDisplayText(item: Item): string {
+  const raw = String(item.command ?? "");
+  const actions = Array.isArray(item.commandActions) ? item.commandActions : [];
+  const parts: string[] = [];
+  for (const a of actions) {
+    const cmd = asObj(a).command;
+    if (typeof cmd === "string" && cmd.trim()) parts.push(cmd);
+  }
+  return parts.length > 0 ? parts.join("\n") : raw;
+}
+
 /** Build the tool_use input payload from a ThreadItem (per-variant fields). */
 export function itemToToolUse(item: Item): ChatEvent {
   const type = item.type ?? "tool";
@@ -35,10 +64,11 @@ export function itemToToolUse(item: Item): ChatEvent {
   switch (type) {
     case "commandExecution": {
       // Map to PPM's canonical shell tools so the chat UI renders the command
-      // (not a raw `commandExecution` JSON blob). Sniff PowerShell vs Bash.
-      const command = String(item.command ?? "");
-      tool = /powershell|pwsh/i.test(command) ? "PowerShell" : "Bash";
-      input = { command, cwd: item.cwd };
+      // (not a raw `commandExecution` JSON blob). Sniff PowerShell vs Bash from
+      // the WRAPPED form — the interpreter only appears there, never in the
+      // unwrapped script that gets displayed.
+      tool = /powershell|pwsh/i.test(String(item.command ?? "")) ? "PowerShell" : "Bash";
+      input = { command: commandDisplayText(item), cwd: item.cwd };
       break;
     }
     case "fileChange": {
@@ -65,6 +95,24 @@ export function itemToToolUse(item: Item): ChatEvent {
       tool = "WebSearch";
       input = { query: item.query };
       break;
+    case "imageGeneration":
+      // The item carries the finished PNG twice: `result` is the whole file as
+      // base64 (~1.2 MB for a 917 KB image) and `savedPath` points at the copy
+      // codex already wrote to disk. Only the path is kept. `result` must never
+      // reach a ChatEvent — the event is held in the in-RAM turnEvents buffer,
+      // appended to the session JSONL, and broadcast to every connected client,
+      // so carrying the payload would cost all three that megabyte per image
+      // to display a picture that is already readable from `savedPath`.
+      //
+      // `file_path` (not `savedPath`) is deliberate: it is the key the chat's
+      // image-preview path check already reads, so the thumbnail comes for free.
+      tool = "ImageGen";
+      input = {
+        file_path: item.savedPath ?? null,
+        prompt: item.revisedPrompt ?? null,
+        transparentBackground: item.transparentBackground ?? false,
+      };
+      break;
     default:
       input = item;
   }
@@ -92,6 +140,13 @@ export function itemToToolResult(item: Item): ChatEvent {
   } else if (type === "dynamicToolCall") {
     output = redactTruncate(item.contentItems ?? "");
     isError = item.success === false;
+  } else if (type === "imageGeneration") {
+    // Same reason as the tool_use side: never let the base64 `result` through.
+    // Falling to the generic branch below would emit 8 KB of truncated base64
+    // as the visible result text.
+    const failure = item.failure;
+    isError = failure != null;
+    output = isError ? redactTruncate(failure) : String(item.savedPath ?? "generated");
   } else {
     output = redactTruncate(item);
   }
@@ -127,7 +182,17 @@ export function mapCodexEvent(notif: Notif, sessionId: string): ChatEvent[] {
     case "item/completed": {
       const item = asObj(p.item) as Item;
       if (item.type === "contextCompaction") return [{ type: "system", subtype: "compact_done" }];
-      if (item.type && !NON_TOOL_ITEM_TYPES.has(item.type)) return [itemToToolResult(item)];
+      if (item.type && !NON_TOOL_ITEM_TYPES.has(item.type)) {
+        // Image generation is announced before the picture exists: at `started`
+        // there is no saved file and no revised prompt, so the call it produced
+        // can show neither. The finished item carries both, so re-emit the call
+        // alongside its result — the chat replaces the card by tool-use id.
+        // Other tools describe themselves fully at `started`; re-sending those
+        // would only cost a second event in the buffer, the log and every
+        // client's socket.
+        if (item.type === "imageGeneration") return [itemToToolUse(item), itemToToolResult(item)];
+        return [itemToToolResult(item)];
+      }
       return [];
     }
 

package/src/providers/codex-app-server/codex-history.ts

@@ -4,6 +4,7 @@ import { join, resolve } from "node:path";
 import { homedir } from "node:os";
 import { redactTruncate } from "./codex-redact.ts";
 import { parseApplyPatch, changeToToolUse } from "./codex-patch.ts";
+import { mapRolloutItem } from "./codex-rollout-items.ts";
 
 /**
  * Independent parser for Codex rollout JSONL transcripts
@@ -110,6 +111,15 @@ export function parseRolloutJsonl(text: string, opts?: { preCompact?: boolean })
   let i = 0;
   let pendingEvents: ChatEvent[] = [];
 
+  // Newer codex records every finished step as an `item_completed` event AND
+  // keeps the raw model exchange in `response_item` records. Both describe the
+  // same tool calls, so taking both renders every command twice — and the
+  // response_item copy of an image generation carries the whole PNG as base64,
+  // which would land in the transcript. When the item events are present they
+  // are the better source: already assembled, already named the way the live
+  // stream names them.
+  const hasItemEvents = text.includes('"item_completed"');
+
   const flushAssistant = (content: string, ts: string) => {
     if (!content && pendingEvents.length === 0) return;
     const events = pendingEvents.length
@@ -131,6 +141,19 @@ export function parseRolloutJsonl(text: string, opts?: { preCompact?: boolean })
         messages.push({ id: `rollout-${i++}`, role: "user", content: p.message, timestamp: ts });
       } else if (p.type === "agent_message" && typeof p.message === "string") {
         flushAssistant(p.message, ts);
+      } else if (p.type === "item_completed") {
+        // Newer codex writes one item per finished step instead of the
+        // user_message/agent_message pair above. Same conversation, different
+        // spelling — see codex-rollout-items.
+        const mapped = mapRolloutItem(p.item);
+        if (mapped.kind === "user") {
+          if (pendingEvents.length) flushAssistant("", ts);
+          messages.push({ id: `rollout-${i++}`, role: "user", content: mapped.text, timestamp: ts });
+        } else if (mapped.kind === "assistant") {
+          flushAssistant(mapped.text, ts);
+        } else if (mapped.kind === "events") {
+          pendingEvents.push(...mapped.events);
+        }
       } else if (p.type === "thread_rolled_back") {
         // codex doesn't truncate the rollout file on rollback/fork — it appends this
         // marker. Drop the last `num_turns` turns (by user-message turn-start) so a
@@ -144,6 +167,7 @@ export function parseRolloutJsonl(text: string, opts?: { preCompact?: boolean })
         }
       }
     } else if (rec.type === "response_item") {
+      if (hasItemEvents) continue; // item_completed already carried these
       if (p.type === "function_call") pendingEvents.push(fnCallToToolUse(p));
       else if (p.type === "function_call_output") pendingEvents.push(fnOutputToToolResult(p));
       // File edits are recorded as custom_tool_call (name=apply_patch) + output.

package/src/providers/codex-app-server/codex-jsonrpc-client.ts

@@ -19,6 +19,14 @@ const ENV_ALLOWLIST = [
 /** Prefixes kept (codex/XDG own their auth + config). */
 const ENV_PREFIX_ALLOWLIST = ["CODEX_", "XDG_", "RUST_"];
 
+/**
+ * Bound for short control calls — handshake, model list, skill list, quota read.
+ * These answer in about a second when the app-server is healthy; anything past
+ * this is a subprocess that will never answer, not a slow one. A turn is NOT a
+ * control call and must never be given this bound.
+ */
+export const CONTROL_REQUEST_TIMEOUT_MS = 15_000;
+
 function buildSpawnEnv(): NodeJS.ProcessEnv {
   const out: NodeJS.ProcessEnv = {};
   for (const [k, v] of Object.entries(process.env)) {
@@ -120,12 +128,41 @@ export class CodexJsonRpcClient {
     }
   }
 
-  request<T = unknown>(method: string, params?: unknown): Promise<T> {
+  /**
+   * Send a request and wait for its reply.
+   *
+   * `timeoutMs` bounds the wait. It is opt-in because a turn legitimately runs
+   * for many minutes, but every short control call should pass one: the
+   * app-server has been observed to accept a spawn and then never answer even
+   * `initialize`. Without a bound, the promise never settles, so the caller's
+   * `finally` never runs, the subprocess is never closed, and any HTTP route
+   * waiting on it hangs until the client gives up — one orphaned app-server per
+   * attempt, and a blank reading at the other end.
+   *
+   * A timeout rejects and drops the pending entry, so a late reply is ignored
+   * rather than resolving a promise the caller already abandoned.
+   */
+  request<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T> {
     if (this.closed) return Promise.reject(new Error("codex client closed"));
     const id = this.nextId++;
     const line = JSON.stringify({ id, method, params }) + "\n";
     return new Promise<T>((resolve, reject) => {
-      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const settle = <A extends unknown[]>(fn: (...args: A) => void) => (...args: A) => {
+        if (timer) clearTimeout(timer);
+        fn(...args);
+      };
+      const wrapped = {
+        resolve: settle(resolve as (v: unknown) => void),
+        reject: settle(reject),
+      };
+      if (timeoutMs != null) {
+        timer = setTimeout(() => {
+          this.pending.delete(id);
+          reject(new Error(`codex ${method} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+      this.pending.set(id, wrapped);
       this.write(line);
     });
   }

package/src/providers/codex-app-server/codex-protocol.ts

@@ -90,6 +90,30 @@ export interface ModelListResponse {
   nextCursor: string | null;
 }
 
+// ── Skills ──
+/** Presentation block codex ships for its own system skills. All fields optional. */
+export interface CodexSkillInterface {
+  displayName?: string;
+  shortDescription?: string;
+  /** Absolute path to an icon file inside the skill directory, not a URL. */
+  iconSmall?: string;
+  iconLarge?: string;
+  defaultPrompt?: string;
+}
+export interface CodexSkill {
+  name: string;
+  description?: string;
+  /** "system" for codex's built-ins; project/user scopes for authored ones. */
+  scope?: string;
+  path?: string;
+  enabled?: boolean;
+  interface?: CodexSkillInterface;
+}
+/** `skills/list` groups its results by the cwd each set was resolved for. */
+export interface SkillListResponse {
+  data: { cwd?: string; skills?: CodexSkill[] }[];
+}
+
 // ── Account rate limits / usage ──
 export interface RateLimitWindow {
   usedPercent: number;

package/src/providers/codex-app-server/codex-provider.ts

@@ -10,17 +10,19 @@ import type {
   UsageInfo,
 } from "../provider.interface.ts";
 import { configService } from "../../services/config.service.ts";
-import { setSessionMetadata, getSessionProjectPath, setSessionProvider, setSessionCodexAccount } from "../../services/db.service.ts";
-import { resolveCodexAccountForSession } from "../../services/codex-account.service.ts";
+import { setSessionMetadata, getSessionProjectPath, setSessionProvider, setSessionCodexAccount, getSessionCodexAccount } from "../../services/db.service.ts";
+import { resolveCodexAccountForSession, getCodexAccount, listCodexAccounts, peekCodexAccount } from "../../services/codex-account.service.ts";
 import { killProcessTree } from "../../services/windows-process-tree.ts";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CodexJsonRpcClient } from "./codex-jsonrpc-client.ts";
+import { CodexJsonRpcClient, CONTROL_REQUEST_TIMEOUT_MS } from "./codex-jsonrpc-client.ts";
 import { permissionModeToCodex, type CodexPermission } from "./codex-permission-map.ts";
 import { mapCodexEvent } from "./codex-event-mapper.ts";
 import { decisionFor, isApprovalMethod, type ApprovalMethod } from "./codex-approval-decision.ts";
 import { parseModelList } from "./codex-model-parser.ts";
-import { fetchCodexUsage } from "./codex-usage-fetch.ts";
+import { getOrFetchUsage, registerUsageSource } from "../../services/provider-usage/usage-registry.ts";
+import { codexUsageSource } from "./codex-usage-source.ts";
+import { AMBIENT_ACCOUNT_KEY } from "../../services/provider-usage/usage-source.ts";
 import { redactTruncate } from "./codex-redact.ts";
 import {
   listCodexRollouts,
@@ -33,12 +35,51 @@ import type {
   JsonRpcNotification,
   ToolRequestUserInputResponse,
   Thread,
+  UserInput,
+  CodexSkill,
 } from "./codex-protocol.ts";
+import { parseSkillList } from "./codex-skill-parser.ts";
 
 const CODEX_SESSIONS_DIR = join(homedir(), ".codex", "sessions");
+
+/**
+ * Every directory a codex rollout for this install could be in, most specific
+ * first.
+ *
+ * `~/.codex/sessions` is only the ambient login's. PPM gives each managed
+ * account its own CODEX_HOME, and the app-server writes that account's
+ * transcripts under it — so a session bound to an account has its history
+ * nowhere near the default directory. Reading only the default is why such a
+ * conversation came back empty once it was no longer live in memory: it was
+ * being served from the in-process transcript, and nothing on disk was ever
+ * found for it.
+ *
+ * `sessionId` narrows to the bound account when there is one; without it the
+ * caller gets every account, which is what listing a project's sessions needs.
+ */
+function codexSessionsDirs(sessionId?: string): string[] {
+  const dirs: string[] = [];
+  const boundId = sessionId ? getSessionCodexAccount(sessionId) : null;
+  const accounts = boundId
+    ? [getCodexAccount(boundId)].filter((a): a is NonNullable<typeof a> => a != null)
+    : listCodexAccounts();
+  for (const account of accounts) dirs.push(join(account.home, "sessions"));
+  dirs.push(CODEX_SESSIONS_DIR);
+  return dirs;
+}
+
+/** First non-empty result across the candidate directories. */
+function fromCodexSessionsDirs<T>(sessionId: string | undefined, read: (dir: string) => T | null): T | null {
+  for (const dir of codexSessionsDirs(sessionId)) {
+    const found = read(dir);
+    if (found != null) return found;
+  }
+  return null;
+}
 const CLIENT_INFO = { name: "ppm", title: "PPM", version: "0.0.0" };
 const CAPABILITIES = { experimentalApi: true, requestAttestation: false, optOutNotificationMethods: null };
 const MODELS_CACHE_TTL = 5 * 60 * 1000;
+const SKILLS_CACHE_TTL = 60 * 1000;
 
 interface PendingApproval {
   codexId: number | string;
@@ -164,6 +205,8 @@ export class CodexAppServerProvider implements AIProvider {
   private sessions = new Map<string, Session>();
   private live = new Map<string, LiveSession>();
   private modelsCache: { models: ModelOption[]; expiry: number } | null = null;
+  /** Keyed by `cwd\0codexHome` — skills differ per workspace AND per account. */
+  private skillsCache = new Map<string, { skills: CodexSkill[]; expiry: number }>();
 
   private get config() {
     try { return configService.get("ai").providers["codex"] ?? null; } catch { return null; }
@@ -207,10 +250,29 @@ export class CodexAppServerProvider implements AIProvider {
   }
 
   async listSessionsByDir(dir: string, opts?: { limit?: number; offset?: number }): Promise<SessionInfo[]> {
-    const sessions = listCodexRollouts(CODEX_SESSIONS_DIR, dir, this.id, opts);
+    const seen = new Set<string>();
+    const sessions: SessionInfo[] = [];
+    for (const sessionsDir of codexSessionsDirs()) {
+      for (const s of listCodexRollouts(sessionsDir, dir, this.id, opts)) {
+        if (seen.has(s.id)) continue;
+        seen.add(s.id);
+        sessions.push(s);
+      }
+    }
     // Backfill provider ownership so reopening a pre-existing codex thread routes
     // to codex (not the default provider) even after a restart.
-    for (const s of sessions) { try { setSessionProvider(s.id, this.id); } catch { /* non-fatal */ } }
+    //
+    // The project path is recorded in the same pass, and it has to be: reading a
+    // session is fail-closed on cwd, so a row registered here without one can
+    // never be read back and the conversation opens blank. `dir` is exactly that
+    // cwd — every rollout listed above matched it — so the attribution is the
+    // one already proven, not a guess.
+    for (const s of sessions) {
+      try {
+        setSessionProvider(s.id, this.id);
+        setSessionMetadata(s.id, s.projectName, dir);
+      } catch { /* non-fatal */ }
+    }
     return sessions;
   }
 
@@ -260,7 +322,12 @@ export class CodexAppServerProvider implements AIProvider {
     live.transcript.push({ id: nextRolloutId(live), role: "user", content: message, timestamp: new Date().toISOString() });
     live.currentAssistant = "";
     live.currentEvents = [];
-    const input = [{ type: "text" as const, text: message, text_elements: [] }];
+    // Codex takes an image as a path, never as a payload, so the uploaded copy is what it
+    // gets. Images lead: the text usually refers to them ("what is this?").
+    const input: UserInput[] = [
+      ...(opts?.imagePaths ?? []).map((path) => ({ type: "localImage" as const, path })),
+      { type: "text" as const, text: message, text_elements: [] },
+    ];
     const turnModel = codexModel(opts?.model);
     live.client.request("turn/start", {
       threadId: live.threadId,
@@ -295,13 +362,13 @@ export class CodexAppServerProvider implements AIProvider {
     client.onClose(() => this.handleClose(live));
     client.start({ cwd, codexHome: account?.home });
 
-    await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES });
+    await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
     client.notify("initialized");
 
     const resumeBase = { cwd, sandbox: permission.sandbox, approvalPolicy: permission.approvalPolicy, ...(model ? { model } : {}) };
     // Only treat as a resume when a rollout for this id is attributable to THIS
     // project (fail-closed cwd guard) — never resume another project's thread.
-    const isResume = !!findRolloutByThreadId(CODEX_SESSIONS_DIR, sessionId, cwd);
+    const isResume = !!fromCodexSessionsDirs(sessionId, (d) => findRolloutByThreadId(d, sessionId, cwd));
     const result = isResume
       ? await client.request("thread/resume", { threadId: sessionId, ...resumeBase })
       : await client.request("thread/start", resumeBase);
@@ -325,7 +392,10 @@ export class CodexAppServerProvider implements AIProvider {
     }
     // Snapshot persisted history so live message ids continue the rollout-N
     // numbering (empty for a brand-new thread; full prior transcript on resume).
-    live.history = getRolloutMessages(CODEX_SESSIONS_DIR, threadId, cwd);
+    live.history = fromCodexSessionsDirs(threadId, (d) => {
+      const msgs = getRolloutMessages(d, threadId, cwd);
+      return msgs.length > 0 ? msgs : null;
+    }) ?? [];
     return live;
   }
 
@@ -360,7 +430,8 @@ export class CodexAppServerProvider implements AIProvider {
     if (notif.method === "item/completed" && live.compactRequested
         && (notif.params as { item?: { type?: string } })?.item?.type === "contextCompaction") {
       live.compactRequested = false;
-      const file = findRolloutByThreadId(CODEX_SESSIONS_DIR, live.threadId ?? "", live.cwd);
+      const file = fromCodexSessionsDirs(live.threadId ?? undefined,
+        (d) => findRolloutByThreadId(d, live.threadId ?? "", live.cwd));
       if (file) {
         const content = `_Conversation compacted to save context._\n\nread the full transcript at: ${file}`;
         live.channel.push({ type: "text", content });
@@ -467,7 +538,10 @@ export class CodexAppServerProvider implements AIProvider {
     // Fail-closed: only return rollout messages attributable to this project's cwd.
     const cwd = this.sessions.get(sessionId)?.projectPath || getSessionProjectPath(sessionId);
     if (!cwd) return [];
-    return getRolloutMessages(CODEX_SESSIONS_DIR, sessionId, cwd);
+    return fromCodexSessionsDirs(sessionId, (d) => {
+      const msgs = getRolloutMessages(d, sessionId, cwd);
+      return msgs.length > 0 ? msgs : null;
+    }) ?? [];
   }
 
   /**
@@ -495,7 +569,7 @@ export class CodexAppServerProvider implements AIProvider {
     try {
       if (!reuse) {
         client.start({ cwd });
-        await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES });
+        await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
         client.notify("initialized");
       }
       const forkRes = await client.request<{ thread?: { id?: string; turns?: unknown[] } }>("thread/fork", { threadId: sessionId, cwd });
@@ -534,12 +608,12 @@ export class CodexAppServerProvider implements AIProvider {
     const client = new CodexJsonRpcClient();
     try {
       client.start({ cwd: process.cwd() });
-      await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES });
+      await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
       client.notify("initialized");
       const all: unknown[] = [];
       let cursor: string | null = null;
       do {
-        const res: ModelListResponse = await client.request<ModelListResponse>("model/list", { cursor });
+        const res: ModelListResponse = await client.request<ModelListResponse>("model/list", { cursor }, CONTROL_REQUEST_TIMEOUT_MS);
         if (Array.isArray(res?.data)) all.push(...res.data);
         cursor = res?.nextCursor ?? null;
       } while (cursor);
@@ -553,8 +627,82 @@ export class CodexAppServerProvider implements AIProvider {
     }
   }
 
-  /** Codex quota for the default account (account/rateLimits/read, 60s cache). */
-  async getUsage(): Promise<UsageInfo> {
-    return fetchCodexUsage();
+  /**
+   * The skills codex itself would resolve for `cwd`, asked of codex rather than
+   * discovered from disk.
+   *
+   * Two reasons it has to come from the app-server. Codex's built-ins live under
+   * `$CODEX_HOME/skills/.system/`, and PPM points CODEX_HOME at a per-account
+   * directory — so scanning the ambient `~/.codex` reads a different, possibly
+   * stale set than the session will actually run. And the app-server is the only
+   * source of `enabled` and of the `interface` block (display name, icons) that
+   * the picker shows.
+   *
+   * Cached briefly per (cwd, account): the list changes when the user installs a
+   * skill, which should show up without a restart, but a picker keystroke must
+   * not spawn an app-server.
+   */
+  async listSkills(sessionId?: string): Promise<CodexSkill[]> {
+    const cwd = (sessionId ? getSessionProjectPath(sessionId) : null) || process.cwd();
+    // Reuse the account already bound to the session; resolving afresh here
+    // would advance a round-robin strategy for a mere UI listing.
+    const accountId = sessionId ? getSessionCodexAccount(sessionId) : null;
+    const home = (accountId ? getCodexAccount(accountId)?.home : null) ?? undefined;
+
+    const key = `${cwd}\0${home ?? ""}`;
+    const hit = this.skillsCache.get(key);
+    if (hit && Date.now() < hit.expiry) return hit.skills;
+
+    const client = new CodexJsonRpcClient();
+    try {
+      client.start({ cwd, codexHome: home });
+      await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
+      client.notify("initialized");
+      const skills = parseSkillList(await client.request("skills/list", {}, CONTROL_REQUEST_TIMEOUT_MS));
+      if (skills.length > 0) this.skillsCache.set(key, { skills, expiry: Date.now() + SKILLS_CACHE_TTL });
+      return skills;
+    } catch {
+      return [];
+    } finally {
+      client.close();
+    }
+  }
+
+  /** Read the session's account without advancing the account-selection strategy. */
+  async getUsage(sessionId?: string): Promise<UsageInfo> {
+    // Idempotent, and needed because a caller can reach the provider before the
+    // server has started background polling — an unregistered source would make
+    // the shared layer answer {} instead of reading codex.
+    registerUsageSource(codexUsageSource);
+    const accountId = sessionId ? getSessionCodexAccount(sessionId) : null;
+    const bound = accountId ? getCodexAccount(accountId) : null;
+    if (bound) {
+      // Through the shared layer, so this answers from the cache or the stored
+      // snapshot and only reaches codex when nothing is known yet — the same
+      // path Claude's usage takes. It used to spawn an app-server inline on
+      // every miss, on the HTTP request's own thread of control.
+      return {
+        ...await getOrFetchUsage(this.id, bound.id),
+        activeAccountId: bound.id,
+        activeAccountLabel: bound.label,
+      };
+    }
+
+    // Nothing bound yet — a session binds on its first send. Name the account
+    // that will serve it, but do NOT read its quota: that spawns an app-server
+    // against a login which is not yet this session's, and which a round-robin
+    // or lowest-usage pick may never hand it. So the toolbar can say WHO will
+    // answer without PPM touching that account on a session's behalf before
+    // the session owns it. The numbers arrive with the first turn.
+    //
+    // Skipped when the session names an account that no longer exists: naming
+    // a different one there would be a lie about a binding that already failed.
+    const pending = accountId ? null : peekCodexAccount();
+    if (pending) return { activeAccountId: pending.id, activeAccountLabel: pending.label };
+
+    // Managed accounts are assigned on first send; don't show an unrelated
+    // ambient login while that assignment is pending or the binding is missing.
+    if (accountId || listCodexAccounts().length > 0) return {};
+    return getOrFetchUsage(this.id, AMBIENT_ACCOUNT_KEY);
   }
 }