@khorsheed/dsh-local-agent-claude-code 0.2.0-rc.1 → 0.2.0-rc.3

package/lib/types/index.d.ts

@@ -1,13 +1,13 @@
 /**
  * Claude Code harness instantiation of the local-agent family. Registers the
  * `claude-code` harness into the core registry: scoped home under the shared
- * homes root (`CLAUDE_CONFIG_DIR`), login as a manual handoff (claude ≥2.1
- * prints no OAuth URL off a TTY, so `/login` replies with the exact terminal
- * command and the registry watches for the credential), and project-file
- * session records. Delegation mounts through the `claude-local` provider
- * (one-shot `claude -p --output-format json` under the scoped home); the
- * bundle patch's `tool-subagent-claude-code-local` row puts the tool on the
- * profile root, so every agent preset can delegate.
+ * homes root (`CLAUDE_CONFIG_DIR`), endpoint-key authentication (the scope's
+ * `endpoint-auth.json` over the plugin config's `baseUrl`/`apiKey`/
+ * `authToken` triple — no OAuth, no browser flow, nothing to authorize inside
+ * a container), and project-file session records. Delegation mounts through
+ * the `claude-local` provider (one-shot `claude -p` under the scoped home);
+ * the bundle patch's `tool-subagent-claude-code-local` row puts the tool on
+ * the profile root, so every agent preset can delegate.
  *
  * @module @khorsheed/dsh-local-agent-claude-code
  */
@@ -17,7 +17,7 @@ import z from '@deepseek-ai/schemastery';
 export declare const name = "local-agent-claude-code";
 /** Services required before the harness can register. */
 export declare const inject: string[];
