/**
 * Reading the prompt text Codex actually assembles.
 *
 * The read-only dialog used to say Codex "does not expose" a layer's text. That
 * was wrong: Codex is open source and ships `codex debug prompt-input`, which
 * renders the model-visible input list as JSON. Reading it is the difference
 * between describing a layer and showing it.
 *
 * What this does NOT cover, stated rather than implied:
 *
 * - `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.
 * - The output reflects the invoking directory and the current config, not a
 *   universal prompt.
 */
import { spawn } from "node:child_process";
import { closeSync, constants, existsSync, fstatSync, openSync, readSync, statSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { expandUserPath } from "../config";
import { clearableDeadline, type ClearableDeadline } from "../lib/abort";
import { parseCatalogJson, readCodexCatalogPathForHome, type RawCatalog, type RawEntry } from "./catalog/parsing";
import {
  CodexExecTrustError,
  validatedCodexExecInvocationAsync,
  type CodexExecBoundaryAsyncDeps,
} from "./exec-boundary";
import type { SpawnInvocation } from "../lib/win-exec";
import { resolveCodexHomeDir } from "./home";
import {
  CODEX_PROGRAM_NOT_FOUND_REASON,
  displayCodexRuntimePath,
  resolveCodexRuntime,
  type CodexRuntimeSource,
  type ResolveCodexRuntimeResult,
} from "./runtime";

/**
 * Layer id -> the tag Codex actually renders it under.
 *
 * Every entry here was read off live `codex debug prompt-input` output across the
 * feature flags that enable each section. None is inferred from the Rust section
 * `ID` constants: those are identifiers for diffing, not wrapper tags, and an
 * earlier guess from them mapped `permissions` to the wrong name while the real
 * tag - `permissions instructions`, with a space - went unmatched.
 *
 * A layer absent from this map is reported as unsupported, never as silent.
 */
const LAYER_SECTION_TAGS: Record<string, string> = {
  skills: "skills_instructions",
  apps: "apps_instructions",
  plugins: "plugins_instructions",
  // Context-dependent: it is absent when the active collaboration mode adds no
  // instructions, but Codex wraps it in this tag when it does render.
  collaboration: "collaboration_mode",
  environment: "environment_context",
  permissions: "permissions instructions",
  // Synthetic: the project doc carries no tag of its own (see extractSections).
  "agents-md": "__agents_md",
};

/**
 * Inventory ids with no confirmed tag in the rendered output. They are listed
 * explicitly rather than left missing: an absent entry made the dialog report a
 * successful probe as unavailable.
 */
const UNMAPPED_LAYER_IDS = [
  "model-switch",
  "context-window-guidance",
  "environments-instructions",
  "tools",
  "multi-agent-mode",
  // Confirmed absent from live output under their own feature flags, so the
  // previous `personality` / `realtime` guesses reported these as silent when the
  // truth is that this extractor has no verified tag for them.
  "personality",
  "realtime",
  // 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 "unmapped" honestly instead of
  // claiming a tag this extractor has never actually matched - the same mistake the
  // header above records for permissions.
  "git-attribution",
] as const;

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" | "unmapped" | "unavailable";
  bytes: number;
  /**
   * `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:
 * a caller that needs "is Codex installed at all" versus "Codex rejected the
 * command" cannot get that from a sentence.
 */
export type PromptProbeFailureKind =
  | "program-not-found"
  | "command-unsupported"
  | "execution-failed"
  | "output-invalid";

export interface PromptProbeFailure {
  kind: PromptProbeFailureKind;
  /** The command line that was attempted or resolved, for display. */
  command: string;
  /**
   * A short fixed phrase plus the command - never captured process output.
   * Codex stderr can carry the user's config path, model name, or environment
   * details, and this response is served over the management API, so raw
   * process output does not belong in it.
   */
  detail: string;
}

export interface PromptTextProbe {
  ok: boolean;
  /** 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. */
  failure?: PromptProbeFailure;
  detail?: string;
}

/** 8 MiB is far above any real prompt and far below anything that hurts the server. */
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[];
  cwd: string;
  timeoutMs: number;
  promptStateFingerprint: string | null;
}

