@jokerized/getresearchdone 0.4.1

package/dist/lib/backend.js

@@ -0,0 +1,1036 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+// --- Constants ---------------------------------------------------------------
+/**
+ * List of valid backend identifiers.
+ */
+const VALID_BACKENDS = [
+    'claude',
+    'codex',
+    'gemini',
+    'opencode',
+    'overstory',
+    'superpowers',
+    'grd',
+];
+/**
+ * Default model name mappings per backend and tier.
+ * Each backend maps the abstract tiers (opus, sonnet, haiku) to concrete
+ * model identifiers recognized by that backend's CLI.
+ */
+const DEFAULT_BACKEND_MODELS = {
+    claude: { opus: 'opus', sonnet: 'sonnet', haiku: 'haiku' },
+    codex: {
+        opus: 'gpt-5.4',
+        sonnet: 'gpt-5.3-codex-spark',
+        haiku: 'gpt-5.4-mini',
+    },
+    gemini: {
+        opus: 'gemini-3.1-pro',
+        sonnet: 'gemini-3.1-flash',
+        haiku: 'gemini-3.1-flash-lite',
+    },
+    opencode: {
+        opus: 'anthropic/claude-opus-4-6',
+        sonnet: 'anthropic/claude-sonnet-4-6',
+        haiku: 'anthropic/claude-haiku-4-5',
+    },
+    overstory: { opus: 'opus', sonnet: 'sonnet', haiku: 'haiku' },
+    superpowers: { opus: 'opus', sonnet: 'sonnet', haiku: 'haiku' },
+    grd: { opus: 'opus', sonnet: 'sonnet', haiku: 'haiku' },
+};
+/**
+ * Capability flags per backend. Describes what orchestration features each
+ * backend supports. Used to degrade gracefully for backends with limited features.
+ */
+const BACKEND_CAPABILITIES = {
+    claude: {
+        subagents: true,
+        parallel: true,
+        teams: true,
+        hooks: true,
+        mcp: true,
+        native_worktree_isolation: true,
+        effort: true,
+        http_hooks: true,
+        cron: true,
+        smart_approvals: false,
+        plan_mode: false,
+        sandbox_gvisor: false,
+        sandbox_lxc: false,
+        mcp_elicitation: true,
+        model_overrides: true,
+        max_output_tokens: { default: 64000, upper_bound: 128000 },
+    },
+    codex: {
+        subagents: true,
+        parallel: true,
+        teams: true,
+        hooks: true,
+        mcp: true,
+        native_worktree_isolation: false,
+        effort: false,
+        http_hooks: false,
+        cron: false,
+        smart_approvals: true,
+        plan_mode: false,
+        sandbox_gvisor: false,
+        sandbox_lxc: false,
+        mcp_elicitation: false,
+        model_overrides: true,
+        max_output_tokens: null,
+    },
+    gemini: {
+        subagents: true,
+        parallel: true,
+        teams: false,
+        hooks: true,
+        mcp: true,
+        native_worktree_isolation: false,
+        effort: false,
+        http_hooks: false,
+        cron: false,
+        smart_approvals: false,
+        plan_mode: true,
+        sandbox_gvisor: true,
+        sandbox_lxc: false,
+        mcp_elicitation: false,
+        model_overrides: true,
+        max_output_tokens: null,
+    },
+    opencode: {
+        subagents: true,
+        parallel: true,
+        teams: false,
+        hooks: true,
+        mcp: true,
+        native_worktree_isolation: false,
+        effort: false,
+        http_hooks: false,
+        cron: false,
+        smart_approvals: false,
+        plan_mode: false,
+        sandbox_gvisor: false,
+        sandbox_lxc: false,
+        mcp_elicitation: false,
+        model_overrides: true,
+        max_output_tokens: null,
+    },
+    overstory: {
+        subagents: true,
+        parallel: true,
+        teams: true,
+        hooks: false,
+        mcp: true,
+        native_worktree_isolation: true,
+        effort: false,
+        http_hooks: false,
+        cron: false,
+        smart_approvals: false,
+        plan_mode: false,
+        sandbox_gvisor: false,
+        sandbox_lxc: false,
+        mcp_elicitation: false,
+        model_overrides: true,
+        max_output_tokens: null,
+    },
+    superpowers: {
+        subagents: true,
+        parallel: true,
+        teams: true,
+        hooks: true,
+        mcp: true,
+        native_worktree_isolation: true,
+        effort: true,
+        http_hooks: false,
+        cron: false,
+        smart_approvals: false,
+        plan_mode: false,
+        sandbox_gvisor: false,
+        sandbox_lxc: false,
+        mcp_elicitation: false,
+        model_overrides: true,
+        max_output_tokens: null,
+    },
+    grd: {
+        subagents: true,
+        parallel: true,
+        teams: true,
+        hooks: true,
+        mcp: true,
+        native_worktree_isolation: true,
+        effort: false,
+        http_hooks: false,
+        cron: false,
+        smart_approvals: false,
+        plan_mode: false,
+        sandbox_gvisor: false,
+        sandbox_lxc: false,
+        mcp_elicitation: false,
+        model_overrides: false,
+        max_output_tokens: null,
+    },
+};
+// --- Effort Level Profiles ---------------------------------------------------
+/**
+ * Default effort levels per agent and profile. Mirrors MODEL_PROFILES in utils.ts
+ * but for the effort dimension. Effort controls reasoning depth in backends that
+ * support it (currently Claude Code v2.1.68+).
+ *
+ * Design intent (from REQ-92):
+ *   quality  => planners/executors get high (deep reasoning), verifiers get medium
+ *   balanced => planners get high, executors get medium, verifiers/lightweight agents get low
+ *   budget   => everything low (fast, minimal reasoning)
+ */
+const EFFORT_PROFILES = {
+    'grd-planner': { quality: 'high', balanced: 'high', budget: 'low' },
+    'grd-roadmapper': { quality: 'high', balanced: 'medium', budget: 'low' },
+    'grd-executor': { quality: 'high', balanced: 'medium', budget: 'low' },
+    'grd-phase-researcher': { quality: 'high', balanced: 'medium', budget: 'low' },
+    'grd-project-researcher': { quality: 'high', balanced: 'medium', budget: 'low' },
+    'grd-research-synthesizer': { quality: 'medium', balanced: 'medium', budget: 'low' },
+    'grd-debugger': { quality: 'high', balanced: 'medium', budget: 'low' },
+    'grd-codebase-mapper': { quality: 'medium', balanced: 'low', budget: 'low' },
+    'grd-verifier': { quality: 'medium', balanced: 'low', budget: 'low' },
+    'grd-critique-agent': { quality: 'medium', balanced: 'low', budget: 'low' },
+    'grd-plan-checker': { quality: 'medium', balanced: 'medium', budget: 'low' },
+    'grd-integration-checker': { quality: 'medium', balanced: 'medium', budget: 'low' },
+    'grd-surveyor': { quality: 'medium', balanced: 'medium', budget: 'low' },
+    'grd-deep-diver': { quality: 'high', balanced: 'medium', budget: 'low' },
+    'grd-feasibility-analyst': { quality: 'high', balanced: 'medium', budget: 'low' },
+    'grd-eval-planner': { quality: 'high', balanced: 'medium', budget: 'low' },
+    'grd-eval-reporter': { quality: 'medium', balanced: 'medium', budget: 'low' },
+    'grd-product-owner': { quality: 'high', balanced: 'high', budget: 'low' },
+    'grd-baseline-assessor': { quality: 'medium', balanced: 'medium', budget: 'low' },
+    'grd-code-reviewer': { quality: 'high', balanced: 'medium', budget: 'low' },
+};
+/**
+ * Resolve the effort level for a given agent type and model profile.
+ *
+ * Returns the effort level from EFFORT_PROFILES for the given agent and profile.
+ * Unknown agent types return 'medium' as a safe default. Unknown profiles
+ * fall back to 'balanced', then to 'medium'.
+ *
+ * @param agentType - Agent type key (e.g., 'grd-executor', 'grd-planner')
+ * @param profile - Model profile name ('quality', 'balanced', or 'budget')
+ * @returns The effort level string: 'low', 'medium', or 'high'
+ */
+function resolveEffortLevel(agentType, profile) {
+    const agentEffort = EFFORT_PROFILES[agentType];
+    if (!agentEffort)
+        return 'medium';
+    return agentEffort[profile] || agentEffort['balanced'] || 'medium';
+}
+/**
+ * Read and parse .planning/config.json from cwd. Returns parsed object or null.
+ * Uses fs.readFileSync directly to avoid circular dependency with lib/utils.js.
+ */
+function readConfig(cwd) {
+    try {
+        const configPath = path.join(cwd, '.planning', 'config.json');
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if any environment variable starts with a given prefix.
+ */
+function hasEnvPrefix(prefix) {
+    return Object.keys(process.env).some((k) => k.startsWith(prefix));
+}
+/**
+ * Check if a file exists at a given path.
+ */
+function fileExists(filePath) {
+    try {
+        fs.statSync(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// --- Exported Functions ------------------------------------------------------
+/**
+ * Detect which AI coding CLI backend is currently running.
+ *
+ * Detection waterfall (highest to lowest priority):
+ *   1. Config override: .planning/config.json `backend` field
+ *   2. Environment variables: CLAUDE_CODE_*, CODEX_HOME, GEMINI_CLI_HOME, OPENCODE
+ *   3. Filesystem clues: .claude-plugin/plugin.json, .codex/config.toml, etc.
+ *   4. Default: 'claude' (backward compatible)
+ *
+ * Note: The AGENT env var is NOT used for OpenCode detection per PITFALLS.md P5
+ * (too generic, may collide with other tools).
+ *
+ * @param cwd - Absolute path to the project root directory used for config and filesystem detection
+ * @returns The detected backend identifier (e.g. 'claude', 'codex', 'gemini', 'opencode')
+ */
+function detectBackend(cwd) {
+    // Step 1: Config override (highest priority)
+    const config = readConfig(cwd);
+    if (config && config.backend && VALID_BACKENDS.includes(config.backend)) {
+        return config.backend;
+    }
+    // Step 2: Environment variable detection
+    // Superpowers detection (highest env priority — orchestrates other backends)
+    if (process.env.SUPERPOWERS_HOME || process.env.SUPERPOWERS_SESSION)
+        return 'superpowers';
+    // Overstory detection (before Claude — takes priority when both present)
+    if (process.env.OVERSTORY_HOME || process.env.OVERSTORY_SESSION)
+        return 'overstory';
+    if (hasEnvPrefix('CLAUDE_CODE_'))
+        return 'claude';
+    // CODEX_THREAD_ID: may be deprecated in newer Codex CLI versions (no docs mention
+    // as of March 2026), but kept for backward compatibility with older installations.
+    if (process.env.CODEX_HOME || process.env.CODEX_THREAD_ID)
+        return 'codex';
+    if (process.env.GEMINI_CLI_HOME)
+        return 'gemini';
+    // OpenCode: actively maintained under anomalyco/opencode (original opencode-ai
+    // repo archived Sept 2025). OPENCODE_PID is NOT used — it's a process management
+    // var, not a presence indicator.
+    if (process.env.OPENCODE)
+        return 'opencode';
+    // Step 3: Filesystem clues
+    if (fileExists(path.join(cwd, '.superpowers', 'config.json')))
+        return 'superpowers';
+    if (fileExists(path.join(cwd, '.overstory', 'config.yaml')))
+        return 'overstory';
+    if (fileExists(path.join(cwd, '.claude-plugin', 'plugin.json')))
+        return 'claude';
+    if (fileExists(path.join(cwd, '.codex', 'config.toml')))
+        return 'codex';
+    if (fileExists(path.join(cwd, '.gemini', 'settings.json')))
+        return 'gemini';
+    if (fileExists(path.join(cwd, 'opencode.json')))
+        return 'opencode';
+    // Step 4: Default (backward compatible)
+    return 'claude';
+}
+// --- Dynamic Model Detection -------------------------------------------------
+/**
+ * Parse `opencode models` stdout into tier-classified model map.
+ * Classifies each model ID by keyword patterns:
+ *   opus tier: /opus/i, /pro/i (non-flash)
+ *   sonnet tier: /sonnet/i
+ *   haiku tier: /haiku/i, /flash/i, /mini/i, /spark/i
+ *
+ * @param stdout - Raw stdout string from the `opencode models` CLI command
+ * @returns A DetectedModels map with opus/sonnet/haiku slots filled where matched, or null if no models were matched
+ */
+function parseOpenCodeModels(stdout) {
+    if (!stdout || typeof stdout !== 'string')
+        return null;
+    const lines = stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('Available') && !l.startsWith('---') && !l.startsWith('#'));
+    const result = { opus: null, sonnet: null, haiku: null };
+    let matched = false;
+    for (const line of lines) {
+        const model = line.split(/\s+/)[0];
+        if (!model || !model.includes('/'))
+            continue;
+        if (/opus/i.test(model)) {
+            if (!result.opus) {
+                result.opus = model;
+                matched = true;
+            }
+        }
+        else if (/sonnet/i.test(model)) {
+            if (!result.sonnet) {
+                result.sonnet = model;
+                matched = true;
+            }
+        }
+        else if (/haiku/i.test(model)) {
+            if (!result.haiku) {
+                result.haiku = model;
+                matched = true;
+            }
+        }
+        else if (/pro/i.test(model) && !/flash/i.test(model)) {
+            if (!result.opus) {
+                result.opus = model;
+                matched = true;
+            }
+        }
+        else if (/flash/i.test(model) || /mini/i.test(model) || /spark/i.test(model)) {
+            if (!result.haiku) {
+                result.haiku = model;
+                matched = true;
+            }
+        }
+    }
+    return matched ? result : null;
+}
+/**
+ * Run backend-specific CLI command to detect available models.
+ * Currently only OpenCode supports programmatic model listing.
+ */
+function detectModels(backend, cwd) {
+    if (backend !== 'opencode')
+        return null;
+    const effectiveCwd = cwd || process.cwd();
+    const cfg = readConfig(effectiveCwd);
+    const timeouts = cfg?.timeouts;
+    const timeout = typeof timeouts?.backend_detect_ms === 'number' ? timeouts.backend_detect_ms : 10000;
+    try {
+        const stdout = execFileSync('opencode', ['models'], {
+            cwd: effectiveCwd,
+            timeout,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return parseOpenCodeModels(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+const _modelCache = new Map();
+const MODEL_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Get cached detected models for a backend, refreshing if TTL expired.
+ */
+function getCachedModels(backend, cwd) {
+    const entry = _modelCache.get(backend);
+    const now = Date.now();
+    if (entry && now - entry.ts < MODEL_CACHE_TTL_MS) {
+        return entry.models;
+    }
+    const models = detectModels(backend, cwd);
+    _modelCache.set(backend, { models, ts: now });
+    return models;
+}
+/**
+ * Clear the model detection cache. Exported for testing.
+ */
+function clearModelCache() {
+    _modelCache.clear();
+}
+/**
+ * Resolve an abstract model tier to a backend-specific model name.
+ *
+ * Checks config.backend_models for user overrides first, then falls back
+ * to DEFAULT_BACKEND_MODELS. Unknown backends fall back to claude mappings.
+ * Unknown tiers return undefined.
+ *
+ * @param backend - The backend identifier (e.g. 'claude', 'codex', 'gemini', 'opencode')
+ * @param tier - The abstract model tier to resolve ('opus', 'sonnet', or 'haiku')
+ * @param config - Optional parsed config.json object used for user-defined backend_models overrides
+ * @param cwd - Optional project root path used for dynamic model detection (opencode only)
+ * @returns The backend-specific model name string, or undefined if the tier is not mapped
+ */
+function resolveBackendModel(backend, tier, config, cwd) {
+    // Check user override from config (highest priority)
+    if (config && config.backend_models) {
+        const backendModelsConfig = config.backend_models;
+        const backendOverrides = backendModelsConfig[backend];
+        if (backendOverrides && backendOverrides[tier] !== undefined) {
+            return backendOverrides[tier];
+        }
+    }
+    // Check dynamically detected models (middle priority)
+    if (cwd) {
+        const detected = getCachedModels(backend, cwd);
+        if (detected && detected[tier]) {
+            return detected[tier];
+        }
+    }
+    // Use built-in defaults, falling back to claude for unknown backends
+    const backendModels = DEFAULT_BACKEND_MODELS[backend] || DEFAULT_BACKEND_MODELS.claude;
+    return backendModels[tier];
+}
+/**
+ * Get capability flags for a backend.
+ *
+ * Returns an object describing what orchestration features the backend supports.
+ * Unknown backends get minimal capabilities (all false) to prevent
+ * accidentally enabling features like native_worktree_isolation or effort.
+ *
+ * @param backend - The backend identifier (e.g. 'claude', 'codex', 'gemini', 'opencode')
+ * @returns A BackendCapabilities object describing which orchestration features are supported
+ */
+function getBackendCapabilities(backend) {
+    if (BACKEND_CAPABILITIES[backend]) {
+        return BACKEND_CAPABILITIES[backend];
+    }
+    // Unknown backend: warn and return minimal capabilities
+    process.stderr.write(`[grd] WARNING: unknown backend "${backend}", using minimal capabilities\n`);
+    return {
+        subagents: true,
+        parallel: false,
+        teams: false,
+        hooks: false,
+        mcp: false,
+        native_worktree_isolation: false,
+        effort: false,
+        http_hooks: false,
+        cron: false,
+        smart_approvals: false,
+        plan_mode: false,
+        sandbox_gvisor: false,
+        sandbox_lxc: false,
+        mcp_elicitation: false,
+        model_overrides: false,
+        max_output_tokens: null,
+    };
+}
+// --- WebMCP Detection --------------------------------------------------------
+/**
+ * Detect whether Chrome DevTools MCP is available.
+ *
+ * Detection waterfall (highest to lowest priority):
+ *   1. Config override: .planning/config.json `webmcp.enabled` field
+ *   2. Environment variables: CHROME_DEVTOOLS_MCP, WEBMCP_AVAILABLE
+ *   3. Claude Code MCP settings: ~/.claude.json `mcpServers` key
+ *   4. Default: not available
+ *
+ * @param cwd - Absolute path to the project root directory used for config-based detection
+ * @returns A WebMcpResult indicating availability, the detection source, and an optional reason when unavailable
+ */
+function detectWebMcp(cwd) {
+    // Step 1: Config override (highest priority)
+    const config = readConfig(cwd);
+    if (config && config.webmcp && typeof config.webmcp === 'object') {
+        const webmcp = config.webmcp;
+        if (typeof webmcp.enabled === 'boolean') {
+            if (webmcp.enabled) {
+                return { available: true, source: 'config' };
+            }
+            return {
+                available: false,
+                source: 'config',
+                reason: 'Disabled via config',
+            };
+        }
+    }
+    // Step 2: Environment variable check
+    const chromeDevToolsMcp = process.env.CHROME_DEVTOOLS_MCP;
+    const webmcpAvailable = process.env.WEBMCP_AVAILABLE;
+    if (chromeDevToolsMcp !== undefined) {
+        if (chromeDevToolsMcp === 'true' || chromeDevToolsMcp === '1') {
+            return { available: true, source: 'env' };
+        }
+        if (chromeDevToolsMcp === 'false' || chromeDevToolsMcp === '0') {
+            return {
+                available: false,
+                source: 'env',
+                reason: 'Disabled via environment variable',
+            };
+        }
+    }
+    if (webmcpAvailable !== undefined) {
+        if (webmcpAvailable === 'true' || webmcpAvailable === '1') {
+            return { available: true, source: 'env' };
+        }
+        if (webmcpAvailable === 'false' || webmcpAvailable === '0') {
+            return {
+                available: false,
+                source: 'env',
+                reason: 'Disabled via environment variable',
+            };
+        }
+    }
+    // Step 3: Claude Code MCP settings check (~/.claude.json)
+    try {
+        const homeDir = os.homedir();
+        const claudeConfigPath = path.join(homeDir, '.claude.json');
+        const raw = fs.readFileSync(claudeConfigPath, 'utf-8');
+        const claudeConfig = JSON.parse(raw);
+        if (claudeConfig && claudeConfig.mcpServers) {
+            const serverNames = Object.keys(claudeConfig.mcpServers);
+            const hasBrowserMcp = serverNames.some((name) => /chrome|devtools|playwright|browser/i.test(name));
+            if (hasBrowserMcp) {
+                return { available: true, source: 'mcp-config' };
+            }
+        }
+    }
+    catch {
+        // ~/.claude.json not found or malformed -- continue to default
+    }
+    // Step 4: Default
+    return {
+        available: false,
+        source: 'default',
+        reason: 'Chrome DevTools MCP not detected in config, environment, or MCP server settings',
+    };
+}
+// --- Playwright Detection ----------------------------------------------------
+/**
+ * Detect whether Playwright MCP is available.
+ *
+ * Detection waterfall (highest to lowest priority):
+ *   1. Config override: .planning/config.json `playwright.enabled` field
+ *   2. Environment variable: PLAYWRIGHT_AVAILABLE
+ *   3. Claude Code MCP settings: ~/.claude.json `mcpServers` key (playwright name match)
+ *   4. Default: not available
+ *
+ * Mirrors the detectWebMcp() pattern exactly — same try/catch around ~/.claude.json,
+ * same config reading via readConfig(cwd), same env var parsing.
+ *
+ * @param cwd - Absolute path to the project root directory used for config-based detection
+ * @returns A PlaywrightResult indicating availability, the detection source, and an optional reason when unavailable
+ */
+function detectPlaywright(cwd) {
+    // Step 1: Config override (highest priority)
+    const config = readConfig(cwd);
+    if (config && config.playwright && typeof config.playwright === 'object') {
+        const playwright = config.playwright;
+        if (typeof playwright.enabled === 'boolean') {
+            if (playwright.enabled) {
+                return { available: true, source: 'config' };
+            }
+            return {
+                available: false,
+                source: 'config',
+                reason: 'Disabled via config',
+            };
+        }
+    }
+    // Step 2: Environment variable check
+    const playwrightAvailable = process.env.PLAYWRIGHT_AVAILABLE;
+    if (playwrightAvailable !== undefined) {
+        if (playwrightAvailable === 'true' || playwrightAvailable === '1') {
+            return { available: true, source: 'env' };
+        }
+        if (playwrightAvailable === 'false' || playwrightAvailable === '0') {
+            return {
+                available: false,
+                source: 'env',
+                reason: 'Disabled via environment variable',
+            };
+        }
+    }
+    // Step 3: Claude Code MCP settings check (~/.claude.json)
+    try {
+        const homeDir = os.homedir();
+        const claudeConfigPath = path.join(homeDir, '.claude.json');
+        const raw = fs.readFileSync(claudeConfigPath, 'utf-8');
+        const claudeConfig = JSON.parse(raw);
+        if (claudeConfig && claudeConfig.mcpServers) {
+            const serverNames = Object.keys(claudeConfig.mcpServers);
+            const hasPlaywrightMcp = serverNames.some((name) => /playwright/i.test(name));
+            if (hasPlaywrightMcp) {
+                return { available: true, source: 'mcp-config' };
+            }
+        }
+    }
+    catch {
+        // ~/.claude.json not found or malformed -- continue to default
+    }
+    // Step 4: Default
+    return {
+        available: false,
+        source: 'default',
+        reason: 'Playwright MCP not detected in config, environment, or MCP server settings',
+    };
+}
+let _availabilityCache = null;
+const AVAILABILITY_CACHE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Dispatchable backends — the four CLIs that discussion.ts can spawn directly.
+ * Meta-backends (overstory, superpowers, grd) are probed as unavailable.
+ */
+const DISPATCHABLE_BACKENDS = ['claude', 'codex', 'gemini', 'opencode'];
+/**
+ * Environment variable that controls the config directory for each backend CLI.
+ * When set, the CLI uses the specified directory for auth/credentials instead of default.
+ */
+const BACKEND_CONFIG_ENV = {
+    claude: 'CLAUDE_CONFIG_DIR',
+    codex: 'CODEX_HOME',
+    gemini: 'GEMINI_CLI_HOME',
+    opencode: 'OPENCODE_CONFIG_DIR',
+};
+/**
+ * Files that prove a config directory has valid auth/credentials for a backend.
+ * Must be actual credential files, not files created by a bare first-run.
+ *
+ * Paths are relative to the config dir. Use nested paths for backends that
+ * store auth in a subdirectory (e.g. gemini stores creds in <dir>/.gemini/).
+ */
+const BACKEND_AUTH_MARKERS = {
+    claude: ['credentials.json', '.credentials.json', 'settings.json'],
+    codex: ['auth.json'],
+    gemini: ['.gemini/oauth_creds.json', '.gemini/google_accounts.json'],
+    opencode: ['auth.json', 'config.json'],
+};
+/** Cached config dir discovery result. */
+let _configDirCache = null;
+/**
+ * Discover the actual config directory for each backend by scanning the home
+ * directory for directories matching ~/.<backend>* that contain auth marker files.
+ *
+ * Priority:
+ * 1. Current env var (e.g. CLAUDE_CONFIG_DIR already set)
+ * 2. First ~/.<backend>-* directory containing an auth marker file
+ * 3. Default ~/.<backend> if it contains an auth marker file
+ * 4. null (no config dir found — use backend's default)
+ */
+function discoverBackendConfigDirs() {
+    if (_configDirCache)
+        return _configDirCache;
+    const homeDir = os.homedir();
+    const result = {};
+    for (const backend of DISPATCHABLE_BACKENDS) {
+        const envVar = BACKEND_CONFIG_ENV[backend];
+        const markers = BACKEND_AUTH_MARKERS[backend];
+        // 1. Check if env var is already set
+        if (envVar && process.env[envVar]) {
+            result[backend] = process.env[envVar];
+            continue;
+        }
+        // 2. Scan home directory for matching config dirs
+        let found = null;
+        try {
+            const entries = fs.readdirSync(homeDir);
+            // Collect candidates: ~/.<backend>-* first (custom profiles), then ~/.<backend> (default)
+            const profileDirs = entries
+                .filter((e) => e.startsWith(`.${backend}-`))
+                .sort();
+            const defaultDir = entries.filter((e) => e === `.${backend}`);
+            const candidates = [...profileDirs, ...defaultDir]
+                .map((e) => path.join(homeDir, e))
+                .filter((p) => {
+                try {
+                    return fs.statSync(p).isDirectory();
+                }
+                catch {
+                    return false;
+                }
+            });
+            // Check each candidate for auth marker files
+            for (const candidate of candidates) {
+                const hasAuth = markers.some((marker) => {
+                    try {
+                        return fs.statSync(path.join(candidate, marker)).isFile();
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                if (hasAuth) {
+                    found = candidate;
+                    break;
+                }
+            }
+        }
+        catch {
+            // Home dir not readable — skip
+        }
+        result[backend] = found;
+    }
+    _configDirCache = result;
+    return result;
+}
+/**
+ * Clear the config dir discovery cache. Exported for testing.
+ */
+function clearConfigDirCache() {
+    _configDirCache = null;
+}
+/**
+ * Build the environment variables needed to run a backend CLI with the correct
+ * config directory. Returns a copy of process.env with the override applied.
+ */
+function buildBackendEnv(backend) {
+    const env = { ...process.env };
+    // Strip Claude session env vars so subprocess doesn't detect nested invocation
+    for (const key of Object.keys(env)) {
+        if (key === 'CLAUDECODE' || key.startsWith('CLAUDE_CODE_') || key.startsWith('CLAUDECODE_')) {
+            delete env[key];
+        }
+    }
+    const configDirs = discoverBackendConfigDirs();
+    const configDir = configDirs[backend];
+    if (!configDir)
+        return env;
+    const envVar = BACKEND_CONFIG_ENV[backend];
+    if (!envVar)
+        return env;
+    return { ...env, [envVar]: configDir };
+}
+/**
+ * Probe which AI CLI backends are available on PATH.
+ *
+ * For each of the four dispatchable backends (claude, codex, gemini, opencode),
+ * runs `<binary> --version` with a 5-second timeout. Success means available.
+ * Meta-backends (overstory, superpowers, grd) are always marked unavailable here.
+ *
+ * Result is cached for 5 minutes (AVAILABILITY_CACHE_TTL_MS). Call
+ * clearAvailabilityCache() to force re-detection in tests.
+ *
+ * @param cwd - Optional working directory for subprocess (defaults to process.cwd())
+ * @returns A map of BackendId to BackendAvailability for all known backends
+ */
+function detectAvailableBackends(cwd) {
+    const now = Date.now();
+    if (_availabilityCache && now - _availabilityCache.ts < AVAILABILITY_CACHE_TTL_MS) {
+        return _availabilityCache.result;
+    }
+    const effectiveCwd = cwd || process.cwd();
+    const unavailable = { available: false, version: null };
+    const probeCfg = readConfig(effectiveCwd);
+    const probeTimeouts = probeCfg?.timeouts;
+    const probeTimeout = typeof probeTimeouts?.backend_probe_ms === 'number' ? probeTimeouts.backend_probe_ms : 5000;
+    const result = {
+        claude: unavailable,
+        codex: unavailable,
+        gemini: unavailable,
+        opencode: unavailable,
+        overstory: unavailable,
+        superpowers: unavailable,
+        grd: unavailable,
+    };
+    for (const backend of DISPATCHABLE_BACKENDS) {
+        try {
+            const stdout = execFileSync(backend, ['--version'], {
+                cwd: effectiveCwd,
+                timeout: probeTimeout,
+                encoding: 'utf-8',
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: buildBackendEnv(backend),
+            });
+            result[backend] = {
+                available: true,
+                version: stdout.trim().split('\n')[0] || null,
+            };
+        }
+        catch {
+            result[backend] = { available: false, version: null };
+        }
+    }
+    _availabilityCache = { result, ts: now };
+    return result;
+}
+/**
+ * Clear the availability detection cache. Exported for testing.
+ */
+function clearAvailabilityCache() {
+    _availabilityCache = null;
+}
+const _TIER_ORDER = ['opus', 'sonnet', 'haiku'];
+/**
+ * Looks up how many tiers to downgrade given the profile, pressure,
+ * and complexity. Returns 0, 1, or 2. Pure function — table-driven.
+ */
+function _lookupDowngradeCount(profile, pressure, complexity) {
+    // quality: only downgrade on critical pressure
+    if (profile === 'quality') {
+        if (pressure === 'critical')
+            return 1;
+        return 0;
+    }
+    // balanced: moderate adaptive downgrade
+    if (profile === 'balanced') {
+        if (pressure === 'none') {
+            if (complexity === 'low')
+                return 1;
+            return 0;
+        }
+        if (pressure === 'warning') {
+            if (complexity === 'high')
+                return 0;
+            return 1;
+        }
+        if (pressure === 'high') {
+            if (complexity === 'high')
+                return 0;
+            if (complexity === 'medium')
+                return 1;
+            return 2; // low
+        }
+        if (pressure === 'critical') {
+            if (complexity === 'high')
+                return 1;
+            return 2;
+        }
+    }
+    // frugal: aggressive downgrade
+    if (profile === 'frugal') {
+        if (pressure === 'none') {
+            if (complexity === 'high')
+                return 0;
+            return 1; // medium or low
+        }
+        if (pressure === 'warning') {
+            if (complexity === 'low')
+                return 2;
+            return 1;
+        }
+        // high or critical
+        return 2;
+    }
+    return 0;
+}
+/**
+ * Applies a downgrade count to a base tier, floored at the lowest tier.
+ * Returns the base tier unchanged if it's not in _TIER_ORDER (passthrough).
+ */
+function _applyDowngrade(baseTier, count) {
+    const baseIndex = _TIER_ORDER.indexOf(baseTier);
+    if (baseIndex === -1)
+        return baseTier;
+    const targetIndex = Math.min(baseIndex + count, _TIER_ORDER.length - 1);
+    return _TIER_ORDER[targetIndex];
+}
+/**
+ * Applies an upgrade count to a base tier, capped at the strongest tier.
+ * Symmetric to _applyDowngrade. Used for verify-fail retry escalation
+ * (Tier-2 #5 of the Ouroboros integration) — when a dispatch is a retry
+ * after a verification failure, the agent runs at a stronger tier than
+ * the base, capped at opus. Returns the base tier unchanged if it's not
+ * in _TIER_ORDER (passthrough).
+ *
+ * Note: _TIER_ORDER is ordered strongest-to-weakest (opus, sonnet, haiku),
+ * so "upgrade" decreases the index.
+ */
+function _applyUpgrade(baseTier, count) {
+    const baseIndex = _TIER_ORDER.indexOf(baseTier);
+    if (baseIndex === -1)
+        return baseTier;
+    const targetIndex = Math.max(baseIndex - count, 0);
+    return _TIER_ORDER[targetIndex];
+}
+/**
+ * Computes the effective model tier for an agent dispatch given the
+ * base tier (from MODEL_PROFILES), the user's token_profile preference,
+ * the current budget pressure level, and the task's complexity level.
+ *
+ * Pure function. Returns a possibly-downgraded ModelTier. The decision
+ * matrix is documented in the spec and implemented in _lookupDowngradeCount.
+ */
+function computeEffectiveModelTier(opts) {
+    const count = _lookupDowngradeCount(opts.tokenProfile, opts.pressure, opts.complexity);
+    return _applyDowngrade(opts.baseTier, count);
+}
+const { estimateComplexity } = require('./complexity');
+const { computeBudgetPressureLevel, logPressureTransition } = require('./scheduler');
+/**
+ * Computes the effective model tier for an agent dispatch by running
+ * the Spec 4 chain: estimateComplexity → computeBudgetPressureLevel →
+ * computeEffectiveModelTier. Returns the tier to pass to
+ * resolveModelForAgent as effectiveTierOverride.
+ *
+ * When scheduler/schedulerConfig/superpowersConfig are null/undefined,
+ * returns the base tier unchanged (preserving pre-Spec-4 behavior).
+ *
+ * @param opts.agentType - Agent type key (e.g. 'grd-executor')
+ * @param opts.prompt - The prompt string (used for promptLength)
+ * @param opts.config - GrdConfig with model_profile and token_profile fields
+ * @param opts.scheduler - Scheduler instance or null when not configured
+ * @param opts.schedulerConfig - Scheduler configuration from config.scheduler
+ * @param opts.superpowersConfig - Superpowers config from config.superpowers
+ * @param opts.modelProfiles - MODEL_PROFILES table (passed in to avoid circular dep)
+ * @returns Effective model tier for this dispatch
+ */
+function getEffectiveTierForDispatch(opts) {
+    const profile = opts.config.model_profile || 'balanced';
+    const agentEntry = opts.modelProfiles[opts.agentType];
+    const baseTier = ((agentEntry && agentEntry[profile]) || 'sonnet');
+    const retryAttempt = opts.retry_attempt && opts.retry_attempt > 0 ? opts.retry_attempt : 0;
+    if (!opts.scheduler || !opts.schedulerConfig || !opts.superpowersConfig) {
+        // No adaptive chain available — apply retry escalation directly to
+        // the base tier so retry_attempt still has an effect.
+        return retryAttempt > 0 ? _applyUpgrade(baseTier, retryAttempt) : baseTier;
+    }
+    const states = opts.scheduler.getStates();
+    // Collect recent samples from all priority accounts (most recent first).
+    // Spec 4 M2: collect agentType so we can prefer same-agent samples for
+    // complexity estimation. Old samples without agentType participate in the
+    // global pool only.
+    let recentSamples;
+    const allSamples = [];
+    for (const backend of opts.schedulerConfig.backend_priority) {
+        const backendAccounts = opts.superpowersConfig.accounts[backend] || [];
+        for (const account of backendAccounts) {
+            const stateKey = `${backend}/${account.config_dir}`;
+            const state = states.get(stateKey);
+            if (!state)
+                continue;
+            for (const sample of state.samples) {
+                allSamples.push({
+                    duration: sample.duration,
+                    tokenEstimate: sample.tokenEstimate,
+                    timestamp: sample.timestamp,
+                    agentType: sample.agentType,
+                });
+            }
+        }
+    }
+    if (allSamples.length >= 3) {
+        // Spec 4 M2: prefer per-agent samples if we have enough, else fall back
+        // to the global tail. Old samples without agentType participate in the
+        // global pool only.
+        const ownAgentSamples = allSamples.filter((s) => s.agentType === opts.agentType);
+        const samplesToUse = ownAgentSamples.length >= 3 ? ownAgentSamples : allSamples;
+        // Sort by timestamp descending, take up to 10 most recent
+        samplesToUse.sort((a, b) => b.timestamp - a.timestamp);
+        recentSamples = samplesToUse.slice(0, 10).map((s) => ({
+            duration: s.duration,
+            tokenEstimate: s.tokenEstimate,
+        }));
+    }
+    const complexity = estimateComplexity({
+        agentType: opts.agentType,
+        promptLength: opts.prompt.length,
+        recentSamples,
+        baselineOverride: opts.config.agent_complexity_overrides?.[opts.agentType],
+        heuristics: opts.config.complexity_heuristics,
+    });
+    const pressure = computeBudgetPressureLevel(states, opts.schedulerConfig.backend_priority, opts.superpowersConfig.accounts, opts.schedulerConfig.budget_pressure_thresholds);
+    const tokenProfile = opts.config.token_profile || 'balanced';
+    const adaptiveTier = computeEffectiveModelTier({
+        baseTier,
+        tokenProfile,
+        pressure,
+        complexity,
+    });
+    // Verify-fail retry escalation (Tier-2 #5). Applied AFTER adaptive
+    // downgrade so that a retry escalates from whatever tier the adaptive
+    // chain landed on, not from the original baseTier. Capped at opus.
+    const effectiveTier = retryAttempt > 0 ? _applyUpgrade(adaptiveTier, retryAttempt) : adaptiveTier;
+    // Spec 4 Goal #7: log on pressure transitions only (O3: use per-scheduler
+    // sessionKey instead of process.pid to avoid shared state across multiple
+    // createScheduler calls in the same process).
+    logPressureTransition(opts.scheduler.sessionKey, pressure, opts.agentType, baseTier, effectiveTier);
+    return effectiveTier;
+}
+// --- Exports -----------------------------------------------------------------
+module.exports = {
+    VALID_BACKENDS,
+    DEFAULT_BACKEND_MODELS,
+    BACKEND_CAPABILITIES,
+    EFFORT_PROFILES,
+    _applyUpgrade,
+    detectBackend,
+    resolveBackendModel,
+    resolveEffortLevel,
+    getBackendCapabilities,
+    parseOpenCodeModels,
+    detectModels,
+    getCachedModels,
+    clearModelCache,
+    detectWebMcp,
+    detectPlaywright,
+    detectAvailableBackends,
+    clearAvailabilityCache,
+    discoverBackendConfigDirs,
+    clearConfigDirCache,
+    buildBackendEnv,
+    BACKEND_CONFIG_ENV,
+    readConfig,
+    computeEffectiveModelTier,
+    getEffectiveTierForDispatch,
+};
+//# sourceMappingURL=backend.js.map