@khorsheed/dsh-local-agent-codex 0.2.0-rc.1 → 0.2.0

package/lib/types/endpoint-auth.js

@@ -0,0 +1,300 @@
+/**
+ * Endpoint-key authentication — the codex harness's ONLY auth mode. There is
+ * no web login anywhere in this package: a delegation round reaches its
+ * endpoint with a custom `model_providers` entry on the argv pointing at the
+ * relay and the key traveling as `OPENAI_API_KEY` in the process environment
+ * (verified against codex-cli 0.163.0: a fresh scoped home with only these
+ * runs `codex exec` with no login file at all). With no credential the spawn
+ * carries no auth at all — it fails loudly at the endpoint, exactly the
+ * honest reading the status shows.
+ *
+ * Verified against codex-cli 0.163.0 (2026-10-20): a fresh scoped home with
+ * only `OPENAI_API_KEY` plus the two `-c` overrides below runs
+ * `codex exec -m <model>` end-to-end through an OpenAI-compatible relay
+ * (openproxy, `wire_api = "responses"`) — no login, no auth.json, no
+ * onboarding gate.
+ *
+ * Two layers, merged per field, file over config:
+ *
+ * - `<scopedHome>/endpoint-auth.json` (mode 0600) — the per-scope credential.
+ *   Its name deliberately matches the eval contract hash's credential denylist
+ *   (`auth`), so the key material never enters an evaluation's condition
+ *   fingerprint; the file's mtime serves as the credential stamp, which makes
+ *   "edit the file" the recovery gesture for a `rejected` grade.
+ * - The plugin config's `baseUrl` / `apiKey` — the deployment default every
+ *   scope without a file shares. Read PER ROUND, so a profile edit applies to
+ *   the next round (and a host restart clears the in-memory `rejected` mark).
+ *
+ * `wireApi` is a file-only escape hatch: the settings card never edits it,
+ * the default `responses` is codex's native wire (relay-verified), and a
+ * hand-edit to `"chat"` survives the card's whole-file writes because the
+ * read merges it back. The env layer rides the family's existing plumbing:
+ * `delegationEnv` on the host, `containerExecSpawn`'s name-only `-e`
+ * forwarding into a container — a containerized round authenticates with the
+ * same credential as the host, nothing is authorized inside the unit.
+ * @module @khorsheed/dsh-local-agent-codex/endpoint-auth
+ */
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * The scoped-home credential file's name. Chosen to match the eval contract
+ * hash's credential-shaped denylist (`/token|key|credential|secret|password|auth|\.env/i`),
+ * so the file is excluded from condition fingerprints by name.
+ */
+export const ENDPOINT_AUTH_FILE = 'endpoint-auth.json';
+/** The custom provider's TOML key in the `-c` overrides (bare-key safe). */
+export const ENDPOINT_PROVIDER_NAME = 'dsh-endpoint';
+/** The env var the custom provider reads the key from (`env_key`). */
+export const ENDPOINT_ENV_KEY = 'OPENAI_API_KEY';
+/** Trim and normalize one credential field; blank reads as absent. */
+function field(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/** Whether a resolved endpoint carries a usable credential. */
+export function hasEndpointCredential(auth) {
+    return auth !== undefined && field(auth.apiKey) !== undefined;
+}
+/**
+ * Read the scope's endpoint-auth.json. Absent or unreadable yields undefined
+ * (the caller falls back to the plugin config); malformed JSON or a non-object
+ * payload also yields undefined — a torn file must not fail a status read.
+ * Non-string fields are dropped, never carried through.
+ * @param homeDir - the `codex` harness's scoped home.
+ * @returns the file's endpoint credential, or undefined.
+ */
+export async function readEndpointAuthFile(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, ENDPOINT_AUTH_FILE), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        const baseUrl = field(parsed['baseUrl']);
+        const apiKey = field(parsed['apiKey']);
+        const wireApi = field(parsed['wireApi']);
+        return {
+            ...baseUrl === undefined ? {} : { baseUrl },
+            ...apiKey === undefined ? {} : { apiKey },
+            ...wireApi === undefined ? {} : { wireApi },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve one scope's effective endpoint credential: the scope's
+ * endpoint-auth.json merged FIELD BY FIELD over the plugin config's
+ * `baseUrl` / `apiKey` (a file that names only a key rotates the key while
+ * keeping the deployment's relay URL). The result may carry no credential at
+ * all — {@link hasEndpointCredential} is the judgment, kept separate so the
+ * caller can still route/log the resolved baseUrl.
+ * @param homeDir - the scope's scoped home.
+ * @param config - the plugin config's deployment-level endpoint pair.
+ * @returns the merged endpoint auth.
+ */
+export async function resolveEndpointAuth(homeDir, config) {
+    const file = await readEndpointAuthFile(homeDir);
+    const configBaseUrl = field(config.baseUrl);
+    const configApiKey = field(config.apiKey);
+    return {
+        ...configBaseUrl === undefined ? {} : { baseUrl: configBaseUrl },
+        ...configApiKey === undefined ? {} : { apiKey: configApiKey },
+        ...file,
+    };
+}
+/**
+ * The spawn-env layer for a resolved endpoint: the key under the custom
+ * provider's `env_key` name, nothing else. A credential-less resolution
+ * yields an empty layer — the spread then adds no keys at all, byte-identical
+ * to the pre-endpoint env. With no baseUrl the CLI's built-in OpenAI provider
+ * reads the same variable, so an official platform key needs no `-c`
+ * override either.
+ * @param auth - the resolved endpoint auth, or undefined.
+ * @returns the explicit env entries for the delegation spawn.
+ */
+export function endpointAuthEnv(auth) {
+    const apiKey = field(auth?.apiKey);
+    return apiKey === undefined ? {} : { [ENDPOINT_ENV_KEY]: apiKey };
+}
+/** Quote one TOML basic string for the `-c` config override. */
+function tomlString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * The `-c` config overrides routing the CLI at the resolved relay: a custom
+ * `model_providers` entry plus the `model_provider` selection, as a flat argv
+ * fragment (`-c <override>` pairs). Empty unless BOTH a key and a baseUrl are
+ * present — a key without a relay URL is served by the built-in provider
+ * through the env layer alone, and a relay URL without a key would route
+ * every round into a 401. Verified end-to-end against codex-cli 0.163.0.
+ * @param auth - the resolved endpoint auth, or undefined.
+ * @returns the argv fragment, possibly empty.
+ */
+export function endpointConfigOverrides(auth) {
+    const baseUrl = field(auth?.baseUrl);
+    const apiKey = field(auth?.apiKey);
+    if (baseUrl === undefined || apiKey === undefined)
+        return [];
+    const wireApi = field(auth?.wireApi) ?? 'responses';
+    return [
+        '-c', `model_provider=${tomlString(ENDPOINT_PROVIDER_NAME)}`,
+        '-c', `model_providers.${ENDPOINT_PROVIDER_NAME}={`
+            + `name=${tomlString(ENDPOINT_PROVIDER_NAME)},`
+            + `base_url=${tomlString(baseUrl)},`
+            + `env_key=${tomlString(ENDPOINT_ENV_KEY)},`
+            + `wire_api=${tomlString(wireApi)}`
+            + `}`,
+    ];
+}
+/**
+ * The credential marker's modification stamp (epoch ms): the endpoint file's
+ * mtime, or undefined when the scope has no file (a config-sourced credential
+ * has no marker — rotating it pairs with the profile edit and instance
+ * restart that clear the in-memory grade marks). A fresh file write is a
+ * fresh stamp, which is how an edited-in key recovers a `rejected` grade.
+ * @param homeDir - the scope's scoped home.
+ * @returns the stamp, or undefined.
+ */
+export async function endpointAuthStamp(homeDir) {
+    try {
+        return (await stat(join(homeDir, ENDPOINT_AUTH_FILE))).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the scope carries its own endpoint file at all. */
+export async function endpointAuthFileExists(homeDir) {
+    return (await endpointAuthStamp(homeDir)) !== undefined;
+}
+/**
+ * Write the scope's endpoint-auth.json (mode 0600, mkdir -p first). The
+ * payload preserves the file-only `wireApi` across card writes: callers pass
+ * the merged object (current file + edits), never a bare card payload.
+ * @param homeDir - the scope's scoped home.
+ * @param auth - the endpoint credential to persist.
+ */
+export async function writeEndpointAuth(homeDir, auth) {
+    await mkdir(homeDir, { recursive: true });
+    const baseUrl = field(auth.baseUrl);
+    const apiKey = field(auth.apiKey);
+    const wireApi = field(auth.wireApi);
+    const payload = {
+        ...baseUrl === undefined ? {} : { baseUrl },
+        ...apiKey === undefined ? {} : { apiKey },
+        ...wireApi === undefined ? {} : { wireApi },
+    };
+    await writeFile(join(homeDir, ENDPOINT_AUTH_FILE), JSON.stringify(payload, undefined, 2) + '\n', { mode: 0o600 });
+}
+/**
+ * Clear the scope's OWN endpoint credential (the endpoint-auth.json file).
+ * A deployment-level credential from the plugin config is untouched — the
+ * core's logout reply then names the profile row as the place to edit.
+ * @param homeDir - the scope's scoped home.
+ */
+export async function clearEndpointAuth(homeDir) {
+    await rm(join(homeDir, ENDPOINT_AUTH_FILE), { force: true });
+}
+/** The official endpoint used when no baseUrl is configured anywhere. */
+export const OFFICIAL_BASE_URL = 'https://api.openai.com';
+/** How many served model ids the check reply lists before truncating. */
+const CHECK_MODEL_LIST_LIMIT = 8;
+/** Bound on the error-body excerpt a failed check reports. */
+const CHECK_ERROR_BODY_LIMIT = 200;
+/**
+ * `GET <baseUrl>/v1/models` with `Authorization: Bearer <key>` — the
+ * token-free endpoint probe shared by the `/codex check` verdict and any
+ * future catalog. OpenAI's own API serves this route with the platform key;
+ * relays (openproxy verified 2026-10-20, 139 models) proxy it and answer the
+ * same OpenAI-list shape. Never throws: every failure mode folds into the
+ * result.
+ * @param endpoint - the resolved endpoint auth with a decided baseUrl.
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param signal - abort for the whole probe (timeout bundled by the caller).
+ * @returns the folded result.
+ */
+export async function fetchEndpointModels(endpoint, fetchImpl, signal) {
+    const headers = {};
+    if (endpoint.apiKey !== undefined)
+        headers['authorization'] = `Bearer ${endpoint.apiKey}`;
+    const fetcher = fetchImpl ?? globalThis.fetch;
+    // The OpenAI convention names the base WITH `/v1` (codex's own
+    // `model_providers.*.base_url` does), the relay convention sometimes omits
+    // it — accept both instead of doubling the segment.
+    const root = endpoint.baseUrl.replace(/\/+$/, '');
+    const url = `${root}${root.endsWith('/v1') ? '' : '/v1'}/models`;
+    let response;
+    try {
+        response = await fetcher(url, { headers, signal: signal ?? AbortSignal.timeout(8_000) });
+    }
+    catch (error) {
+        return { kind: 'unreachable', message: error instanceof Error ? error.message : String(error) };
+    }
+    if (!response.ok) {
+        return { kind: 'http', status: response.status, body: (await response.text().catch(() => '')).slice(0, CHECK_ERROR_BODY_LIMIT) };
+    }
+    let data;
+    try {
+        data = JSON.parse(await response.text()).data;
+    }
+    catch {
+        return { kind: 'malformed' };
+    }
+    if (!Array.isArray(data))
+        return { kind: 'malformed' };
+    const models = [];
+    for (const entry of data) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const id = entry.id;
+        if (typeof id === 'string' && id !== '')
+            models.push(id);
+    }
+    return { kind: 'models', models };
+}
+/**
+ * Probe the resolved endpoint with a cheap, token-free round-trip: `GET
+ * <baseUrl>/v1/models` with the resolved credential's Bearer header. A 200
+ * proves both reachability and credential validity — the exact evidence a
+ * "verify" button needs — and the served model list rides the reply. One
+ * transport-level retry rides along: a local proxy restart (a Surge/clash
+ * reload) stalls the first attempt into the timeout and answers the retry
+ * immediately. Never throws: every failure mode folds into the reply text,
+ * since the reply IS the diagnostic.
+ * @param endpoint - the resolved endpoint auth (scope file over settings).
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param timeoutMs - one attempt's deadline (two attempts at most).
+ * @returns the human-readable verdict for the check reply.
+ */
+export async function checkCodexEndpoint(endpoint, fetchImpl, timeoutMs = 20_000) {
+    if (!hasEndpointCredential(endpoint)) {
+        return 'No endpoint credential configured — fill Base URL and API Key on the settings card (or the profile row) first.';
+    }
+    const baseUrl = (endpoint.baseUrl ?? OFFICIAL_BASE_URL).replace(/\/+$/, '');
+    let result = await fetchEndpointModels({ ...endpoint, baseUrl }, fetchImpl, AbortSignal.timeout(timeoutMs));
+    if (result.kind === 'unreachable') {
+        result = await fetchEndpointModels({ ...endpoint, baseUrl }, fetchImpl, AbortSignal.timeout(timeoutMs));
+    }
+    if (result.kind === 'unreachable')
+        return `Endpoint unreachable (${baseUrl}): ${result.message}`;
+    if (result.kind === 'http') {
+        return `Endpoint answered HTTP ${String(result.status)} (${baseUrl})${result.body === '' ? '' : `: ${result.body}`}`;
+    }
+    if (result.kind === 'malformed') {
+        return `Endpoint reachable (${baseUrl}) but the model list did not parse — the credential worked, the reply was not /v1/models-shaped.`;
+    }
+    if (result.models.length === 0)
+        return `Endpoint reachable (${baseUrl}); it serves no models.`;
+    const listed = result.models.slice(0, CHECK_MODEL_LIST_LIMIT).join(', ');
+    const more = result.models.length > CHECK_MODEL_LIST_LIMIT ? `, … +${String(result.models.length - CHECK_MODEL_LIST_LIMIT)} more` : '';
+    return `Endpoint reachable (${baseUrl}): ${String(result.models.length)} model(s) served — ${listed}${more}`;
+}

package/lib/types/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * Codex harness instantiation of the local-agent family. Registers the
  * `codex` harness into the core registry: scoped home under the shared homes
- * root (`CODEX_HOME`), device-code login through `codex login --device-auth`
- * (prompt captured from stdout), and rollout-file session records.
+ * root (`CODEX_HOME`), endpoint-key authentication (endpoint-auth.ts — no web
+ * login anywhere), and rollout-file session records.
  * Delegation mounts through the `codex-local` provider (one-shot
  * `codex exec` under the scoped home); the bundle patch's
  * `tool-subagent-codex-local` row puts the tool on the profile root, so
@@ -16,7 +16,8 @@ import z from '@deepseek-ai/schemastery';
 export declare const name = "local-agent-codex";
 /**
  * Boot delay before the model catalog's eager warmup probe fires. The probe
- * spawns a `codex app-server` — cheap, but not free — so it waits out the
+ * fetches the endpoint's served model list AND spawns a `codex app-server`
+ * (the native metadata side) — cheap, but not free — so it waits out the
  * boot storm instead of competing with it, and the FIRST settings-card open
  * usually hits a warm cache. A card opened before the timer fires simply
  * triggers the probe itself (the read path's lazy kick), so the delay never
@@ -29,6 +30,21 @@ export declare const inject: string[];
 export interface Config {
     /** Codex sandbox policy for `codex exec` / app-server threads; defaults to workspace-write. */
     sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    /**
+     * Deployment-level endpoint credential: the relay's base URL (an
+     * OpenAI-compatible `/v1` root, e.g. a proxy relay). Merged per field UNDER
+     * the scope's own `endpoint-auth.json` (the settings card writes that file
+     * through the endpointAuth face). A scope with an endpoint key
+     * authenticates by endpoint — the round's argv routes at the relay; a scope
+     * without one is unauthenticated (there is no login flow).
+     */
+    baseUrl?: string;
+    /**
+     * Deployment-level endpoint key (the custom provider's `env_key` value,
+     * sent as `Authorization: Bearer`). See {@link baseUrl} for the merge
+     * order. Absent everywhere = unauthenticated.
+     */
+    apiKey?: string;
     /**
      * The model every delegation round starts the CLI with (`codex exec -m
      * <model>`, and `-c model=…` for the resident app-server). Absent — the

package/lib/types/index.js

@@ -1,8 +1,8 @@
 /**
  * Codex harness instantiation of the local-agent family. Registers the
  * `codex` harness into the core registry: scoped home under the shared homes
- * root (`CODEX_HOME`), device-code login through `codex login --device-auth`
- * (prompt captured from stdout), and rollout-file session records.
+ * root (`CODEX_HOME`), endpoint-key authentication (endpoint-auth.ts — no web
+ * login anywhere), and rollout-file session records.
  * Delegation mounts through the `codex-local` provider (one-shot
  * `codex exec` under the scoped home); the bundle patch's
  * `tool-subagent-codex-local` row puts the tool on the profile root, so
@@ -11,20 +11,22 @@
  * @module @khorsheed/dsh-local-agent-codex
  */
 import z from '@deepseek-ai/schemastery';
-import { settingsFace, vol } from '@khorsheed/dsh-local-agent';
+import { firstModelOf, readModelList, readModelListSync, settingsFace, vol, writeModelList } from '@khorsheed/dsh-local-agent';
 import { endpointHost } from '@khorsheed/dsh-local-agent/types';
 import { CodexCliProvider, codexCliVersion } from './codex-cli-provider.js';
+import { checkCodexEndpoint, clearEndpointAuth, endpointAuthFileExists, endpointAuthStamp, hasEndpointCredential, readEndpointAuthFile, resolveEndpointAuth, writeEndpointAuth, } from './endpoint-auth.js';
 import { DEFAULT_LIVE_IDLE_MS } from './live-driver.js';
 import { LiveDriverSwitch } from './live-switch.js';
 import { CodexModelBroker } from './model-broker.js';
 import { CodexModelCatalog } from './model-catalog.js';
-import { codexAuthenticated, listCodexSessions } from './records.js';
-import { codexCredentialStamp, codexLogout, provisionCodexConfig, readCodexBaseUrl, readCodexModel, readCodexReasoningEffort } from './provision.js';
+import { listCodexSessions } from './records.js';
+import { provisionCodexConfig, readCodexBaseUrl, readCodexModel, readCodexReasoningEffort } from './provision.js';
 /** Stable Cordis plugin name; the bundle patch row id. */
 export const name = 'local-agent-codex';
 /**
  * Boot delay before the model catalog's eager warmup probe fires. The probe
- * spawns a `codex app-server` — cheap, but not free — so it waits out the
+ * fetches the endpoint's served model list AND spawns a `codex app-server`
+ * (the native metadata side) — cheap, but not free — so it waits out the
  * boot storm instead of competing with it, and the FIRST settings-card open
  * usually hits a warm cache. A card opened before the timer fires simply
  * triggers the probe itself (the read path's lazy kick), so the delay never
@@ -65,6 +67,10 @@ export const Config = z.object({
         z.const('workspace-write'),
         z.const('danger-full-access'),
     ]),
+    // The deployment-level endpoint pair is plain config (never volatile): it
+    // is the profile row's business, and the card writes the scope's own file.
+    baseUrl: z.string(),
+    apiKey: z.string(),
     model: volatilize(SETTINGS_FIELDS.model),
     live: volatilize(SETTINGS_FIELDS.live),
     liveIdleMs: z.number().default(DEFAULT_LIVE_IDLE_MS),
@@ -93,8 +99,8 @@ export function apply(ctx, config) {
     ctx.effect(() => {
         const sandbox = config.sandbox ?? DEFAULT_SANDBOX;
         const homeDir = ctx.localAgent.homeDir('codex');
-        // Codex's default credential store on macOS is the keychain; pin
-        // file-based storage so login lands in the scoped home's auth.json.
+        // Provision the scoped config (and sweep the web-login era's leftover
+        // auth.json — the harness no longer consults it).
         void provisionCodexConfig(homeDir).catch((error) => {
             ctx.logger.warn(`local-agent-codex: config.toml provisioning failed: ${error instanceof Error ? error.message : String(error)}`);
         });
@@ -134,10 +140,16 @@ export function apply(ctx, config) {
         // delegation without a plugin reload — exactly like the live toggle.
         // Blank is not a model: a whitespace-only value means "unset", which is
         // the pre-key argv.
-        const resolveModel = () => {
+        const resolveModelKey = () => {
             const model = face.get().model?.trim();
             return model === undefined || model === '' ? undefined : model;
         };
+        // The settings layer for one scoped home: the curated model list's FIRST
+        // entry (models.json, edited on the card), ahead of the settings key; an
+        // empty list leaves the pre-existing chain untouched. Read sync per call
+        // — one small file, and a card write always reaches the next round.
+        const resolveModelFor = (homeDir) => firstModelOf(readModelListSync(homeDir)) ?? resolveModelKey();
+        const resolveModel = (scope) => resolveModelFor(ctx.localAgent.homeDir('codex', scope));
         // The member-level model surface: the composer picker's session-level
         // overrides (in-memory, deliberately lost on a host restart), shared by
         // reference with the broker (which writes them), the exec provider (which
@@ -146,9 +158,20 @@ export function apply(ctx, config) {
         // different model retires that runtime — the next round respawns onto the
         // new model while the codex thread itself resumes.
         const memberModelOverrides = new Map();
+        // The endpoint credential's deployment level: the plugin config pair,
+        // merged per field UNDER the scope's own endpoint-auth.json at resolve
+        // time. Resolved PER READ against the scope's home — a card write (which
+        // lands in the file through the endpointAuth face) takes effect on the
+        // next round with no reload.
+        const endpointConfig = {
+            ...config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl },
+            ...config.apiKey === undefined ? {} : { apiKey: config.apiKey },
+        };
+        const resolveEndpoint = (scopeHome) => resolveEndpointAuth(scopeHome, endpointConfig);
         const modelCatalog = new CodexModelCatalog({
             spawn: spec => ctx.subprocess.spawn(spec),
             warn: message => ctx.logger.warn(message),
+            endpoint: resolveEndpoint,
         });
         // Eager warmup: kick one background probe of the DEFAULT scoped home
         // shortly after apply completes (never blocking it — read() is the
@@ -164,12 +187,18 @@ export function apply(ctx, config) {
         warmup.unref();
         const liveSwitch = new LiveDriverSwitch(ctx, face, {
             sandbox,
-            model: childSessionId => memberModelOverrides.get(childSessionId) ?? resolveModel(),
+            // The member's scope decides whose list answers: a named scope's
+            // rounds read that scope's models.json, exactly like its endpoint
+            // credential.
+            model: childSessionId => memberModelOverrides.get(childSessionId)
+                ?? resolveModel((ctx.localAgent.memberBinding?.(childSessionId) ?? ctx.localAgent.getDelegation(childSessionId))?.scope),
+            endpoint: resolveEndpoint,
             ...config.liveIdleMs === undefined ? {} : { liveIdleMs: config.liveIdleMs },
         });
         const modelBroker = new CodexModelBroker({
             ctx,
-            settingsModel: resolveModel,
+            settingsModel: resolveModelFor,
+            modelList: homeDir => readModelListSync(homeDir),
             recentModels: () => face.get().recentModels ?? [],
             homeDir: childSessionId => ctx.localAgent.homeDir('codex', childSessionId === undefined ? undefined : (ctx.localAgent.memberBinding?.(childSessionId) ?? ctx.localAgent.getDelegation(childSessionId))?.scope),
             cwd: childSessionId => childSessionId === undefined ? undefined : (ctx.localAgent.memberBinding?.(childSessionId) ?? ctx.localAgent.getDelegation(childSessionId))?.cwd,
@@ -189,7 +218,7 @@ export function apply(ctx, config) {
             // cache.
             catalogDefault: (scopedHome, cwd) => modelCatalog.readDefault(scopedHome, cwd),
         });
-        const disposeProvider = ctx.subagents.registerProvider(new CodexCliProvider(ctx, sandbox, liveSwitch.resolve, resolveModel, childSessionId => memberModelOverrides.get(childSessionId)));
+        const disposeProvider = ctx.subagents.registerProvider(new CodexCliProvider(ctx, sandbox, liveSwitch.resolve, resolveModel, childSessionId => memberModelOverrides.get(childSessionId), resolveEndpoint));
         const disposeHarness = ctx.localAgent.register({
             prepareMember: async ({ binding, childSession, configuration, signal }) => {
                 const driver = liveSwitch.resolve(binding.childSessionId);
@@ -203,39 +232,109 @@ export function apply(ctx, config) {
             homeEnvVar: 'CODEX_HOME',
             delegationProvider: 'codex-local',
             modelBroker,
-            // A PTY run of plain `codex login` starts a localhost callback server
-            // (no device code, no paste) and opens the browser itself — the
-            // first-class flow. `--device-auth` remains the documented headless
-            // fallback for remote terminals.
-            login: { pty: { command: 'codex', args: ['login'] } },
+            // The settings card's curated model list (the default scope's
+            // models.json; named scopes carry their own, read per round).
+            modelList: {
+                read: home => readModelList(home),
+                write: (home, models) => writeModelList(home, models),
+            },
+            // No `login` declaration: the harness authenticates by endpoint key
+            // (endpoint-auth.ts), so the core reports the harness as not loginable
+            // and `/codex login` answers that there is no login flow — no browser,
+            // no device code, nothing to authorize inside a container.
             records: { listSessions: homeDir => listCodexSessions(homeDir) },
             // A NAMED scope's directory is provisioned through this hook when the
             // registry materializes it — the same `config.toml` storage pin the
-            // default scope gets from the apply above, so a scope's first login
-            // lands in its own `auth.json` instead of the macOS keychain.
+            // default scope gets from the apply above.
             provision: scopedHome => provisionCodexConfig(scopedHome).then(() => { }),
-            isAuthenticated: codexAuthenticated,
-            credentialStamp: codexCredentialStamp,
-            logout: codexLogout,
+            // Endpoint-key only: a scope is authenticated when its resolved
+            // endpoint (scope file over plugin config) carries a non-empty key.
+            // The web login is gone — provisioning sweeps its leftover auth.json,
+            // so a stale grant can never keep a round alive past the upgrade.
+            // The verdict rides the family's credential grades untouched — a
+            // completed round grades `verified`, a round's 401 grades `rejected`
+            // until the credential marker's mtime moves past the mark.
+            isAuthenticated: async (home) => hasEndpointCredential(await resolveEndpoint(home)),
+            // The settings card's verify button: a cheap token-free probe of the
+            // SAVED endpoint (the reply tells the user to save first when a
+            // credential is missing). Session-less via the gateway Remote.
+            checkEndpoint: home => resolveEndpoint(home).then(endpoint => checkCodexEndpoint(endpoint)),
+            // The settings card's credential form: read the resolved per-field
+            // state (the key as a boolean), write edits into the scope's own
+            // endpoint-auth.json — the harness's 0600 store, never the profile
+            // patch document. A cleared field falls back to the config pair; the
+            // file-only `wireApi` survives card writes through the merge.
+            endpointAuth: {
+                read: async (home) => {
+                    const endpoint = await resolveEndpoint(home);
+                    return {
+                        ...endpoint.baseUrl === undefined ? {} : { baseUrl: endpoint.baseUrl },
+                        apiKeySet: endpoint.apiKey !== undefined,
+                        authTokenSet: false,
+                    };
+                },
+                write: async (home, fields) => {
+                    const current = await readEndpointAuthFile(home) ?? {};
+                    const next = { ...current };
+                    // The card's vocabulary is baseUrl/apiKey; an authToken field never
+                    // applies to codex's Bearer key and is refused loudly by the merge
+                    // below (ignored here so the shared face stays usable).
+                    for (const [field, value] of Object.entries(fields)) {
+                        if (field !== 'baseUrl' && field !== 'apiKey')
+                            continue;
+                        if (value === undefined)
+                            continue;
+                        const trimmed = typeof value === 'string' ? value.trim() : '';
+                        if (value === null || trimmed === '')
+                            delete next[field];
+                        else
+                            next[field] = trimmed;
+                    }
+                    if (Object.keys(next).length === 0)
+                        await clearEndpointAuth(home);
+                    else
+                        await writeEndpointAuth(home, next);
+                },
+            },
+            // The grade marker is the endpoint file's mtime (editing it IS the
+            // re-login gesture); a config-sourced credential has no marker, and a
+            // host restart clears the in-memory `rejected` mark.
+            credentialStamp: endpointAuthStamp,
+            // Logout clears the scope's OWN endpoint file. A config-sourced
+            // credential outlives it — said out loud, or the status would flip
+            // right back and read as a failed logout.
+            logout: async (home) => {
+                if (await endpointAuthFileExists(home)) {
+                    await clearEndpointAuth(home);
+                    return;
+                }
+                throw new Error('codex has no scoped endpoint-auth.json to clear — the credential comes from the settings card or the profile row (baseUrl/apiKey); clear it there instead');
+            },
             // The eval snapshot: the sandbox policy comes from the plugin config
             // (it rides every spawn argv); effort and endpoint are read live from
             // the scoped config, which codex itself reads — a person-edited value
             // is exactly what the rounds run with. The model follows the family's
-            // fixed order: the plugin config key (it overrides the file on every
-            // argv) before the scoped config's own `model`, absent when neither
-            // names one.
+            // fixed order: the scope's curated list (its first entry) before the
+            // plugin config key before the scoped config's own `model`, absent
+            // when none names one.
             // The directory is a PARAMETER, not the apply-time capture: a status
             // read (or an evaluation snapshot) of a named scope must report the
             // config that scope's rounds would run with, which is the config in
             // that scope's own directory.
             effectiveSettings: async (scopedHome) => {
-                const [reasoningEffort, baseUrl, scopedModel, cliVersion] = await Promise.all([
+                const [reasoningEffort, endpoint, scopedModel, cliVersion] = await Promise.all([
                     readCodexReasoningEffort(scopedHome).catch(() => undefined),
-                    readCodexBaseUrl(scopedHome).catch(() => undefined),
+                    resolveEndpoint(scopedHome).catch(() => undefined),
                     readCodexModel(scopedHome).catch(() => undefined),
                     codexCliVersion(ctx, scopedHome).catch(() => undefined),
                 ]);
-                const model = resolveModel() ?? scopedModel;
+                // The endpoint in effect: an endpoint credential's own baseUrl (the
+                // relay the rounds route at) wins; with no credential the scoped
+                // config.toml's custom provider answers, as it always did.
+                const baseUrl = hasEndpointCredential(endpoint)
+                    ? endpoint.baseUrl
+                    : await readCodexBaseUrl(scopedHome).catch(() => undefined);
+                const model = resolveModelFor(scopedHome) ?? scopedModel;
                 const baseUrlHost = baseUrl !== undefined ? endpointHost(baseUrl) : undefined;
                 return {
                     drive: face.get().live ? 'live' : 'exec',

package/lib/types/live-driver.d.ts

@@ -27,6 +27,7 @@ import { type SubagentRun, type SubagentStartRequest } from '@deepseek-ai/dsh-su
 import type { Config } from './index.ts';
 import type { LocalAgentResolvedConfiguration } from '@khorsheed/dsh-local-agent/types';
 import { type CodexTranscriptLine } from './codex-cli-provider.ts';
+import { type CodexEndpointAuth } from './endpoint-auth.ts';
 /** Default idle lifetime of an unused resident runtime before reclaim. */
 export declare const DEFAULT_LIVE_IDLE_MS: number;
 /** Default timeout for a wire request acknowledgement. */
@@ -41,11 +42,6 @@ export declare const DEFAULT_LIVE_CHANNEL_RETRY_MS: number;
 export declare const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 50;
 /** Default minimum text growth between one streaming item's snapshot messages. */
 export declare const DEFAULT_SNAPSHOT_MIN_CHARS = 0;
-/**
- * The app-server channel could not come up (spawn failure or handshake
- * timeout/mismatch). The provider catches exactly this and falls back to the
- * exec one-shot; any other error is a real round failure.
- */
 export declare class LiveChannelUnavailableError extends Error {
     constructor(message: string);
 }
@@ -146,6 +142,14 @@ export declare class CodexLiveDriver {
          * argv unchanged.
          */
         model?: (childSessionId: string) => string | undefined;
+        /**
+         * Resolver for the scope's endpoint credential, read at each RUNTIME
+         * SPAWN so a settings-card write reaches the next respawn without a
+         * reload. A resolution carrying a key routes the app-server at the
+         * relay (custom `model_providers` `-c` overrides plus the key in the
+         * process env), exactly as on the exec path.
+         */
+        endpoint?: (scopeHome: string) => Promise<CodexEndpointAuth>;
     }, timeouts?: CodexLiveDriverTimeouts);
     /** Whether the channel is in its post-failure cooldown (rounds fall back to exec). */
     get disabled(): boolean;