interface PromptProbeFlight {
  key: string;
  controller: AbortController;
  result: Promise<PromptProbeExecutionResult | null>;
  closed: Promise<void>;
  waiters: number;
  joinable: boolean;
  resultSettled: boolean;
  settled: boolean;
}

interface PromptProbeExecution {
  result: Promise<PromptProbeExecutionResult | null>;
  closed: Promise<void>;
}

/**
 * The process outcome travels with its classification so a shared flight hands
 * every joined caller the same `failure`, not just the same null.
 */
interface PromptProbeExecutionResult {
  raw: string | null;
  failure: PromptProbeFailure | null;
}

type SharedPromptProbeOutcome =
  | { kind: "output"; raw: string }
  | { kind: "failed"; failure?: PromptProbeFailure }
  | { kind: "busy" };

/**
 * The fixed phrase that distinguishes a deadline expiry from every other
 * termination. The shared flight's timer and a caller's own deadline both
 * report it, so a waiter can tell "the budget ran out" from "the probe was
 * stopped" without reading process output - which this response never carries.
 */
const PROMPT_PROBE_TIMEOUT_PHRASE = "codex prompt probe timed out";

let activePromptProbe: PromptProbeFlight | null = null;
let probeCommandForTests: { binary: string; args: string[] } | null = null;
let probeRuntimeForTests: { command: string; source: CodexRuntimeSource } | null | undefined;
let probeSpawnAttemptsForTests = 0;
let probeCloseBarrierForTests: Promise<void> | null = null;
let probeExecBoundaryDepsForTests: CodexExecBoundaryAsyncDeps | null = null;
let probeMetadataBarrierForTests: Promise<void> | null = null;

function commandKey(command: ProbeCommand): string {
  return JSON.stringify([
    command.binary,
    command.args,
    command.cwd,
    command.timeoutMs,
    command.promptStateFingerprint,
  ]);
}

function completedExecution(value: PromptProbeExecutionResult | null): PromptProbeExecution {
  return { result: Promise.resolve(value), closed: Promise.resolve() };
}

/**
 * The command line as it may be shown to a caller.
 *
 * Redacted, because this response is served over the management API and a
 * resolved Codex path is a user path: the Windows Codex App lives under the
 * profile directory, so echoing the raw command would put the account name in
 * a diagnostic. `displayCodexRuntimePath` is the same helper the runtime log
 * line and doctor output already use, so the probe reports a path in the form
 * the rest of the product reports it.
 */
function commandDescription(command: ProbeCommand): string {
  return [displayCodexRuntimePath(command.binary), ...command.args].join(" ");
}

function probeFailure(
  command: ProbeCommand,
  kind: PromptProbeFailureKind,
  detail: string,
): PromptProbeFailure {
  return { kind, command: commandDescription(command), detail };
}

/**
 * A non-zero exit whose stderr reports an unknown subcommand means the resolved
 * binary is a Codex too old (or too new) for `debug prompt-input` - a different
 * remedy than "the process died". The stderr text itself is used only for this
 * check; it never enters the response.
 */
function classifyProcessFailure(command: ProbeCommand, code: number | null, stderr: string): PromptProbeFailure {
  const lower = stderr.toLowerCase();
  const unsupported =
    (/unrecognized|unknown|unexpected|invalid/.test(lower) && /subcommand|command|argument|option/.test(lower))
    || /usage:/.test(lower);
  const kind: PromptProbeFailureKind = unsupported ? "command-unsupported" : "execution-failed";
  const phrase = unsupported
    ? "codex does not support this probe command"
    : `codex probe exited with code ${code ?? "unknown"}`;
  return probeFailure(command, kind, `${phrase}: ${commandDescription(command)}`);
}

/**
 * The resolver reports why each candidate lost. A candidate that is simply not
 * there (issue 4458's repeated "path does not exist" on Windows) is a
 * program-not-found; a candidate that exists but could not be probed is an
 * execution problem on an installed program.
 */
