super-dsh 0.1.9 → 0.1.10-e

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

@@ -0,0 +1,71 @@
+/** The approval policies Codex actually implements (unknown values are ignored). */
+const APPROVAL_POLICIES = ["never", "on-request", "on-failure", "untrusted"];
+/** The Dash preset table (mirrors the base bundle's permission plugin config). */
+const PRESETS = {
+    "danger-full-access": { sandbox: "danger-full-access", approval: "never", codexPolicy: "never" },
+    "workspace-write": { sandbox: "workspace-write", approval: "ask", codexPolicy: "on-request" },
+    "read-only": { sandbox: "read-only", approval: "ask", codexPolicy: "never" },
+};
+/** Narrow an untrusted value to a known preset name. */
+export function isPresetName(raw) {
+    return typeof raw === "string" && Object.hasOwn(PRESETS, raw);
+}
+/**
+ * `CODEX_APPROVAL_MODE` when it names an approval policy Codex implements,
+ * else undefined. An invalid value is IGNORED (the preset mapping applies).
+ */
+export function envApprovalMode() {
+    const raw = process.env.CODEX_APPROVAL_MODE;
+    return raw !== undefined && APPROVAL_POLICIES.includes(raw) ? raw : undefined;
+}
+/**
+ * Map a preset onto Codex's `--approval-mode` value; no preset → never.
+ * A value that is ALREADY a codex approval policy (the env override rides
+ * through the same folded call) passes through untouched; unknown preset
+ * names degrade to never.
+ */
+export function codexApprovalMode(preset) {
+    if (preset !== undefined && APPROVAL_POLICIES.includes(preset))
+        return preset;
+    return isPresetName(preset) ? PRESETS[preset].codexPolicy : "never";
+}
+/**
+ * The default preset for FUTURE sessions, as the permission service
+ * resolves it (settings-backed; the profile patch pins the base default).
+ * Undefined when the service is absent or its getter fails — callers fall
+ * back to the codex default policy.
+ */
+export function defaultPermissionPreset(ctx) {
+    const service = ctx.get("permissionPresets");
+    if (service === undefined)
+        return undefined;
+    try {
+        const preset = service.defaultPreset;
+        return isPresetName(preset) ? preset : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The session's effective preset: the last `permission/preset` event. */
+export function presetFromEvents(events) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event.type === "permission/preset" && isPresetName(event.data?.preset))
+            return event.data.preset;
+    }
+    return undefined;
+}
+/**
+ * The three Dash events `pinInitialPermission` stamps for a fresh session,
+ * in its append order (preset, sandbox, approval). Cold replay prepends
+ * them so the UI shows the session's permission after wrapper restarts.
+ */
+export function permissionEventsFor(preset, time) {
+    const spec = PRESETS[preset];
+    return [
+        { type: "permission/preset", time, data: { preset } },
+        { type: "sandbox/mode", time, data: { mode: spec.sandbox } },
+        { type: "approval/policy", time, data: { policy: spec.approval } },
+    ];
+}

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

