instar 0.28.113 → 0.28.115

package/dist/core/CoherenceReviewer.js

@@ -6,19 +6,15 @@
  * preambles, structured message passing) and fail-open semantics.
  */
 import crypto from 'node:crypto';
-import { resolveModelId } from './models.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const ANTHROPIC_API_URL = 'https://api.anthropic.com/v1/messages';
-const ANTHROPIC_API_VERSION = '2023-06-01';
 const DEFAULT_TIMEOUT_MS = 10_000;
 // ---------------------------------------------------------------------------
 // Base class
 // ---------------------------------------------------------------------------
 export class CoherenceReviewer {
     name;
-    apiKey;
     intelligence;
     options;
     metrics = {
@@ -28,9 +24,8 @@ export class CoherenceReviewer {
         totalLatencyMs: 0,
         jsonParseErrors: 0,
     };
-    constructor(name, apiKey, options) {
+    constructor(name, options) {
         this.name = name;
-        this.apiKey = apiKey;
         this.options = options ?? {};
         this.intelligence = options?.intelligence ?? null;
     }
@@ -137,65 +132,33 @@ export class CoherenceReviewer {
         }
     }
     /**
-     * Run the reviewer's LLM call. Routes through IntelligenceProvider when available
-     * (supports Claude CLI subscription + Anthropic API), else falls back to the
-     * direct Anthropic API path using the constructor apiKey.
+     * Run the reviewer's LLM call. Routes through the IntelligenceProvider, which
+     * itself routes through the Claude CLI (Agent SDK / subscription path) per
+     * Rule 2 of the path constraints. If no IntelligenceProvider is wired,
+     * throws — the previous direct-Anthropic-API fallback path was removed
+     * during the path-constraint lockdown (no raw `api.anthropic.com` calls
+     * may live on routine inference paths).
      *
-     * Uses AbortController to enforce timeoutMs on the direct-API path so the underlying
-     * fetch is cancelled when a Promise.race timeout fires. Without cancellation,
-     * timed-out fetches keep running, pile up, and eventually cause the HTTP request
-     * timeout middleware to return 408 after 30s.
+     * Wraps the provider call in a timeout race so the reviewer can fail
+     * within `timeoutMs` even if the provider's own timeout is longer.
      */
     async callApi(prompt) {
         const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-        if (this.intelligence) {
-            const intelOptions = {
-                model: this.mapModelToTier(this.options.model ?? 'haiku'),
-                maxTokens: 200,
-                temperature: 0,
-            };
-            // IntelligenceProvider implementations set their own timeouts; wrap here too.
-            return await Promise.race([
-                this.intelligence.evaluate(prompt, intelOptions),
-                new Promise((_, reject) => setTimeout(() => reject(new Error(`Reviewer timeout after ${timeoutMs}ms`)), timeoutMs)),
-            ]);
-        }
-        const model = resolveModelId(this.options.model ?? 'haiku');
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
-        try {
-            const response = await fetch(ANTHROPIC_API_URL, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'x-api-key': this.apiKey,
-                    'anthropic-version': ANTHROPIC_API_VERSION,
-                },
-                body: JSON.stringify({
-                    model,
-                    max_tokens: 200,
-                    temperature: 0,
-                    messages: [{ role: 'user', content: prompt }],
-                }),
-                signal: controller.signal,
-            });
-            if (!response.ok) {
-                const errorText = await response.text().catch(() => 'unknown error');
-                throw new Error(`Anthropic API error ${response.status}: ${errorText}`);
-            }
-            const data = (await response.json());
-            const textBlock = data.content?.find((block) => block.type === 'text');
-            return textBlock?.text ?? '';
-        }
-        catch (err) {
-            if (err instanceof Error && err.name === 'AbortError') {
-                throw new Error(`Request timeout after ${timeoutMs}ms`);
-            }
-            throw err;
-        }
-        finally {
-            clearTimeout(timer);
+        if (!this.intelligence) {
+            throw new Error(`Reviewer "${this.name}" was constructed without an IntelligenceProvider. `
+                + `Direct Anthropic API path is no longer supported (see specs/provider-portability/04-anthropic-path-constraints.md). `
+                + `Wire an IntelligenceProvider through options.intelligence.`);
         }
+        const intelOptions = {
+            model: this.mapModelToTier(this.options.model ?? 'haiku'),
+            maxTokens: 200,
+            temperature: 0,
+        };
+        // IntelligenceProvider implementations set their own timeouts; wrap here too.
+        return await Promise.race([
+            this.intelligence.evaluate(prompt, intelOptions),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Reviewer timeout after ${timeoutMs}ms`)), timeoutMs)),
+        ]);
     }
     /**
      * Map a reviewer model string (e.g., 'haiku', 'sonnet', full ID) to an

package/dist/core/CoherenceReviewer.js.map

@@ -1 +1 @@
-{"version":3,"file":"CoherenceReviewer.js","sourceRoot":"","sources":["../../src/core/CoherenceReviewer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CoherenceReviewer.js","sourceRoot":"","sources":["../../src/core/CoherenceReviewer.ts"],"names":[],"mappings":"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"}

package/dist/core/Config.d.ts

@@ -9,7 +9,114 @@ export declare function getInstarVersion(): string;
 export declare function detectGitPath(): string | null;
 export declare function detectGhPath(): string | null;
 export declare function detectTmuxPath(): string | null;
+/**
+ * Per-framework CLI binary identifiers.
+ *
+ * Provider-portability v1.0.0: every framework Instar can drive has its
+ * own CLI binary. `detectFrameworkBinary` locates it across the common
+ * install paths (npm-global, Homebrew, nvm/fnm, system PATH) without
+ * baking any single absolute path into the codebase. Add a framework
+ * here and detection works automatically.
+ */
+export type FrameworkBinary = 'claude' | 'codex' | 'gemini' | 'aider' | 'goose' | 'cursor-cli' | 'opencode' | 'plandex';
+/**
+ * Generic framework binary detection. Searches:
+ *   1. Framework-specific install location (e.g. `~/.claude/local/claude`)
+ *   2. Standard system paths (`/usr/local/bin`, `/opt/homebrew/bin`)
+ *   3. npm global bin (where `npm install -g` lands)
+ *   4. nvm-managed bin directories
+ *   5. System PATH (via `which`)
+ *
+ * Returns the absolute path or null if not found.
+ *
+ * Never hardcodes developer-specific install paths — the result depends
+ * on what's installed on THIS machine, not where the binary lives on
+ * the developer's machine.
+ */
+export declare function detectFrameworkBinary(name: FrameworkBinary): string | null;
+/**
+ * Detect the Claude Code CLI. Convenience wrapper preserved for
+ * backwards-compat with existing call sites. New code should use
+ * `detectFrameworkBinary('claude')` directly.
+ */
 export declare function detectClaudePath(): string | null;
+/**
+ * Detect the OpenAI Codex CLI. Provider-portability v1.0.0 sibling of
+ * detectClaudePath. Replaces hardcoded developer-specific path that
+ * previously lived in `src/providers/adapters/openai-codex/config.ts`.
+ */
+export declare function detectCodexPath(): string | null;
+/**
+ * Inputs to the framework-prerequisite check. Pure-function shape so the
+ * check is unit-testable without spawning a real Config.load() against
+ * the host filesystem.
+ */
+export interface FrameworkPrerequisiteInput {
+    /** Framework selected by config or env. */
+    configuredFramework: 'claude-code' | 'codex-cli';
+    /** Path to claude binary if detected, else null. */
+    claudePathDetected: string | null;
+    /** Path to codex binary if detected, else null. */
+    codexPathDetected: string | null;
+}
+export interface FrameworkPrerequisiteResult {
+    /** True when the configured framework's binary is present. */
+    satisfied: boolean;
+    /**
+     * Human-readable error message when satisfied=false. Includes the
+     * install URL/command for the missing framework.
+     */
+    error?: string;
+}
+/**
+ * Check whether the configured framework's required binary is available.
+ *
+ * Provider-portability v1.0.0: this replaces the v0.x unconditional
+ * "Claude CLI not found" error that blocked every non-Claude install
+ * at startup. Now codex-cli installs only need the codex binary,
+ * claude-code installs only need the claude binary.
+ */
+export declare function checkFrameworkPrerequisite(input: FrameworkPrerequisiteInput): FrameworkPrerequisiteResult;
+/**
+ * Resolve the configured framework from a (possibly-undefined) config
+ * file value and the current environment. Pure function so callers can
+ * unit-test the resolution independently.
+ */
+export declare function resolveConfiguredFramework(configValue: 'claude-code' | 'codex-cli' | undefined, envValue: string | undefined): 'claude-code' | 'codex-cli';
+/**
+ * Look up a provider's credential. Returns null when none is configured.
+ *
+ * Use this in any code path that previously read `config.anthropicApiKey`
+ * — the helper consults the new `credentials` map first and falls back
+ * to the legacy field for 'anthropic' so existing installs continue to
+ * work without migration.
+ *
+ * @example
+ *   const cred = getProviderCredential(config, 'anthropic');
+ *   if (cred?.kind === 'oauth-token') { ... }
+ */
+export declare function getProviderCredential(config: import('./types.js').SessionManagerConfig, providerId: string): import('./types.js').ProviderCredential | null;
+/**
+ * Build env vars to inject into a spawned subprocess for the given
+ * provider credential. Provider-aware: maps the credential to the env
+ * var the framework's CLI expects.
+ *
+ * For Anthropic:
+ *   - oauth-token → CLAUDE_CODE_OAUTH_TOKEN set, ANTHROPIC_API_KEY cleared
+ *   - api-key     → ANTHROPIC_API_KEY set, CLAUDE_CODE_OAUTH_TOKEN cleared
+ *   - baseUrl     → ANTHROPIC_BASE_URL set
+ *
+ * For OpenAI/Codex:
+ *   - api-key     → OPENAI_API_KEY set
+ *   - oauth-token → (no env var — Codex CLI reads its own auth.json)
+ *
+ * For Google/Gemini:
+ *   - api-key     → GOOGLE_API_KEY set
+ *
+ * Returns a flat list of [`-e`, `KEY=value`, ...] suitable for tmux
+ * `new-session -e KEY=VAL`. Empty if the credential is missing/unknown.
+ */
+export declare function buildProviderEnvFlags(providerId: string, credential: import('./types.js').ProviderCredential): ReadonlyArray<string>;
 export declare function detectProjectDir(startDir?: string): string;
 /**
  * Get the path to the standalone agents directory.

package/dist/core/Config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../src/core/Config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,YAAY,EAAuE,MAAM,YAAY,CAAC;AAMpH,wBAAgB,gBAAgB,IAAI,MAAM,CAgBzC;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAoB7C;AAED,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAoB5C;AAED,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAoB9C;AAED,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAoChD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAY1D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAwC3D;AAED,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,CA8I5D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAcrD"}
+{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../src/core/Config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,YAAY,EAAuE,MAAM,YAAY,CAAC;AAMpH,wBAAgB,gBAAgB,IAAI,MAAM,CAgBzC;AAED,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAoB7C;AAED,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAoB5C;AAED,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAoB9C;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,GACP,OAAO,GACP,YAAY,GACZ,UAAU,GACV,SAAS,CAAC;AAEd;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAyD1E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAID;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,2CAA2C;IAC3C,mBAAmB,EAAE,aAAa,GAAG,WAAW,CAAC;IACjD,oDAAoD;IACpD,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,2BAA2B;IAC1C,8DAA8D;IAC9D,SAAS,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,0BAA0B,GAChC,2BAA2B,CA6B7B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,aAAa,GAAG,WAAW,GAAG,SAAS,EACpD,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,aAAa,GAAG,WAAW,CAO7B;AA6CD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,YAAY,EAAE,oBAAoB,EACjD,UAAU,EAAE,MAAM,GACjB,OAAO,YAAY,EAAE,kBAAkB,GAAG,IAAI,CAkBhD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,OAAO,YAAY,EAAE,kBAAkB,GAClD,aAAa,CAAC,MAAM,CAAC,CAkEvB;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAY1D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAwC3D;AAED,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,CAgL5D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAcrD"}

package/dist/core/Config.js

@@ -96,42 +96,287 @@ export function detectTmuxPath() {
     }
     return null;
 }
-export function detectClaudePath() {
+/**
+ * Generic framework binary detection. Searches:
+ *   1. Framework-specific install location (e.g. `~/.claude/local/claude`)
+ *   2. Standard system paths (`/usr/local/bin`, `/opt/homebrew/bin`)
+ *   3. npm global bin (where `npm install -g` lands)
+ *   4. nvm-managed bin directories
+ *   5. System PATH (via `which`)
+ *
+ * Returns the absolute path or null if not found.
+ *
+ * Never hardcodes developer-specific install paths — the result depends
+ * on what's installed on THIS machine, not where the binary lives on
+ * the developer's machine.
+ */
+export function detectFrameworkBinary(name) {
     const home = process.env.HOME || '';
-    const candidates = [
-        path.join(home, '.claude', 'local', 'claude'),
-        '/usr/local/bin/claude',
-        '/opt/homebrew/bin/claude',
-    ];
-    // Also check npm global bin directory (where `npm install -g` puts things)
+    const candidates = [];
+    // Framework-specific known locations.
+    switch (name) {
+        case 'claude':
+            candidates.push(path.join(home, '.claude', 'local', 'claude'));
+            break;
+        case 'codex':
+            candidates.push(path.join(home, '.codex', 'bin', 'codex'));
+            break;
+        case 'gemini':
+            candidates.push(path.join(home, '.gemini', 'bin', 'gemini'));
+            break;
+        default:
+            // No framework-specific path; falls through to system + PATH.
+            break;
+    }
+    // Standard system locations.
+    candidates.push(`/opt/homebrew/bin/${name}`); // macOS ARM
+    candidates.push(`/usr/local/bin/${name}`); // macOS Intel / Linux
+    candidates.push(`/usr/bin/${name}`); // Linux system
+    // npm global bin (where `npm install -g <pkg>` lands).
     try {
-        const npmPrefix = execFileSync('npm', ['config', 'get', 'prefix'], { encoding: 'utf-8', stdio: 'pipe' }).trim();
-        if (npmPrefix) {
-            candidates.push(path.join(npmPrefix, 'bin', 'claude'));
-        }
+        const npmPrefix = execFileSync('npm', ['config', 'get', 'prefix'], {
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        }).trim();
+        if (npmPrefix)
+            candidates.push(path.join(npmPrefix, 'bin', name));
     }
     catch {
-        // @silent-fallback-ok — claude path detection loop
+        // @silent-fallback-ok — npm prefix detection
     }
-    // Check nvm/fnm managed paths
+    // nvm-managed bin.
     if (process.env.NVM_BIN) {
-        candidates.push(path.join(process.env.NVM_BIN, 'claude'));
+        candidates.push(path.join(process.env.NVM_BIN, name));
     }
     for (const candidate of candidates) {
         if (fs.existsSync(candidate))
             return candidate;
     }
-    // Fallback: check PATH
+    // Last resort: PATH lookup.
     try {
-        const result = execFileSync('which', ['claude'], { encoding: 'utf-8', stdio: 'pipe' }).trim();
+        const result = execFileSync('which', [name], {
+            encoding: 'utf-8',
+            stdio: 'pipe',
+        }).trim();
         if (result && fs.existsSync(result))
             return result;
     }
     catch {
-        // @silent-fallback-ok — claude path detection loop
+        // @silent-fallback-ok — which fallback
     }
     return null;
 }
+/**
+ * Detect the Claude Code CLI. Convenience wrapper preserved for
+ * backwards-compat with existing call sites. New code should use
+ * `detectFrameworkBinary('claude')` directly.
+ */
+export function detectClaudePath() {
+    return detectFrameworkBinary('claude');
+}
+/**
+ * Detect the OpenAI Codex CLI. Provider-portability v1.0.0 sibling of
+ * detectClaudePath. Replaces hardcoded developer-specific path that
+ * previously lived in `src/providers/adapters/openai-codex/config.ts`.
+ */
+export function detectCodexPath() {
+    return detectFrameworkBinary('codex');
+}
+/**
+ * Check whether the configured framework's required binary is available.
+ *
+ * Provider-portability v1.0.0: this replaces the v0.x unconditional
+ * "Claude CLI not found" error that blocked every non-Claude install
+ * at startup. Now codex-cli installs only need the codex binary,
+ * claude-code installs only need the claude binary.
+ */
+export function checkFrameworkPrerequisite(input) {
+    switch (input.configuredFramework) {
+        case 'claude-code':
+            if (!input.claudePathDetected) {
+                return {
+                    satisfied: false,
+                    error: 'Claude CLI not found. INSTAR_FRAMEWORK is set to claude-code (or unset, '
+                        + 'which defaults to claude-code). Install from: https://docs.anthropic.com/en/docs/claude-code '
+                        + 'or switch frameworks via INSTAR_FRAMEWORK=codex-cli.',
+                };
+            }
+            return { satisfied: true };
+        case 'codex-cli':
+            if (!input.codexPathDetected) {
+                return {
+                    satisfied: false,
+                    error: 'Codex CLI not found. INSTAR_FRAMEWORK is set to codex-cli. '
+                        + 'Install with: npm install -g @openai/codex',
+                };
+            }
+            return { satisfied: true };
+        default: {
+            const _exhaustive = input.configuredFramework;
+            void _exhaustive;
+            return { satisfied: false, error: 'Unknown framework' };
+        }
+    }
+}
+/**
+ * Resolve the configured framework from a (possibly-undefined) config
+ * file value and the current environment. Pure function so callers can
+ * unit-test the resolution independently.
+ */
+export function resolveConfiguredFramework(configValue, envValue) {
+    if (configValue === 'claude-code' || configValue === 'codex-cli') {
+        return configValue;
+    }
+    const env = envValue?.trim().toLowerCase();
+    if (env === 'codex-cli' || env === 'codex')
+        return 'codex-cli';
+    return 'claude-code';
+}
+// ── Provider Credentials ───────────────────────────────────────────────
+/**
+ * Build the credentials map from raw config file contents.
+ *
+ * Provider-portability v1.0.0: migrates the legacy single-provider
+ * fields (`sessions.anthropicApiKey`, `sessions.anthropicBaseUrl`) into
+ * the new multi-provider `credentials` map. If both are present, the
+ * explicit `credentials.anthropic` wins.
+ *
+ * Returns a copy — never mutates the input.
+ */
+function buildCredentialsMap(sessionsConfig) {
+    if (!sessionsConfig)
+        return undefined;
+    const existingMap = sessionsConfig['credentials'];
+    const credentials = {
+        ...(existingMap ?? {}),
+    };
+    // Legacy field migration: only fill in if not explicitly set.
+    if (!credentials['anthropic']) {
+        const legacyKey = sessionsConfig['anthropicApiKey'];
+        const legacyBaseUrl = sessionsConfig['anthropicBaseUrl'];
+        if (legacyKey || legacyBaseUrl) {
+            // OAuth tokens start with `sk-ant-oat`; everything else is an API key.
+            const kind = legacyKey && legacyKey.startsWith('sk-ant-oat') ? 'oauth-token' : 'api-key';
+            credentials['anthropic'] = {
+                kind,
+                value: legacyKey ?? '',
+                ...(legacyBaseUrl ? { baseUrl: legacyBaseUrl } : {}),
+            };
+        }
+    }
+    return Object.keys(credentials).length > 0 ? credentials : undefined;
+}
+/**
+ * Look up a provider's credential. Returns null when none is configured.
+ *
+ * Use this in any code path that previously read `config.anthropicApiKey`
+ * — the helper consults the new `credentials` map first and falls back
+ * to the legacy field for 'anthropic' so existing installs continue to
+ * work without migration.
+ *
+ * @example
+ *   const cred = getProviderCredential(config, 'anthropic');
+ *   if (cred?.kind === 'oauth-token') { ... }
+ */
+export function getProviderCredential(config, providerId) {
+    const fromMap = config.credentials?.[providerId];
+    if (fromMap)
+        return fromMap;
+    // Backwards-compat for the only previously-supported provider.
+    if (providerId === 'anthropic' && config.anthropicApiKey !== undefined) {
+        const value = config.anthropicApiKey;
+        const kind = value.startsWith('sk-ant-oat')
+            ? 'oauth-token'
+            : 'api-key';
+        return {
+            kind,
+            value,
+            ...(config.anthropicBaseUrl ? { baseUrl: config.anthropicBaseUrl } : {}),
+        };
+    }
+    return null;
+}
+/**
+ * Build env vars to inject into a spawned subprocess for the given
+ * provider credential. Provider-aware: maps the credential to the env
+ * var the framework's CLI expects.
+ *
+ * For Anthropic:
+ *   - oauth-token → CLAUDE_CODE_OAUTH_TOKEN set, ANTHROPIC_API_KEY cleared
+ *   - api-key     → ANTHROPIC_API_KEY set, CLAUDE_CODE_OAUTH_TOKEN cleared
+ *   - baseUrl     → ANTHROPIC_BASE_URL set
+ *
+ * For OpenAI/Codex:
+ *   - api-key     → OPENAI_API_KEY set
+ *   - oauth-token → (no env var — Codex CLI reads its own auth.json)
+ *
+ * For Google/Gemini:
+ *   - api-key     → GOOGLE_API_KEY set
+ *
+ * Returns a flat list of [`-e`, `KEY=value`, ...] suitable for tmux
+ * `new-session -e KEY=VAL`. Empty if the credential is missing/unknown.
+ */
+export function buildProviderEnvFlags(providerId, credential) {
+    const flags = [];
+    const push = (key, value) => {
+        flags.push('-e', `${key}=${value}`);
+    };
+    switch (providerId) {
+        case 'anthropic':
+            if (credential.kind === 'oauth-token') {
+                push('CLAUDE_CODE_OAUTH_TOKEN', credential.value);
+                push('ANTHROPIC_API_KEY', '');
+            }
+            else {
+                push('ANTHROPIC_API_KEY', credential.value);
+                push('CLAUDE_CODE_OAUTH_TOKEN', '');
+            }
+            if (credential.baseUrl) {
+                push('ANTHROPIC_BASE_URL', credential.baseUrl);
+            }
+            break;
+        case 'openai':
+            // Codex CLI reads ~/.codex/auth.json for OAuth — the subscription path
+            // requires no env vars on this side. The raw-API-key path is forbidden
+            // per Spec 12 Rule 1 ("OpenAI path constraints"): Codex must route via
+            // ChatGPT subscription OAuth; raw OPENAI_API_KEY is not an acceptable
+            // routine path. If a caller wires up an api-key credential for openai,
+            // that's a misconfiguration we refuse loudly rather than silently
+            // emitting the leak.
+            //
+            // RULE 3: EXEMPT — this OPENAI_API_KEY identifier is part of the
+            // refusal text in the spec-enforcement message, not an emission of
+            // the value as an env var.
+            if (credential.kind === 'api-key') {
+                throw new Error('buildProviderEnvFlags refuses openai api-key credential: ' +
+                    'Spec 12 Rule 1 forbids the raw OPENAI_API_KEY path. ' +
+                    'Codex must route through ChatGPT subscription OAuth in ' +
+                    '~/.codex/auth.json. See specs/provider-portability/' +
+                    '12-openai-path-constraints.md for the migration path.');
+            }
+            // OAuth path: no env vars to emit (Codex reads ~/.codex/auth.json).
+            // baseUrl override remains legitimate for user-installed Codex proxies
+            // (Spec 12 § "Scope clarification — user-installed proxies are
+            // user-owned compatibility").
+            if (credential.baseUrl) {
+                push('OPENAI_BASE_URL', credential.baseUrl);
+            }
+            break;
+        case 'google':
+            if (credential.kind === 'api-key') {
+                push('GOOGLE_API_KEY', credential.value);
+            }
+            if (credential.baseUrl) {
+                push('GEMINI_BASE_URL', credential.baseUrl);
+            }
+            break;
+        default:
+            // Unknown provider — return empty. Adapters can implement their
+            // own env-mapping when they register; this default is safe.
+            break;
+    }
+    return flags;
+}
 export function detectProjectDir(startDir) {
     let dir = startDir || process.cwd();
     // Walk up to find a directory with CLAUDE.md or .git
@@ -218,17 +463,42 @@ export function loadConfig(projectDir) {
         // Non-fatal — config works without secrets (just missing the secret values)
     }
     const tmuxPath = fileConfig.sessions?.tmuxPath || detectTmuxPath();
-    const claudePath = fileConfig.sessions?.claudePath || detectClaudePath();
+    // Provider-portability v1.0.0: boot requires the configured framework's
+    // binary, not Claude unconditionally. resolveConfiguredFramework picks
+    // from (sessions.framework | INSTAR_FRAMEWORK | default claude-code).
+    // checkFrameworkPrerequisite gates startup — codex-cli installs no
+    // longer get rejected just because Claude isn't installed.
+    const configuredFramework = resolveConfiguredFramework(fileConfig.sessions?.['framework'], process.env['INSTAR_FRAMEWORK']);
+    const claudePathDetected = fileConfig.sessions?.claudePath || detectClaudePath();
+    const codexPathDetected = detectCodexPath();
     if (!tmuxPath) {
         throw new Error('tmux not found. Install with: brew install tmux (macOS) or apt install tmux (Linux)');
     }
-    if (!claudePath) {
-        throw new Error('Claude CLI not found. Install from: https://docs.anthropic.com/en/docs/claude-code');
+    const prereq = checkFrameworkPrerequisite({
+        configuredFramework,
+        claudePathDetected,
+        codexPathDetected,
+    });
+    if (!prereq.satisfied) {
+        throw new Error(prereq.error);
     }
+    // The SessionManagerConfig's claudePath field is kept for backwards-compat
+    // with existing spawn paths; for codex-cli installs it carries the codex
+    // binary path. Spawn paths will be migrated to read `frameworkBinaryPath`
+    // (or similar) in a follow-up slice.
+    const claudePath = configuredFramework === 'codex-cli'
+        ? (codexPathDetected ?? claudePathDetected ?? '')
+        : (claudePathDetected ?? '');
     const projectName = fileConfig.projectName || path.basename(resolvedProjectDir);
     const sessions = {
         tmuxPath,
         claudePath,
+        // Expose every detected framework binary so spawnInteractiveSession
+        // can route a session to any framework without re-running detection.
+        frameworkBinaryPaths: {
+            ...(claudePathDetected ? { 'claude-code': claudePathDetected } : {}),
+            ...(codexPathDetected ? { 'codex-cli': codexPathDetected } : {}),
+        },
         projectDir: resolvedProjectDir,
         maxSessions: fileConfig.sessions?.maxSessions ?? DEFAULT_MAX_SESSIONS,
         protectedSessions: fileConfig.sessions?.protectedSessions || [`${projectName}-server`],
@@ -241,6 +511,7 @@ export function loadConfig(projectDir) {
         port: fileConfig.port ?? 4040,
         anthropicApiKey: fileConfig.sessions?.anthropicApiKey,
         anthropicBaseUrl: fileConfig.sessions?.anthropicBaseUrl,
+        credentials: buildCredentialsMap(fileConfig.sessions),
     };
     const scheduler = {
         jobsFile: fileConfig.scheduler?.jobsFile || path.join(stateDir, 'jobs.json'),