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

package/lib/types/model-broker.js

@@ -97,6 +97,42 @@ export class ClaudeScopedModelMemory {
 }
 /** How long one transcript read-back answer is reused (repeated card opens). */
 export const OBSERVED_MODEL_CACHE_TTL_MS = 60_000;
+/**
+ * Scope the served directory to the surface asking for it (the same helper
+ * lives in each provider's broker — fold into the family core when the
+ * directory faces next evolve):
+ *
+ * - memberless (the card's add-model dialog, the invite picker): the
+ *   endpoint's served catalog only — the configuration/history extras the
+ *   broker's info extension adds for STATUS display must never become add
+ *   candidates;
+ * - a member whose harness has a curated list: the list IS the vocabulary,
+ *   in the list's own order (the same rule `choices` already follows) — a
+ *   curated value the endpoint no longer serves stays as a bare row (the
+ *   card shows it the same way), and the member's current effective model is
+ *   kept visible as a bare entry when it sits outside the list, so a pre-list
+ *   binding never renders blank;
+ * - a member without a curated list: the legacy extended vocabulary.
+ */
+function scopeServedDirectory(directory, opts) {
+    if (opts.member && opts.curated.length === 0)
+        return directory;
+    const served = directory.entries.filter(entry => entry.source === 'native');
+    if (!opts.member)
+        return { ...directory, entries: served };
+    const byValue = new Map(served.flatMap(entry => entry.resolvedModel === undefined
+        ? [[entry.value, entry]]
+        : [[entry.value, entry], [entry.resolvedModel, entry]]));
+    // Curated ORDER leads (the card's first row is the default); a curated value
+    // the endpoint no longer serves stays listed as a bare row, exactly like the
+    // card shows it.
+    const entries = opts.curated.map(value => byValue.get(value) ?? { value, label: value, source: 'configuration' });
+    const current = opts.current?.trim();
+    if (current !== undefined && current !== '' && !entries.some(entry => entry.value === current || entry.resolvedModel === current)) {
+        entries.push({ value: current, label: current, source: 'configuration' });
+    }
+    return { ...directory, entries };
+}
 export class ClaudeModelBroker {
     deps;
     constructor(deps) {
@@ -111,7 +147,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)
@@ -136,8 +172,14 @@ export class ClaudeModelBroker {
     async modelDirectory(childSessionId, refresh = false) {
         if (refresh)
             await this.deps.directory?.(childSessionId, true);
-        const info = await this.modelInfo(childSessionId, childSessionId === undefined ? undefined : this.deps.localAgent.getDelegation(childSessionId)?.model);
-        return info.directory ?? { entries: [], complete: false, customInput: true, status: 'unsupported', refreshing: false, revision: 0 };
+        const record = childSessionId === undefined ? undefined : this.deps.localAgent.getDelegation(childSessionId);
+        const info = await this.modelInfo(childSessionId, record?.model);
+        const directory = info.directory ?? { entries: [], complete: false, customInput: true, status: 'unsupported', refreshing: false, revision: 0 };
+        return scopeServedDirectory(directory, {
+            member: childSessionId !== undefined,
+            curated: this.deps.modelList?.(record?.scope) ?? [],
+            current: info.effective,
+        });
     }
     async *followModelDirectory(childSessionId, signal) {
         if (this.deps.followDirectory === undefined) {
@@ -179,9 +221,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 +236,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 +255,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 +290,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);

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

@@ -1,16 +1,45 @@
-import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
 import type { LocalAgentModelDirectory, LocalAgentModelDirectoryData } from '@khorsheed/dsh-local-agent/types';
+import type { ClaudeEndpointAuth, EndpointCheckFetch } from './endpoint-auth.ts';
 type JsonObject = Record<string, unknown>;
-/** Initialize's native picker vocabulary, not an account entitlement claim. */
+/**
+ * Fold the CLI's own `initialize` model vocabulary. Consumed by the LIVE
+ * DRIVER's runtime init handling; the catalog no longer reads this — a
+ * local list cannot prove anything about the configured endpoint, and
+ * showing it made an invalid credential look valid.
+ */
 export declare function claudeDirectory(result: JsonObject): LocalAgentModelDirectoryData;
-/** Scoped native control probe. Never syncs credentials, writes settings or submits a user turn. */
+/**
+ * The model directory, sourced from the configured ENDPOINT (`GET
+ * <baseUrl>/v1/models` with the resolved credential) — never from the local
+ * CLI: what the picker lists is exactly what the endpoint serves, so a
+ * credential that does not work can never hide behind a locally-known list.
+ * The answers are deliberate:
+ *
+ * - no credential resolved → empty with a "save a key first" reason;
+ * - 401/403 → empty with the rejection (definitive — cached as data);
+ * - another HTTP status → empty with it (the relay serves no model route);
+ * - a transport failure THROWS, so the cache keeps the last good list and
+ *   retries on schedule instead of blanking a momentarily-down endpoint.
+ *
+ * Effort levels ride the served entries' `effort` capability when the
+ * endpoint advertises them. Entries carry `source: 'native'` — they are the
+ * harness's native vocabulary, just read from the endpoint in force.
+ */
 export declare class ClaudeModelCatalog {
     private readonly deps;
     private readonly cache;
     constructor(deps: {
-        spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
-        baseUrl?: string;
-        cli?: string;
+        /** Per-probe endpoint credential resolver (the scope's file over the settings layer). */
+        endpoint?: (homeDir: string) => Promise<ClaudeEndpointAuth>;
+        /**
+         * The cache key's endpoint component: the settings layer's baseUrl plus a
+         * short credential digest, resolved per read so a card write (either
+         * field) re-keys the cache. A scope FILE's contribution needs no place
+         * here — the file itself is in the key's fingerprinted file list.
+         */
+        endpointLabel?: () => string | undefined;
+        /** The HTTP fetch (injected in tests). */
+        fetchImpl?: EndpointCheckFetch;
         timeoutMs?: number;
         ttlMs?: number;
         warn?: (message: string) => void;

package/lib/types/model-catalog.js

@@ -1,8 +1,12 @@
-import { dirname, join } from 'node:path';
-import { StringDecoder } from 'node:string_decoder';
-import { ModelDirectoryCache, delegationEnv, modelDirectoryContextKey } from '@khorsheed/dsh-local-agent';
-import { ClaudeControlRequests } from './control-requests.js';
-/** Initialize's native picker vocabulary, not an account entitlement claim. */
+import { join } from 'node:path';
+import { ModelDirectoryCache, modelDirectoryContextKey } from '@khorsheed/dsh-local-agent';
+import { fetchEndpointModels, hasEndpointCredential, OFFICIAL_BASE_URL } from './endpoint-auth.js';
+/**
+ * Fold the CLI's own `initialize` model vocabulary. Consumed by the LIVE
+ * DRIVER's runtime init handling; the catalog no longer reads this — a
+ * local list cannot prove anything about the configured endpoint, and
+ * showing it made an invalid credential look valid.
+ */
 export function claudeDirectory(result) {
     const models = result['models'];
     if (models === undefined)
@@ -28,7 +32,27 @@ export function claudeDirectory(result) {
     }
     return { entries: [...entries.values()], complete: true, customInput: true, ...entries.has('default') ? { defaultModel: 'default' } : {} };
 }
-/** Scoped native control probe. Never syncs credentials, writes settings or submits a user turn. */
+/** One directory answer that names why it is empty. */
+function unsupported(reason) {
+    return { entries: [], complete: false, customInput: true, unsupported: true, reason };
+}
+/**
+ * The model directory, sourced from the configured ENDPOINT (`GET
+ * <baseUrl>/v1/models` with the resolved credential) — never from the local
+ * CLI: what the picker lists is exactly what the endpoint serves, so a
+ * credential that does not work can never hide behind a locally-known list.
+ * The answers are deliberate:
+ *
+ * - no credential resolved → empty with a "save a key first" reason;
+ * - 401/403 → empty with the rejection (definitive — cached as data);
+ * - another HTTP status → empty with it (the relay serves no model route);
+ * - a transport failure THROWS, so the cache keeps the last good list and
+ *   retries on schedule instead of blanking a momentarily-down endpoint.
+ *
+ * Effort levels ride the served entries' `effort` capability when the
+ * endpoint advertises them. Entries carry `source: 'native'` — they are the
+ * harness's native vocabulary, just read from the endpoint in force.
+ */
 export class ClaudeModelCatalog {
     deps;
     cache;
@@ -44,75 +68,41 @@ export class ClaudeModelCatalog {
         });
     }
     key(homeDir, cwd = homeDir) {
-        const files = [join(homeDir, 'settings.json'), join(homeDir, '.credentials.json'), join(homeDir, '.claude.json')];
-        for (let directory = cwd;; directory = dirname(directory)) {
-            files.push(join(directory, '.claude', 'settings.json'), join(directory, '.claude', 'settings.local.json'));
-            if (dirname(directory) === directory)
-                break;
-        }
-        return modelDirectoryContextKey({ provider: 'claude-code', homeDir, cwd, cli: [this.deps.cli ?? 'claude'], files, ...this.deps.baseUrl === undefined ? {} : { endpoint: this.deps.baseUrl } });
+        const files = [join(homeDir, 'settings.json'), join(homeDir, 'endpoint-auth.json')];
+        const endpointLabel = this.deps.endpointLabel?.();
+        return modelDirectoryContextKey({ provider: 'claude-code', homeDir, cwd, cli: [], files, ...endpointLabel === undefined ? {} : { endpoint: endpointLabel } });
     }
     read(homeDir, cwd) { return this.cache.read(this.key(homeDir, cwd)); }
     refresh(homeDir, cwd) { return this.cache.refresh(this.key(homeDir, cwd)); }
     follow(homeDir, cwd, signal) { return this.cache.follow(() => this.key(homeDir, cwd), signal); }
     invalidate(homeDir, cwd) { this.cache.invalidate(this.key(homeDir, cwd)); }
     dispose() { this.cache.dispose(); }
-    async probe(homeDir, cwd, signal) {
-        const child = this.deps.spawn({
-            argv: [this.deps.cli ?? 'claude', '-p', '--verbose', '--input-format', 'stream-json', '--output-format', 'stream-json',
-                '--no-session-persistence', '--settings', '{"disableAllHooks":true}', '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}', '--'],
-            cwd, stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' }, graceMs: 2_000,
-            env: delegationEnv({ CLAUDE_CONFIG_DIR: homeDir, ...this.deps.baseUrl === undefined ? {} : { ANTHROPIC_BASE_URL: this.deps.baseUrl } }),
-        });
-        const controls = new ClaudeControlRequests(frame => {
-            if (child.stdin === undefined)
-                throw new Error('Claude discovery stdin is unavailable');
-            child.stdin.write(JSON.stringify(frame) + '\n');
-        }, this.deps.timeoutMs ?? 5_000);
-        const decoder = new StringDecoder('utf8');
-        let buffer = '';
-        child.stdout?.on('data', (chunk) => {
-            buffer += decoder.write(chunk);
-            if (buffer.length > 1_048_576) {
-                controls.close();
-                child.terminate();
-                return;
-            }
-            let index;
-            while ((index = buffer.indexOf('\n')) >= 0) {
-                const line = buffer.slice(0, index);
-                buffer = buffer.slice(index + 1);
-                let event;
-                try {
-                    event = JSON.parse(line);
-                }
-                catch {
-                    continue;
-                }
-                if (controls.accept(event))
-                    continue;
-                if (event['type'] === 'control_request' && typeof event['request_id'] === 'string') {
-                    child.stdin?.write(JSON.stringify({ type: 'control_response', response: { subtype: 'error', request_id: event['request_id'], error: 'Model discovery does not execute tools' } }) + '\n');
-                }
-            }
-        });
-        child.stderr?.on('data', () => { });
-        void child.done.then(() => controls.close(), () => controls.close());
-        let cleanupTimer;
-        try {
-            return claudeDirectory(await controls.request({ subtype: 'initialize', hooks: {} }, signal));
+    async probe(homeDir, _cwd, signal) {
+        const endpoint = await this.deps.endpoint?.(homeDir);
+        if (!hasEndpointCredential(endpoint)) {
+            return unsupported('No endpoint credential configured — the model list loads from the endpoint once an API Key or Auth Token is saved');
         }
-        finally {
-            controls.close();
-            child.stdin?.end();
-            await Promise.race([child.done.catch(() => { }), new Promise(resolve => {
-                    cleanupTimer = setTimeout(resolve, 1_000);
-                    cleanupTimer.unref();
-                })]);
-            if (cleanupTimer !== undefined)
-                clearTimeout(cleanupTimer);
-            child.terminate();
-            await child.waitForExit().catch(() => { });
+        const result = await fetchEndpointModels({ ...endpoint, baseUrl: endpoint.baseUrl ?? OFFICIAL_BASE_URL }, this.deps.fetchImpl, AbortSignal.any([signal, AbortSignal.timeout(this.deps.timeoutMs ?? 20_000)]));
+        if (result.kind === 'unreachable') {
+            // Not a verdict: the cache keeps the last good list and retries.
+            throw new Error(`endpoint unreachable: ${result.message}`);
+        }
+        if (result.kind === 'malformed')
+            return unsupported('The endpoint answered but the model list did not parse (not /v1/models-shaped)');
+        if (result.kind === 'http') {
+            if (result.status === 401 || result.status === 403) {
+                return unsupported(`The endpoint rejected the credential (HTTP ${String(result.status)}) — the list loads once a valid key is saved`);
+            }
+            return unsupported(`The endpoint does not serve a model list (HTTP ${String(result.status)})`);
         }
+        const entries = result.models.map(model => ({
+            value: model.id,
+            label: model.displayName ?? model.id,
+            source: 'native',
+            ...model.efforts === undefined ? {} : { reasoning: { options: model.efforts.map(effort => ({ value: effort, label: effort })) } },
+        }));
+        if (entries.length === 0)
+            return unsupported('The endpoint serves no models');
+        return { entries, complete: true, customInput: true };
     }
 }

package/lib/types/provision.d.ts

@@ -1,29 +1,47 @@
 /**
- * Claude Code scoped-home provisioning. Unlike codex (whose credential store
- * must be pinned to a file) and kimi (which needs a provider config),
- * claude's `CLAUDE_CONFIG_DIR` scoped home needs nothing beyond the
- * directory itself: login via `claude auth login` writes `.claude.json`
- * (with the `oauthAccount` record) into it, and the real credential lands in
- * the macOS keychain under a hashed entry or — on Linux, despite upstream
- * bug #47661 — in the default `~/.claude/.credentials.json` while the config
- * stays scoped. Sign-out removes the scoped config so `status` reports not
- * authenticated; the keychain entry on macOS persists until the CLI removes
- * it, which the framework's file-based logout cannot reach.
+ * Claude Code scoped-home provisioning. The harness authenticates by
+ * endpoint key (see endpoint-auth.ts), so a scoped home needs nothing beyond
+ * the directory itself: `claude -p` scaffolds `.claude.json` on its first
+ * run, and the endpoint credential arrives per round through the spawn env
+ * (resolved from the scope's endpoint-auth.json over the plugin config).
+ * When `proxyUrl` is configured, the scoped `settings.json` gains an env
+ * block pointing the CLI's own traffic at it — claude reads proxy settings
+ * from this file, so the child works even when the host process environment
+ * carries no proxy (a supervisor-spawned instance's env is not the user's
+ * shell env).
  * @module @khorsheed/dsh-local-agent-claude-code/provision
  */
 /**
  * Provision the scoped home directory. Claude creates it lazily on first
  * use, but creating it eagerly keeps the harness's homeDir contract uniform
- * with the other harnesses. When `proxyUrl` is configured, the scoped
- * `settings.json` gains an env block pointing the CLI's own traffic at it —
- * claude reads proxy settings from this file, so the child works even when
- * the host process environment carries no proxy (a supervisor-spawned
- * instance's env is not the user's shell env). An existing settings file is
- * merged, not overwritten; only the two proxy keys are managed.
+ * with the other harnesses. Two maintenance duties run here:
+ *
+ * - Legacy OAuth sweep: the endpoint-key era never reads `.credentials.json`
+ *   or the `.claude.json` `oauthAccount` marker — both are deleted so a
+ *   pre-migration scoped home carries no dead grant (measured: claude
+ *   2.1.296 prefers the env credential over a stored one anyway; the sweep
+ *   is hygiene, not priority repair). Other `.claude.json` keys survive.
+ * - When `proxyUrl` is configured, the scoped `settings.json` gains an env
+ *   block pointing the CLI's own traffic at it — claude reads proxy settings
+ *   from this file, so the child works even when the host process environment
+ *   carries no proxy (a supervisor-spawned instance's env is not the user's
+ *   shell env). An existing settings file is merged, not overwritten; only
+ *   the two proxy keys are managed.
  * @param homeDir - the `claude-code` harness's scoped home.
  * @param proxyUrl - optional HTTP proxy URL for the child CLI's traffic.
  */
 export declare function provisionClaudeHome(homeDir: string, proxyUrl?: string): Promise<void>;
+/**
+ * Remove the OAuth era's artifacts from the scoped home: the
+ * `.credentials.json` grant file outright, and the `oauthAccount` marker key
+ * from `.claude.json` (the file itself carries live CLI state and stays).
+ * Idempotent and best-effort per file — a missing or malformed file is
+ * simply not a sweep target. The macOS keychain entry is deliberately left
+ * alone: the CLI never consults it once an env credential rides the spawn,
+ * and keychain writes are outside the harness's file-based contract.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ */
+export declare function sweepLegacyOauth(homeDir: string): Promise<void>;
 /**
  * Read the scoped settings' configured model: the `model` key of
  * `<homeDir>/settings.json` — the model a delegation round pins when the
@@ -49,15 +67,4 @@ export declare function readClaudeConfiguredEffort(homeDir: string): Promise<str
  * @param model - the model to scratch in, or undefined to remove the key.
  */
 export declare function writeClaudeScopedModel(homeDir: string, model: string | undefined): Promise<void>;
-/**
- * Sign out of the scoped account: remove the scoped config file, so
- * `/<name> status` reports not authenticated and the next login authorizes
- * a fresh account. The macOS keychain entry (a hashed
- * `Claude Code-credentials-<sha256(path)[:8]>` record keyed to the scoped
- * home path) is NOT removed — the CLI's `claude auth logout` owns that, and
- * the harness logout contract is file-based; the stale entry is harmless
- * because a fresh login rewrites the same hashed slot.
- * @param homeDir - the `claude-code` harness's scoped home.
- */
-export declare function claudeLogout(homeDir: string): Promise<void>;
 //# sourceMappingURL=provision.d.ts.map

package/lib/types/provision.js

@@ -1,36 +1,42 @@
 /**
- * Claude Code scoped-home provisioning. Unlike codex (whose credential store
- * must be pinned to a file) and kimi (which needs a provider config),
- * claude's `CLAUDE_CONFIG_DIR` scoped home needs nothing beyond the
- * directory itself: login via `claude auth login` writes `.claude.json`
- * (with the `oauthAccount` record) into it, and the real credential lands in
- * the macOS keychain under a hashed entry or — on Linux, despite upstream
- * bug #47661 — in the default `~/.claude/.credentials.json` while the config
- * stays scoped. Sign-out removes the scoped config so `status` reports not
- * authenticated; the keychain entry on macOS persists until the CLI removes
- * it, which the framework's file-based logout cannot reach.
+ * Claude Code scoped-home provisioning. The harness authenticates by
+ * endpoint key (see endpoint-auth.ts), so a scoped home needs nothing beyond
+ * the directory itself: `claude -p` scaffolds `.claude.json` on its first
+ * run, and the endpoint credential arrives per round through the spawn env
+ * (resolved from the scope's endpoint-auth.json over the plugin config).
+ * When `proxyUrl` is configured, the scoped `settings.json` gains an env
+ * block pointing the CLI's own traffic at it — claude reads proxy settings
+ * from this file, so the child works even when the host process environment
+ * carries no proxy (a supervisor-spawned instance's env is not the user's
+ * shell env).
  * @module @khorsheed/dsh-local-agent-claude-code/provision
  */
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-/** The scoped config file holding the oauthAccount auth marker. */
-const SCOPED_CONFIG = '.claude.json';
 /** The scoped settings file carrying the CLI's env block. */
 const SCOPED_SETTINGS = 'settings.json';
 /**
  * Provision the scoped home directory. Claude creates it lazily on first
  * use, but creating it eagerly keeps the harness's homeDir contract uniform
- * with the other harnesses. When `proxyUrl` is configured, the scoped
- * `settings.json` gains an env block pointing the CLI's own traffic at it —
- * claude reads proxy settings from this file, so the child works even when
- * the host process environment carries no proxy (a supervisor-spawned
- * instance's env is not the user's shell env). An existing settings file is
- * merged, not overwritten; only the two proxy keys are managed.
+ * with the other harnesses. Two maintenance duties run here:
+ *
+ * - Legacy OAuth sweep: the endpoint-key era never reads `.credentials.json`
+ *   or the `.claude.json` `oauthAccount` marker — both are deleted so a
+ *   pre-migration scoped home carries no dead grant (measured: claude
+ *   2.1.296 prefers the env credential over a stored one anyway; the sweep
+ *   is hygiene, not priority repair). Other `.claude.json` keys survive.
+ * - When `proxyUrl` is configured, the scoped `settings.json` gains an env
+ *   block pointing the CLI's own traffic at it — claude reads proxy settings
+ *   from this file, so the child works even when the host process environment
+ *   carries no proxy (a supervisor-spawned instance's env is not the user's
+ *   shell env). An existing settings file is merged, not overwritten; only
+ *   the two proxy keys are managed.
  * @param homeDir - the `claude-code` harness's scoped home.
  * @param proxyUrl - optional HTTP proxy URL for the child CLI's traffic.
  */
 export async function provisionClaudeHome(homeDir, proxyUrl) {
     await mkdir(homeDir, { recursive: true });
+    await sweepLegacyOauth(homeDir);
     if (proxyUrl === undefined)
         return;
     const path = join(homeDir, SCOPED_SETTINGS);
@@ -49,6 +55,31 @@ export async function provisionClaudeHome(homeDir, proxyUrl) {
     settings.env = env;
     await writeFile(path, JSON.stringify(settings, undefined, 2) + '\n');
 }
+/**
+ * Remove the OAuth era's artifacts from the scoped home: the
+ * `.credentials.json` grant file outright, and the `oauthAccount` marker key
+ * from `.claude.json` (the file itself carries live CLI state and stays).
+ * Idempotent and best-effort per file — a missing or malformed file is
+ * simply not a sweep target. The macOS keychain entry is deliberately left
+ * alone: the CLI never consults it once an env credential rides the spawn,
+ * and keychain writes are outside the harness's file-based contract.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ */
+export async function sweepLegacyOauth(homeDir) {
+    await rm(join(homeDir, '.credentials.json'), { force: true });
+    const configPath = join(homeDir, '.claude.json');
+    let config;
+    try {
+        config = JSON.parse(await readFile(configPath, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    if (typeof config !== 'object' || config === null || !('oauthAccount' in config))
+        return;
+    delete config['oauthAccount'];
+    await writeFile(configPath, JSON.stringify(config, undefined, 2) + '\n');
+}
 /**
  * Read the scoped settings' configured model: the `model` key of
  * `<homeDir>/settings.json` — the model a delegation round pins when the
@@ -117,16 +148,3 @@ export async function writeClaudeScopedModel(homeDir, model) {
     }
     await writeFile(path, JSON.stringify(settings, undefined, 2) + '\n');
 }
-/**
- * Sign out of the scoped account: remove the scoped config file, so
- * `/<name> status` reports not authenticated and the next login authorizes
- * a fresh account. The macOS keychain entry (a hashed
- * `Claude Code-credentials-<sha256(path)[:8]>` record keyed to the scoped
- * home path) is NOT removed — the CLI's `claude auth logout` owns that, and
- * the harness logout contract is file-based; the stale entry is harmless
- * because a fresh login rewrites the same hashed slot.
- * @param homeDir - the `claude-code` harness's scoped home.
- */
-export async function claudeLogout(homeDir) {
-    await rm(join(homeDir, SCOPED_CONFIG), { force: true });
-}

package/lib/types/records.d.ts

@@ -11,71 +11,13 @@
  * timestamp the listing needs; the rest of the file (conversation) is not
  * parsed. Files are append-only with torn-tail tolerance, and contents are
  * always untrusted input.
+ *
+ * Credentials are NOT this module's business: the harness authenticates by
+ * endpoint key only (see endpoint-auth.ts), which needs no keychain read,
+ * no `.credentials.json` reconcile, and no OAuth marker probe.
  * @module @khorsheed/dsh-local-agent-claude-code/records
  */
-import { execFile } from 'node:child_process';
 import type { LocalAgentSessionRecord } from '@khorsheed/dsh-local-agent';
-/** Test-swappable process exec (the keychain read goes through `security`). */
-export declare const internals: {
-    exec: typeof execFile.__promisify__;
-};
-/**
- * The scoped `.claude.json`'s modification stamp (epoch ms), undefined when
- * absent. A completed login rewrites this file, so the stamp distinguishes a
- * fresh login from a leftover marker (a revoked token's record lingers).
- * @param homeDir - the `claude-code` harness's scoped home.
- * @returns the marker's mtime, or undefined when no scoped config exists.
- */
-export declare function claudeCredentialStamp(homeDir: string): Promise<number | undefined>;
-/**
- * Reconcile the keychain credential with `<homeDir>/.credentials.json`,
- * NEWER WINS. Claude 2.1.236 on macOS WRITES the scoped login to the hashed
- * keychain entry but READS the credentials file at runtime (the same
- * write/read split as the Linux #47661 bug) — a login that lands only in the
- * keychain still answers "Not logged in", so the file has to be kept current.
- *
- * The file is not this process's private mirror, though: a containerized
- * round bind-mounts this very directory read-write (the unit has no keychain,
- * so the CLI inside it reads and writes the file), and the pre-spawn sync runs
- * against the HOST path moments before the unit reads it through the mount.
- * An unconditional mirror therefore makes this function the one participant
- * that can move the credential chain BACKWARD: it hands the next run a refresh
- * token the other writer already spent, the endpoint rejects it, and the CLI
- * answers by CLEARING the file — which logs the instance out, because that
- * file is the instance's credential. So the keychain blob is written only when
- * it is not older than the file's. Undefined expiry on either side keeps the
- * pre-newer-wins behavior (the keychain writes), and a file that is not USABLE
- * never wins.
- *
- * Only a USABLE blob (non-empty token, see `readKeychainCredential`) is
- * mirrored; with none in the keychain, a file holding an empty-token shell —
- * debris from an earlier first-match read, or a cleared credential — is
- * REMOVED, so the runtime says "Not logged in" instead of the misleading
- * "OAuth session expired". Idempotent and content-compare before write.
- * @param homeDir - the `claude-code` harness's scoped home.
- * @param log - warn channel for the two decisions that used to be silent.
- * @returns true when a usable credential is in the file after the call.
- */
-export declare function syncClaudeCredentialFile(homeDir: string, log?: (message: string) => void): Promise<boolean>;
-/**
- * Whether the scoped home holds usable Claude Code credentials: the scoped
- * `.claude.json` carries an `oauthAccount` record once a device-code login
- * has completed, AND the keychain credential is not past its stored expiry
- * (when the expiry is readable — a server-side REVOCATION is not visible
- * locally; providers report those through `localAgent.reportAuthFailure`).
- * The real credential lives in the macOS keychain under a hashed entry
- * (`Claude Code-credentials-<sha256(path)[:8]>`, hashed from the config-dir
- * path) or in the default `~/.claude/.credentials.json` on Linux (upstream
- * bug #47661: `CLAUDE_CONFIG_DIR` does not isolate the credentials file
- * there — it writes the scoped dir but READS the default home, so Linux
- * credentials may exist even when the scoped home has none). Spawning the
- * CLI to probe auth is avoided; the platform differences are documented in
- * the README.
- * @param homeDir - the `claude-code` harness's scoped home.
- * @param log - warn channel handed to the credential reconcile below.
- * @returns true when a completed login is recorded and not locally expired.
- */
-export declare function claudeAuthenticated(homeDir: string, log?: (message: string) => void): Promise<boolean>;
 /**
  * Parse the head of a session file for the listing fields. The first `user`
  * event carries `sessionId`, `cwd`, and `timestamp`; its `cwd` is the only