function classifyRuntimeFailure(result: ResolveCodexRuntimeResult): PromptProbeFailure {
  const isNotFound = (reason: string) =>
    reason === CODEX_PROGRAM_NOT_FOUND_REASON || /does not exist|not found|ENOENT/i.test(reason);
  const representative = result.failures.find(item => !isNotFound(item.reason))
    ?? result.failures[0];
  const kind: PromptProbeFailureKind = !representative || isNotFound(representative.reason)
    ? "program-not-found"
    : "execution-failed";
  // Same redaction obligation as commandDescription: a rejected candidate is a
  // real filesystem path, and every one of them is reported to the caller.
  const command = displayCodexRuntimePath(representative?.command ?? result.runtime.command);
  const phrase = kind === "program-not-found" ? "codex program not found" : "codex runtime could not be probed";
  return { kind, command, detail: `${phrase}: ${command}` };
}

function runProbe(
  command: ProbeCommand,
  controller: AbortController,
  onStopping: () => void,
): PromptProbeExecution {
  const signal = controller.signal;
  if (signal.aborted) return completedExecution({ raw: null, failure: null });
  let resolveResult!: (value: PromptProbeExecutionResult | null) => void;
  let resolveClosed!: () => void;
  const result = new Promise<PromptProbeExecutionResult | null>(resolve => { resolveResult = resolve; });
  const closed = new Promise<void>(resolve => { resolveClosed = resolve; });
  let resultSettled = false;
  let closeSettled = false;

  const finishResult = (value: PromptProbeExecutionResult | null) => {
    if (resultSettled) return;
    resultSettled = true;
    resolveResult(value);
  };
  const finishClosed = () => {
    if (closeSettled) return;
    closeSettled = true;
    resolveClosed();
  };

  // One deadline covers trust verification AND the probe child. The timer
  // aborts the flight controller rather than terminating directly, so the
  // signal reaches an in-flight trust check (which must stop and reap its own
  // helper) exactly like it reaches the probe child. The slot is never
  // released while a verification promise is still unsettled.
  let child: ReturnType<typeof spawn> | undefined;
  let settled = false;
  let stopping = false;
  let stoppingFailure: PromptProbeFailure | null = null;
  let timer: ReturnType<typeof setTimeout> | undefined;

  const finish = (value: PromptProbeExecutionResult) => {
    if (settled) return;
    settled = true;
    if (timer) clearTimeout(timer);
    signal.removeEventListener("abort", onAbort);
    finishResult(value);
    finishClosed();
  };

  // Keep the flight admitted until `close`: kill() only requests termination
  // and does not prove the exact child has released its process and stdio.
  const terminate = (
    failure = probeFailure(
      command,
      "execution-failed",
      // The flight timer aborts with a TimeoutError; every other abort reason
      // is a stop, not an expired budget. Callers match on the fixed phrase to
      // report "timed out" instead of a generic termination.
      signal.reason instanceof DOMException && signal.reason.name === "TimeoutError"
        ? `${PROMPT_PROBE_TIMEOUT_PHRASE}: ${commandDescription(command)}`
        : `codex probe was terminated: ${commandDescription(command)}`,
    ),
  ) => {
    if (settled || stopping) return;
    stopping = true;
    stoppingFailure = failure;
    onStopping();
    if (timer) clearTimeout(timer);
    signal.removeEventListener("abort", onAbort);
    child?.stdout?.destroy();
    // The caller is bounded even if OS termination later fails. Admission is
    // retained separately by `closed`, and later probes fail soft while this
    // exact execution remains unproven terminal.
    finishResult({ raw: null, failure });
    if (!child || child.exitCode !== null || child.signalCode !== null) return;
    try {
      child.kill("SIGKILL");
    } catch {
      // Exact child state is ambiguous. Keep admission non-joinable until its
      // own `close` proves terminal instead of targeting a reusable numeric PID.
    }
  };
  const onAbort = () => terminate();

  const start = async () => {
    // The flight owns trust verification too: it runs under the shared
    // deadline and the controller's abort, and a rejected target becomes this
    // flight's shared failure instead of spawning beside the single slot.
    let invocation: SpawnInvocation;
    try {
      invocation = await validatedCodexExecInvocationAsync(command.binary, command.args, {
        env: process.env,
        cwd: command.cwd,
        signal,
        ...(probeExecBoundaryDepsForTests ?? {}),
      });
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      finish({
        raw: null,
        failure: probeFailure(
          command,
          error instanceof CodexExecTrustError
            ? "execution-failed"
            : /ENOENT|not found/i.test(message) ? "program-not-found" : "execution-failed",
          `codex probe could not start: ${commandDescription(command)}`,
        ),
      });
      return;
    }
    if (stopping || settled) {
      // Terminated while verification was in flight; its await has now settled
      // and no probe child exists, so the slot can be released.
      finishClosed();
      return;
    }
    // A probe must never hang OR balloon the management API: it is bounded in
    // time AND in bytes, and every failure degrades to "unavailable" rather
    // than an error page.
    try {
      if (probeCommandForTests) probeSpawnAttemptsForTests += 1;
      child = spawn(invocation.file, invocation.args, {
        cwd: command.cwd,
        stdio: ["ignore", "pipe", "pipe"],
        windowsHide: true,
        ...invocation.options,
      });
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      finish({
        raw: null,
        failure: probeFailure(
          command,
          /ENOENT|not found/i.test(message) ? "program-not-found" : "execution-failed",
          `codex probe could not start: ${commandDescription(command)}`,
        ),
      });
      return;
    }
    const proc = child;
    const chunks: Buffer[] = [];
    const errorChunks: Buffer[] = [];
    let size = 0;
    let errorSize = 0;

    proc.stdout?.on("data", (chunk: Buffer) => {
      size += chunk.length;
      if (size > MAX_PROBE_OUTPUT_BYTES) { terminate(); return; }
      chunks.push(chunk);
    });
    proc.stderr?.on("data", (chunk: Buffer) => {
      errorSize += chunk.length;
      if (errorSize <= MAX_PROBE_STDERR_BYTES) errorChunks.push(chunk);
    });
    proc.on("error", error => {
      // No PID means spawn itself failed, so there is no live child to drain.
      if (proc.pid === undefined) {
        const message = error instanceof Error ? error.message : String(error);
        finish({
          raw: null,
          failure: probeFailure(
            command,
            /ENOENT|not found/i.test(message) ? "program-not-found" : "execution-failed",
            `codex probe could not start: ${commandDescription(command)}`,
          ),
        });
      }
      else terminate(probeFailure(
        command,
        "execution-failed",
        `codex probe process error: ${commandDescription(command)}`,
      ));
    });
    proc.on("close", code => {
      // Decode once, at the end: `String(chunk)` per chunk corrupts any UTF-8
      // character that straddles a chunk boundary.
      const recordClose = () => {
        if (stopping) {
          finish({
            raw: null,
            failure: stoppingFailure ?? probeFailure(
              command,
              "execution-failed",
              `codex probe was terminated: ${commandDescription(command)}`,
            ),
          });
        } else if (code === 0) {
          finish({ raw: Buffer.concat(chunks).toString("utf8"), failure: null });
        } else {
          finish({
            raw: null,
            failure: classifyProcessFailure(command, code, Buffer.concat(errorChunks).toString("utf8")),
          });
        }
      };
      const barrier = probeCloseBarrierForTests;
      if (barrier) void barrier.then(recordClose, recordClose);
      else recordClose();
    });
    // Close the race between the pre-spawn check and listener registration.
    if (signal.aborted) terminate();
  };

  timer = setTimeout(() => {
    // Abort rather than terminate directly so the signal also reaches a trust
    // check that is still running: it must stop and reap its helper before the
    // flight releases the slot.
    controller.abort(new DOMException("prompt probe timed out", "TimeoutError"));
  }, command.timeoutMs);
  signal.addEventListener("abort", onAbort, { once: true });
  void start().catch(() => {
    finish({
      raw: null,
      failure: probeFailure(
        command,
        "execution-failed",
        `codex probe failed: ${commandDescription(command)}`,
      ),
    });
  });
  return { result, closed };
}

