@hienlh/ppm 0.20.0 → 0.20.2

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

@@ -10,8 +10,19 @@ import type {
   UsageInfo,
 } from "../provider.interface.ts";
 import { configService } from "../../services/config.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 { setSessionMetadata, getSessionProjectPath, setSessionProvider, setSessionCodexAccount, getSessionCodexAccount, getSessionTitles } from "../../services/db.service.ts";
+import {
+  resolveCodexAccountForSession,
+  getCodexAccount,
+  listCodexAccounts,
+  peekCodexAccount,
+  selectCodexAccount,
+  getAllCodexUsages,
+  codexUsageLevel,
+  type CodexAccount,
+} from "../../services/codex-account.service.ts";
+import { isCodexAccountUsageLimited, markCodexAccountUsageLimited } from "../../services/codex-account-cooldown.ts";
+import { isCodexUsageLimit, codexErrorMessage, parseCodexUsageLimitReset } from "./codex-usage-limit.ts";
 import { killProcessTree } from "../../services/windows-process-tree.ts";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -24,6 +35,7 @@ import { getOrFetchUsage, registerUsageSource } from "../../services/provider-us
 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 { localizeRollout } from "./codex-rollout-transfer.ts";
 import {
   listCodexRollouts,
   findRolloutByThreadId,
@@ -54,16 +66,22 @@ const CODEX_SESSIONS_DIR = join(homedir(), ".codex", "sessions");
  * 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.
+ * `sessionId` puts the bound account's directory FIRST, because a thread that
+ * has been continued on that account has its newest rollout there. It no longer
+ * restricts the search to it: an account switch — manual, or forced by a usage
+ * limit — leaves the conversation's history in the home of whichever account
+ * was serving when it was written. Searching the bound account alone is what
+ * made a switched session come back empty and silently start over as a new
+ * thread, since resume is only attempted when a rollout is found.
  */
 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"));
+  const accounts = listCodexAccounts();
+  const ordered = boundId
+    ? [...accounts.filter((a) => a.id === boundId), ...accounts.filter((a) => a.id !== boundId)]
+    : accounts;
+  for (const account of ordered) dirs.push(join(account.home, "sessions"));
   dirs.push(CODEX_SESSIONS_DIR);
   return dirs;
 }
@@ -76,6 +94,29 @@ function fromCodexSessionsDirs<T>(sessionId: string | undefined, read: (dir: str
   }
   return null;
 }
+
+/**
+ * The rollout for a thread AND the sessions directory it was found in.
+ *
+ * The directory is what a plain path cannot tell us, and resuming needs it: a rollout
+ * belonging to another account has to be copied into the serving account's own home before
+ * codex will resolve it, and the copy has to keep its position relative to that directory.
+ */
+function locateRollout(
+  sessionId: string,
+  cwd: string,
+): { path: string; sessionsDir: string } | null {
+  for (const dir of codexSessionsDirs(sessionId)) {
+    const found = findRolloutByThreadId(dir, sessionId, cwd);
+    if (found) return { path: found, sessionsDir: dir };
+  }
+  return null;
+}
+
+/** Where the app-server on this account writes and looks for rollouts. */
+function sessionsDirForHome(codexHome?: string): string {
+  return codexHome ? join(codexHome, "sessions") : CODEX_SESSIONS_DIR;
+}
 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;
@@ -118,6 +159,13 @@ interface LiveSession {
   interruptRequested?: boolean;
   /** Follow-ups waiting for the current turn, in the order they will be sent. */
   pendingTurns: QueuedTurn[];
+  /** A usage-limit rotation is underway: the old app-server is being torn down and
+   *  replaced by one running on another account. Everything the dying subprocess still
+   *  emits belongs to the turn being abandoned, so it is dropped rather than shown. */
+  rotating?: boolean;
+  /** The turn currently in flight, kept so a rotation can send it again on the new
+   *  account. Cleared when the turn ends — there is then nothing to replay. */
+  lastTurnInput?: { message: string; opts?: SendMessageOpts };
 }
 
 /** A follow-up held back because a turn was already running. */
@@ -281,6 +329,11 @@ export class CodexAppServerProvider implements AIProvider {
         sessions.push(s);
       }
     }
