super-dsh 0.1.9 → 0.1.10-e

package/{agent-codex/dist/codex-client.js → agent-codex-sdk/dist/codex-sdk-client.js}

@@ -15,37 +15,162 @@
  * (SDK env is REPLACE semantics — Task 1 spike fact, so the spread is
  * mandatory) and carries NO `CODEX_HOME`: the CLI resolves its own native
  * `~/.codex` (user ruling 2026-09-17 — never redirect the native app home at
- * spawn; tests redirect via `process.env.CODEX_HOME`). The SDK constructor
- * itself is injectable via {@link setCodexFactory}.
+ * spawn; tests redirect via `process.env.CODEX_HOME`).
+ *
+ * 2026-10-04 user ruling: this package declares NO SDK dependency — the whole
+ * runtime is fetched into the world home on the first real prompt
+ * (sdk-runtime.ts). The default factory therefore returns a zero-IO
+ * {@link DeferredCodex} that materializes the real SDK inside `ensureStarted()`
+ * (and, defensively, on the first `runStreamed`): constructing a client — which
+ * the provider does at session-create time — touches no disk and no network,
+ * and a session that never gets a prompt never fetches anything.
+ * {@link setCodexFactory} replaces that construction wholesale, so the unit
+ * suite stays green with the SDK absent.
  *
  * Wire events flow through `projectThreadEvent` (codex-events.ts) before
  * reaching listeners, so Task 7's agent.ts switch is unchanged from omp.
  */
-import { Codex } from "@openai/codex-sdk";
-import { projectThreadEvent } from "./codex-events.js";
-let codexFactory = (options) => new Codex(options);
-/** Replace the SDK constructor (tests inject a fake Codex). */
+import { loadCodexSdk } from "./sdk-runtime.js";
+import { NATIVE_SDK_LAUNCH } from "./codex-sdk-launch.js";
+import { projectThreadEvent } from "./codex-sdk-events.js";
+/**
+ * The production handle: a stand-in that constructs the REAL SDK entry on first
+ * materialization. Deferring is what keeps session-create at zero IO while
+ * still letting the fetch happen exactly once, from `ensureStarted()`.
+ */
+class DeferredCodex {
+    #build;
+    #real = null;
+    constructor(build) {
+        this.#build = build;
+    }
+    /** Fetch (first time) + construct the real instance; resolves when usable. */
+    warm() {
+        return this.#realCodex().then(() => undefined);
+    }
+    startThread(options) {
+        return new DeferredThread(() => this.#realCodex().then((real) => real.startThread(options)));
+    }
+    resumeThread(id, options) {
+        return new DeferredThread(() => this.#realCodex().then((real) => real.resumeThread(id, options)));
+    }
+    #realCodex() {
+        if (this.#real === null) {
+            // A rejected bootstrap must not be cached: the runtime fetch heals on the
+            // next call (a failure leaves no marker), so a retried prompt can succeed.
+            this.#real = this.#build().catch((error) => {
+                this.#real = null;
+                throw error;
+            });
+        }
+        return this.#real;
+    }
+}
+/** The thread half of {@link DeferredCodex}: materializes on first `runStreamed`. */
+class DeferredThread {
+    #build;
+    #target = null;
+    #materialize = null;
+    constructor(build) {
+        this.#build = build;
+    }
+    get id() {
+        return this.#target?.id ?? null;
+    }
+    async runStreamed(input, turnOptions) {
+        // Local narrowing: the materializer resolves inside a callback, so TS
+        // cannot see the field become non-null across the await.
+        let target = this.#target;
+        if (target === null) {
+            this.#materialize ??= this.#build()
+                .then((resolved) => {
+                this.#target = resolved;
+                return resolved;
+            })
+                .catch((error) => {
+                this.#materialize = null;
+                throw error;
+            });
+            target = await this.#materialize;
+        }
+        return target.runStreamed(input, turnOptions);
+    }
+}
+/**
+ * The default factory: the deferred handle wired to the durable runtime. A
+ * world home is mandatory on this path — deriving one from ambient env inside
+ * the client is the prod-home trap the adapter rules forbid (the provider owns
+ * the resolution and passes it in).
+ */
+const defaultCodexFactory = (options, worldHome) => {
+    if (worldHome === "") {
+        throw new Error("codex-sdk: the client needs the world home to fetch its SDK runtime into (the provider passes dshHomePath)");
+    }
+    return new DeferredCodex(async () => {
+        const sdk = await loadCodexSdk(worldHome);
+        // `options` already carries the provider's config overrides (when it has
+        // any) and the env the caller composed — the SDK is constructed exactly as
+        // the pinning launch asked, on first materialization.
+        return new sdk.Codex(options);
+    });
+};
+let codexFactory = defaultCodexFactory;
+/** Replace the SDK construction (tests inject a fake: zero fetch, zero disk). */
 export function setCodexFactory(factory) {
     codexFactory = factory;
 }
 // ---------------------------------------------------------------------------