function startPromptProbeFlight(command: ProbeCommand): PromptProbeFlight {
  const controller = new AbortController();
  const flight: PromptProbeFlight = {
    key: commandKey(command),
    controller,
    result: Promise.resolve(null),
    closed: Promise.resolve(),
    waiters: 0,
    joinable: true,
    resultSettled: false,
    settled: false,
  };
  const execution = runProbe(command, controller, () => {
    flight.joinable = false;
  });
  flight.result = execution.result
    .catch(() => null)
    .finally(() => {
      flight.resultSettled = true;
    });
  flight.closed = execution.closed
    .finally(() => {
      flight.settled = true;
      if (activePromptProbe === flight) activePromptProbe = null;
    });
  activePromptProbe = flight;
  return flight;
}

async function runSharedPromptProbe(
  command: ProbeCommand,
  signal?: AbortSignal,
): Promise<SharedPromptProbeOutcome> {
  const key = commandKey(command);
  if (signal?.aborted) return { kind: "failed" };
  const active = activePromptProbe;
  if (!active) {
    // The new flight claims the sole slot synchronously, before any await:
    // trust verification runs inside it under the probe deadline, and a
    // rejected target becomes the flight's shared failure for every joiner.
    const result = await waitForPromptProbeFlight(startPromptProbeFlight(command), signal);
    if (!result) return { kind: "failed" };
    if (result.failure) return { kind: "failed", failure: result.failure };
    return result.raw === null ? { kind: "failed" } : { kind: "output", raw: result.raw };
  }
  if (active.key === key && active.joinable && !active.controller.signal.aborted) {
    const result = await waitForPromptProbeFlight(active, signal);
    if (!result) return { kind: "failed" };
    if (result.failure) return { kind: "failed", failure: result.failure };
    return result.raw === null ? { kind: "failed" } : { kind: "output", raw: result.raw };
  }
  // A different or terminating flight still owns the sole process slot. Never
  // wait unboundedly for an unproven close and never launch beside it.
  return { kind: "busy" };
}