+    // A title the user set by hand outranks the one derived from the opening
+    // prompt, and it is the only place a renamed codex session is recorded.
+    const customTitles = getSessionTitles(sessions.map((s) => s.id));
+    for (const s of sessions) s.title = customTitles[s.id] ?? s.title;
+
     // Backfill provider ownership so reopening a pre-existing codex thread routes
     // to codex (not the default provider) even after a restart.
     //
@@ -328,7 +381,15 @@ export class CodexAppServerProvider implements AIProvider {
     this.startTurn(live, content, opts);
   }
 
-  private startTurn(live: LiveSession, message: string, opts?: SendMessageOpts): void {
+  /**
+   * Send a turn on the live thread.
+   *
+   * `replay` marks the same turn being sent again on a different account after a usage
+   * limit. It skips the transcript append only: the user typed the message once, and a
+   * second entry would both show it twice and shift every later `rollout-N` id, which
+   * fork anchors resolve against.
+   */
+  private startTurn(live: LiveSession, message: string, opts?: SendMessageOpts, replay = false): void {
     if (!live.threadId) return;
     // One turn at a time — anything sent now would be dropped without a trace.
     // `now` additionally cuts the running turn short so this one answers next.
@@ -351,7 +412,8 @@ export class CodexAppServerProvider implements AIProvider {
       });
       return;
     }
-    live.transcript.push({ id: nextRolloutId(live), role: "user", content: message, timestamp: new Date().toISOString() });
+    if (!replay) live.transcript.push({ id: nextRolloutId(live), role: "user", content: message, timestamp: new Date().toISOString() });
+    live.lastTurnInput = { message, opts };
     live.currentAssistant = "";
     live.currentEvents = [];
     // Codex takes an image as a path, never as a payload, so the uploaded copy is what it