@@ -0,0 +1,307 @@
+/**
+ * sdk-runtime.ts — the lazy, durable Codex SDK runtime the opt-in `codex-sdk`
+ * line runs on.
+ *
+ * 2026-10-04 user ruling (dev-rules §7 note + super-dsh/AGENTS.md): this
+ * package declares NO SDK dependency — not in `dependencies`, not in
+ * `optionalDependencies`, and not in `peerDependencies` — and ships NO
+ * postinstall/allow-scripts hook. Nothing is fetched at install time; the FIRST
+ * real prompt fetches the runtime into the world home, where it is durable
+ * across sessions, restarts and package upgrades. A second use reuses it
+ * (idempotent), and a FAILED fetch leaves a trace on disk instead of silently
+ * degrading into a confusing import crash at the first prompt.
+ *
+ * Why the world home rather than the package root: the package root is the
+ * installed tarball — read-only in every real consumer install, and shared by
+ * every world. The world home is per-runtime, writable, and already the home of
+ * this adapter's own DSH state (`dsh-sessions.json`).
+ *
+ * Layout (the codex line is far simpler than the OMP one: the runtime is a
+ * plain npm tree, so there is no bun, no sidecar, no per-platform native
+ * binding dance):
+ *
+ *   <worldHome>/sdk-runtime/
+ *     package.json                 written by us (private, never published)
+ *     node_modules/                `npm install --exact --ignore-scripts --omit=dev`
+ *     node_modules/@openai/codex-sdk/dist/index.js   the entry `loadCodexSdk` imports
+ *   <worldHome>/sdk-runtime.json       marker — written LAST, its presence is the contract
+ *   <worldHome>/sdk-runtime.lock       atomic (mkdir) bootstrap lock
+ *   <worldHome>/sdk-runtime.error.log  written ONLY by a failed fetch
+ *
+ * Both packages are pinned together at 0.154.0 — the SDK resolves the native
+ * `@openai/codex` binary package as its one dependency, so pinning only the
+ * SDK would let a re-resolve drift the binary underneath it.
+ *
+ * The entry is imported BY RESOLVED PATH, never by bare specifier: the runtime
+ * lives in the world home while this module lives in the plugin tarball, so a
+ * bare-specifier form could not resolve it (and would quietly reintroduce the
+ * dependency this module exists to delete). The package guard in
+ * test/package-contract.test.mjs scans the EMITTED JS for that shape, so keep
+ * this paragraph free of a literal import statement.
+ *
+ * Measured probe (2026-10-04): `@openai/codex-sdk@0.154.0` exports `"." ->
+ * "./dist/index.js"` and its only dependency is `@openai/codex@0.154.0`.
+ */
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+/** The coding-agent SDK this line drives (a plain npm package). */
+export const SDK_PACKAGE = "@openai/codex-sdk";
+/** The native binary package the SDK resolves at run time; pinned with the SDK. */
+export const SDK_BINARY_PACKAGE = "@openai/codex";
+/**
+ * Pin of BOTH packages — the same 0.154.0 the app-server (primary) line pins,
+ * so the two Codex faces agree on the wire behaviour they bridge.
+ */
+export const SDK_PACKAGE_VERSION = "0.154.0";
+/** The entry `loadCodexSdk` imports, relative to the runtime dir. */
+const SDK_ENTRY_RELATIVE = ["node_modules", SDK_PACKAGE, "dist", "index.js"];
+export function sdkRuntimeLayout(worldHome) {
+    const dir = join(worldHome, "sdk-runtime");
+    return {
+        dir,
+        manifest: join(dir, "package.json"),
+        nodeModules: join(dir, "node_modules"),
+        entry: join(dir, ...SDK_ENTRY_RELATIVE),
+        marker: join(worldHome, "sdk-runtime.json"),
+        lock: join(worldHome, "sdk-runtime.lock"),
+        errorLog: join(worldHome, "sdk-runtime.error.log"),
+    };
+}
+/** Read the install marker; undefined when absent or unreadable. */
+export function readSdkRuntimeRecord(worldHome) {
+    const { marker } = sdkRuntimeLayout(worldHome);
+    if (!existsSync(marker))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(marker, "utf8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fast path: the runtime is complete AND matches `identity` → its record.
+ *
+ * Returns undefined when the marker is absent/corrupt, when any identity field
+ * differs (the adapter or a pin changed — a pin bump must refetch), or when the
+ * recorded entry file is gone. In every such case the caller must (re)fetch.
+ */
+export function sdkRuntimeReady(worldHome, identity) {
+    const record = readSdkRuntimeRecord(worldHome);
+    if (record === undefined)
+        return undefined;
+    if (record.pluginVersion !== identity.pluginVersion)
+        return undefined;
+    if (record.packageVersion !== identity.packageVersion)
+        return undefined;
+    if (record.binaryVersion !== identity.binaryVersion)
+        return undefined;
+    if (!existsSync(sdkRuntimeLayout(worldHome).entry))
+        return undefined;
+    return record;
+}
+/** A held lock older than this is treated as abandoned and reclaimed. */
+const LOCK_STALE_MS = 30 * 60 * 1000;
+/** The npm command the runtime tree is installed with (kept pure for the test). */
+export function sdkInstallArgv(packageVersion = SDK_PACKAGE_VERSION) {
+    return [
+        "install",
+        "--exact",
+        "--ignore-scripts",
+        "--omit=dev",
+        `${SDK_PACKAGE}@${packageVersion}`,
+        `${SDK_BINARY_PACKAGE}@${packageVersion}`,
+    ];
+}
+/**
+ * The PRODUCTION {@link SdkRuntimeDeps}: the npm invocation plus the marker
+ * identity read from this package's own manifest.
+ *
+ * Kept IN THE MODULE (not in `scripts/fetch-sdk-runtime.mjs`) so the manual
+ * pre-warm script and the first-prompt lazy fetch (`loadCodexSdk`) share ONE
+ * implementation: a second copy is exactly how the two paths would drift.
+ *
+ * `pluginDir` defaults to this package's root (the parent of the compiled
+ * `dist/`), from which the marker identity reads the package's own version.
+ *
+ * @param pluginDir - package root holding `package.json`.
+ * @returns deps for {@link ensureSdkRuntime}.
+ */
+export function createSdkRuntimeDeps(pluginDir = dirname(dirname(fileURLToPath(import.meta.url)))) {
+    return {
+        run: runCommand,
+        pluginVersion: readPluginVersion(pluginDir),
+        pluginDir,
+        log: (line) => process.stderr.write(`[agent-codex-sdk] ${line}\n`),
+    };
+}
+/** The version of the adapter package at `pluginDir` (the marker identity half). */
+export function readPluginVersion(pluginDir) {
+    const raw = readFileSync(join(pluginDir, "package.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version !== "string" || parsed.version === "") {
+        throw new Error(`codex-sdk: ${join(pluginDir, "package.json")} carries no version`);
+    }
+    return parsed.version;
+}
+const execFileAsync = promisify(execFile);
+/**
+ * Run a command to completion, inheriting the environment except for the
+ * explicit overrides ({@link SdkRuntimeRunOptions.env}); an `undefined`
+ * override REMOVES the key from the child. Rejects on a non-zero exit.
+ */
+async function runCommand(cmd, args, opts) {
+    const env = { ...process.env };
+    if (opts?.env !== undefined) {
+        for (const [key, value] of Object.entries(opts.env)) {
+            if (value === undefined)
+                delete env[key];
+            else
+                env[key] = value;
+        }
+    }
+    await execFileAsync(cmd, args, { cwd: opts?.cwd, env, maxBuffer: 64 * 1024 * 1024 });
+}
+/**
+ * Return the record for `<worldHome>`'s durable SDK runtime, fetching it first
+ * when it is absent, incomplete or does not match the running adapter.
+ *
+ * Idempotent: a complete, matching runtime short-circuits without touching the
+ * network. Concurrent callers: the bootstrap is guarded by a `mkdir` lock — a
+ * second caller that finds a FRESH lock throws a clear "fetch in progress"
+ * error (no waiting; the SDK handle is a per-process singleton and the real
+ * race is another dsh process on the same world home), while an abandoned lock
+ * (older than {@link LOCK_STALE_MS}) is reclaimed so a crashed fetch cannot
+ * brick the line.
+ *
+ * Failures append to `<worldHome>/sdk-runtime.error.log` and throw a single
+ * actionable error — never a partial runtime behind a success marker.
+ */
+export async function ensureSdkRuntime(worldHome, deps) {
+    const layout = sdkRuntimeLayout(worldHome);
+    const identity = {
+        pluginVersion: deps.pluginVersion,
+        packageVersion: SDK_PACKAGE_VERSION,
+        binaryVersion: SDK_PACKAGE_VERSION,
+    };
+    const ready = sdkRuntimeReady(worldHome, identity);
+    if (ready !== undefined) {
+        deps.log(`codex-sdk: runtime ready (${SDK_PACKAGE}@${ready.packageVersion})`);
+        return ready;
+    }
+    mkdirSync(worldHome, { recursive: true });
+    acquireLock(layout, deps);
+    try {
+        // Re-check inside the lock: a peer may have completed the fetch in the
+        // window between our check and the lock, in which case we pay nothing.
+        const done = sdkRuntimeReady(worldHome, identity);
+        if (done !== undefined)
+            return done;
+        try {
+            return await buildRuntime(layout, deps, identity);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const stamp = new Date().toISOString();
+            try {
+                appendFileSync(layout.errorLog, `[${stamp}] codex-sdk runtime fetch failed: ${detail}\n`);
+            }
+            catch {
+                /* the trace is best-effort; the throw below is the contract */
+            }
+            throw new Error(`codex-sdk: could not fetch the SDK runtime ` +
+                `(${SDK_PACKAGE}@${SDK_PACKAGE_VERSION} + ${SDK_BINARY_PACKAGE}@${SDK_PACKAGE_VERSION}) at ${layout.dir}: ${detail}. ` +
+                `Pre-warm it by hand with \`npm run fetch-sdk-runtime\`. Trace: ${layout.errorLog}`);
+        }
+    }
+    finally {
+        rmSync(layout.lock, { recursive: true, force: true });
+    }
+}
+/** The idempotent build steps; the marker is written last, after the smoke check. */
+async function buildRuntime(layout, deps, identity) {
+    mkdirSync(layout.dir, { recursive: true });
+    // npm needs a manifest to own the tree; `private` + a throwaway version keep
+    // it unambiguously not-a-publishable-package, and an existing one is left
+    // alone so a later install can still be reproduced by hand.
+    if (!existsSync(layout.manifest)) {
+        writeFileSync(layout.manifest, JSON.stringify({ name: "codex-sdk-runtime", private: true, version: "0.0.0" }, null, 2) + "\n");
+    }
+    deps.log(`codex-sdk: installing ${SDK_PACKAGE}@${SDK_PACKAGE_VERSION} + ${SDK_BINARY_PACKAGE}@${SDK_PACKAGE_VERSION}`);
+    await deps.run("npm", sdkInstallArgv(), { cwd: layout.dir });
+    // Smoke step: import the installed entry through its RESOLVED path and
+    // require a constructor. Without it a broken tree would only surface at the
+    // first prompt, inside the agent's cold-start error path, far from the fetch
+    // that produced it.
+    if (!existsSync(layout.entry)) {
+        throw new Error(`npm install produced no ${layout.entry} (the package layout changed?)`);
+    }
+    deps.log(`codex-sdk: smoke-importing ${SDK_PACKAGE}@${SDK_PACKAGE_VERSION}`);
+    const module = (await import(pathToFileURL(layout.entry).href));
+    if (typeof module.Codex !== "function") {
+        throw new Error(`smoke import of ${SDK_PACKAGE}@${SDK_PACKAGE_VERSION} exposed no Codex constructor`);
+    }
+    // Marker LAST — a crash before this point leaves an incomplete runtime that
+    // the next call heals, never a false success.
+    const record = {
+        ...identity,
+        entryPath: layout.entry,
+        installedAt: new Date().toISOString(),
+    };
+    writeFileSync(layout.marker, JSON.stringify(record, null, 2) + "\n");
+    rmSync(layout.errorLog, { force: true });
+    deps.log(`codex-sdk: runtime ready at ${layout.dir}`);
+    return record;
+}
+/**
+ * Ensure the durable runtime and return the installed SDK module — the ONE
+ * function the client's default factory calls, and the only place a real
+ * download/install happens on the lazy path.
+ *
+ * The returned module is a real ESM namespace; the caller treats it
+ * structurally (the client declares its own interfaces and never imports this
+ * package's types).
+ */
+export async function loadCodexSdk(worldHome) {
+    await ensureSdkRuntime(worldHome, createSdkRuntimeDeps());
+    const { entry } = sdkRuntimeLayout(worldHome);
+    const module = (await import(pathToFileURL(entry).href));
+    if (typeof module.Codex !== "function") {
+        throw new Error(`codex-sdk: ${entry} exposes no Codex constructor`);
+    }
+    return module;
+}
+/**
+ * mkdir-based mutex. Returns owning the lock; throws when a fresh lock is held
+ * by someone else; reclaims a lock older than {@link LOCK_STALE_MS}.
+ */
+function acquireLock(layout, deps) {
+    for (;;) {
+        try {
+            mkdirSync(layout.lock);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        let ageMs;
+        try {
+            ageMs = Date.now() - statSync(layout.lock).mtimeMs;
+        }
+        catch {
+            continue; // released between the mkdir attempt and the stat — retry now
+        }
+        if (ageMs > LOCK_STALE_MS) {
+            deps.log(`codex-sdk: reclaiming stale runtime lock (age ${Math.round(ageMs / 1000)}s)`);
+            rmSync(layout.lock, { recursive: true, force: true });
+            continue;
+        }
+        throw new Error(`codex-sdk: another SDK runtime fetch is already in progress (lock ${layout.lock}). ` +
+            `Retry once it finishes; if no fetch is running, remove that lock directory.`);
+    }
+}

package/agent-codex-sdk/dist/session-map.js

@@ -0,0 +1,167 @@
+/**
+ * DSH-session ↔ Codex-thread identity map (the "mapping only" model,
+ * 2026-09-16).
+ *
+ * The DSH session id is the authority: it is supplied by the harness at
+ * create/resume and is what the API layer routes on. Codex's thread id only
+ * materializes after the first turn, so the pairing is persisted here, in an
+ * adapter-owned JSON file in the world's DSH home root (NOT inside the codex
+ * app home — the app home is the CLI's native `~/.codex` since the 2026-09-17
+ * home ruling; DSH bookkeeping never lives in the runtime's native tree):
+ *
+ *   `<worldHome>/dsh-sessions.json`   (`<DSH home>/agents/codex-sdk/dsh-sessions.json`)
+ *
+ * Shape: `{ "<dshSessionId>": { threadId, cwd, createdAt, preset } }` —
+ * `threadId` is `null` until the Codex thread starts. Writes are atomic
+ * (temp file + rename); reads are fail-soft (malformed JSON reads as empty)
+ * and never throw, so a corrupt map degrades to "unknown session" rather
+ * than breaking every operation.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/** An `Error` carrying a stable {@link CodexResumeErrorCode}. */
+export class CodexResumeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CodexResumeError";
+        this.code = code;
+    }
+}
+/**
+ * The adapter's DSH-side state dir — the world's DSH home root
+ * (`<dshHome>/agents/codex-sdk`, the world key this package registers in
+ * world-plugin.ts), never the codex app home. Precedence: explicit world home
+ * (boot-provided `dshHomePath`), then `$DSH_HOME` (a hub home, so the world
+ * layout nests `agents/codex-sdk`), then the line's historical test-home
+ * default.
+ */
+export function resolveCodexStateDir(home) {
+    if (home !== undefined) {
+        const dir = resolve(home);
+        return dir;
+    }
+    const fallbackHome = resolve(process.env.DSH_HOME ?? join(process.cwd(), ".tests", "superd"));
+    const dir = join(fallbackHome, "agents", "codex-sdk");
+    return dir;
+}
+/** The map file's path at the world DSH-home root. */
+export function sessionMapPath(home) {
+    return join(resolveCodexStateDir(home), "dsh-sessions.json");
+}
+/** Read the map. Fail-soft: a missing or malformed file reads as `{}`. */
+export function readSessionMap(home) {
+    let raw;
+    try {
+        raw = readFileSync(sessionMapPath(home), "utf8");
+    }
+    catch {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return {};
+    const out = {};
+    for (const [id, value] of Object.entries(parsed)) {
+        const record = coerceRecord(value);
+        if (record !== undefined)
+            out[id] = record;
+    }
+    return out;
+}
+/** Validate one entry; malformed entries are dropped (fail-soft). */
+function coerceRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    const cwd = raw["cwd"];
+    const createdAt = raw["createdAt"];
+    if (typeof cwd !== "string" || cwd === "")
+        return undefined;
+    const threadId = raw["threadId"];
+    const preset = raw["preset"];
+    return {
+        threadId: typeof threadId === "string" && threadId !== "" ? threadId : null,
+        cwd,
+        createdAt: typeof createdAt === "number" && Number.isFinite(createdAt) ? createdAt : 0,
+        preset: typeof preset === "string" && preset !== "" ? preset : null,
+        ...(typeof raw["resumable"] === "boolean" ? { resumable: raw["resumable"] } : {}),
+    };
+}
+/** One session's record, or `undefined` when the id is unknown. */
+export function sessionRecord(home, dshSessionId) {
+    return readSessionMap(home)[dshSessionId];
+}
+/**
+ * Insert or merge one session's record and persist the map atomically
+ * (temp file + rename, same directory). Merge semantics: an omitted `patch`
+ * field keeps the stored value; `threadId: null` explicitly records "not yet
+ * materialized". Throws only when the write itself fails — the caller owns
+ * that decision (create treats an unwritable map as fatal; the observation
+ * path logs and continues).
+ */
+export function upsertSession(home, dshSessionId, patch) {
+    const path = sessionMapPath(home);
+    const map = readSessionMap(home);
+    const previous = map[dshSessionId];
+    const next = {
+        threadId: patch.threadId !== undefined ? patch.threadId : previous?.threadId ?? null,
+        cwd: patch.cwd !== undefined ? patch.cwd : previous?.cwd ?? "",
+        createdAt: patch.createdAt !== undefined ? patch.createdAt : previous?.createdAt ?? Date.now(),
+        preset: patch.preset !== undefined ? patch.preset : previous?.preset ?? null,
+        // Sticky once false (an omitted patch keeps the stored refusal).
+        ...(patch.resumable !== undefined
+            ? { resumable: patch.resumable }
+            : previous?.resumable === false
+                ? { resumable: false }
+                : {}),
+    };
+    map[dshSessionId] = next;
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(map, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        renameSync(temp, path);
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch {
+            // The rename failure is primary.
+        }
+        throw error;
+    }
+    return next;
+}
+/** Drop one session's record (idempotent; failure to persist rethrows). */
+export function forgetSession(home, dshSessionId) {
+    const path = sessionMapPath(home);
+    if (!existsSync(path))
+        return;
+    const map = readSessionMap(home);
+    if (map[dshSessionId] === undefined)
+        return;
+    delete map[dshSessionId];
+    const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(map, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        renameSync(temp, path);
+    }
+    catch (error) {
+        try {
+            rmSync(temp, { force: true });
+        }
+        catch {
+            // The rename failure is primary.
+        }
+        throw error;
+    }
+}

package/agent-codex-sdk/dist/world-plugin.js

@@ -0,0 +1,93 @@
+/**
+ * agent-codex-sdk — the Codex adapter's WORLD plugin (spec S2):
+ * activation IS roster membership.
+ *
+ * AW-B data-plane shape (DL1–DL5 → path-separation T-D), mirroring
+ * `@pgmi-builds/agent-omp/world` so the hub sees both foreign runtimes through
+ * one shape: the world is spawned as a sibling ROOT context with NO listener
+ * and NO webui composition (`worldMountPatches`) — a pure data plane behind
+ * the hub's `/hub` family —
+ *
+ *   1. ctx0 publishes the host mount record (the world's addressability
+ *      entry — no webServer, no fence: those legs retired with the world
+ *      pages) before spawn;
+ *   2. the world's entry row provides the virtual `webServer` (a silent
+ *      sink) plus the neutral `webRuntime` facts its connection row injects;
+ *   3. the hub's `/hub` family answers `?agent=codex-sdk` traffic in ctx0's auth
+ *      domain and dispatches into this world's gateway instance (the
+ *      per-label `/<label>/api` + `/<label>/api/remote.mux` mounts retired
+ *      in T-C, `mountWorld` deleted in T-D).
+ */
+import { mkdirSync } from 'node:fs';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { join } from 'node:path';
+import { spawnWorld, registerAgent, unregisterAgent, setReady, registerForeignTarget, registerHostMount, worldMountPatches, provisionWorldProfile, resolveInstallAnchor, } from '../../superd-hub/dist/index.js';
+export const name = 'agent-codex-sdk';
+/** Runtime key — also the mount label. */
+const KEY = 'codex-sdk';
+export function apply(ctx) {
+    // Roster membership is FIBER-SCOPED (2026-10-03 acceptance finding):
+    // disabling this row from the plugin manager disposes the fiber, and the
+    // entry must go with it. The `/api/agent-runtime` view hides a row whose
+    // host mount is gone, but the raw roster map is never pruned — so without
+    // this disposer a later re-enable dies on `roster: duplicate agent key
+    // codex-sdk`.
+    ctx.effect?.(() => {
+        registerAgent({ key: KEY, label: 'Codex (SDK)', ready: false });
+        return () => unregisterAgent(KEY);
+    }, `agent-${KEY}: roster`);
+    // Harness resolver (env → ~/.dsh): a consumer install has no DSH_HOME and
+    // no cwd contract — deriving the world root from cwd spawns worlds into a
+    // garbage tree or throws inside apply() and kills the whole host boot.
+    const root = resolveDshHome();
+    // S7 nested home: every runtime owns one root under `agents/<label>`, and the
+    // world's DSH data lives INSIDE it (sessions / settings / workspaces), so no
+    // two runtimes ever share a session list. This world's own durable SDK
+    // runtime lives in the same root (`<worldHome>/sdk-runtime/`).
+    const worldHome = join(root, 'agents', KEY);
+    mkdirSync(join(worldHome, 'profiles'), { recursive: true });
+    // Publish story: a foreign install has no line bootstrap, so the nested
+    // profile + @pgmi-builds links are provisioned HERE (idempotent).
+    provisionWorldProfile({
+        key: KEY,
+        adapterPkg: '@pgmi-builds/agent-codex-sdk',
+        worldHome,
+    });
+    const world = (async () => {
+        // T-D: no ctx0 listening-stack wait — the mount record is addressability
+        // only and the /hub family wires its own gate in ctx0 (gateway.ts).
+        const dropHostMount = registerHostMount({ key: KEY, labelPath: `/${KEY}` });
+        const ctxW = await spawnWorld({
+            appName: `superd-${KEY}`,
+            profileName: 'web',
+            installAnchor: resolveInstallAnchor(ctx), // lazy: never at module scope — import must stay side-effect-free
+            home: worldHome,
+            dataHome: worldHome,
+            // The host's live table carries this world: spawnWorld republishes a
+            // widened successor before boot imports anything (spec §2.1), and
+            // @pgmi-builds rows resolve from the profile-local links written above.
+            host: ctx,
+            extraPatches: worldMountPatches(KEY),
+        });
+        const gateway = ctxW.get('typertGateway');
+        registerForeignTarget({ key: KEY, gateway });
+        setReady(KEY, true);
+        ctx.effect?.(() => () => {
+            dropHostMount();
+        }, `agent-${KEY}: mount`);
+        // Toggling the row off must really UNLOAD the world (2026-10-03 omp-sdk
+        // acceptance finding, same shape here): disposing the world's own fiber
+        // disposes its provider, which releases every transport and the refcounted
+        // SDK handle — without this the world outlives its own row.
+        ctx.effect?.(() => () => {
+            void ctxW.fiber?.dispose();
+        }, `agent-${KEY}: world teardown`);
+        return ctxW;
+    })().catch((cause) => {
+        // A failed world degrades to a not-ready roster row; a rejected provided
+        // promise would fail the entire host boot (loader entry apply).
+        console.error(`[super-dsh] ${KEY} world failed:`, cause);
+        return null;
+    });
+    ctx.provide(`superd.world.${KEY}`, world);
+}