async function waitForPromptProbeFlight(
  flight: PromptProbeFlight,
  signal?: AbortSignal,
): Promise<PromptProbeExecutionResult | null> {
  if (signal?.aborted) {
    if (flight.waiters === 0 && !flight.settled) flight.controller.abort();
    return null;
  }
  flight.waiters += 1;
  let onAbort: (() => void) | undefined;
  try {
    if (!signal) return await flight.result;
    const aborted = new Promise<PromptProbeExecutionResult | null>(resolve => {
      onAbort = () => resolve(null);
      signal.addEventListener("abort", onAbort, { once: true });
      if (signal.aborted) onAbort();
    });
    return await Promise.race([flight.result, aborted]);
  } finally {
    if (onAbort) signal?.removeEventListener("abort", onAbort);
    flight.waiters = Math.max(0, flight.waiters - 1);
    if (flight.waiters === 0 && !flight.resultSettled) {
      flight.controller.abort(new DOMException("All prompt probe callers cancelled", "AbortError"));
    }
  }
}

/** Pull every `<tag>...</tag>` section out of the rendered developer messages. */
function extractSections(raw: string): Map<string, string> {
  const sections = new Map<string, string>();
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    return sections;
  }
  if (!Array.isArray(parsed)) return sections;
  for (const item of parsed) {
    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
    const content = (item as { content?: unknown }).content;
    if (!Array.isArray(content)) continue;
    const text = content.map(part => {
      if (!part || typeof part !== "object" || Array.isArray(part)) return "";
      const value = (part as { text?: unknown }).text;
      return typeof value === "string" ? value : "";
    }).join("");
    // Tag names are NOT all snake_case: Codex renders `<permissions instructions>`
    // with a space. A `[a-z_]+` pattern silently skipped it, and the layer was
    // reported as "sent nothing" while its text sat right there.
    for (const match of text.matchAll(/<([a-zA-Z_][a-zA-Z0-9_ -]*)>([\s\S]*?)<\/\1>/g)) {
      sections.set(match[1]!, match[2]!.trim());
    }
    // AGENTS.md is NOT tagged: it arrives as a `# AGENTS.md instructions`
    // block among the tagged sections. Matching only on tags would report the
    // layer as unrendered while its text sits in the same message.
    //
    // Bounded at both ends. Capturing to end-of-message swept up any unrelated
    // untagged prose that happened to follow, and stripping tag-shaped blocks
    // first also deleted XML-like text the user had written INSIDE their own
    // AGENTS.md. Codex wraps the body in <INSTRUCTIONS>, so that is the boundary.
    // No line anchor: the block is concatenated directly onto the previous
    // section's closing tag, so requiring a newline before it never matched.
    //
    // The `for <path>` suffix is OPTIONAL. Upstream emits three shapes from
    // `contextual_user_fragment().render()` (core/src/context.rs) and this has
    // to read all three rather than the one that existed when the probe was
    // written: the legacy single-root form `# AGENTS.md instructions for
    // <dir>`, the no-directory form `# AGENTS.md instructions`, and the
    // multi-environment form where each project's block is labeled `for \`<env>\`
    // with root <cwd>` INSIDE the INSTRUCTIONS wrapper. The labels are part of
    // what the model sees, so they stay in the captured body.
    const projectDoc = /# AGENTS\.md instructions(?: for [^\n]*)?\n+<INSTRUCTIONS>\n?([\s\S]*?)\n?<\/INSTRUCTIONS>/.exec(text);
    if (projectDoc) sections.set("__agents_md", projectDoc[1]!.trim());
    else if (/# AGENTS\.md instructions/.test(text)) {
      // The header rendered but in a shape this extractor does not recognize -
      // a future upstream format, or prose truncated by the output cap. Claiming
      // the layer "sent nothing" would be a lie about a block that is plainly
      // present; the sentinel maps it to `unmapped`, the existing honest answer
      // for "rendered in a form we cannot show".
      sections.set("__agents_md_unmatched", "");
    }
  }
  return sections;
}