@@ -371,7 +433,12 @@ export class CodexAppServerProvider implements AIProvider {
       const id = (res as { turn?: { id?: string } })?.turn?.id;
       if (id && !live.activeTurnId) this.setActiveTurn(live, id);
     }).catch((err) => {
-      if (!live.client.isClosed) live.channel.push({ type: "error", message: redactTruncate((err as Error)?.message ?? String(err), 256) });
+      const reason = (err as Error)?.message ?? String(err);
+      // A quota refusal can come back as the rejection of the request itself rather than
+      // as an `error` notification, and it is the same situation either way — move the
+      // turn to an account that still has room instead of showing the refusal.
+      if (isCodexUsageLimit(reason) && this.beginRotation(live, reason)) return;
+      if (!live.client.isClosed) live.channel.push({ type: "error", message: redactTruncate(reason, 256) });
       // No turn is running, so nothing will report `turn/completed` — release the
       // queue here or every later follow-up waits on a turn that never existed.
       this.endTurn(live);
@@ -410,10 +477,195 @@ export class CodexAppServerProvider implements AIProvider {
     live.turnInFlight = false;
     live.activeTurnId = null;
     live.interruptRequested = false;
+    live.lastTurnInput = undefined;
     const next = live.pendingTurns.shift();
     if (next) this.startTurn(live, next.message, next.opts);
   }
 
+  // ── Usage-limit rotation ──
+
+  /**
+   * Take over a turn Codex refused for an exhausted quota, if another account can serve it.
+   *
+   * Answers synchronously so the caller knows, before it decides what to show, whether the
+   * refusal is being handled or has to be reported. The rotation itself is asynchronous —
+   * it respawns a subprocess and resumes the thread — but whether one is possible is a
+   * question about which accounts exist, which needs no I/O.
+   *
+   * Returns false when nothing else could serve the turn, and the refusal then reaches the
+   * user untouched. That is the honest outcome: an error saying the quota is spent is worth
+   * more than a silent retry on the account that just said so.
+   */
+  private beginRotation(live: LiveSession, reason: string): boolean {
+    const threadId = live.threadId;
+    if (!threadId || live.rotating) return false;
+    const currentId = getSessionCodexAccount(threadId);
+    const candidates = listCodexAccounts().filter(
+      (a) => a.status !== "disabled" && a.id !== currentId && !isCodexAccountUsageLimited(a.id),
+    );
+    if (candidates.length === 0) return false;
+    live.rotating = true;
+    void this.rotateAccount(live, threadId, currentId, reason);
+    return true;
+  }
+
+  /** Park the spent account, move the session onto a fresh one, and send the turn again. */
+  private async rotateAccount(
+    live: LiveSession,
+    threadId: string,
+    currentId: string | null,
+    reason: string,
+  ): Promise<void> {
+    const pending = live.lastTurnInput;
+    const reset = parseCodexUsageLimitReset(reason);
+    if (currentId) markCodexAccountUsageLimited(currentId, reset?.atMs);
+
+    let next: CodexAccount | null = null;
+    try {
+      // Usage picks the emptiest of the remaining accounts rather than merely the next one,
+      // so a rotation forced by a limit does not land on an account that is nearly at its own.
+      const usages = await getAllCodexUsages();
+      next = selectCodexAccount({
+        usageOf: (id) => codexUsageLevel(usages[id]),
+        ...(currentId ? { exclude: [currentId] } : {}),
+      });
+    } catch {
+      next = selectCodexAccount(currentId ? { exclude: [currentId] } : undefined);
+    }
+
+    if (!next) { this.abandonRotation(live, reason, reset?.text); return; }
+
+    console.warn(`[codex] session=${threadId} usage limit — switching to ${next.id} (${next.label})`);
+    live.channel.push({
+      type: "account_retry",
+      reason: "Usage limit reached — switching account",
+      accountId: next.id,
+      accountLabel: next.label,
+    });
+
+    try {
+      await this.respawnOn(live, threadId, next);
+    } catch (e) {
+      console.error(`[codex] session=${threadId} rotation to ${next.id} failed: ${redactTruncate((e as Error)?.message, 200)}`);
+      this.abandonRotation(live, reason, reset?.text);
+      return;
+    }
+
+    live.rotating = false;
+    // The refused turn never reached `turn/completed`, so the flags it set are still on.
+    live.turnInFlight = false;
+    live.activeTurnId = null;
+    live.interruptRequested = false;
+    if (pending) this.startTurn(live, pending.message, pending.opts, true);
+    else this.endTurn(live);
+  }
+
+  /** No account could take the turn — report the refusal and close the turn out. */
+  private abandonRotation(live: LiveSession, reason: string, resetText?: string): void {
+    live.rotating = false;
+    const suffix = resetText ? ` Try again ${resetText}.` : "";
+    live.channel.push({
+      type: "error",
+      message: `${redactTruncate(reason, 512)}${suffix} Add another account in Settings → Accounts, or wait for the reset.`,
+    });
+    live.channel.push({ type: "done", sessionId: live.threadId ?? "", resultSubtype: "error_during_execution" });
+    this.endTurn(live);
+  }
+
+  /**
+   * Put this session's app-server on another account, keeping the session itself intact.
+   *
+   * The subprocess is replaced, not the `LiveSession`: the caller of `sendMessage` is
+   * iterating this session's channel, and handing it a new one would end its stream mid-turn
+   * and leave the rest of the answer with nobody listening. Transcript, history and pending
+   * follow-ups all survive for the same reason.
+   *
+   * The outgoing client's handlers are cleared before it is closed. `close()` only asks the
+   * process to exit, so its `close` event lands well after this returns — by which time
+   * `rotating` is off again, and the inherited `onClose` would tear down the session that
+   * had just been repaired.
+   */
+  private async respawnOn(live: LiveSession, threadId: string, account: CodexAccount): Promise<void> {
+    const old = live.client;
+    old.onNotification(() => {});
+    old.onServerRequest(() => {});
+    old.onClose(() => {});
+    const pid = old.pid;
+    const proc = old.process;
+    old.close();
+    if (process.platform === "win32" && pid) killProcessTree(pid);
+    else if (proc) setTimeout(() => { try { proc.kill("SIGKILL"); } catch { /* dead */ } }, 2000).unref?.();
+
+    // Written before the rollout lookup so the new account's own directory is searched
+    // first — on a second rotation that is where the freshest history sits.
+    setSessionCodexAccount(threadId, account.id);
+
+    const client = new CodexJsonRpcClient();
+    client.onNotification((n) => this.handleNotification(live, n));
+    client.onServerRequest((r) => this.handleServerRequest(live, r));
+    client.onClose(() => this.handleClose(live));
+    client.start({ cwd: live.cwd, codexHome: account.home });
+    live.client = client;
+
+    await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
+    client.notify("initialized");
+
+    const resumeBase = {
+      cwd: live.cwd,
+      sandbox: live.permission.sandbox,
+      approvalPolicy: live.permission.approvalPolicy,
+      ...(live.model ? { model: live.model } : {}),
+    };
+    const found = locateRollout(threadId, live.cwd);
+    if (found) {
+      await this.resumeThread(client, threadId, found, account.home, resumeBase);
+      return;
+    }
+    // No rollout yet means the limit hit the very first turn, before codex had written one.
+    // There is nothing to resume, so the thread starts fresh — and it comes back under a
+    // new id, which every map keyed by the old one has to learn about or the next turn is
+    // sent to a thread this app-server has never heard of.
+    const started = await client.request("thread/start", resumeBase);
+    const newId = extractThreadId(started);
+    if (!newId || newId === threadId) return;
+    live.threadId = newId;
+    this.live.set(newId, live);
+    const meta = this.sessions.get(threadId);
+    if (meta) { this.sessions.delete(threadId); meta.id = newId; this.sessions.set(newId, meta); }
+    setSessionMetadata(newId, meta?.projectName, live.cwd);
+    setSessionProvider(newId, this.id);
+    setSessionCodexAccount(newId, account.id);
+    live.channel.push({ type: "session_migrated", oldSessionId: threadId, newSessionId: newId });
+  }
+
+  /**
+   * Resume a thread from the rollout file we located, wherever it lives.
+   *
+   * The `path` matters because a rollout is written inside the CODEX_HOME of whichever
+   * account served the turn, and this app-server is running on the account serving the
+   * session NOW. Asked by thread id alone, it searches only its own home and answers "no
+   * rollout found for thread id …" for a conversation that plainly exists — which is how
+   * an account switch used to lose the history and open a brand-new thread instead.
+   *
+   * The id-only form is kept as a fallback for a codex build that predates `path`: there
+   * the argument is rejected outright, and a resume that can still work by id should not
+   * be downgraded into a new thread over a field name.
+   */
+  private async resumeThread(
+    client: CodexJsonRpcClient,
+    threadId: string,
+    found: { path: string; sessionsDir: string },
+    codexHome: string | undefined,
+    resumeBase: Record<string, unknown>,
+  ): Promise<unknown> {
+    const target = sessionsDirForHome(codexHome);
+    const path = localizeRollout(found.path, found.sessionsDir, target);
+    if (path !== found.path) {
+      console.log(`[codex] thread=${threadId} rollout copied into the serving account's home to resume`);
+    }
+    return client.request("thread/resume", { threadId, path, ...resumeBase });
+  }
+
   private async connect(sessionId: string, opts?: SendMessageOpts): Promise<LiveSession> {
     const meta = this.sessions.get(sessionId);
     const cwd = meta?.projectPath || getSessionProjectPath(sessionId) || process.cwd();
@@ -445,12 +697,12 @@ export class CodexAppServerProvider implements AIProvider {
     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 = !!fromCodexSessionsDirs(sessionId, (d) => findRolloutByThreadId(d, sessionId, cwd));
-    const result = isResume
-      ? await client.request("thread/resume", { threadId: sessionId, ...resumeBase })
+    const found = locateRollout(sessionId, cwd);
+    const result = found
+      ? await this.resumeThread(client, sessionId, found, account?.home, resumeBase)
       : await client.request("thread/start", resumeBase);
 
-    const threadId = extractThreadId(result) ?? (isResume ? sessionId : null);
+    const threadId = extractThreadId(result) ?? (found ? sessionId : null);
     if (!threadId) throw new Error("codex thread/start returned no thread id");
     live.threadId = threadId;
 
@@ -480,6 +732,16 @@ export class CodexAppServerProvider implements AIProvider {
   }
 
   private handleNotification(live: LiveSession, notif: JsonRpcNotification): void {
+    // A quota refusal is an ordinary `error` notification, so it has to be recognised
+    // before the mapper turns it into a plain error card in front of the user.
+    if (notif.method === "error" && !live.rotating) {
+      const reason = codexErrorMessage(notif.params);
+      if (isCodexUsageLimit(reason) && this.beginRotation(live, reason)) return;
+    }
+    // Mid-rotation the subprocess behind this session is being replaced. Anything it still
+    // emits describes the turn that was refused — including its `turn/completed`, which
+    // would close the turn the caller is about to be given a second time.
+    if (live.rotating) return;
     if (notif.method === "item/agentMessage/delta") {
       const d = (notif.params as { delta?: string })?.delta;
       if (typeof d === "string") live.currentAssistant += d;

package/src/providers/codex-app-server/codex-rollout-header.ts

@@ -0,0 +1,99 @@
+import { mapRolloutItem } from "./codex-rollout-items.ts";
+
+/**
+ * Line primitives for a codex rollout JSONL, plus the header a session list
+ * needs: which project the thread ran in, whether it is a thread of its own,
+ * and what to call it.
+ *
+ * Kept apart from the transcript parser because listing reads every rollout in
+ * the tree while parsing reads one — the listing path must be able to stop at
+ * the first few records instead of walking a multi-megabyte transcript.
+ */
+
+export interface RolloutLine {
+  timestamp?: string;
+  type?: string;
+  payload?: Record<string, unknown>;
+}
+
+/** Split into complete, newline-terminated lines only (drop a trailing partial). */
+export function completeLines(text: string): string[] {
+  const lines = text.split("\n");
+  // If the text does not end in a newline, the last element is a partial line.
+  if (!text.endsWith("\n")) lines.pop();
+  return lines.filter((l) => l.trim() !== "");
+}
+
+export function parseLine(line: string): RolloutLine | null {
+  try { return JSON.parse(line) as RolloutLine; } catch { return null; }
+}
+
+export interface RolloutHeader {
+  id?: string;
+  cwd?: string;
+  timestamp?: string;
+  /**
+   * The thread that spawned this one. Present ONLY on a subagent's own rollout,
+   * which codex writes into the same sessions tree as a real conversation — so
+   * this is what separates "a session the user started" from "one step inside
+   * one".
+   */
+  parentThreadId?: string;
+  /** First user prompt, trimmed to a session-list label. */
+  title?: string;
+}
+
+/** How far into a rollout to look for the opening prompt before giving up. */
+const TITLE_SCAN_LINES = 2000;
+const TITLE_MAX_CHARS = 80;
+
+/** First user prompt → a one-line label. */
+function toTitle(text: string): string | undefined {
+  const flat = text.replace(/\s+/g, " ").trim();
+  if (!flat) return undefined;
+  return flat.length > TITLE_MAX_CHARS ? `${flat.slice(0, TITLE_MAX_CHARS - 1)}…` : flat;
+}
+
+/**
+ * Read the `session_meta` header, and (when `withTitle`) the first user prompt.
+ *
+ * A subagent rollout has no user prompt at all — its task arrives as encrypted
+ * scaffolding — so the title scan is skipped for one rather than walking the
+ * whole file to find nothing.
+ */
+export function readRolloutHeader(text: string, opts?: { withTitle?: boolean }): RolloutHeader | null {
+  let header: RolloutHeader | null = null;
+  let scanned = 0;
+
+  for (const line of completeLines(text)) {
+    const rec = parseLine(line);
+    if (!rec) continue;
+    const p = rec.payload ?? {};
+
+    if (rec.type === "session_meta" && !header) {
+      header = {
+        id: typeof p.id === "string" ? p.id : undefined,
+        cwd: typeof p.cwd === "string" ? p.cwd : undefined,
+        timestamp: typeof p.timestamp === "string" ? p.timestamp : rec.timestamp,
+        parentThreadId: typeof p.parent_thread_id === "string" ? p.parent_thread_id : undefined,
+      };
+      if (!opts?.withTitle || header.parentThreadId) return header;
+      continue;
+    }
+
+    if (!header || rec.type !== "event_msg") continue;
+    if (++scanned > TITLE_SCAN_LINES) break;
+
+    if (p.type === "user_message" && typeof p.message === "string") {
+      header.title = toTitle(p.message);
+      if (header.title) return header;
+    } else if (p.type === "item_completed") {
+      const mapped = mapRolloutItem(p.item);
+      if (mapped.kind === "user") {
+        header.title = toTitle(mapped.text);
+        if (header.title) return header;
+      }
+    }
+  }
+  return header;
+}

package/src/providers/codex-app-server/codex-rollout-items.ts

@@ -1,5 +1,6 @@
 import type { ChatEvent } from "../provider.interface.ts";
 import { redactTruncate } from "./codex-redact.ts";
+import { parseSubagentActivity, type SubagentActivity } from "./codex-subagent-thread.ts";
 
 /**
  * Rollout `item_completed` records → PPM chat events.
@@ -25,6 +26,9 @@ export type RolloutItemMapping =
   | { kind: "user"; text: string }
   | { kind: "assistant"; text: string }
   | { kind: "events"; events: ChatEvent[] }
+  // A spawned thread: the parser turns it into a card and hangs the child
+  // transcript under it, which needs the sessions dir it cannot reach itself.
+  | { kind: "subagent"; activity: SubagentActivity }
   | { kind: "ignore" };
 
 const IGNORED_ITEM_TYPES = new Set([
@@ -129,6 +133,8 @@ export function mapRolloutItem(item: unknown): RolloutItemMapping {
   const type = typeof it.type === "string" ? it.type : "";
 
   if (IGNORED_ITEM_TYPES.has(type)) return { kind: "ignore" };
+  const subagent = parseSubagentActivity(it);
+  if (subagent) return { kind: "subagent", activity: subagent };
   if (type === "UserMessage") {
     const text = textFrom(it.content);
     return text ? { kind: "user", text } : { kind: "ignore" };

package/src/providers/codex-app-server/codex-rollout-transfer.ts

@@ -0,0 +1,58 @@
+/**
+ * Moving a conversation's transcript into the CODEX_HOME that is about to serve it.
+ *
+ * Codex resolves a thread only against its OWN sessions directory. The `path` argument to
+ * `thread/resume` looks like an escape from that, and it is not: a path outside the running
+ * app-server's CODEX_HOME is refused with the same "no rollout found for thread id" as
+ * passing no path at all. Verified directly — the identical request succeeds when the
+ * app-server runs on the home the rollout lives in, and fails when it runs on another.
+ *
+ * So a session that changes account — because the user picked a different one, or because a
+ * usage limit forced the move — has its history sitting in a directory the new account's
+ * app-server will not look in, and resuming it is impossible until the file is there. It
+ * gets copied rather than moved: the account it came from may still be serving other
+ * sessions whose own history sits in the same tree, and the original is what PPM reads for
+ * any view of the conversation that is not this live thread.
+ *
+ * From here codex appends to the copy, so the newest history is in the account now serving
+ * the session — which is why `codexSessionsDirs` searches the bound account's directory
+ * first.
+ */
+
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+/** Case-insensitive on win32, so two spellings of one directory compare equal. */
+function samePath(a: string, b: string): boolean {
+  const norm = (p: string) => (process.platform === "win32" ? resolve(p).toLowerCase() : resolve(p));
+  return norm(a) === norm(b);
+}
+
+/**
+ * Ensure a rollout is inside `targetSessionsDir`, and return the path to use.
+ *
+ * A rollout already in the target directory is returned untouched — the common case, where
+ * the session is still on the account that wrote it, and nothing should be copied.
+ *
+ * The relative layout is preserved (`YYYY/MM/DD/rollout-….jsonl`) because that is where
+ * codex's own scan expects to find it.
+ *
+ * Failures are surfaced rather than swallowed: the caller's next act is a resume that
+ * cannot work without this, and a silent failure there turns into a conversation that
+ * quietly starts over as a new thread.
+ */
+export function localizeRollout(
+  rolloutPath: string,
+  foundInSessionsDir: string,
+  targetSessionsDir: string,
+): string {
+  if (samePath(foundInSessionsDir, targetSessionsDir)) return rolloutPath;
+  const dest = join(targetSessionsDir, relative(foundInSessionsDir, rolloutPath));
+  if (existsSync(dest)) return dest;
+  const destDir = dirname(dest);
+  // Only create what is missing. A recursive mkdir over an existing Windows directory
+  // carrying the read-only attribute throws EEXIST rather than succeeding quietly.
+  if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+  copyFileSync(rolloutPath, dest);
+  return dest;
+}

package/src/providers/codex-app-server/codex-subagent-thread.ts

@@ -0,0 +1,103 @@
+import type { ChatEvent, ChatMessage } from "../provider.interface.ts";
+import { redactTruncate } from "./codex-redact.ts";
+
+/**
+ * Subagent threads, rendered as one Agent card in the conversation that spawned
+ * them.
+ *
+ * Codex writes a spawned subagent as a rollout of its own, in the same sessions
+ * tree and with the same `cwd` as a real conversation. Left alone it surfaces
+ * twice over: once as a top-level session that opens mid-stream (it has no user
+ * prompt — the task is handed over as encrypted scaffolding), and once as two
+ * bare `SubAgentActivity` cards in the parent. Folding the child transcript into
+ * the parent's card is what makes it one step of one conversation again.
+ */
+
+/** Codex spells the item PascalCase in a rollout and camelCase on the wire. */
+export const SUBAGENT_ITEM_TYPES = new Set(["SubAgentActivity", "subAgentActivity"]);
+
+export interface SubagentActivity {
+  /** Rollout id of the spawned thread — the link to its transcript. */
+  threadId: string;
+  /** Codex's name for the agent, e.g. `/root/simplify_login`. */
+  path: string;
+  done: boolean;
+}
+
+/** The transcript of a spawned thread, ready to hang under its card. */
+export interface SubagentTranscript {
+  events: ChatEvent[];
+  /** The agent's closing message — its report back to the parent. */
+  finalText: string;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v ? v : undefined;
+}
+
+/** A `SubAgentActivity` item → normalized activity, or null if it is not one. */
+export function parseSubagentActivity(item: unknown): SubagentActivity | null {
+  if (!item || typeof item !== "object") return null;
+  const it = item as Record<string, unknown>;
+  if (!SUBAGENT_ITEM_TYPES.has(String(it.type ?? ""))) return null;
+  const threadId = str(it.agent_thread_id) ?? str(it.agentThreadId);
+  if (!threadId) return null;
+  const kind = String(it.kind ?? "");
+  return {
+    threadId,
+    path: str(it.agent_path) ?? str(it.agentPath) ?? "subagent",
+    done: kind === "completed" || kind === "failed",
+  };
+}
+
+/**
+ * Card id derived from the spawned thread.
+ *
+ * The started and completed records carry DIFFERENT item ids (`call_…` vs
+ * `subagent-completed-…`), so pairing on the item id leaves the call unanswered
+ * and the completion orphaned as a second card. The thread they both name is
+ * the stable key.
+ */
+export function subagentCardId(threadId: string): string {
+  return `subagent-${threadId}`;
+}
+
+/** The spawn, as the Agent card the chat already knows how to expand. */
+export function subagentToolUse(activity: SubagentActivity, transcript?: SubagentTranscript | null): ChatEvent {
+  return {
+    type: "tool_use",
+    tool: "Agent",
+    input: { description: activity.path },
+    toolUseId: subagentCardId(activity.threadId),
+    ...(transcript?.events.length ? { children: transcript.events } : {}),
+  };
+}
+
+/** The completion, answering the card above with the agent's own report. */
+export function subagentToolResult(activity: SubagentActivity, transcript?: SubagentTranscript | null): ChatEvent {
+  return {
+    type: "tool_result",
+    output: redactTruncate(transcript?.finalText || `${activity.path} finished`),
+    toolUseId: subagentCardId(activity.threadId),
+  };
+}
+
+/** A parsed child transcript → the flat event list a card nests. */
+export function transcriptToEvents(messages: ChatMessage[]): ChatEvent[] {
+  const events: ChatEvent[] = [];
+  for (const m of messages) {
+    // An assistant turn with tool calls already carries its text as the last event.
+    if (m.events?.length) events.push(...m.events);
+    else if (m.content) events.push({ type: "text", content: m.content });
+  }
+  return events;
+}
+
+/** The agent's closing message, which is what it reported back. */
+export function finalAssistantText(messages: ChatMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]!;
+    if (m.role === "assistant" && m.content) return m.content;
+  }
+  return "";
+}