-// Shared Codex instance (module-level singleton, refcounted — omp sidecar pattern)
+// Shared Codex instances (module-level, refcounted PER PROVIDER — omp sidecar
+// pattern, 2026-10-04 multi-provider rework)
 // ---------------------------------------------------------------------------
-let sharedCodex = null;
+/**
+ * Registry key for "let the native `config.toml` decide". Also the key every
+ * client starts on: the route is not known until the first turn resolves it.
+ */
+const NATIVE_KEY = "native";
+/**
+ * One entry per PROVIDER, not one for the process: a provider is a property of
+ * the config object the SDK is constructed with, so clients on different
+ * providers must not share an instance. Clients on the same provider still do —
+ * that is what keeps a many-session world at one SDK handle per provider.
+ */
+const sharedCodex = new Map();
 let refcount = 0;
-function acquire() {
-    if (sharedCodex === null) {
-        sharedCodex = codexFactory({ env: { ...process.env } });
+/**
+ * Refcount one provider's handle, constructing it on first use. The construction
+ * is cheap by contract: the default factory returns a {@link DeferredCodex}
+ * (zero disk, zero network) and a test factory returns a plain fake. The REAL
+ * instance — and therefore the runtime fetch — is materialized later, from
+ * `ensureStarted()`.
+ *
+ * The first launch for a key wins. That is sound because the key IS the
+ * provider: two launches on one key carry the same provider table, the same
+ * catalog path and the same synthetic key name, so the handle they would build
+ * is the same handle.
+ */
+function acquire(key, worldHome, launch) {
+    let entry = sharedCodex.get(key);
+    if (entry === undefined) {
+        entry = {
+            codex: codexFactory({ env: { ...process.env }, ...(Object.keys(launch.config).length === 0 ? {} : { config: launch.config }) }, worldHome, launch),
+            refs: 0,
+        };
+        sharedCodex.set(key, entry);
     }
+    entry.refs += 1;
     refcount += 1;
-    return sharedCodex;
+    return entry.codex;
 }
-function release() {
+function release(key) {
+    const entry = sharedCodex.get(key);
+    if (entry === undefined)
+        return;
+    entry.refs -= 1;
     refcount = Math.max(0, refcount - 1);
-    if (refcount === 0)
-        sharedCodex = null;
+    if (entry.refs <= 0)
+        sharedCodex.delete(key);
 }
-/** Test/observability hook: current shared-instance refcount (0 = none alive). */
+/** Test/observability hook: current handle refcount across providers (0 = none alive). */
 export function codexClientRefCount() {
     return refcount;
 }
@@ -84,7 +209,22 @@ function parseSpawnArgs(args) {
 }
 // ---------------------------------------------------------------------------
 export class CodexSdkClient {
+    /** The handle in force; swapped when the route moves to another provider. */
     #codex;
+    /**
+     * The world home the SDK runtime is fetched into. Held (not just borrowed at
+     * spawn) because a provider switch constructs the NEXT handle from it.
+     */
+    #worldHome;
+    /**
+     * The launch the next turn must run under, and the registry key it maps to.
+     * `applyLaunch` is the only writer; both start native, because the route is
+     * not known until the first turn resolves it.
+     */
+    #launch = NATIVE_SDK_LAUNCH;
+    #launchKey = NATIVE_KEY;
+    /** The key `#codex` is currently a handle of (what `close()` must release). */
+    #appliedProvider = NATIVE_KEY;
     #listeners = new Set();
     #failureListeners = new Set();
     #threadOptions;
@@ -102,8 +242,11 @@ export class CodexSdkClient {
     #lastUsage = null;
     /** Bumped by newSession()/close() to orphan runs started on an earlier thread. */
     #sessionEpoch = 0;
-    constructor(codex, cwd, approvalMode, resumeThreadId) {
+    /** One-shot latch for `ensureStarted()` — the runtime fetch happens there. */
+    #startPromise = null;
+    constructor(codex, cwd, approvalMode, resumeThreadId, worldHome = "") {
         this.#codex = codex;
+        this.#worldHome = worldHome;
         this.#approvalMode = approvalMode;
         // skipGitRepoCheck: adapters spawn from arbitrary test/worktree cwds (Task 1 spike precedent).
         // Launch-only approval mapping (Task 7): present only when the provider
@@ -119,17 +262,25 @@ export class CodexSdkClient {
             resumeThreadId === undefined ? codex.startThread(this.#threadOptions) : codex.resumeThread(resumeThreadId, this.#threadOptions);
     }
     /**
-     * Start a session on the shared Codex instance and resolve once ready.
+     * Construct a client on the shared handle. ZERO IO by contract: the default
+     * factory hands back a deferred SDK stand-in, so neither the runtime fetch
+     * nor the real SDK construction happens here — `ensureStarted()` owns both.
+     * A session that is created and never prompted therefore fetches nothing.
      * Mirrors `OmpSdkClient.spawn(args, cwd)`.
      */
-    static async spawn(args = [], cwd) {
+    static async spawn(args = [], cwd, worldHome) {
         const { approvalMode, resumeThreadId } = parseSpawnArgs(args);
-        const codex = acquire();
+        // Born on the native key: the route is not known until the first turn
+        // resolves it, and `applyLaunch` moves this client onto the provider it
+        // names. The handle is deferred either way, so nothing is constructed,
+        // fetched or even decided by this call.
+        const home = worldHome ?? "";
+        const codex = acquire(NATIVE_KEY, home, NATIVE_SDK_LAUNCH);
         try {
-            return new CodexSdkClient(codex, cwd, approvalMode, resumeThreadId);
+            return new CodexSdkClient(codex, cwd, approvalMode, resumeThreadId, home);
         }
         catch (error) {
-            release();
+            release(NATIVE_KEY);
             throw error;
         }
     }
@@ -273,7 +424,7 @@ export class CodexSdkClient {
     async setModel(provider, modelId) {
         this.#ensureUsable();
         void provider;
-        this.#pendingModel = modelId;
+        this.#pendingModel = this.#modelOverride(modelId);
         return ok("set_model");
     }
     /** Abort the current streaming run (AbortController per run, turn-level signal). */
@@ -300,9 +451,27 @@ export class CodexSdkClient {
         this.#appliedModel = null; // a pending model still applies at the next run
         return ok("new_session");
     }
-    /** Lazy-surface parity: a real client is born live (see OmpAgentRpc.spawned). */
-    ensureStarted() {
-        return Promise.resolve();
+    /**
+     * Materialize the durable SDK runtime (fetch on first call, then free) and
+     * the real SDK instance behind it. This is the ONLY place the production path
+     * may touch the network — `create()`/`spawn()` stay zero-IO.
+     *
+     * A failure is NOT memoized: the runtime bootstrap leaves no marker and heals
+     * on the next call, so a later prompt in the same session retries instead of
+     * being permanently bricked.
+     */
+    async ensureStarted() {
+        if (this.#startPromise === null) {
+            this.#startPromise = (async () => {
+                const warm = this.#codex.warm;
+                if (typeof warm === "function")
+                    await warm.call(this.#codex);
+            })().catch((error) => {
+                this.#startPromise = null;
+                throw error;
+            });
+        }
+        return this.#startPromise;
     }
     /**
      * The current Codex thread id, exactly as the SDK thread exposes it (null
@@ -312,7 +481,12 @@ export class CodexSdkClient {
     get threadId() {
         return this.#thread.id;
     }
-    /** Lazy-surface parity: a real client is born live (see OmpAgentRpc.spawned). */
+    /**
+     * Lazy-surface parity: a real client is born live (see OmpAgentRpc.spawned).
+     * Kept `true` on the deferred path on purpose: the client's whole surface is
+     * usable from construction, and `ensureStarted()` only warms the runtime —
+     * this flag was never the "has the fetch happened" bit.
+     */
     get spawned() {
         return true;
     }
@@ -323,7 +497,7 @@ export class CodexSdkClient {
         this.#closed = true;
         this.#sessionEpoch += 1; // a settled run must not drain the queue after close
         this.#currentAbort?.abort();
-        release();
+        release(this.#appliedProvider);
         this.#fail(new Error("codex sdk client closed"));
     }
     // -------------------------------------------------------------------------
@@ -361,7 +535,7 @@ export class CodexSdkClient {
         const controller = new AbortController();
         this.#currentAbort = controller;
         try {
-            this.#applyPendingModel();
+            this.#reconcileRoute();
             const streamed = await this.#thread.runStreamed(message, { signal: controller.signal });
             for await (const raw of streamed.events) {
                 const record = asRecord(raw);
@@ -400,17 +574,64 @@ export class CodexSdkClient {
             }
         }
     }
-    /** Rebuild the thread with the pending model when one is pending (next run). */
-    #applyPendingModel() {
-        if (this.#pendingModel === this.#appliedModel)
+    /**
+     * Put the resolved route in force for the next run: swap the handle if the
+     * PROVIDER moved, then rebuild the thread object against it.
+     *
+     * Cheaper than the app-server line's equivalent by construction. There, a
+     * provider is an argv-level property of a LONG-LIVED child, so a switch means
+     * killing it and re-attaching the thread to a new one (`reattach`). Here the
+     * SDK spawns `codex exec` (or `codex exec resume <id>`) PER RUN, so the
+     * provider is a property of the handle we are about to ask for a run — the
+     * switch is just "use the other handle from now on", and the thread keeps its
+     * identity because the id is a rollout on disk that both handles read.
+     *
+     * That also means a mid-turn switch lands on the next turn for free, exactly
+     * as the app-server line promises: the user message already dispatched keeps
+     * the handle it started with, and the next `#runTurn` re-reads the route.
+     */
+    #reconcileRoute() {
+        const key = this.#launchKey;
+        const providerMoved = key !== this.#appliedProvider;
+        if (!providerMoved && this.#pendingModel === this.#appliedModel)
             return;
+        if (providerMoved) {
+            this.#codex = acquire(key, this.#worldHome, this.#launch);
+            release(this.#appliedProvider);
+            this.#appliedProvider = key;
+        }
         const model = this.#pendingModel;
         const options = model === null ? { ...this.#threadOptions } : { ...this.#threadOptions, model };
+        // Resume by id whenever the thread has one: that is what carries the
+        // conversation across BOTH a model change and a provider change.
         const currentId = this.#thread.id;
         this.#thread =
             currentId !== null ? this.#codex.resumeThread(currentId, options) : this.#codex.startThread(options);
         this.#appliedModel = model;
     }
+    /**
+     * Pin the provider the NEXT run must use (2026-10-04 multi-provider rework).
+     *
+     * Called by the agent at turn open with the launch it resolved, so the client
+     * never has to know what a provider IS — it is handed a config and an env and
+     * runs on them. `providerId` is `null` for "let the native `config.toml`
+     * decide", which is what a session pinned to the retired single `codex` route
+     * resolves to.
+     */
+    applyRoute(launch, providerId, model) {
+        this.#launch = launch;
+        this.#launchKey = providerId ?? NATIVE_KEY;
+        this.#pendingModel = this.#modelOverride(model);
+    }
+    /**
+     * An empty model id means "pin no model", not "pin the empty model": the
+     * native `config.toml` then decides, which is what a route the adapter cannot
+     * resolve falls back to. Letting `model=""` through would emit
+     * `--config model=""` and codex would reject every turn.
+     */
+    #modelOverride(model) {
+        return model === "" ? null : model;
+    }
     /** Mirror wire events into the getMessages accumulator (best effort). */
     #mirror(wire) {
         if (wire.type === "message_end") {

package/agent-codex-sdk/dist/codex-sdk-launch.js

@@ -0,0 +1,92 @@
+/**
+ * codex-sdk-launch.ts — how a provider reaches the in-process Codex SDK
+ * (2026-10-04 multi-provider rework).
+ *
+ * This is the SDK half of `agent-codex/codex-launch.ts`. That module turns a
+ * provider into argv for a `codex app-server` child; this one turns the same
+ * provider into the structured object the SDK's `CodexOptions.config` takes —
+ * and underneath they are the same mechanism. The SDK's own type docs say it
+ * "flatten[s] it into dotted paths and serialize[s] values as TOML literals so
+ * they are compatible with the CLI's `--config` parsing", which is exactly the
+ * `--config key=value` channel the app-server line drives by hand. A provider
+ * therefore costs nothing on disk on this path either, and is scoped to the
+ * process that builds the config, which is what a per-session provider choice
+ * needs.
+ *
+ * The one transport difference is env. A spawned app-server child inherits the
+ * process environment, so `codex-launch.ts` hands back ADDITIONS and its caller
+ * spreads them (`env: { ...process.env, ...launch.env }`). The SDK's `env` is
+ * REPLACE semantics — "When provided, the SDK will not inherit variables from
+ * `process.env`" — so the caller must spread the same way before constructing
+ * `Codex`. This module still hands back additions only: composing the full map
+ * belongs to the caller, and keeping the addition set small is what makes the
+ * synthetic-key branch legible in tests.
+ *
+ * The measured constraints `codex-launch.ts` encodes carry over unchanged (see
+ * `docs/test-reports/2026-10-03-codex-provider-model-switch-probe.md`):
+ *
+ *  - a HYPHENATED id is fine in a dotted path (`model_providers.zhipu-cn.…`),
+ *    so native table names survive verbatim as provider ids;
+ *  - `model_catalog_json` is resolved against the process CWD when it arrives
+ *    as an override, so the path is always absolute;
+ *  - `env_key` is the one auth shape that never consults the auth manager, so a
+ *    stored API key rides the child's environment under a synthetic variable
+ *    name. That is also what makes a keyed provider usable behind a ChatGPT
+ *    login, where `requires_openai_auth` is silently shadowed.
+ *
+ * @module agent-codex-sdk/codex-sdk-launch
+ */
+import { writeProviderCatalog } from "./codex-native-config.js";
+/** The environment variable prefix for a key this adapter injects itself. */
+const SYNTHETIC_KEY_PREFIX = "SUPERD_CODEX_KEY_";
+/** The launch for "no provider injection at all" (the native config applies). */
+export const NATIVE_SDK_LAUNCH = { config: {}, env: {}, providerId: "" };
+/** The environment variable a stored API key is handed to the child as. */
+export function syntheticKeyName(providerId) {
+    return `${SYNTHETIC_KEY_PREFIX}${providerId.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+}
+/**
+ * The launch that pins one provider for the life of an SDK process.
+ *
+ * @param worldHome - the world's DSH home (our per-provider catalogs live there).
+ * @param codexHome - the native codex home; READ ONLY (catalog template material).
+ * @param provider - the provider the SDK must run on.
+ * @returns the structured config, the environment additions, and the provider id they pin.
+ */
+export function providerSdkLaunch(worldHome, codexHome, provider) {
+    // The SDK serializes these values as TOML literals itself, so unlike the argv
+    // line there is no hand-quoting here: a bare object is the whole override.
+    const table = {
+        name: provider.label,
+        base_url: provider.baseUrl,
+        wire_api: provider.protocol,
+    };
+    const env = {};
+    if (provider.auth.kind === "env") {
+        table["env_key"] = provider.auth.name;
+    }
+    else if (provider.auth.value !== "") {
+        // A key we hold: never touch auth.json, never go through the auth manager.
+        const name = syntheticKeyName(provider.id);
+        table["env_key"] = name;
+        env[name] = provider.auth.value;
+    }
+    else {
+        // The seeded shape — the runtime's own auth.json already holds this key.
+        table["requires_openai_auth"] = true;
+    }
+    // Top-level defaults for this process, so a thread that does not restate the
+    // provider still lands on the right one. `model_providers` is nested rather
+    // than pre-dotted: the SDK owns the flattening, and a nested table is what
+    // its `CodexConfigObject` type describes.
+    const config = {
+        model_providers: { [provider.id]: table },
+        model_provider: provider.id,
+    };
+    const catalog = writeProviderCatalog(worldHome, codexHome, provider);
+    // Absolute on purpose: codex resolves this override against the process cwd
+    // (`writeProviderCatalog` returns it under the absolute world home).
+    if (catalog !== undefined)
+        config["model_catalog_json"] = catalog;
+    return { config, env, providerId: provider.id };
+}

package/agent-codex-sdk/dist/codex-store.js

@@ -0,0 +1,180 @@
+/**
+ * Codex home resolution + the rollout-HEAD metadata reader.
+ *
+ * The listing/replay scanner that used to live here is GONE (2026-09-16): the
+ * DSH session log is now the session authority (upstream `sessionPersistence`
+ * owns list/read/replay), so the adapter no longer derives session ids or
+ * transcripts from Codex's rollout store. What remains is:
+ *
+ *  - home resolution (native `~/.codex`, never redirected; `CODEX_HOME` is the
+ *    test/operator override), and
+ *  - {@link readRolloutHead}: a bounded, memoized reader of ONE rollout's
+ *    FIRST line (`session_meta`), used only to recover the Codex system
+ *    prompt (`payload.base_instructions`) and the recorded cwd. It never
+ *    parses the transcript and never throws.
+ *
+ * Single-direction valve (spec S7): this module NEVER writes under the codex
+ * home; the rollout stays Codex's transcript of record.
+ */
+import { closeSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/**
+ * Resolve the Codex CLI's app-data home — the NATIVE `~/.codex` (user ruling
+ * 2026-09-17, pi precedent): the installed app keeps its own home, so the
+ * adapter never redirects it when spawning the SDK/CLI and never seeds config
+ * into it. Precedence: `CODEX_HOME` (tests / operator override), then the
+ * native default.
+ *
+ * The world's DSH home (`<dshHome>/agents/codex-sdk`) is NOT an input here anymore
+ * — it anchors adapter-owned DSH state only (session-map.ts). A home without
+ * `config.toml` would make the CLI fall back to OpenAI's own endpoint
+ * (region-blocked here), but that is the operator's native home: provisioning
+ * it is the operator's business (test helper: scripts/setup-codex-home.mjs).
+ */
+export function resolveCodexHome() {
+    if (process.env.CODEX_HOME !== undefined) {
+        const env = resolve(process.env.CODEX_HOME);
+        return env;
+    }
+    const native = join(homedir(), ".codex");
+    return native;
+}
+/**
+ * Take an explicit codex home as-is (prod-guarded) — for callers that already
+ * hold the final path (models.ts, the spike); distinct from
+ * {@link resolveCodexHome}, which resolves the native default.
+ */
+export function useCodexHome(path) {
+    const resolved = resolve(path);
+    return resolved;
+}
+/** Bounded read budget: `session_meta` is the FIRST line, so this is generous. */
+const HEAD_BYTES = 64 * 1024;
+/** Memoized heads by thread id — the head line is immutable once written. */
+const headCache = new Map();
+/**
+ * Locate one thread's rollout file under `<codexHome>/sessions/<Y>/<M>/<D>/`.
+ * The rollout file name embeds the thread id, so presence is the match test;
+ * a miss is retried (a thread's rollout may not exist yet at first call).
+ */
+function findRolloutFile(codexHome, threadId) {
+    const root = join(codexHome, "sessions");
+    try {
+        for (const year of readdirSync(root, { withFileTypes: true })) {
+            if (!year.isDirectory())
+                continue;
+            for (const month of readdirSync(join(root, year.name), { withFileTypes: true })) {
+                if (!month.isDirectory())
+                    continue;
+                for (const day of readdirSync(join(root, year.name, month.name), { withFileTypes: true })) {
+                    if (!day.isDirectory())
+                        continue;
+                    const dir = join(root, year.name, month.name, day.name);
+                    for (const file of readdirSync(dir)) {
+                        if (file.endsWith(".jsonl") && file.includes(threadId))
+                            return join(dir, file);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+/** Read (at most) the first line of a file; fail-soft. */
+function readFirstLine(path) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const chunk = Buffer.allocUnsafe(HEAD_BYTES);
+        const read = readSync(fd, chunk, 0, chunk.length, 0);
+        if (read <= 0)
+            return undefined;
+        const text = chunk.subarray(0, read).toString("utf8");
+        const end = text.indexOf("\n");
+        return end === -1 ? text : text.slice(0, end);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Read the `session_meta` head of the rollout belonging to `threadId`:
+ * the Codex system prompt and the recorded cwd. Memoized per thread id (the
+ * head line never changes); fail-soft — an unknown thread, an unwritten
+ * rollout, or a malformed head all yield `undefined`.
+ */
+/**
+ * Codex writes `payload.base_instructions` either as a plain string or as an
+ * object `{ text }` (observed 2026-09-16 on the SDK line: the object form is
+ * what the vendored binary emits today). Accept both; anything else is absent.
+ */
+function baseInstructionsText(value) {
+    if (typeof value === "string")
+        return value.trim() === "" ? undefined : value;
+    if (value !== null && typeof value === "object") {
+        const text = value["text"];
+        if (typeof text === "string" && text.trim() !== "")
+            return text;
+    }
+    return undefined;
+}
+export function readRolloutHead(codexHome, threadId) {
+    const cached = headCache.get(threadId);
+    if (cached !== undefined)
+        return cached;
+    const file = findRolloutFile(codexHome, threadId);
+    if (file === undefined)
+        return undefined;
+    // Cheap existence/size gate before paying for a read.
+    try {
+        if (!statSync(file).isFile())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const line = readFirstLine(file);
+    if (line === undefined)
+        return undefined;
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (record === null || typeof record !== "object")
+        return undefined;
+    const rec = record;
+    if (rec["type"] !== "session_meta")
+        return undefined;
+    const payload = rec["payload"];
+    if (payload === null || typeof payload !== "object")
+        return undefined;
+    const meta = payload;
+    const head = {
+        ...(typeof meta["id"] === "string" && meta["id"] !== "" ? { threadId: meta["id"] } : {}),
+        ...(typeof meta["cwd"] === "string" && meta["cwd"] !== "" ? { cwd: meta["cwd"] } : {}),
+        ...(baseInstructionsText(meta["base_instructions"]) === undefined
+            ? {}
+            : { baseInstructions: baseInstructionsText(meta["base_instructions"]) }),
+    };
+    headCache.set(threadId, head);
+    return head;
+}
+/** Test hygiene: drop memoized heads. */
+export function clearRolloutHeadCache() {
+    headCache.clear();
+}