/** Test seam: the extraction is the part worth pinning, not the spawn. */
export const extractSectionsForTests = extractSections;

function mapSectionsToLayers(sections: Map<string, string>): Record<string, LayerText> {
  const layers: Record<string, LayerText> = {};
  for (const [layerId, tag] of Object.entries(LAYER_SECTION_TAGS)) {
    const text = sections.get(tag) ?? null;
    layers[layerId] = text === null
      // Registered but not rendered on this turn, which is an ordinary state for
      // a diff-rendered section rather than an error.
      ? { text: null, reason: "not-rendered", bytes: 0 }
      : { text, reason: "ok", bytes: Buffer.byteLength(text, "utf8") };
  }
  // `__agents_md_unmatched` is the sentinel for "the AGENTS.md header rendered in
  // a shape the bounded extractor does not recognize". `unmapped` is the honest
  // answer for it: the text exists but cannot be shown, which `not-rendered`
  // would deny outright.
  if (layers["agents-md"]?.reason === "not-rendered" && sections.has("__agents_md_unmatched")) {
    layers["agents-md"] = { text: null, reason: "unmapped", bytes: 0 };
  }
  return layers;
}

/** Test seam: pin section-to-layer projection independently of the subprocess. */
export const mapSectionsToLayersForTests = mapSectionsToLayers;

/**
 * Probe once and map every known layer to its rendered text.
 *
 * `cwd` matters: AGENTS.md and environment context are directory-dependent, so a
 * probe from the wrong place would describe a prompt the user never sees.
 */
export async function probePromptText(
  timeoutMs = 15_000,
  signal?: AbortSignal,
  promptStateFingerprint: string | null = null,
): Promise<PromptTextProbe> {
  // Metadata time counts against the caller budget; synchronous reads cannot
  // be interrupted, so expiry blocks admission after they return. Waiting and
  // trust verification are cancellable. The flight keeps its fixed deadline:
  // caller expiry ends only that wait, without extending the shared backstop.
  // The child also stops on output overflow, process errors or last-waiter exit.
  const deadlineAt = Date.now() + timeoutMs;
  const deadline = clearableDeadline(timeoutMs, signal);
  try {
    const result = await probePromptTextWithinDeadline(timeoutMs, deadlineAt, deadline, promptStateFingerprint);
    if (!deadline.didExpire()) return result;
    const command = `${result.runtime?.command ?? "codex"} debug prompt-input`;
    return {
      ...result,
      ok: false,
      detail: "prompt probe timed out",
      failure: {
        kind: "execution-failed",
        command,
        detail: `${PROMPT_PROBE_TIMEOUT_PHRASE}: ${command}`,
      },
    };
  } finally {
    deadline.clear();
  }
}