-/** Plugin config: the permission mode fresh delegations default to, plus the live driver. */
+/** Plugin config: the permission mode fresh delegations default to, the endpoint credential, plus the live driver. */
 export interface Config {
     /**
      * `claude -p` permission handling; `skip` passes
@@ -36,17 +36,33 @@ export interface Config {
      */
     model?: string;
     /**
-     * `ANTHROPIC_BASE_URL` for the child CLI; absent inherits the host
-     * process environment (a user-level proxy like `https://proxy.example.com/anthropic`
-     * is typically exported there). Set when delegations must route through a
-     * different endpoint than the login flow used.
+     * The deployment-level endpoint: `ANTHROPIC_BASE_URL` for every delegation
+     * (e.g. a relay like `https://openproxy.to/claude`, or absent for the
+     * official API). A scope's own `endpoint-auth.json` overrides it field by
+     * field — the settings card's credential form edits THAT file (never the
+     * profile). See endpoint-auth.ts for the whole auth model — there is no
+     * OAuth path in this package.
      */
     baseUrl?: string;
     /**
-     * HTTP proxy for the child CLI's own traffic (model calls AND OAuth
-     * refresh), provisioned into the scoped `settings.json` env block. Needed
-     * when the host process environment carries no proxy (a supervisor-spawned
-     * instance does not inherit the user's shell exports).
+     * The deployment-level credential, sent as `ANTHROPIC_API_KEY` (the
+     * `x-api-key` header). Keep it in the LOCAL profile row only — never commit
+     * it (the repo hygiene gate blocks credential-shaped strings, but the
+     * profile is not the repo's business).
+     */
+    apiKey?: string;
+    /**
+     * The deployment-level credential, sent as `ANTHROPIC_AUTH_TOKEN` (the
+     * `Authorization: Bearer` header) — some relays expect Bearer instead of
+     * `x-api-key`. When both keys are set the CLI's own precedence applies.
+     */
+    authToken?: string;
+    /**
+     * HTTP proxy for the child CLI's own traffic, provisioned into the scoped
+     * `settings.json` env block. Needed when the host process environment
+     * carries no proxy (a supervisor-spawned instance does not inherit the
+     * user's shell exports). Distinct from {@link baseUrl}: this is a local
+     * traffic forwarder, not the model endpoint.
      */
     proxyUrl?: string;
     /**

package/lib/types/index.js

@@ -1,13 +1,13 @@
 /**
  * Claude Code harness instantiation of the local-agent family. Registers the
  * `claude-code` harness into the core registry: scoped home under the shared
- * homes root (`CLAUDE_CONFIG_DIR`), login as a manual handoff (claude ≥2.1
- * prints no OAuth URL off a TTY, so `/login` replies with the exact terminal
- * command and the registry watches for the credential), and project-file
- * session records. Delegation mounts through the `claude-local` provider
- * (one-shot `claude -p --output-format json` under the scoped home); the
- * bundle patch's `tool-subagent-claude-code-local` row puts the tool on the
- * profile root, so every agent preset can delegate.
+ * homes root (`CLAUDE_CONFIG_DIR`), endpoint-key authentication (the scope's
+ * `endpoint-auth.json` over the plugin config's `baseUrl`/`apiKey`/
+ * `authToken` triple — no OAuth, no browser flow, nothing to authorize inside
+ * a container), and project-file session records. Delegation mounts through
+ * the `claude-local` provider (one-shot `claude -p` under the scoped home);
+ * the bundle patch's `tool-subagent-claude-code-local` row puts the tool on
+ * the profile root, so every agent preset can delegate.
  *
  * @module @khorsheed/dsh-local-agent-claude-code
  */
@@ -15,19 +15,22 @@ import z from '@deepseek-ai/schemastery';
 import { settingsFace, vol } from '@khorsheed/dsh-local-agent';
 import { endpointHost } from '@khorsheed/dsh-local-agent/types';
 import { ClaudeCliProvider, claudeCliVersion } from './claude-cli-provider.js';
+import { checkClaudeEndpoint, 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 { ClaudeModelCatalog } from './model-catalog.js';
 import { ClaudeModelBroker, ClaudeScopedModelMemory } from './model-broker.js';
-import { claudeAuthenticated, claudeCredentialStamp, listClaudeSessions, readClaudeTranscriptModel, syncClaudeCredentialFile } from './records.js';
-import { claudeLogout, provisionClaudeHome, readClaudeConfiguredModel } from './provision.js';
+import { firstModelOf, readModelList, readModelListSync, writeModelList } from '@khorsheed/dsh-local-agent';
+import { listClaudeSessions, readClaudeTranscriptModel } from './records.js';
+import { provisionClaudeHome, readClaudeConfiguredModel } from './provision.js';
 /** Stable Cordis plugin name; the bundle patch row id. */
 export const name = 'local-agent-claude-code';
 /** Services required before the harness can register. */
 export const inject = ['localAgent', 'subagents', 'subprocess', 'settings'];
 /**
  * The settings fields (`live`, `liveMirrorGranularity`, `model`,
- * `recentModels`) ride the plugin Config, marked `.volatile()` where the
+ * `recentModels`, and the endpoint credential `baseUrl`/`apiKey`/`authToken`)
+ * ride the plugin Config, marked `.volatile()` where the
  * host's schemastery has it (3.18.4+, the rc.1 line — probed, never sniffed):
  * there the SettingsForms writes hot-track the running fiber's Volatile
  * references without a remount, and the official one-shot import moves an old
@@ -58,6 +61,8 @@ export const Config = z.object({
     ]),
     model: volatilize(SETTINGS_FIELDS.model),
     baseUrl: z.string(),
+    apiKey: z.string(),
+    authToken: z.string(),
     proxyUrl: z.string(),
     live: volatilize(SETTINGS_FIELDS.live),
     liveIdleMs: z.number().default(DEFAULT_LIVE_IDLE_MS),
@@ -85,7 +90,6 @@ const CLAUDE_SETTINGS_SCHEMA = z.object(SETTINGS_FIELDS);
 export function apply(ctx, config) {
     ctx.effect(() => {
         const permissionMode = config.permissionMode ?? DEFAULT_PERMISSION_MODE;
-        const baseUrl = config.baseUrl;
         const homeDir = ctx.localAgent.homeDir('claude-code');
         // Claude creates the scoped home lazily; create it eagerly so the
         // harness's homeDir contract is uniform with the other harnesses.
@@ -123,15 +127,28 @@ export function apply(ctx, config) {
             legacyBase,
             read: readSettings,
         });
-        // The model is read PER ROUND, not captured at apply: the settings card
-        // writes the same namespace field, so a change has to reach the next
-        // 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 = () => {
+        // The endpoint credential's deployment level: the plugin config triple,
+        // 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 },
+            ...config.authToken === undefined ? {} : { authToken: config.authToken },
+        };
+        const resolveEndpoint = (scopeHome) => resolveEndpointAuth(scopeHome, endpointConfig);
+        // The memberless model key: the plugin-config/settings `model`, blank = unset.
+        const settingsModelKey = () => {
             const model = face.get().model?.trim();
             return model === undefined || model === '' ? undefined : model;
         };
+        // The harness's default model for a scope: 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 resolveModel = (scope) => firstModelOf(readModelListSync(ctx.localAgent.homeDir('claude-code', scope))) ?? settingsModelKey();
         // The member model layers above the settings key: the session-level
         // override map (the composer's picker writes it through the broker; both
         // round paths and the live spawn read it) and the scoped-settings.json
@@ -152,18 +169,24 @@ export function apply(ctx, config) {
             const named = delegationModel?.trim();
             if (named !== undefined && named !== '')
                 return named;
-            return 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.
+            const record = ctx.localAgent.memberBinding?.(childSessionId) ?? ctx.localAgent.getDelegation(childSessionId);
+            return resolveModel(record?.scope);
         };
         const liveSwitch = new LiveDriverSwitch(ctx, face, {
             ...config.permissionMode === undefined ? {} : { permissionMode: config.permissionMode },
-            ...config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl },
+            endpoint: resolveEndpoint,
             ...config.liveIdleMs === undefined ? {} : { liveIdleMs: config.liveIdleMs },
             model: effectiveModel,
             provisionModel: (home, model) => scopedModelMemory.provision(home, model),
         });
         const modelCatalog = new ClaudeModelCatalog({
-            spawn: spec => ctx.subprocess.spawn(spec),
-            ...config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl },
+            endpoint: resolveEndpoint,
+            // Re-key on the config baseUrl; the scope file's own edits (the card's
+            // credential writes land there) are covered by its fingerprint in the
+            // key's file list.
+            endpointLabel: () => config.baseUrl,
             warn: message => ctx.logger.warn(message),
         });
         const modelContext = (childSessionId) => {
@@ -177,6 +200,7 @@ export function apply(ctx, config) {
                 return { home, directory: refresh => refresh ? modelCatalog.refresh(home, binding.cwd) : modelCatalog.read(home, binding.cwd) };
             },
             settingsModel: resolveModel,
+            modelList: scope => readModelListSync(ctx.localAgent.homeDir('claude-code', scope)),
             cliDefault: childSessionId => {
                 const context = modelContext(childSessionId);
                 return context.home === homeDir ? scopedModelMemory.cliDefault(homeDir) : readClaudeConfiguredModel(context.home);
@@ -198,7 +222,7 @@ export function apply(ctx, config) {
             // live-settle report.
             transcriptModel: (cliSessionId, childSessionId) => readClaudeTranscriptModel(modelContext(childSessionId).home, cliSessionId),
         });
-        const disposeProvider = ctx.subagents.registerProvider(new ClaudeCliProvider(ctx, permissionMode, baseUrl, liveSwitch.resolve, effectiveModel));
+        const disposeProvider = ctx.subagents.registerProvider(new ClaudeCliProvider(ctx, permissionMode, resolveEndpoint, liveSwitch.resolve, effectiveModel));
         const disposeHarness = ctx.localAgent.register({
             prepareMember: async ({ binding, childSession, configuration, signal }) => {
                 const driver = liveSwitch.resolve(binding.childSessionId);
@@ -211,57 +235,90 @@ export function apply(ctx, config) {
             displayName: 'Claude Code',
             homeEnvVar: 'CLAUDE_CONFIG_DIR',
             delegationProvider: 'claude-local',
-            login: {
-                // claude ≥2.1 (verified 2.1.235+) runs its auth only on a TTY: under
-                // the pty wrapper it auto-opens the user's browser and prints the
-                // OAuth URL as fallback; the page hands back a code the user pastes
-                // via /claude-code code <value>. The relay env is scrubbed and the
-                // scoped home pinned so the credential lands where delegations read
-                // it (the wrapper passes the harness env through).
-                // The argv pins the config directory itself (an `env NAME=VALUE`
-                // assignment outranks the spawn env), so it is built from the
-                // directory being logged in: `/claude-code login --scope <name>`
-                // authorizes THAT scope, not the default one.
-                pty: {
-                    command: 'env',
-                    args: (scopedHome) => ['-u', 'ANTHROPIC_API_KEY', '-u', 'ANTHROPIC_BASE_URL', `CLAUDE_CONFIG_DIR=${scopedHome}`, 'claude', 'auth', 'login'],
-                },
-                // The watch syncs the keychain credential into the runtime-readable
-                // file first (claude 2.1.236 writes keychain but reads the file),
-                // then probes.
-                watch: async (home) => {
-                    await syncClaudeCredentialFile(home, message => { ctx.logger.warn(message); });
-                    return claudeAuthenticated(home, message => { ctx.logger.warn(message); });
-                },
-            },
+            // No `login` declaration: the harness authenticates by endpoint key
+            // (endpoint-auth.ts), so the core reports the harness as not loginable
+            // and `/claude-code login` answers that there is no login flow — no
+            // browser, no OAuth, nothing to authorize inside a container.
             records: { listSessions: homeDir => listClaudeSessions(homeDir) },
             // A NAMED scope's directory is provisioned through this hook when the
             // registry materializes it — the same eager creation and settings the
             // default scope gets from the apply above.
             provision: scopedHome => provisionClaudeHome(scopedHome, config.proxyUrl).then(() => { }),
-            // The logger is wired here because this probe is the clobber site the
-            // spawn sites do not cover: every status read and every readiness check
-            // reconciles the two credential stores through it.
-            isAuthenticated: home => claudeAuthenticated(home, message => { ctx.logger.warn(message); }),
-            credentialStamp: claudeCredentialStamp,
-            logout: claudeLogout,
+            // Endpoint-key presence: the scope's endpoint-auth.json merged over the
+            // plugin config must carry a non-empty key. The verdict rides the
+            // family's credential grades untouched: presence grades
+            // `present-unverified`, a completed round grades `verified`, a round's
+            // 401 grades `rejected` until the endpoint file's mtime moves past the
+            // mark (editing the file IS the re-login gesture).
+            isAuthenticated: home => resolveEndpoint(home).then(endpoint => hasEndpointCredential(endpoint)),
+            // 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 => checkClaudeEndpoint(endpoint)),
+            // The settings card's credential form: read the resolved per-field
+            // state (secrets as booleans), 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 triple.
+            endpointAuth: {
+                read: async (home) => {
+                    const endpoint = await resolveEndpoint(home);
+                    return {
+                        ...endpoint.baseUrl === undefined ? {} : { baseUrl: endpoint.baseUrl },
+                        apiKeySet: endpoint.apiKey !== undefined,
+                        authTokenSet: endpoint.authToken !== undefined,
+                    };
+                },
+                write: async (home, fields) => {
+                    const current = await readEndpointAuthFile(home) ?? {};
+                    const next = { ...current };
+                    for (const [field, value] of Object.entries(fields)) {
+                        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);
+                },
+            },
+            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('claude-code has no scoped endpoint-auth.json to clear — the credential comes from the settings card or the profile row (baseUrl/apiKey/authToken); clear it there instead');
+            },
             // The model surface: the settings card reads the memberless info ("what
             // would a round run with"), the member composer reads and switches a
             // member's session-level override through the same broker.
             modelBroker,
+            // 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),
+            },
             // The eval snapshot: the permission mode is the plugin config resolved
             // at apply (it selects the spawn flags); the endpoint mirrors the
-            // provider's own resolution order — the config item wins over the host
-            // process environment's ANTHROPIC_BASE_URL. The model follows the
-            // family's fixed order: the plugin config key (it rides every argv)
-            // before the scoped settings.json's own `model`. The CLI's own default
-            // model is never guessed, so neither one configured means no field.
-            // The directory is a PARAMETER, not the apply-time capture: a status
-            // read (or an evaluation snapshot) of a named scope must report the
-            // settings that scope's rounds would run with.
+            // provider's own resolution — the scope's file over the config triple.
+            // The model follows the family's fixed order: the plugin config key (it
+            // rides every argv) before the scoped settings.json's own `model`. The
+            // CLI's own default model is never guessed, so neither one configured
+            // means no field. The directory is a PARAMETER, not the apply-time
+            // capture: a status read (or an evaluation snapshot) of a named scope
+            // must report the settings that scope's rounds would run with.
             effectiveSettings: async (scopedHome) => {
-                const effectiveBaseUrl = baseUrl ?? process.env.ANTHROPIC_BASE_URL;
-                const baseUrlHost = effectiveBaseUrl !== undefined ? endpointHost(effectiveBaseUrl) : undefined;
+                const endpoint = await resolveEndpoint(scopedHome);
+                const baseUrlHost = endpoint.baseUrl !== undefined ? endpointHost(endpoint.baseUrl) : undefined;
                 const [scopedModel, cliVersion] = await Promise.all([
                     readClaudeConfiguredModel(scopedHome).catch(() => undefined),
                     claudeCliVersion(ctx, scopedHome).catch(() => undefined),
@@ -270,7 +327,7 @@ export function apply(ctx, config) {
                 return {
                     drive: face.get().live ? 'live' : 'exec',
                     permissionMode,
-                    baseUrlSet: effectiveBaseUrl !== undefined,
+                    baseUrlSet: endpoint.baseUrl !== undefined,
                     ...baseUrlHost !== undefined ? { baseUrlHost } : {},
                     ...model !== undefined ? { model } : {},
                     ...cliVersion !== undefined ? { cliVersion } : {},
@@ -287,6 +344,15 @@ export function apply(ctx, config) {
                             : records.map(r => `${r.id} ${r.workDir}`).join('\n'),
                     }));
                 }
+                // `/claude-code check`: 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).
+                if (verb === 'check') {
+                    const scopeHome = invocation.agent.ctx.localAgent.homeDir('claude-code');
+                    return resolveEndpoint(scopeHome)
+                        .then(endpoint => checkClaudeEndpoint(endpoint))
+                        .then(text => ({ kind: 'success', text }));
+                }
                 return undefined;
             },
         });

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

@@ -3,6 +3,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { Session } from '@deepseek-ai/dsh-session';
 import { type SubagentRun, type SubagentStartRequest } from '@deepseek-ai/dsh-subagent';
 import type { Config } from './index.ts';
+import type { ClaudeEndpointAuth } 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 the turn's system/init ack (a cold boot can be slow). */
@@ -85,7 +86,14 @@ export declare class ClaudeLiveDriver {
      */
     private draining;
     private readonly disposeController;
-    constructor(ctx: Context, config: Pick<Config, 'permissionMode' | 'baseUrl'> & {
+    constructor(ctx: Context, config: Pick<Config, 'permissionMode'> & {
+        /**
+         * Resolver for the spawn's endpoint credential (endpoint-auth.ts: the
+         * member's scoped endpoint-auth.json over the plugin config triple),
+         * read per RUNTIME SPAWN — a key rotation reaches the resident process
+         * at its next respawn. Absent, no `ANTHROPIC_*` variables are set.
+         */
+        endpoint?: (homeDir: string) => Promise<ClaudeEndpointAuth>;
         liveIdleMs?: number;
         liveMirrorGranularity?: ClaudeLiveMirrorGranularity;
         /** Maximum batching wait for incremental streaming messages. */

package/lib/types/live-driver.js

@@ -12,12 +12,10 @@ import { claudeDirectory } from './model-catalog.js';
  * continuable) and the same-shape push stream folded live per turn.
  *
  * Auth discipline (a hard requirement): the resident process runs under the
- * family's scoped `CLAUDE_CONFIG_DIR` and nothing else — the OAuth marker in
- * the scoped `.claude.json` and the keychain entry hashed to that path are
- * exactly what the exec mode's one-shot processes already use. The driver
- * never touches the user's global `~/.claude`, never runs any `auth` verb,
- * and only adds `ANTHROPIC_BASE_URL` when the plugin config supplies it (the
- * exec path's exact env rule).
+ * family's scoped `CLAUDE_CONFIG_DIR` plus the resolved endpoint credential's
+ * `ANTHROPIC_*` variables (the scope's endpoint-auth.json over the plugin
+ * config — the exec path's exact env rule, resolved per spawn). The driver
+ * never touches the user's global `~/.claude` and never runs any `auth` verb.
  *
  * Protocol facts (all probed): the first stdin `user` message triggers
  * `system/init` carrying the server-assigned session id (EVERY turn emits a
@@ -62,11 +60,13 @@ import { claudeDirectory } from './model-catalog.js';
  */
 import { ClaudeControlRequests } from './control-requests.js';
 import { StringDecoder } from 'node:string_decoder';
+import { randomUUID } from 'node:crypto';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { SessionId } from '@deepseek-ai/dsh-session';
 import { settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
 import { delegationEnv, persistChildSession, LiveStreamPublisher, LiveFlush, LIVE_FLUSH_INTERVAL_MS } from '@khorsheed/dsh-local-agent';
 import { appendClaudeTranscriptLine, assistantEvent, claudeLineText, ClaudeStreamParser, claudeVersionFromInit, DEFAULT_DISPOSE_GRACE_MS, registerClaudeMemberRun, textTask, toolCallsOf, } from './claude-cli-provider.js';
-import { syncClaudeCredentialFile } from './records.js';
+import { endpointAuthEnv } from './endpoint-auth.js';
 /** Default idle lifetime of an unused resident runtime before reclaim. */
 export const DEFAULT_LIVE_IDLE_MS = 30 * 60_000;
 /** Default timeout for the turn's system/init ack (a cold boot can be slow). */
@@ -419,14 +419,10 @@ export class ClaudeLiveDriver {
         if (this.disposed) {
             throw new LiveChannelUnavailableError('the live driver is disposed');
         }
-        // Keychain→file sync before EVERY spawn: claude 2.1.236 reads
-        // <home>/.credentials.json at runtime while login and the process's own
-        // refresh write the keychain — the file goes stale on every rotation
-        // (single-rotation refresh tokens make a consumed copy poison for the
-        // next spawn). The login watch's sync alone cannot keep a resident
-        // runtime authenticatable across rotations. Best-effort: a missing grant
-        // fails the turn with the CLI's own "Not logged in", not here.
-        await syncClaudeCredentialFile(spec.homeDir, message => { this.ctx.logger.warn(message); }).catch(() => false);
+        // The endpoint credential is resolved per spawn (the scope's
+        // endpoint-auth.json over the plugin config): a key rotation reaches the
+        // resident runtime at its next respawn, with no reload and no reconcile.
+        const endpoint = await this.config.endpoint?.(spec.homeDir);
         // The member bridge rides the spawn argv (`--mcp-config` + `--allowedTools`),
         // exactly as in the exec path; the resident process serves one member, so
         // its token lives with the process.
@@ -460,11 +456,11 @@ export class ClaudeLiveDriver {
             stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' },
             graceMs: DEFAULT_DISPOSE_GRACE_MS,
             // The auth discipline: exactly the exec path's env — the scoped config
-            // dir, plus the configured base URL override only.
+            // dir plus the resolved endpoint credential's `ANTHROPIC_*` variables.
             env: delegationEnv({
                 CLAUDE_CONFIG_DIR: spec.homeDir,
                 ...spec.configuration === undefined ? {} : { CLAUDE_CODE_EFFORT_LEVEL: spec.configuration.effort ?? 'auto' },
-                ...this.config.baseUrl === undefined ? {} : { ANTHROPIC_BASE_URL: this.config.baseUrl },
+                ...endpointAuthEnv(endpoint),
             }),
         };
         let child;
@@ -1039,7 +1035,11 @@ export class ClaudeLiveDriver {
         // never hold it hostage — a cancel returns immediately.
         await Promise.race([accepted, abortBranch.catch(() => undefined)]);
         return subprocessRunHandle({
-            id: childSession.id,
+            // Host 0.2.1: a fresh PER-EXECUTION run id — the activation manager
+            // rejects a run id naming a live Session (this child session is live),
+            // and resume rounds reuse the child session id. The family's durable
+            // tracking key (the child session id) rides the staged intent instead.
+            id: SessionId(randomUUID()),
             result,
             signal: request.signal,
             onAbort,

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

@@ -13,6 +13,7 @@
 import type { Context } from '@deepseek-ai/cordis';
 import type { SettingsFace } from '@khorsheed/dsh-local-agent';
 import type { Config } from './index.ts';
+import type { ClaudeEndpointAuth } from './endpoint-auth.ts';
 import { ClaudeLiveDriver } from './live-driver.ts';
 import type { ClaudeLiveMirrorGranularity } from './live-driver.ts';
 /** The resolved live settings (rc.1: volatile row config; 0.1.5: schema defaults ← YAML base ← user layer). */
@@ -25,8 +26,10 @@ export interface ClaudeLiveSettings {
     recentModels?: readonly string[];
 }
 /** The Cordis-config inputs every driver generation shares. */
-type DriverBase = Pick<Config, 'permissionMode' | 'baseUrl'> & {
+type DriverBase = Pick<Config, 'permissionMode'> & {
     liveIdleMs?: number;
+    /** Per-spawn endpoint credential resolver, handed to every driver generation. */
+    endpoint?: (homeDir: string) => Promise<ClaudeEndpointAuth>;
     /**
      * Per-spawn member model resolver, handed to every driver generation:
      * answers the member's effective model from its session-level override, the

package/lib/types/model-broker.d.ts

@@ -70,8 +70,10 @@ export interface ClaudeModelBrokerDeps {
         home: string;
         directory: (refresh?: boolean) => LocalAgentModelDirectory | Promise<LocalAgentModelDirectory>;
     };
-    /** The settings layer: the plugin-config model, read per call. */
-    readonly settingsModel: () => string | undefined;
+    /** The settings layer: the curated list's first entry, else the plugin-config model, read per call. */
+    readonly settingsModel: (scope?: string) => string | undefined;
+    /** The scope's curated model list, read per call (empty = the fallback chain decides the vocabulary too). */
+    readonly modelList?: (scope?: string) => readonly string[];
     /** The scoped settings.json's own model, minus live-spawn scratch writes. */
     readonly cliDefault: (childSessionId?: string) => Promise<string | undefined>;
     readonly directory?: (childSessionId?: string, refresh?: boolean) => LocalAgentModelDirectory | Promise<LocalAgentModelDirectory>;

package/lib/types/model-broker.js

@@ -111,7 +111,7 @@ export class ClaudeModelBroker {
             if (directory.status === 'loading')
                 directory = await context.directory(true);
             const model = selection.model.mode === 'value' ? selection.model.value
-                : (selection.model.mode === 'inherit' ? binding.model : undefined) ?? this.deps.settingsModel()
+                : (selection.model.mode === 'inherit' ? binding.model : undefined) ?? this.deps.settingsModel(binding.scope)
                     ?? await readClaudeConfiguredModel(context.home) ?? directory.defaultModel;
             const entry = directory.entries.find(entry => entry.value === model || entry.resolvedModel === model);
             const effort = (selection.effort.mode === 'value' ? selection.effort.value : selection.effort.mode === 'inherit' ? binding.effort : undefined)
@@ -179,9 +179,10 @@ export class ClaudeModelBroker {
      * would a round run with" read.
      */
     async modelInfo(childSessionId, delegationModel) {
+        const record = childSessionId === undefined ? undefined : this.deps.localAgent.getDelegation(childSessionId);
         const override = childSessionId === undefined ? undefined : this.deps.overrides.get(childSessionId);
         const delegation = delegationModel?.trim() === '' ? undefined : delegationModel?.trim();
-        const settings = this.deps.settingsModel();
+        const settings = this.deps.settingsModel(record?.scope);
         const cliDefault = await this.deps.cliDefault(childSessionId);
         const native = await this.deps.directory?.(childSessionId);
         const [effective, source] = override !== undefined
@@ -193,9 +194,14 @@ export class ClaudeModelBroker {
                     : cliDefault !== undefined
                         ? [cliDefault, 'cli-config']
                         : [native?.defaultModel, 'cli-builtin'];
-        // Native candidates plus labelled configuration and historical suggestions.
-        const choices = [...new Set([settings, cliDefault, ...native?.entries.filter(entry => !entry.hidden).map(entry => entry.value) ?? [], ...this.deps.recentModels()]
-                .filter((value) => value !== undefined))];
+        // The curated list is the whole vocabulary when non-empty — nothing from
+        // outside the endpoint's served catalog sneaks in. Empty falls back to
+        // the pre-list chain (native candidates plus configuration and history).
+        const curated = this.deps.modelList?.(record?.scope) ?? [];
+        const choices = curated.length > 0
+            ? [...curated]
+            : [...new Set([settings, cliDefault, ...native?.entries.filter(entry => !entry.hidden).map(entry => entry.value) ?? [], ...this.deps.recentModels()]
+                    .filter((value) => value !== undefined))];
         const lastObserved = await this.lastObserved(childSessionId);
         const active = childSessionId !== undefined && this.deps.localAgent.isDelegationActive(childSessionId);
         return {
@@ -207,7 +213,11 @@ export class ClaudeModelBroker {
             ...cliDefault === undefined ? {} : { cliDefault },
             ...lastObserved === undefined ? {} : { lastObserved },
             choices,
-            ...native === undefined ? {} : { directory: extendModelDirectory(native, [settings, cliDefault], [...this.deps.recentModels(), lastObserved]) },
+            // The picker's extended vocabulary follows the same rule as choices:
+            // a curated list is complete on its own (no history entries sneak in);
+            // settings/cliDefault still extend so the member's CURRENT bound model
+            // stays selectable even when it is not in the list.
+            ...native === undefined ? {} : { directory: extendModelDirectory(native, [settings, cliDefault], curated.length > 0 ? [] : [...this.deps.recentModels(), lastObserved]) },
             live: this.deps.live(),
             switchable: !active,
             ...active
@@ -238,8 +248,9 @@ export class ClaudeModelBroker {
         else
             this.deps.overrides.set(childSessionId, next);
         // What the next spawn would bind, in the round resolvers' own order.
-        const delegation = this.deps.localAgent.getDelegation(childSessionId)?.model?.trim();
-        const spawnModel = next ?? (delegation === undefined || delegation === '' ? undefined : delegation) ?? this.deps.settingsModel();
+        const record = this.deps.localAgent.getDelegation(childSessionId);
+        const delegation = record?.model?.trim();
+        const spawnModel = next ?? (delegation === undefined || delegation === '' ? undefined : delegation) ?? this.deps.settingsModel(record?.scope);
         const host = this.deps.liveSwitch.hostingDriver(childSessionId);
         if (host !== undefined && host.runtimeModel(childSessionId) !== spawnModel) {
             await host.retireRuntime(childSessionId);