@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/codex/orca-import.ts

@@ -0,0 +1,219 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, unlinkSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { atomicWriteFile, getConfigDir, getConfigPath, mutatePersistedConfig, readConfigDiagnostics, withConfigMutationLockSync } from "../config";
+import { readAlivePid, readRuntimePort } from "../config/process-state";
+import { getCodexHome } from "./paths";
+import { advanceCodexCredentialMutationEpoch } from "./credential-mutation-epoch";
+import { assertPlainLocalPath, ORCA_ACCOUNT_DIRECTORY, parseOrcaAuth, readBoundedLocalFile, readOrcaAuthSource, sameLocalPath } from "./orca-auth-source";
+
+export class OrcaImportError extends Error {
+  constructor(message: string) { super(message); this.name = "OrcaImportError"; }
+}
+
+export interface OrcaImportResult {
+  mode: "preview" | "apply";
+  discovered: number;
+  eligible: number;
+  imported: number;
+  duplicates: number;
+  invalid: number;
+  invalidReasons: Partial<Record<OrcaImportInvalidReason, number>>;
+}
+
+export type OrcaImportInvalidReason = "unsupported_entry" | "home_mismatch" | "source_invalid";
+
+class OrcaImportEntryError extends Error {
+  constructor(readonly reason: OrcaImportInvalidReason) { super(reason); }
+}
+
+function noteInvalid(result: OrcaImportResult, error: unknown): void {
+  const reason = error instanceof OrcaImportEntryError ? error.reason : "source_invalid";
+  result.invalid++;
+  result.invalidReasons[reason] = (result.invalidReasons[reason] ?? 0) + 1;
+}
+
+function optionalFile(path: string): string | undefined {
+  try { return readBoundedLocalFile(path, 4 * 1024 * 1024); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new OrcaImportError("A target or main credential file is unreadable; import refused.");
+  }
+}
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new OrcaImportError("Invalid existing account state; import refused.");
+  return value as Record<string, unknown>;
+}
+
+function assertStopped(): void {
+  let running = readAlivePid() !== null;
+  const runtime = readRuntimePort();
+  if (runtime) {
+    try { process.kill(runtime.pid, 0); running = true; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") running = true; }
+  }
+  if (running) throw new OrcaImportError("Stop the opencodex proxy before applying an Orca import.");
+}
+
+function prepare(sourceDir: string, registryPath: string) {
+  const configRaw = optionalFile(getConfigPath());
+  if (!configRaw || readConfigDiagnostics().source !== "file") {
+    throw new OrcaImportError("Initialize a valid opencodex configuration before importing.");
+  }
+  const config = object(JSON.parse(configRaw));
+  const accounts = config.codexAccounts ?? [];
+  if (!Array.isArray(accounts)) throw new OrcaImportError("Invalid existing account configuration.");
+  const identities = new Set<string>();
+  const configuredIds = new Set<string>();
+  for (const entry of accounts) {
+    const row = object(entry);
+    if (typeof row.id === "string") configuredIds.add(row.id);
+    if (row.chatgptAccountId !== undefined && typeof row.chatgptAccountId !== "string") throw new OrcaImportError("Invalid existing account identity.");
+    if (typeof row.chatgptAccountId === "string" && row.chatgptAccountId) identities.add(row.chatgptAccountId);
+  }
+  const reservedIdentities = new Set(identities);
+  const storedIdentityCounts = new Map<string, number>();
+  const recoverable = new Map<string, { id: string; credential: Record<string, unknown> }>();
+  const storePath = join(getConfigDir(), "codex-accounts.json");
+  const storeRaw = optionalFile(storePath);
+  const store = storeRaw === undefined ? {} : object(JSON.parse(storeRaw));
+  for (const [id, entry] of Object.entries(store)) {
+    const record = object(entry);
+    // Retain orphan and tombstoned records; a credential is still evidence of identity.
+    if (record.credential === undefined && typeof record.generation === "number") continue;
+    const credential = object(record.credential ?? record);
+    if (typeof credential.chatgptAccountId !== "string" || !credential.chatgptAccountId
+      || typeof credential.accessToken !== "string" || typeof credential.refreshToken !== "string"
+      || typeof credential.expiresAt !== "number") throw new OrcaImportError("Invalid existing credential store.");
+    identities.add(credential.chatgptAccountId);
+    storedIdentityCounts.set(credential.chatgptAccountId, (storedIdentityCounts.get(credential.chatgptAccountId) ?? 0) + 1);
+    // A process can die after the credential rename but before config registration. Only
+    // the untouched initial record emitted by this importer may finish that registration.
+    // Older, validated, replaced, tombstoned, or independently owned orphans remain blockers.
+    if (id.startsWith("orca-") && ORCA_ACCOUNT_DIRECTORY.test(id.slice(5)) && !configuredIds.has(id)
+      && record.generation === 1 && record.codexValidationPending === true
+      && record.deletedAt === undefined && record.replacedAt === undefined
+      && record.lastCodexValidatedAt === undefined && record.lastCodexValidationStatus === undefined
+      && record.lastCodexValidationError === undefined && record.lastCodexValidationTerminal === undefined
+      && credential.refreshToken === "" && typeof credential.sourceAuthPath === "string"
+      && typeof credential.sourceSubject === "string" && credential.sourceSubject) {
+      recoverable.set(credential.chatgptAccountId, { id, credential });
+    }
+  }
+  const mainRaw = optionalFile(join(getCodexHome(), "auth.json"));
+  if (mainRaw !== undefined) {
+    const main = object(JSON.parse(mainRaw));
+    if (main.tokens !== undefined) {
+      const identity = parseOrcaAuth(mainRaw, false).chatgptAccountId;
+      identities.add(identity);
+      reservedIdentities.add(identity);
+    }
+    else if (typeof main.OPENAI_API_KEY !== "string") throw new OrcaImportError("Main Codex identity is unknown; import refused.");
+  }
+  const root = assertPlainLocalPath(resolve(sourceDir));
+  const directory = assertPlainLocalPath(join(root, "codex-accounts"));
+  if (!lstatSync(directory).isDirectory()) throw new OrcaImportError("Invalid Orca data directory.");
+  const registryRaw = readBoundedLocalFile(resolve(registryPath), 32 * 1024 * 1024);
+  const registry = object(JSON.parse(registryRaw));
+  const registered = object(registry.settings).codexManagedAccounts;
+  if (!Array.isArray(registered) || registered.length > 1024) {
+    throw new OrcaImportError("Invalid Orca account registry or account limit exceeded.");
+  }
+  const result: OrcaImportResult = {
+    mode: "preview", discovered: registered.length, eligible: 0, imported: 0,
+    duplicates: 0, invalid: 0, invalidReasons: {},
+  };
+  const candidates: { credential: ReturnType<typeof readOrcaAuthSource>; recoverId?: string }[] = [];
+  const sourceIds = new Set<string>();
+  for (const entry of registered) {
+    try {
+      const row = object(entry);
+      if (typeof row.id !== "string" || !ORCA_ACCOUNT_DIRECTORY.test(row.id)
+        || typeof row.managedHomePath !== "string"
+        || (row.managedHomeRuntime !== undefined && row.managedHomeRuntime !== "host")) {
+        throw new OrcaImportEntryError("unsupported_entry");
+      }
+      const home = join(directory, row.id, "home");
+      if (!sameLocalPath(assertPlainLocalPath(row.managedHomePath), assertPlainLocalPath(home))) {
+        throw new OrcaImportEntryError("home_mismatch");
+      }
+      if (sourceIds.has(row.id)) { result.duplicates++; continue; }
+      sourceIds.add(row.id);
+      const credential = readOrcaAuthSource(join(home, "auth.json"));
+      let recoverId: string | undefined;
+      if (identities.has(credential.chatgptAccountId)) {
+        const orphan = recoverable.get(credential.chatgptAccountId);
+        if (orphan && !reservedIdentities.has(credential.chatgptAccountId)
+          && storedIdentityCounts.get(credential.chatgptAccountId) === 1
+          && sameLocalPath(orphan.credential.sourceAuthPath as string, credential.sourceAuthPath)
+          && orphan.credential.sourceSubject === credential.sourceSubject) {
+          recoverId = orphan.id;
+          recoverable.delete(credential.chatgptAccountId);
+        } else { result.duplicates++; continue; }
+      }
+      identities.add(credential.chatgptAccountId);
+      candidates.push({ credential, recoverId });
+      result.eligible++;
+    } catch (error) { noteInvalid(result, error); }
+  }
+  return { configRaw, registryRaw, storeRaw, storePath, store, candidates, result };
+
+}
+
+/** Offline, explicit-source import. The returned report deliberately contains no identities or paths. */
+export function importOrcaAccounts(options: { sourceDir: string; registryPath: string; apply?: boolean }): OrcaImportResult {
+  try {
+    if (!options.apply) return prepare(options.sourceDir, options.registryPath).result;
+    assertStopped();
+    return withConfigMutationLockSync(() => {
+      assertStopped();
+      const state = prepare(options.sourceDir, options.registryPath);
+      state.result.mode = "apply";
+      if (!state.candidates.length) return state.result;
+      const writesCredentials = state.candidates.some(candidate => candidate.recoverId === undefined);
+      const additions = state.candidates.map(({ credential, recoverId }) => {
+        let id = recoverId;
+        if (id === undefined) {
+          do { id = `orca-${randomUUID()}`; } while (state.store[id]);
+          state.store[id] = { credential, generation: 1, codexValidationPending: true };
+        }
+        return { id, email: "", alias: "Orca account", isMain: false, chatgptAccountId: credential.chatgptAccountId };
+      });
+      // Re-read registry and sources immediately before publishing either target file.
+      if (readBoundedLocalFile(resolve(options.registryPath), 32 * 1024 * 1024) !== state.registryRaw) {
+        throw new OrcaImportError("Orca registry changed during import; retry.");
+      }
+      for (const { credential } of state.candidates) {
+        if (JSON.stringify(readOrcaAuthSource(credential.sourceAuthPath)) !== JSON.stringify(credential)) {
+          throw new OrcaImportError("Orca credentials changed during import; retry.");
+        }
+      }
+      assertStopped();
+      if (optionalFile(getConfigPath()) !== state.configRaw || optionalFile(state.storePath) !== state.storeRaw) {
+        throw new OrcaImportError("Target accounts changed during import; retry.");
+      }
+      if (writesCredentials) atomicWriteFile(state.storePath, JSON.stringify(state.store, null, 2) + "\n");
+      try {
+        const outcome = mutatePersistedConfig(config => {
+          if (optionalFile(getConfigPath()) !== state.configRaw) throw new OrcaImportError("Target configuration changed; retry.");
+          config.codexAccounts = [...(config.codexAccounts ?? []), ...additions];
+          return { changed: true, value: undefined };
+        });
+        if (outcome.status !== "committed") throw new OrcaImportError("Target configuration could not be committed.");
+      } catch (error) {
+        if (writesCredentials) {
+          if (state.storeRaw === undefined) unlinkSync(state.storePath);
+          else atomicWriteFile(state.storePath, state.storeRaw);
+        }
+        throw error;
+      }
+      advanceCodexCredentialMutationEpoch();
+      state.result.imported = additions.length;
+      return state.result;
+    });
+  } catch (error) {
+    if (error instanceof OrcaImportError) throw error;
+    throw new OrcaImportError("Orca import could not complete; verify source and target local account files.");
+  }
+}

package/src/codex/prompt-text-probe.ts

@@ -8,8 +8,11 @@
  *
  * What this does NOT cover, stated rather than implied:
  *
- * - `base-instructions` is absent. `prompt_debug.rs` returns `prompt.input` and
- *   discards `base_instructions`, so the base prompt never appears here.
+ * - `base-instructions` is absent from the probed output: Codex returns
+ *   `prompt.input` and discards `base_instructions`, so the base prompt never
+ *   appears there. It is read here from the configured sources instead - the
+ *   `model_instructions_file` override when one is set, otherwise the selected
+ *   model's catalog row - and reported separately as `base`.
  * - World-state sections are DIFF-rendered (`add_section` registers state, it does
  *   not emit text). A section that renders nothing on a first turn is missing
  *   from this output even though its layer exists.
@@ -17,8 +20,10 @@
  *   universal prompt.
  */
 import { spawn } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, constants, existsSync, fstatSync, openSync, readSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { expandUserPath } from "../config";
+import { parseCatalogJson, readCodexCatalogPathForHome, type RawCatalog, type RawEntry } from "./catalog/parsing";
 import { codexExecInvocation } from "./exec-invocation";
 import { resolveCodexHomeDir } from "./home";
 import {
@@ -70,7 +75,7 @@ const UNMAPPED_LAYER_IDS = [
   // The Rust source names a <git_attribution> marker pair, but a world-state section is
   // DIFF-rendered: it emits nothing on a turn where its state has not changed. Live
   // `codex debug prompt-input` (codex-cli 0.145.0, 32978 bytes) showed no such block and
-  // no attribution text. Listing the id here reports "not exposed" honestly instead of
+  // no attribution text. Listing the id here reports "unmapped" honestly instead of
   // claiming a tag this extractor has never actually matched - the same mistake the
   // header above records for permissions.
   "git-attribution",
@@ -80,12 +85,60 @@ export interface LayerText {
   /** Rendered text, when this layer produced a section on the probed turn. */
   text: string | null;
   /** Why the text is absent, when it is. */
-  reason: "ok" | "empty-source" | "not-rendered" | "not-exposed" | "unavailable";
+  reason: "ok" | "empty-source" | "not-rendered" | "not-exposed" | "unmapped" | "unavailable";
   bytes: number;
-  /** For `empty-source`: the file that exists but has nothing in it. */
+  /**
+   * `expanded` is text Codex sends as written. `template` is a catalog
+   * `instructions_template`, which Codex expands before sending. Absent for every
+   * layer read out of the probed output, whose text is rendered by definition.
+   */
+  representation?: "expanded" | "template";
+  /**
+   * For `empty-source`: the file that exists but has nothing in it. For
+   * `base-instructions`: the configured file the base prompt was read from, or
+   * the one that could not be read.
+   */
   sourcePath?: string;
 }
 
+/**
+ * Why the base prompt is or is not readable, at the granularity a reader can act
+ * on. `LayerText.reason` has six coarse values and cannot express any of this,
+ * which is why the detailed answer travels on its own record.
+ */
+export type BasePromptReason =
+  | "ok"
+  | "config-not-found"
+  | "config-unreadable"
+  | "config-too-large"
+  | "model-not-selected"
+  | "model-not-found"
+  | "catalog-not-found"
+  | "catalog-unreadable"
+  | "catalog-too-large"
+  | "not-published"
+  | "override-empty"
+  | "override-not-found"
+  | "override-too-large"
+  | "override-unreadable";
+
+export interface BasePromptText {
+  /** The base prompt, when a configured source published one. */
+  text: string | null;
+  reason: BasePromptReason;
+  bytes: number;
+  /** The model selected in `config.toml`, when the config named one. */
+  model: string | null;
+  /** The file the answer came from, when a file was reached at all. */
+  sourcePath: string | null;
+  /**
+   * `expanded` is the text Codex sends. `template` is a catalog
+   * `instructions_template`: a template even when it currently carries no
+   * placeholder, so it is never presented as the text the model receives.
+   */
+  representation: "expanded" | "template" | "unavailable";
+}
+
 /**
  * Why a probe failed, as a stable token the caller can branch on. The prose
  * `detail` string is kept for display, but matching on it was never a contract:
@@ -116,6 +169,12 @@ export interface PromptTextProbe {
   /** The Codex home the probe reported on. */
   codexHome: string;
   layers: Record<string, LayerText>;
+  /**
+   * The base prompt, read from configuration rather than from the probed output.
+   * Present on every outcome: it is computed before the subprocess, so it answers
+   * even when Codex cannot be resolved, the probe fails, or the caller cancels.
+   */
+  base: BasePromptText;
   /** The runtime the probe resolved and tried, when resolution produced one. */
   runtime?: { command: string; source: CodexRuntimeSource };
   /** Stable failure classification; `detail` remains the display string. */
@@ -129,6 +188,208 @@ const MAX_PROBE_OUTPUT_BYTES = 8 * 1024 * 1024;
 /** stderr is captured only to classify the failure, never to echo back. */
 const MAX_PROBE_STDERR_BYTES = 64 * 1024;
 
+/** Read chunk for local prompt sources; the ceiling is MAX_PROBE_OUTPUT_BYTES. */
+const PROMPT_SOURCE_CHUNK_BYTES = 64 * 1024;
+
+function errorWithCode(message: string, code: string): NodeJS.ErrnoException {
+  const error = new Error(message) as NodeJS.ErrnoException;
+  error.code = code;
+  return error;
+}
+
+function errorCodeOf(error: unknown): string | undefined {
+  return (error as NodeJS.ErrnoException | null)?.code;
+}
+
+/**
+ * Read one configured prompt source, bounded, from a single descriptor.
+ *
+ * Three properties are load-bearing, and all three are about this running
+ * synchronously on the Bun request thread:
+ *
+ * - `O_NONBLOCK` is set BEFORE anything else. `openSync(path, "r")` on a FIFO with
+ *   no writer blocks forever, and nothing can recover it: the probe timeout and
+ *   request cancellation both need the event loop this call is holding. Windows
+ *   has no such flag, so the constant is absent there and contributes nothing.
+ * - The regular-file check reads `fstatSync` on the OPENED descriptor. A path stat
+ *   describes whatever the name pointed at a moment ago, not what got opened.
+ * - The ceiling is enforced while reading, not from a preflight size. A
+ *   stat-then-read pair is a window in which the file can change, and it would let
+ *   an unbounded body through into a management-API response.
+ */
+function readBoundedPromptSource(path: string): string {
+  // `O_NONBLOCK` is POSIX-only: Windows omits it from `fs.constants` even though the
+  // type declares it, so it is read defensively and contributes nothing there.
+  const nonBlocking = (constants as { O_NONBLOCK?: number }).O_NONBLOCK ?? 0;
+  const descriptor = openSync(path, constants.O_RDONLY | nonBlocking);
+  try {
+    if (!fstatSync(descriptor).isFile()) {
+      throw errorWithCode(`prompt source is not a regular file: ${path}`, "EFTYPE");
+    }
+    const parts: Buffer[] = [];
+    const view = Buffer.allocUnsafe(PROMPT_SOURCE_CHUNK_BYTES);
+    let total = 0;
+    for (;;) {
+      const read = readSync(descriptor, view, 0, view.length, total);
+      if (read === 0) break;
+      total += read;
+      // One byte past the ceiling is the whole answer: refuse before the content
+      // is retained, so an oversized source costs no more than a bounded read.
+      if (total > MAX_PROBE_OUTPUT_BYTES) {
+        throw errorWithCode(`prompt source exceeds ${MAX_PROBE_OUTPUT_BYTES} bytes: ${path}`, "EFBIG");
+      }
+      parts.push(Buffer.from(view.subarray(0, read)));
+    }
+    return Buffer.concat(parts).toString("utf8");
+  } finally {
+    try { closeSync(descriptor); } catch { /* the descriptor is already unusable */ }
+  }
+}
+
+function unavailableBase(
+  reason: BasePromptReason,
+  model: string | null = null,
+  sourcePath: string | null = null,
+): BasePromptText {
+  return { text: null, reason, bytes: 0, model, sourcePath, representation: "unavailable" };
+}
+
+function readableBase(
+  text: string,
+  representation: "expanded" | "template",
+  model: string,
+  sourcePath: string,
+): BasePromptText {
+  return { text, reason: "ok", bytes: Buffer.byteLength(text, "utf8"), model, sourcePath, representation };
+}
+
+function publishedString(entry: RawEntry, key: string): string | null {
+  const value = entry[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+/**
+ * The base prompt for the configured model, read from the same files Codex reads.
+ *
+ * Precedence follows Codex: `model_instructions_file` replaces the base prompt
+ * outright, so an override that is set decides the answer whether or not it can be
+ * read. Without one, the selected catalog row's `base_instructions` is the
+ * published text, and `model_messages.instructions_template` is the fallback -
+ * reported as a template, because that is what it is.
+ *
+ * Every failure is a reason, never an exception: this feeds a GET that must
+ * degrade to "we could not read it" rather than to a 500.
+ */
+function readBasePrompt(codexHome: string): BasePromptText {
+  const configPath = join(codexHome, "config.toml");
+  let configText: string;
+  try {
+    configText = readBoundedPromptSource(configPath);
+  } catch (error) {
+    // ENOENT is "no config"; anything else is "the config we have could not be
+    // read". `existsSync` cannot separate those: it races the read, and it reports
+    // a permission failure as absence.
+    const code = errorCodeOf(error);
+    return unavailableBase(
+      code === "ENOENT" ? "config-not-found" : code === "EFBIG" ? "config-too-large" : "config-unreadable",
+    );
+  }
+  let root: Record<string, unknown>;
+  try {
+    const parsed = Bun.TOML.parse(configText);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("config.toml is not a table");
+    root = parsed as Record<string, unknown>;
+  } catch {
+    // The WHOLE document has to parse before any key from it is trusted. Codex
+    // rejects a malformed config outright, so a model scraped out of the readable
+    // first lines would make this display a prompt that is never sent.
+    return unavailableBase("config-unreadable", null, configPath);
+  }
+  const configuredModel = typeof root.model === "string" ? root.model.trim() : "";
+  // A `model_instructions_file` with no model is out of scope here: the base
+  // prompt this reports on is the selected model's, and there is no selection.
+  if (!configuredModel) return unavailableBase("model-not-selected", null, configPath);
+  const model = configuredModel;
+
+  const override = typeof root.model_instructions_file === "string" ? root.model_instructions_file : null;
+  if (override !== null) {
+    // A blank value names no file. The key is still set, so Codex does not fall
+    // back to the catalog default and neither does this: reporting the catalog row
+    // would describe a base prompt this configuration never produces.
+    if (override.trim().length === 0) return unavailableBase("override-not-found", model);
+    // Relative to the config file's own directory, which is how the rest of this
+    // repository resolves the key.
+    const overridePath = resolve(dirname(configPath), expandUserPath(override));
+    let text: string;
+    try {
+      text = readBoundedPromptSource(overridePath);
+    } catch (error) {
+      const code = errorCodeOf(error);
+      return unavailableBase(
+        code === "ENOENT" ? "override-not-found" : code === "EFBIG" ? "override-too-large" : "override-unreadable",
+        model,
+        overridePath,
+      );
+    }
+    // Codex rejects this config with "model instructions file is empty", so
+    // reporting `ok` here would claim text that is never sent - and claim it for a
+    // configuration that does not start.
+    if (text.trim().length === 0) return unavailableBase("override-empty", model, overridePath);
+    return readableBase(text, "expanded", model, overridePath);
+  }
+
+  const catalogPath = readCodexCatalogPathForHome(codexHome, configText);
+  let catalog: RawCatalog | null;
+  try {
+    catalog = parseCatalogJson(readBoundedPromptSource(catalogPath));
+  } catch (error) {
+    const code = errorCodeOf(error);
+    return unavailableBase(
+      code === "ENOENT" ? "catalog-not-found" : code === "EFBIG" ? "catalog-too-large" : "catalog-unreadable",
+      model,
+      catalogPath,
+    );
+  }
+  if (!catalog) return unavailableBase("catalog-unreadable", model, catalogPath);
+  // Each candidate is guarded rather than trusted: `parseCatalogJson` validates
+  // only that `models` is an array, so a row of `null` would throw on property
+  // access and turn this read into a 500 on the management API.
+  const entry = catalog.models?.find(candidate => (
+    candidate !== null
+    && typeof candidate === "object"
+    && !Array.isArray(candidate)
+    && (candidate.slug === model || candidate.id === model)
+  )) ?? null;
+  if (!entry) return unavailableBase("model-not-found", model, catalogPath);
+  const published = publishedString(entry, "base_instructions");
+  if (published) return readableBase(published, "expanded", model, catalogPath);
+  const messages = entry.model_messages;
+  const template = messages !== null && typeof messages === "object" && !Array.isArray(messages)
+    ? publishedString(messages as RawEntry, "instructions_template")
+    : null;
+  if (template) return readableBase(template, "template", model, catalogPath);
+  return unavailableBase("not-published", model, catalogPath);
+}
+
+/**
+ * Project the base prompt onto the legacy `base-instructions` layer slot.
+ *
+ * The slot is lossy by construction - six coarse reasons, no renderer that reads
+ * `representation` - so it carries only what it can carry honestly: published text
+ * when the source is text Codex sends, and otherwise no text at all. A template is
+ * deliberately NOT `ok` here, because the dialog labels every `ok` layer "Text
+ * sent to the model" and an unexpanded template is not that. The detailed answer
+ * stays on `base`.
+ */
+function promptLayerForBase(base: BasePromptText): LayerText {
+  const source = base.sourcePath ? { sourcePath: base.sourcePath } : {};
+  if (base.reason === "ok" && base.text !== null && base.representation === "expanded") {
+    return { text: base.text, reason: "ok", bytes: base.bytes, representation: "expanded", ...source };
+  }
+  if (base.reason === "ok") return { text: null, reason: "not-exposed", bytes: 0, representation: "template", ...source };
+  return { text: null, reason: "unavailable", bytes: 0, ...source };
+}
+
 interface ProbeCommand {
   binary: string;
   args: string[];
@@ -557,8 +818,13 @@ export async function probePromptText(
   // and it also described a prompt that depends on where Codex happened to run.
   // The global home is the one context this page can honestly report on.
   const codexHome = resolveCodexHomeDir();
+  // Read before anything is spawned. The base prompt comes from files this process
+  // reads itself, so binding it to the subprocess would lose the one layer the
+  // probed output never carries the moment Codex is missing, slow, or cancelled.
+  const base = readBasePrompt(codexHome);
+  const baseLayers = { "base-instructions": promptLayerForBase(base) };
   if (signal?.aborted) {
-    return { ok: false, codexHome, layers: {}, detail: "prompt probe cancelled" };
+    return { ok: false, codexHome, layers: { ...baseLayers }, base, detail: "prompt probe cancelled" };
   }
   // Resolve through the shared runtime resolver, not a private path list: the
   // old four-path POSIX check could never match the Codex App's Windows install
@@ -600,7 +866,8 @@ export async function probePromptText(
     return {
       ok: false,
       codexHome,
-      layers: {},
+      layers: { ...baseLayers },
+      base,
       ...(reportedRuntime ? { runtime: reportedRuntime } : {}),
       failure,
       detail: "codex binary not found",
@@ -618,7 +885,8 @@ export async function probePromptText(
     return {
       ok: false,
       codexHome,
-      layers: {},
+      layers: { ...baseLayers },
+      base,
       ...(reportedRuntime ? { runtime: reportedRuntime } : {}),
       ...(outcome.kind === "failed" && outcome.failure ? { failure: outcome.failure } : {}),
       detail: signal?.aborted
@@ -636,7 +904,8 @@ export async function probePromptText(
     return {
       ok: false,
       codexHome,
-      layers: {},
+      layers: { ...baseLayers },
+      base,
       ...(reportedRuntime ? { runtime: reportedRuntime } : {}),
       failure: probeFailure(
         command,
@@ -669,16 +938,20 @@ export async function probePromptText(
       // An unreadable file stays "not-rendered": we cannot claim it is empty.
     }
   }
-  // The base prompt travels outside prompt.input and cannot be read this way.
-  layers["base-instructions"] = { text: null, reason: "not-exposed", bytes: 0 };
+  // Read from configuration above, not from this output: Codex discards
+  // `base_instructions` before rendering `prompt.input`.
+  Object.assign(layers, baseLayers);
 
   // Layers whose rendered tag we have not confirmed against live output. Leaving
   // them absent made the GUI fall through to "unavailable", which claims the probe
-  // failed when it succeeded. Saying we have no mapping is the smaller claim.
+  // failed when it succeeded. Keep this distinct from the base prompt's
+  // "not-exposed", which is confirmed to travel outside the printable message
+  // list - reusing it showed a base-prompt-specific explanation for unrelated
+  // layers.
   for (const id of UNMAPPED_LAYER_IDS) {
-    layers[id] ??= { text: null, reason: "not-exposed", bytes: 0 };
+    layers[id] ??= { text: null, reason: "unmapped", bytes: 0 };
   }
-  return { ok: true, codexHome, layers, ...(reportedRuntime ? { runtime: reportedRuntime } : {}) };
+  return { ok: true, codexHome, layers, base, ...(reportedRuntime ? { runtime: reportedRuntime } : {}) };
 }
 
 /** Test-only command seam; production always resolves the installed Codex binary. */

package/src/codex/quota-401-recovery.ts

@@ -105,6 +105,18 @@ export function settleQuotaRecovery(
   records.set(accountId, { state: "spent", lineage: fenced });
 }
 
+/**
+ * Fence a same-grant alias that adopted the credential produced by another account's refresh.
+ *
+ * Propagation advances the alias without making it a separate credential lineage. Leaving its
+ * committed generation unspent would let a later quota poll rotate the same refresh grant again.
+ * This deliberately supersedes an old live claim for the alias: that claim targets the
+ * pre-propagation generation, and its eventual settlement must not erase this newer fence.
+ */
+export function fencePropagatedQuotaRecovery(accountId: string, lineage: number): void {
+  records.set(accountId, { state: "spent", lineage });
+}
+
 /**
  * Record a refresh that failed with proof the grant itself is dead.
  *