async function probePromptTextWithinDeadline(
  timeoutMs: number,
  deadlineAt: number,
  deadline: ClearableDeadline,
  promptStateFingerprint: string | null,
): Promise<PromptTextProbe> {
  const signal = deadline.signal;
  // The probe runs in CODEX_HOME, never in a caller-supplied directory. A `cwd`
  // parameter let an authenticated request read any readable folder's AGENTS.md,
  // 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: { ...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
  // under %LOCALAPPDATA%\OpenAI\Codex\bin\<version>, so the probe reported
  // "not found" on machines where Codex was plainly installed (issue 4458).
  //
  // Both flags are deliberate. This runs on a request path: discoverAlternatives
  // would walk the whole PATH just to fill a newerAvailable diagnostic the probe
  // never shows, and probeVersion would pay a blocking `--version` exec per
  // candidate. The probe needs a command it can spawn; the version is irrelevant.
  const resolved = probeCommandForTests || probeRuntimeForTests !== undefined
    ? null
    : resolveCodexRuntime({ discoverAlternatives: false, probeVersion: false });
  const runtime: { command: string; source: CodexRuntimeSource } | undefined =
    probeRuntimeForTests !== undefined
      ? probeRuntimeForTests ?? undefined
      : resolved && resolved.runtime.source !== "fallback"
        ? { command: resolved.runtime.command, source: resolved.runtime.source }
        : undefined;
  // A `fallback` result is the resolver saying "nothing concrete was found" -
  // its command is the bare word "codex", not a located binary. Reporting it as
  // resolved would just relabel the same not-found as a spawn failure.
  const binary = probeCommandForTests?.binary ?? runtime?.command ?? null;
  // The response travels over the management API, so the reported runtime is
  // redacted while `binary` keeps the real path the spawn needs. On Windows the
  // Codex App install sits under the user's profile directory, so the raw
  // command carries the account name.
  const reportedRuntime = runtime
    ? { command: displayCodexRuntimePath(runtime.command), source: runtime.source }
    : undefined;
  if (!binary) {
    const failure = resolved
      ? classifyRuntimeFailure(resolved)
      : probeFailure(
          { binary: "codex", args: ["debug", "prompt-input"], cwd: codexHome, timeoutMs, promptStateFingerprint },
          "program-not-found",
          "codex program not found: codex debug prompt-input",
        );
    return {
      ok: false,
      codexHome,
      layers: { ...baseLayers },
      base,
      ...(reportedRuntime ? { runtime: reportedRuntime } : {}),
      failure,
      detail: "codex binary not found",
    };
  }
  const command: ProbeCommand = {
    binary,
    args: probeCommandForTests?.args ?? ["debug", "prompt-input"],
    cwd: codexHome,
    timeoutMs,
    promptStateFingerprint,
  };
  // The absolute check complements the abort signal: a synchronous metadata
  // read that consumed the whole budget starves the timer callback, so the
  // signal can still be quiet here after the absolute deadline passed. An
  // expired caller must never start a flight.
  const metadataBarrier = probeMetadataBarrierForTests;
  if (metadataBarrier) await metadataBarrier;
  if (signal.aborted && !deadline.didExpire()) {
    return {
      ok: false,
      codexHome,
      layers: { ...baseLayers },
      base,
      ...(reportedRuntime ? { runtime: reportedRuntime } : {}),
      detail: "prompt probe cancelled",
    };
  }
  if (deadline.didExpire() || Date.now() >= deadlineAt) {
    return {
      ok: false,
      codexHome,
      layers: { ...baseLayers },
      base,
      ...(reportedRuntime ? { runtime: reportedRuntime } : {}),
      detail: "prompt probe timed out",
      failure: probeFailure(
        command,
        "execution-failed",
        `${PROMPT_PROBE_TIMEOUT_PHRASE}: ${commandDescription(command)}`,
      ),
    };
  }
  const outcome = await runSharedPromptProbe(command, signal);
  if (outcome.kind !== "output") {
    return {
      ok: false,
      codexHome,
      layers: { ...baseLayers },
      base,
      ...(reportedRuntime ? { runtime: reportedRuntime } : {}),
      ...(outcome.kind === "failed" && outcome.failure ? { failure: outcome.failure } : {}),
      detail: signal?.aborted
        ? "prompt probe cancelled"
        : outcome.kind === "busy"
          ? "another prompt probe is still finishing; retry shortly"
          : outcome.kind === "failed" && outcome.failure?.detail.startsWith(PROMPT_PROBE_TIMEOUT_PHRASE)
            ? "prompt probe timed out"
            : "codex debug prompt-input failed",
    };
  }
  const raw = outcome.raw;
  const sections = extractSections(raw);
  if (sections.size === 0) {
    // Zero sections from a zero-exit probe means the output did not parse, which
    // is a failed read - not fifteen layers that each chose to send nothing.
    return {
      ok: false,
      codexHome,
      layers: { ...baseLayers },
      base,
      ...(reportedRuntime ? { runtime: reportedRuntime } : {}),
      failure: probeFailure(
        command,
        "output-invalid",
        `codex prompt output could not be parsed: ${commandDescription(command)}`,
      ),
      detail: "prompt output could not be parsed",
    };
  }
  const layers = mapSectionsToLayers(sections);

  // A file that exists and is empty is not the same as a layer that chose to send
  // nothing. Reporting "sent nothing" for an empty AGENTS.md tells the user their
  // layer is idle when the real answer is that the file they wrote is blank.
  const agentsMdPath = join(codexHome, "AGENTS.md");
  if (layers["agents-md"]?.reason === "not-rendered" && existsSync(agentsMdPath)) {
    try {
      if (statSync(agentsMdPath).size === 0) {
        layers["agents-md"] = { text: null, reason: "empty-source", bytes: 0, sourcePath: agentsMdPath };
      }
    } catch {
      // An unreadable file stays "not-rendered": we cannot claim it is empty.
    }
  }
  // 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. 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: "unmapped", bytes: 0 };
  }
  return { ok: true, codexHome, layers, base, ...(reportedRuntime ? { runtime: reportedRuntime } : {}) };
}

