@jstn-sdk/rcs 0.1.0

package/dist/cli/doctor.js

@@ -0,0 +1,1072 @@
+/**
+ * rcs doctor - Validate Roblox Creator Skills installation
+ */
+import { existsSync } from "fs";
+import { readdir, readFile } from "fs/promises";
+import { join } from "path";
+import { codexHome, codexConfigPath, codexPromptsDir, userSkillsDir, projectSkillsDir, rcsStateDir, detectLegacySkillRootOverlap, } from "../utils/paths.js";
+import { classifySpawnError, spawnPlatformCommandSync, } from "../utils/platform-command.js";
+import { getCatalogExpectations } from "./catalog-contract.js";
+import { parse as parseToml } from "@iarna/toml";
+import { getBuiltinExploreHarnessUnsupportedReason, resolvePackagedExploreHarnessCommand, EXPLORE_BIN_ENV, } from "./explore.js";
+import { getPackageRoot } from "../utils/package.js";
+import { hasLegacyRcsTeamRunTable, getModelContextRecommendation, } from "../config/generator.js";
+import { getMissingManagedCodexHookEvents } from "../config/codex-hooks.js";
+import { RCS_FIRST_PARTY_MCP_SERVER_NAMES } from "../config/rcs-first-party-mcp.js";
+import { getDefaultBridge, isBridgeEnabled } from "../runtime/bridge.js";
+import { RCS_EXPLORE_CMD_ENV, isExploreCommandRoutingEnabled, } from "../hooks/explore-routing.js";
+import { isLeaderRuntimeStale } from "../team/leader-activity.js";
+import { triagePrompt } from "../hooks/triage-heuristic.js";
+import { readTriageConfig } from "../hooks/triage-config.js";
+import { readPersistedSetupPreferences, } from "./setup-preferences.js";
+import { RCS_LOCAL_MARKETPLACE_NAME, resolvePackagedRcsMarketplace, } from "./plugin-marketplace.js";
+async function resolveDoctorScope(cwd) {
+    const persisted = await readPersistedSetupPreferences(cwd);
+    if (persisted?.scope) {
+        return {
+            scope: persisted.scope,
+            source: "persisted",
+            installMode: persisted.installMode,
+        };
+    }
+    return { scope: "user", source: "default" };
+}
+function resolveDoctorPaths(cwd, scope) {
+    if (scope === "project") {
+        const codexHomeDir = join(cwd, ".codex");
+        return {
+            codexHomeDir,
+            configPath: join(codexHomeDir, "config.toml"),
+            hooksPath: join(codexHomeDir, "hooks.json"),
+            promptsDir: join(codexHomeDir, "prompts"),
+            skillsDir: projectSkillsDir(cwd),
+            stateDir: rcsStateDir(cwd),
+        };
+    }
+    return {
+        codexHomeDir: codexHome(),
+        configPath: codexConfigPath(),
+        hooksPath: join(codexHome(), "hooks.json"),
+        promptsDir: codexPromptsDir(),
+        skillsDir: userSkillsDir(),
+        stateDir: rcsStateDir(cwd),
+    };
+}
+export async function doctor(options = {}) {
+    if (options.team) {
+        await doctorTeam();
+        return;
+    }
+    const cwd = process.cwd();
+    const scopeResolution = await resolveDoctorScope(cwd);
+    const paths = resolveDoctorPaths(cwd, scopeResolution.scope);
+    const scopeSourceMessage = scopeResolution.source === "persisted"
+        ? " (from .rcs/setup-scope.json)"
+        : "";
+    console.log("RCS doctor");
+    console.log("==================\n");
+    console.log(`Resolved setup scope: ${scopeResolution.scope}${scopeSourceMessage}`);
+    if (scopeResolution.installMode) {
+        console.log(`Resolved setup install mode: ${scopeResolution.installMode}${scopeSourceMessage}`);
+    }
+    console.log();
+    const checks = [];
+    // Check 1: Codex CLI installed
+    checks.push(checkCodexCli());
+    // Check 2: Node.js version
+    checks.push(checkNodeVersion());
+    // Check 2.5: Explore harness readiness
+    checks.push(checkExploreHarness());
+    // Check 3: Codex home directory
+    checks.push(checkDirectory("Codex home", paths.codexHomeDir));
+    // Check 4: Config file
+    checks.push(await checkConfig(paths.configPath));
+    // Check 4.1: Model context recommendation
+    const contextRecommendationCheck = await checkModelContextRecommendation(paths.configPath);
+    if (contextRecommendationCheck)
+        checks.push(contextRecommendationCheck);
+    // Check 4.25: Native hooks coverage
+    checks.push(await checkNativeHooks(paths.hooksPath, paths.configPath));
+    // Check 4.5: Explore routing default
+    checks.push(await checkExploreRouting(paths.configPath));
+    // Check 5: Prompts installed
+    checks.push(await checkPrompts(paths.promptsDir, scopeResolution.installMode));
+    // Check 6: Skills installed
+    checks.push(await checkSkills(paths, scopeResolution.installMode));
+    // Check 6.5: Legacy/current skill-root overlap
+    if (scopeResolution.scope === "user") {
+        checks.push(await checkLegacySkillRootOverlap());
+    }
+    // Check 7: AGENTS.md in project
+    checks.push(checkAgentsMd(scopeResolution.scope, paths.codexHomeDir, scopeResolution.installMode));
+    // Check 8: State directory
+    checks.push(checkDirectory("State dir", paths.stateDir));
+    // Check 9: MCP servers configured
+    checks.push(await checkMcpServers(paths.configPath, scopeResolution.installMode));
+    // Check 10: Prompt triage
+    checks.push(checkPromptTriage());
+    // Print results
+    let passCount = 0;
+    let warnCount = 0;
+    let failCount = 0;
+    for (const check of checks) {
+        const icon = check.status === "pass"
+            ? "[OK]"
+            : check.status === "warn"
+                ? "[!!]"
+                : "[XX]";
+        console.log(`  ${icon} ${check.name}: ${check.message}`);
+        if (check.status === "pass")
+            passCount++;
+        else if (check.status === "warn")
+            warnCount++;
+        else
+            failCount++;
+    }
+    console.log(`\nResults: ${passCount} passed, ${warnCount} warnings, ${failCount} failed`);
+    if (failCount > 0) {
+        console.log('\nRun "rcs setup" to fix installation issues.');
+    }
+    else if (warnCount > 0) {
+        console.log('\nRun "rcs setup --force" to refresh all components.');
+    }
+    else {
+        console.log("\nAll checks passed! RCS is ready.");
+    }
+}
+async function doctorTeam() {
+    console.log("RCS doctor --team");
+    console.log("=========================\n");
+    const issues = await collectTeamDoctorIssues(process.cwd());
+    if (issues.length === 0) {
+        console.log("  [OK] team diagnostics: no issues");
+        console.log("\nAll team checks passed.");
+        return;
+    }
+    const failureCount = issues.filter((issue) => issue.severity === "fail").length;
+    const warningCount = issues.length - failureCount;
+    for (const issue of issues) {
+        const icon = issue.severity === "warn" ? "[!!]" : "[XX]";
+        console.log(`  ${icon} ${issue.code}: ${issue.message}`);
+    }
+    console.log(`\nResults: ${warningCount} warnings, ${failureCount} failed`);
+    // Ensure non-zero exit for `rcs doctor --team` failures.
+    if (failureCount > 0)
+        process.exitCode = 1;
+}
+async function collectTeamDoctorIssues(cwd) {
+    const issues = [];
+    const stateDir = rcsStateDir(cwd);
+    const teamsRoot = join(stateDir, "team");
+    const nowMs = Date.now();
+    const lagThresholdMs = 60_000;
+    const shutdownThresholdMs = 30_000;
+    const leaderStaleThresholdMs = 180_000;
+    // Rust-first: if the runtime bridge is enabled, use Rust-authored readiness
+    // and authority as the semantic truth source for runtime health.
+    if (isBridgeEnabled()) {
+        const bridge = getDefaultBridge(stateDir);
+        const readiness = bridge.readReadiness();
+        const authority = bridge.readAuthority();
+        if (readiness && !readiness.ready) {
+            for (const reason of readiness.reasons) {
+                issues.push({
+                    code: "resume_blocker",
+                    message: `runtime not ready: ${reason}`,
+                    severity: "fail",
+                });
+            }
+        }
+        if (authority?.stale) {
+            issues.push({
+                code: "stale_leader",
+                message: `authority stale (owner: ${authority.owner ?? "unknown"}): ${authority.stale_reason ?? "unknown reason"}`,
+                severity: "fail",
+            });
+        }
+    }
+    const teamDirs = [];
+    if (existsSync(teamsRoot)) {
+        const entries = await readdir(teamsRoot, { withFileTypes: true });
+        for (const e of entries) {
+            if (e.isDirectory())
+                teamDirs.push(e.name);
+        }
+    }
+    const tmuxSessions = listTeamTmuxSessions();
+    const tmuxUnavailable = tmuxSessions === null;
+    const knownTeamSessions = new Set();
+    for (const teamName of teamDirs) {
+        const teamDir = join(teamsRoot, teamName);
+        const manifestPath = join(teamDir, "manifest.v2.json");
+        const configPath = join(teamDir, "config.json");
+        let tmuxSession = `rcs-team-${teamName}`;
+        let workerLaunchMode = "interactive";
+        let promptWorkers = [];
+        if (existsSync(manifestPath)) {
+            try {
+                const raw = await readFile(manifestPath, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (typeof parsed.tmux_session === "string" &&
+                    parsed.tmux_session.trim() !== "") {
+                    tmuxSession = parsed.tmux_session;
+                }
+                if (parsed.policy?.worker_launch_mode === "prompt") {
+                    workerLaunchMode = "prompt";
+                }
+                if (Array.isArray(parsed.workers))
+                    promptWorkers = parsed.workers;
+            }
+            catch {
+                // ignore malformed manifest
+            }
+        }
+        else if (existsSync(configPath)) {
+            try {
+                const raw = await readFile(configPath, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (typeof parsed.tmux_session === "string" &&
+                    parsed.tmux_session.trim() !== "") {
+                    tmuxSession = parsed.tmux_session;
+                }
+                if (parsed.worker_launch_mode === "prompt") {
+                    workerLaunchMode = "prompt";
+                }
+                if (Array.isArray(parsed.workers))
+                    promptWorkers = parsed.workers;
+            }
+            catch {
+                // ignore malformed config
+            }
+        }
+        knownTeamSessions.add(tmuxSession);
+        if (workerLaunchMode === "prompt") {
+            for (const worker of promptWorkers) {
+                const pid = worker.pid ?? 0;
+                if (Number.isFinite(pid) && pid > 0 && isPidAlive(pid)) {
+                    issues.push({
+                        code: "prompt_resume_unavailable",
+                        message: `${teamName}/${worker.name ?? "unknown"} pid ${pid} appears to be running, but doctor cannot verify that the PID still belongs to the original prompt-mode worker after CLI restart; if this is the original worker, shut it down or start a new team`,
+                        severity: "warn",
+                    });
+                }
+            }
+        }
+        else if (!tmuxUnavailable && !tmuxSessions.has(tmuxSession)) {
+            // resume_blocker: only meaningful if tmux is available to query for interactive teams.
+            issues.push({
+                code: "resume_blocker",
+                message: `${teamName} references missing tmux session ${tmuxSession}`,
+                severity: "fail",
+            });
+        }
+        // delayed_status_lag + slow_shutdown checks
+        const workersRoot = join(teamDir, "workers");
+        if (!existsSync(workersRoot))
+            continue;
+        const workers = await readdir(workersRoot, { withFileTypes: true });
+        for (const worker of workers) {
+            if (!worker.isDirectory())
+                continue;
+            const workerDir = join(workersRoot, worker.name);
+            const statusPath = join(workerDir, "status.json");
+            const heartbeatPath = join(workerDir, "heartbeat.json");
+            const shutdownReqPath = join(workerDir, "shutdown-request.json");
+            const shutdownAckPath = join(workerDir, "shutdown-ack.json");
+            if (existsSync(statusPath) && existsSync(heartbeatPath)) {
+                try {
+                    const [statusRaw, hbRaw] = await Promise.all([
+                        readFile(statusPath, "utf-8"),
+                        readFile(heartbeatPath, "utf-8"),
+                    ]);
+                    const status = JSON.parse(statusRaw);
+                    const hb = JSON.parse(hbRaw);
+                    const lastTurnMs = hb.last_turn_at
+                        ? Date.parse(hb.last_turn_at)
+                        : NaN;
+                    if (status.state === "working" &&
+                        Number.isFinite(lastTurnMs) &&
+                        nowMs - lastTurnMs > lagThresholdMs) {
+                        issues.push({
+                            code: "delayed_status_lag",
+                            message: `${teamName}/${worker.name} working with stale heartbeat`,
+                            severity: "fail",
+                        });
+                    }
+                }
+                catch {
+                    // ignore malformed files
+                }
+            }
+            if (existsSync(shutdownReqPath) && !existsSync(shutdownAckPath)) {
+                try {
+                    const reqRaw = await readFile(shutdownReqPath, "utf-8");
+                    const req = JSON.parse(reqRaw);
+                    const reqMs = req.requested_at ? Date.parse(req.requested_at) : NaN;
+                    if (Number.isFinite(reqMs) && nowMs - reqMs > shutdownThresholdMs) {
+                        issues.push({
+                            code: "slow_shutdown",
+                            message: `${teamName}/${worker.name} has stale shutdown request without ack`,
+                            severity: "fail",
+                        });
+                    }
+                }
+                catch {
+                    // ignore malformed files
+                }
+            }
+        }
+    }
+    // stale_leader: team has active workers but leader has no recent activity
+    const hudStatePath = join(stateDir, "hud-state.json");
+    const leaderActivityPath = join(stateDir, "leader-runtime-activity.json");
+    if ((existsSync(hudStatePath) || existsSync(leaderActivityPath)) &&
+        teamDirs.length > 0) {
+        try {
+            const leaderIsStale = await isLeaderRuntimeStale(stateDir, leaderStaleThresholdMs, nowMs);
+            if (leaderIsStale && !tmuxUnavailable) {
+                // Check if any team tmux session has live worker panes
+                for (const teamName of teamDirs) {
+                    const session = knownTeamSessions.has(`rcs-team-${teamName}`)
+                        ? `rcs-team-${teamName}`
+                        : [...knownTeamSessions].find((s) => s.includes(teamName));
+                    if (!session || !tmuxSessions.has(session))
+                        continue;
+                    issues.push({
+                        code: "stale_leader",
+                        message: `${teamName} has active tmux session but leader has no recent activity`,
+                        severity: "fail",
+                    });
+                }
+            }
+        }
+        catch {
+            // ignore malformed HUD state
+        }
+    }
+    // orphan_tmux_session: session exists but no matching team state
+    if (!tmuxUnavailable) {
+        for (const session of tmuxSessions) {
+            if (!knownTeamSessions.has(session)) {
+                issues.push({
+                    code: "orphan_tmux_session",
+                    message: `${session} exists without matching team state (possibly external project)`,
+                    severity: "warn",
+                });
+            }
+        }
+    }
+    return dedupeIssues(issues);
+}
+function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'ESRCH')
+            return false;
+        return false;
+    }
+}
+function dedupeIssues(issues) {
+    const seen = new Set();
+    const out = [];
+    for (const issue of issues) {
+        const key = `${issue.code}:${issue.message}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(issue);
+    }
+    return out;
+}
+function listTeamTmuxSessions() {
+    const { result: res } = spawnPlatformCommandSync("tmux", ["list-sessions", "-F", "#{session_name}"], { encoding: "utf-8" });
+    if (res.error) {
+        // tmux binary unavailable or not executable.
+        return null;
+    }
+    if (res.status !== 0) {
+        const stderr = (res.stderr || "").toLowerCase();
+        // tmux installed but no server/session is running.
+        if (stderr.includes("no server running") ||
+            stderr.includes("failed to connect to server")) {
+            return new Set();
+        }
+        return null;
+    }
+    const sessions = (res.stdout || "")
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((s) => s.startsWith("rcs-team-"));
+    return new Set(sessions);
+}
+function checkCodexCli() {
+    const { result } = spawnPlatformCommandSync("codex", ["--version"], {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    if (result.error) {
+        const code = result.error.code;
+        const kind = classifySpawnError(result.error);
+        if (kind === "missing") {
+            return {
+                name: "Codex CLI",
+                status: "fail",
+                message: "not found - install from https://github.com/openai/codex",
+            };
+        }
+        if (kind === "blocked") {
+            return {
+                name: "Codex CLI",
+                status: "fail",
+                message: `found but could not be executed in this environment (${code || "blocked"})`,
+            };
+        }
+        return {
+            name: "Codex CLI",
+            status: "fail",
+            message: `probe failed - ${result.error.message}`,
+        };
+    }
+    if (result.status === 0) {
+        const version = (result.stdout || "").trim();
+        return {
+            name: "Codex CLI",
+            status: "pass",
+            message: `installed (${version})`,
+        };
+    }
+    const stderr = (result.stderr || "").trim();
+    return {
+        name: "Codex CLI",
+        status: "fail",
+        message: stderr !== ""
+            ? `probe failed - ${stderr}`
+            : `probe failed with exit ${result.status}`,
+    };
+}
+function checkNodeVersion() {
+    const major = parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    if (isNaN(major)) {
+        return {
+            name: "Node.js",
+            status: "fail",
+            message: `v${process.versions.node} (unable to parse major version)`,
+        };
+    }
+    if (major >= 20) {
+        return {
+            name: "Node.js",
+            status: "pass",
+            message: `v${process.versions.node}`,
+        };
+    }
+    return {
+        name: "Node.js",
+        status: "fail",
+        message: `v${process.versions.node} (need >= 20)`,
+    };
+}
+export function checkExploreHarness(platform = process.platform, env = process.env) {
+    const packageRoot = getPackageRoot();
+    const manifestPath = join(packageRoot, "crates", "rcs-explore", "Cargo.toml");
+    if (!existsSync(manifestPath)) {
+        return {
+            name: "Explore Harness",
+            status: "warn",
+            message: "Rust harness sources not found in this install (rcs explore unavailable until packaged or RCS_EXPLORE_BIN is set)",
+        };
+    }
+    const override = env[EXPLORE_BIN_ENV]?.trim();
+    if (override) {
+        const resolved = join(packageRoot, override);
+        if (existsSync(override) || existsSync(resolved)) {
+            return {
+                name: "Explore Harness",
+                status: "pass",
+                message: `${EXPLORE_BIN_ENV} configured (${override})`,
+            };
+        }
+        return {
+            name: "Explore Harness",
+            status: "warn",
+            message: `RCS_EXPLORE_BIN is set but path was not found (${override})`,
+        };
+    }
+    const unsupportedReason = getBuiltinExploreHarnessUnsupportedReason(platform, env);
+    if (unsupportedReason) {
+        return {
+            name: "Explore Harness",
+            status: "warn",
+            message: unsupportedReason,
+        };
+    }
+    const packaged = resolvePackagedExploreHarnessCommand(packageRoot);
+    if (packaged) {
+        return {
+            name: "Explore Harness",
+            status: "pass",
+            message: `ready (packaged native binary: ${packaged.command})`,
+        };
+    }
+    const { result } = spawnPlatformCommandSync("cargo", ["--version"], {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    if (result.error) {
+        const kind = classifySpawnError(result.error);
+        if (kind === "missing") {
+            return {
+                name: "Explore Harness",
+                status: "warn",
+                message: `Rust harness sources are packaged, but no compatible packaged prebuilt or cargo was found (install Rust or set ${EXPLORE_BIN_ENV} for rcs explore)`,
+            };
+        }
+        return {
+            name: "Explore Harness",
+            status: "warn",
+            message: `Rust harness sources are packaged, but cargo probe failed (${result.error.message})`,
+        };
+    }
+    if (result.status === 0) {
+        const version = (result.stdout || "").trim();
+        return {
+            name: "Explore Harness",
+            status: "pass",
+            message: `ready (${version || "cargo available"})`,
+        };
+    }
+    return {
+        name: "Explore Harness",
+        status: "warn",
+        message: `Rust harness sources are packaged, but cargo probe failed with exit ${result.status} (install Rust or set ${EXPLORE_BIN_ENV})`,
+    };
+}
+function checkDirectory(name, path) {
+    if (existsSync(path)) {
+        return { name, status: "pass", message: path };
+    }
+    return { name, status: "warn", message: `${path} (not created yet)` };
+}
+function validateToml(content) {
+    try {
+        parseToml(content);
+        return null;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        return "unknown TOML parse error";
+    }
+}
+async function checkConfig(configPath) {
+    if (!existsSync(configPath)) {
+        return { name: "Config", status: "warn", message: "config.toml not found" };
+    }
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const tomlError = validateToml(content);
+        if (tomlError) {
+            const hint = tomlError.includes("Can't redefine existing key") ||
+                tomlError.includes("duplicate") ||
+                tomlError.includes("[tui]")
+                ? "possible duplicate TOML table such as [tui]"
+                : "invalid TOML syntax";
+            return {
+                name: "Config",
+                status: "fail",
+                message: `invalid config.toml (${hint})`,
+            };
+        }
+        if (hasLegacyRcsTeamRunTable(content)) {
+            return {
+                name: "Config",
+                status: "warn",
+                message: 'retired [mcp_servers.rcs_team_run] table still present; run "rcs setup --force" to repair the config',
+            };
+        }
+        const hasRcsTomlSignals = content.includes("rcs_") || content.includes("roblox-ai-os-creator-skills");
+        if (hasRcsTomlSignals) {
+            return {
+                name: "Config",
+                status: "pass",
+                message: "config.toml has RCS entries",
+            };
+        }
+        return {
+            name: "Config",
+            status: "warn",
+            message: 'config.toml exists but no RCS entries yet (expected before first setup; run "rcs setup --force" once)',
+        };
+    }
+    catch {
+        return {
+            name: "Config",
+            status: "fail",
+            message: "cannot read config.toml",
+        };
+    }
+}
+function formatContextRecommendationWarning(configuredValues, recommendedContextWindow, recommendedAutoCompactLimit) {
+    return `${configuredValues.join(", ")} exceeds the RCS setup recommendation for gpt-5.5 (${recommendedContextWindow} / ${recommendedAutoCompactLimit}); doctor does not rewrite user config, so lower these values or verify your active Codex runtime/provider behavior if this customization is intentional`;
+}
+async function checkModelContextRecommendation(configPath) {
+    if (!existsSync(configPath))
+        return null;
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const parsed = parseToml(content);
+        const model = parsed.model;
+        if (typeof model !== "string")
+            return null;
+        const recommendation = getModelContextRecommendation(model);
+        if (!recommendation)
+            return null;
+        const configuredValues = [];
+        const contextWindow = parsed.model_context_window;
+        if (typeof contextWindow === "number" &&
+            contextWindow > recommendation.modelContextWindow) {
+            configuredValues.push(`model_context_window=${contextWindow}`);
+        }
+        const autoCompactLimit = parsed.model_auto_compact_token_limit;
+        if (typeof autoCompactLimit === "number" &&
+            autoCompactLimit > recommendation.modelAutoCompactTokenLimit) {
+            configuredValues.push(`model_auto_compact_token_limit=${autoCompactLimit}`);
+        }
+        if (configuredValues.length === 0)
+            return null;
+        return {
+            name: "Model context recommendation",
+            status: "warn",
+            message: formatContextRecommendationWarning(configuredValues, recommendation.modelContextWindow, recommendation.modelAutoCompactTokenLimit),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function checkExploreRouting(configPath) {
+    const envValue = process.env[RCS_EXPLORE_CMD_ENV];
+    if (typeof envValue === "string" &&
+        !isExploreCommandRoutingEnabled(process.env)) {
+        return {
+            name: "Explore routing",
+            status: "warn",
+            message: "disabled by environment override; enable with USE_RCS_EXPLORE_CMD=1 (or remove the explicit opt-out)",
+        };
+    }
+    if (!existsSync(configPath)) {
+        return {
+            name: "Explore routing",
+            status: "pass",
+            message: "enabled by default (config.toml not found yet)",
+        };
+    }
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const parsed = parseToml(content);
+        const configuredValue = parsed?.shell_environment_policy?.set?.USE_RCS_EXPLORE_CMD ??
+            parsed?.env?.USE_RCS_EXPLORE_CMD;
+        if (typeof configuredValue === "string" &&
+            !isExploreCommandRoutingEnabled({
+                USE_RCS_EXPLORE_CMD: configuredValue,
+            })) {
+            return {
+                name: "Explore routing",
+                status: "warn",
+                message: 'disabled in config.toml; set USE_RCS_EXPLORE_CMD = "1" under [shell_environment_policy.set] to restore default explore-first routing',
+            };
+        }
+        return {
+            name: "Explore routing",
+            status: "pass",
+            message: "enabled by default",
+        };
+    }
+    catch {
+        return {
+            name: "Explore routing",
+            status: "fail",
+            message: "cannot read config.toml for explore routing check",
+        };
+    }
+}
+async function checkNativeHooks(hooksPath, configPath) {
+    if (!existsSync(hooksPath)) {
+        if (existsSync(configPath)) {
+            try {
+                const configContent = await readFile(configPath, "utf-8");
+                const hasRcsTomlSignals = configContent.includes("rcs_") ||
+                    configContent.includes("roblox-ai-os-creator-skills");
+                if (hasRcsTomlSignals) {
+                    return {
+                        name: "Native hooks",
+                        status: "warn",
+                        message: 'hooks.json not found even though config.toml has RCS entries; run "rcs setup --force" to restore native hook coverage',
+                    };
+                }
+            }
+            catch {
+                // fall through to the neutral first-setup path when config cannot be read here;
+                // the dedicated config check will report read failures separately.
+            }
+        }
+        return {
+            name: "Native hooks",
+            status: "pass",
+            message: "hooks.json not found yet (expected before first setup)",
+        };
+    }
+    try {
+        const content = await readFile(hooksPath, "utf-8");
+        const missingEvents = getMissingManagedCodexHookEvents(content);
+        if (missingEvents === null) {
+            return {
+                name: "Native hooks",
+                status: "fail",
+                message: 'invalid hooks.json; Codex may skip RCS hook coverage until "rcs setup --force" repairs it',
+            };
+        }
+        if (missingEvents.length > 0) {
+            return {
+                name: "Native hooks",
+                status: "warn",
+                message: `hooks.json is missing RCS-managed coverage for ${missingEvents.join(", ")}; run "rcs setup --force" to restore native hooks`,
+            };
+        }
+        return {
+            name: "Native hooks",
+            status: "pass",
+            message: "hooks.json includes RCS-managed coverage for all native hook events",
+        };
+    }
+    catch {
+        return {
+            name: "Native hooks",
+            status: "fail",
+            message: "cannot read hooks.json",
+        };
+    }
+}
+async function checkPrompts(dir, installMode) {
+    if (installMode === "plugin") {
+        return {
+            name: "Prompts",
+            status: "pass",
+            message: "plugin mode intentionally omits setup-owned prompts; Codex plugin discovery supplies workflow surfaces",
+        };
+    }
+    const expectations = getCatalogExpectations();
+    if (!existsSync(dir)) {
+        return {
+            name: "Prompts",
+            status: "warn",
+            message: "prompts directory not found",
+        };
+    }
+    try {
+        const files = await readdir(dir);
+        const mdFiles = files.filter((f) => f.endsWith(".md"));
+        if (mdFiles.length >= expectations.promptMin) {
+            return {
+                name: "Prompts",
+                status: "pass",
+                message: `${mdFiles.length} agent prompts installed`,
+            };
+        }
+        return {
+            name: "Prompts",
+            status: "warn",
+            message: `${mdFiles.length} prompts (expected >= ${expectations.promptMin})`,
+        };
+    }
+    catch {
+        return {
+            name: "Prompts",
+            status: "fail",
+            message: "cannot read prompts directory",
+        };
+    }
+}
+async function checkLegacySkillRootOverlap() {
+    const overlap = await detectLegacySkillRootOverlap();
+    if (!overlap.legacyExists) {
+        return {
+            name: "Legacy skill roots",
+            status: "pass",
+            message: "no ~/.agents/skills overlap detected",
+        };
+    }
+    if (overlap.sameResolvedTarget) {
+        return {
+            name: "Legacy skill roots",
+            status: "pass",
+            message: `~/.agents/skills links to canonical ${overlap.canonicalDir}; treating both paths as one shared skill root`,
+        };
+    }
+    if (overlap.overlappingSkillNames.length === 0) {
+        return {
+            name: "Legacy skill roots",
+            status: "warn",
+            message: `legacy ~/.agents/skills still exists (${overlap.legacySkillCount} skills) alongside canonical ${overlap.canonicalDir}; remove or archive it if Codex shows duplicate entries`,
+        };
+    }
+    const mismatchMessage = overlap.mismatchedSkillNames.length > 0
+        ? `; ${overlap.mismatchedSkillNames.length} differ in SKILL.md content`
+        : "";
+    return {
+        name: "Legacy skill roots",
+        status: "warn",
+        message: `${overlap.overlappingSkillNames.length} overlapping skill names between ${overlap.canonicalDir} and ${overlap.legacyDir}${mismatchMessage}; Codex Enable/Disable Skills may show duplicates until ~/.agents/skills is cleaned up`,
+    };
+}
+function getParsedMarketplaceRegistration(content) {
+    const parsed = parseToml(content);
+    return parsed.marketplaces?.[RCS_LOCAL_MARKETPLACE_NAME] ?? null;
+}
+async function checkPluginMarketplaceRegistration(configPath) {
+    const packagedMarketplace = await resolvePackagedRcsMarketplace(getPackageRoot());
+    if (!packagedMarketplace) {
+        return {
+            name: "Skills",
+            status: "warn",
+            message: `plugin mode selected, but packaged ${RCS_LOCAL_MARKETPLACE_NAME} metadata was not found; reinstall @jstn-sdk/rcs or run from a package that includes plugins/`,
+        };
+    }
+    if (!existsSync(configPath)) {
+        return {
+            name: "Skills",
+            status: "warn",
+            message: `plugin mode selected, but ${RCS_LOCAL_MARKETPLACE_NAME} is not registered because config.toml is missing; run "rcs setup --plugin --force"`,
+        };
+    }
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const registration = getParsedMarketplaceRegistration(content);
+        if (!registration) {
+            return {
+                name: "Skills",
+                status: "warn",
+                message: `plugin mode selected, but Codex marketplace ${RCS_LOCAL_MARKETPLACE_NAME} is not registered; run "rcs setup --plugin --force"`,
+            };
+        }
+        if (registration.source_type !== "local") {
+            return {
+                name: "Skills",
+                status: "warn",
+                message: `Codex marketplace ${RCS_LOCAL_MARKETPLACE_NAME} has source_type=${String(registration.source_type)} (expected local); run "rcs setup --plugin --force"`,
+            };
+        }
+        if (registration.source !== getPackageRoot()) {
+            return {
+                name: "Skills",
+                status: "warn",
+                message: `Codex marketplace ${RCS_LOCAL_MARKETPLACE_NAME} points to ${String(registration.source)} (expected ${getPackageRoot()}); run "rcs setup --plugin --force"`,
+            };
+        }
+        return {
+            name: "Skills",
+            status: "pass",
+            message: `plugin marketplace ${RCS_LOCAL_MARKETPLACE_NAME} registered; RCS skills are supplied by ${packagedMarketplace.pluginRoot}`,
+        };
+    }
+    catch {
+        return {
+            name: "Skills",
+            status: "fail",
+            message: "cannot read or parse config.toml for plugin marketplace registration",
+        };
+    }
+}
+async function checkSkills(paths, installMode) {
+    if (installMode === "plugin") {
+        return checkPluginMarketplaceRegistration(paths.configPath);
+    }
+    const expectations = getCatalogExpectations();
+    if (!existsSync(paths.skillsDir)) {
+        return {
+            name: "Skills",
+            status: "warn",
+            message: "skills directory not found",
+        };
+    }
+    try {
+        const entries = await readdir(paths.skillsDir, { withFileTypes: true });
+        const skillDirs = entries.filter((e) => e.isDirectory());
+        if (skillDirs.length >= expectations.skillMin) {
+            return {
+                name: "Skills",
+                status: "pass",
+                message: `${skillDirs.length} skills installed`,
+            };
+        }
+        return {
+            name: "Skills",
+            status: "warn",
+            message: `${skillDirs.length} skills (expected >= ${expectations.skillMin})`,
+        };
+    }
+    catch {
+        return {
+            name: "Skills",
+            status: "fail",
+            message: "cannot read skills directory",
+        };
+    }
+}
+function checkAgentsMd(scope, codexHomeDir, installMode) {
+    if (scope === "user") {
+        const userAgentsMd = join(codexHomeDir, "AGENTS.md");
+        if (existsSync(userAgentsMd)) {
+            return {
+                name: "AGENTS.md",
+                status: "pass",
+                message: `found in ${userAgentsMd}`,
+            };
+        }
+        if (installMode === "plugin") {
+            return {
+                name: "AGENTS.md",
+                status: "pass",
+                message: `optional plugin-mode AGENTS.md defaults not installed in ${userAgentsMd}`,
+            };
+        }
+        return {
+            name: "AGENTS.md",
+            status: "warn",
+            message: `not found in ${userAgentsMd} (run rcs setup --scope user)`,
+        };
+    }
+    const projectAgentsMd = join(process.cwd(), "AGENTS.md");
+    if (existsSync(projectAgentsMd)) {
+        return {
+            name: "AGENTS.md",
+            status: "pass",
+            message: "found in project root",
+        };
+    }
+    if (installMode === "plugin") {
+        return {
+            name: "AGENTS.md",
+            status: "pass",
+            message: "optional plugin-mode AGENTS.md defaults not installed in project root",
+        };
+    }
+    return {
+        name: "AGENTS.md",
+        status: "warn",
+        message: "not found in project root (run rcs agents-init . or rcs setup --scope project)",
+    };
+}
+function checkPromptTriage() {
+    try {
+        const config = readTriageConfig();
+        if (config.status === "disabled") {
+            return {
+                name: "Prompt triage",
+                status: "warn",
+                message: `disabled via ${config.path}`,
+            };
+        }
+        if (config.status === "invalid") {
+            return {
+                name: "Prompt triage",
+                status: "warn",
+                message: `config file malformed at ${config.path} — fails closed to disabled`,
+            };
+        }
+        // Smoke test: verify the classifier is callable and returns the expected shape.
+        const decision = triagePrompt("hello");
+        const validLanes = new Set(["HEAVY", "LIGHT", "PASS"]);
+        if (!decision ||
+            typeof decision !== "object" ||
+            !validLanes.has(decision.lane)) {
+            return {
+                name: "Prompt triage",
+                status: "fail",
+                message: `classifier returned unexpected shape (lane: ${String(decision?.lane)})`,
+            };
+        }
+        const sourceLabel = config.status === "defaulted" ? "enabled (default)" : "enabled";
+        return {
+            name: "Prompt triage",
+            status: "pass",
+            message: `config: ${sourceLabel}`,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            name: "Prompt triage",
+            status: "fail",
+            message: `module load error — ${msg}`,
+        };
+    }
+}
+async function checkMcpServers(configPath, installMode) {
+    if (!existsSync(configPath)) {
+        if (installMode === "plugin") {
+            return {
+                name: "MCP Servers",
+                status: "warn",
+                message: 'plugin mode selected, but config.toml is missing; run "rcs setup --plugin --force" to register plugin discovery',
+            };
+        }
+        return {
+            name: "MCP Servers",
+            status: "warn",
+            message: "config.toml not found",
+        };
+    }
+    try {
+        const content = await readFile(configPath, "utf-8");
+        const mcpCount = (content.match(/\[mcp_servers\./g) || []).length;
+        if (hasLegacyRcsTeamRunTable(content)) {
+            return {
+                name: "MCP Servers",
+                status: "warn",
+                message: `${mcpCount} servers configured, but retired [mcp_servers.rcs_team_run] is not supported; run "rcs setup --force" to repair the config`,
+            };
+        }
+        if (installMode === "plugin") {
+            return {
+                name: "MCP Servers",
+                status: "pass",
+                message: "plugin mode uses plugin-scoped MCP metadata; setup-owned RCS MCP tables are intentionally omitted",
+            };
+        }
+        if (mcpCount > 0) {
+            const hasRcsFirstPartyMcp = RCS_FIRST_PARTY_MCP_SERVER_NAMES.some((name) => content.includes(name));
+            if (hasRcsFirstPartyMcp) {
+                return {
+                    name: "MCP Servers",
+                    status: "pass",
+                    message: `${mcpCount} servers configured (RCS present)`,
+                };
+            }
+            return {
+                name: "MCP Servers",
+                status: "warn",
+                message: `${mcpCount} servers but no RCS servers yet (expected before first setup; run "rcs setup --force" once)`,
+            };
+        }
+        return {
+            name: "MCP Servers",
+            status: "warn",
+            message: "no MCP servers configured",
+        };
+    }
+    catch {
+        return {
+            name: "MCP Servers",
+            status: "fail",
+            message: "cannot read config.toml",
+        };
+    }
+}
+//# sourceMappingURL=doctor.js.map