/** Test-only command seam; production always resolves the installed Codex binary. */
export function setPromptTextProbeCommandForTests(command: { binary: string; args: string[] } | null): void {
  probeCommandForTests = command ? { binary: command.binary, args: [...command.args] } : null;
}

/** Test-only runtime seam: stands in for the shared resolver's answer. */
export function setPromptTextProbeRuntimeForTests(
  runtime: { command: string; source: CodexRuntimeSource } | null | undefined,
): void {
  probeRuntimeForTests = runtime;
}

/** Test-only process-start counter for proving admission without timing guesses. */
export function promptTextProbeSpawnAttemptsForTests(): number {
  return probeSpawnAttemptsForTests;
}

/** Test-only close barrier for proving admission is not released at process exit. */
export function setPromptTextProbeCloseBarrierForTests(barrier: Promise<void> | null): void {
  probeCloseBarrierForTests = barrier;
}

/** Test-only metadata-phase barrier; models elapsed work before flight admission. */
export function setPromptTextProbeMetadataBarrierForTests(barrier: Promise<void> | null): void {
  probeMetadataBarrierForTests = barrier;
}

/** Test-only exec-boundary dep seam; production resolves the real environment. */
export function setPromptTextProbeExecBoundaryDepsForTests(deps: CodexExecBoundaryAsyncDeps | null): void {
  probeExecBoundaryDepsForTests = deps;
}

/** Test-only fail-closed drain so one failed lifecycle case cannot poison another. */
export async function resetPromptTextProbeForTests(): Promise<void> {
  const active = activePromptProbe;
  if (active && !active.settled) {
    active.controller.abort(new DOMException("Prompt probe test reset", "AbortError"));
    const drained = await Promise.race([
      active.closed.then(() => true),
      Bun.sleep(2_000).then(() => false),
    ]);
    if (!drained) throw new Error("prompt probe child did not close during test reset");
  }
  if (activePromptProbe === active) activePromptProbe = null;
  probeCommandForTests = null;
  probeRuntimeForTests = undefined;
  probeSpawnAttemptsForTests = 0;
  probeCloseBarrierForTests = null;
  probeExecBoundaryDepsForTests = null;
  probeMetadataBarrierForTests = null;
}
