specrails-desktop 2.0.0

package/server/dist/setup-manager.js

@@ -0,0 +1,1165 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SetupManager = exports.EMPTY_SUMMARY = exports.QUICK_CHECKPOINTS = exports.CHECKPOINTS = void 0;
+exports.detectCheckpointFromText = detectCheckpointFromText;
+exports.validateInstalledCore = validateInstalledCore;
+exports.computeSummary = computeSummary;
+exports.sweepLegacySrCommands = sweepLegacySrCommands;
+const child_process_1 = require("child_process");
+const readline_1 = require("readline");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const tree_kill_1 = __importDefault(require("tree-kill"));
+const core_compat_1 = require("./core-compat");
+const cli_prompt_1 = require("./util/cli-prompt");
+const win_spawn_1 = require("./util/win-spawn");
+const setup_prerequisites_1 = require("./setup-prerequisites");
+const core_package_1 = require("./core-package");
+const providers_1 = require("./providers");
+/**
+ * specrails-core's installer (Node-native from v4.2.0 onward, bash
+ * prior) always scaffolds into `.claude/` regardless of which AI
+ * CLI the project uses. The provider choice affects which binary
+ * runs (claude vs codex), not where the framework files live.
+ */
+const SPECRAILS_DIR = '.claude';
+// ─── specrails-core binary resolution ────────────────────────────────────────
+// Default: npx CORE_PACKAGE_SPEC (major-pinned range, see core-package.ts)
+// Override: set SPECRAILS_CORE_BIN to use a local/linked version, e.g.
+//   SPECRAILS_CORE_BIN=specrails-core npm run dev
+const WHICH_CMD = process.platform === 'win32' ? 'where' : 'which';
+function resolveCoreBinary(bin) {
+    if ((0, path_1.isAbsolute)(bin))
+        return bin;
+    if (bin.includes('/') || bin.includes('\\'))
+        return (0, path_1.resolve)(bin);
+    const result = (0, child_process_1.spawnSync)(WHICH_CMD, [bin], {
+        env: process.env,
+        shell: process.platform === 'win32',
+        encoding: 'utf-8',
+        timeout: 5_000,
+    });
+    if (result.error || (result.status ?? 1) !== 0)
+        return bin;
+    const first = `${result.stdout ?? ''}`.trim().split(/\r?\n/)[0]?.trim();
+    return first && first.length > 0 ? first : bin;
+}
+function getCoreCommand() {
+    const override = process.env.SPECRAILS_CORE_BIN;
+    if (override) {
+        return { bin: resolveCoreBinary(override), pkg: '' };
+    }
+    return { bin: 'npx', pkg: core_package_1.CORE_PACKAGE_SPEC };
+}
+function buildCoreArgs(args) {
+    const { bin, pkg } = getCoreCommand();
+    const fullArgs = pkg ? ['--yes', '--prefer-online', pkg, ...args] : args;
+    return { bin, fullArgs };
+}
+function spawnCoreInit(args, cwd) {
+    const { bin, fullArgs } = buildCoreArgs(['init', ...args]);
+    console.log(`[SetupManager] spawning core: ${bin} ${fullArgs.join(' ')} (cwd=${cwd}) (SPECRAILS_CORE_BIN=${process.env.SPECRAILS_CORE_BIN ?? '<unset>'})`);
+    // M15: use the cross-spawn wrapper instead of `spawn(..., { shell: win32 })`.
+    // With shell:true, Node concatenates the argv into one cmd.exe command line and
+    // does NOT quote individual args, so `--from-config C:\Users\John Doe\...yaml`
+    // (and `--root-dir <path with spaces>`) split on the space and break install on
+    // any Windows account/project path containing a space. cross-spawn resolves the
+    // .cmd shim AND quotes each arg, so spaces (and newlines) survive intact.
+    return (0, win_spawn_1.spawnCli)(bin, fullArgs, {
+        cwd,
+        env: process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+}
+// H19: hard cap on the runtime probe. `npx --yes --prefer-online
+// <CORE_PACKAGE_SPEC> version` does a network round-trip to the npm
+// registry, and spawnSync blocks the single event loop — without a timeout a
+// hung network froze the WHOLE app indefinitely during Add Project. On
+// timeout the probe degrades to ok:false, which the install paths surface as
+// a setup_error instead of hanging.
+const CORE_PROBE_TIMEOUT_MS = 60_000;
+function probeCoreRuntimeVersion(cwd) {
+    const { bin, fullArgs } = buildCoreArgs(['version']);
+    const result = (0, child_process_1.spawnSync)(bin, fullArgs, {
+        cwd,
+        env: process.env,
+        shell: process.platform === 'win32',
+        encoding: 'utf-8',
+        timeout: CORE_PROBE_TIMEOUT_MS,
+    });
+    if (result.error) {
+        const timedOut = result.error.code === 'ETIMEDOUT';
+        return {
+            ok: false,
+            bin,
+            error: timedOut
+                ? `probe timed out after ${CORE_PROBE_TIMEOUT_MS / 1000}s — npm registry unreachable?`
+                : result.error.message,
+        };
+    }
+    if ((result.status ?? 1) !== 0) {
+        const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+        const stdout = typeof result.stdout === 'string' ? result.stdout.trim() : '';
+        return { ok: false, bin, error: stderr || stdout || `exit code ${result.status ?? 'unknown'}` };
+    }
+    const output = `${result.stdout ?? ''}`.trim();
+    const match = output.match(/\d+\.\d+\.\d+/);
+    if (!match) {
+        return { ok: false, bin, error: `could not parse version from output: ${output}` };
+    }
+    return { ok: true, bin, version: match[0] };
+}
+// ─── YAML helpers ─────────────────────────────────────────────────────────────
+function writeSpawnInstallConfig(projectId, yamlText) {
+    const tmpDir = (0, os_1.tmpdir)();
+    const tempPath = (0, path_1.join)(tmpDir, `specrails-desktop-install-config-${projectId}-${Date.now()}.yaml`);
+    (0, fs_1.writeFileSync)(tempPath, yamlText, 'utf-8');
+    return tempPath;
+}
+function readInstallConfig(projectPath) {
+    const configPath = (0, path_1.join)(projectPath, '.specrails', 'install-config.yaml');
+    try {
+        const text = (0, fs_1.readFileSync)(configPath, 'utf-8');
+        const tierMatch = text.match(/^tier:\s*(\w+)/m);
+        const tier = (tierMatch?.[1] === 'quick' ? 'quick' : 'full');
+        let selectedAgents = [];
+        // Inline format: selected: [a, b, c]
+        const inlineMatch = text.match(/selected:\s*\[([^\]]*)\]/);
+        if (inlineMatch) {
+            selectedAgents = inlineMatch[1].split(',').map((s) => s.trim()).filter(Boolean);
+        }
+        else {
+            // Multi-line format: selected:\n    - a\n    - b
+            const multilineMatch = text.match(/selected:\s*\n((?:\s+-\s+\S+\n?)+)/);
+            if (multilineMatch) {
+                selectedAgents = multilineMatch[1].match(/- (\S+)/g)?.map((m) => m.replace('- ', '')) ?? [];
+            }
+        }
+        return { tier, selectedAgents };
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Template deployment (post-install) ──────────────────────────────────────
+function deployTemplates(projectPath, selectedAgents) {
+    const templatesDir = (0, path_1.join)(projectPath, '.specrails', 'setup-templates');
+    const targetDir = (0, path_1.join)(projectPath, SPECRAILS_DIR);
+    let agents = 0, commands = 0, personas = 0;
+    // Deploy selected agent templates
+    const agentTemplatesDir = (0, path_1.join)(templatesDir, 'agents');
+    const agentTargetDir = (0, path_1.join)(targetDir, 'agents');
+    if ((0, fs_1.existsSync)(agentTemplatesDir)) {
+        (0, fs_1.mkdirSync)(agentTargetDir, { recursive: true });
+        for (const file of (0, fs_1.readdirSync)(agentTemplatesDir)) {
+            if (!file.endsWith('.md'))
+                continue;
+            const agentId = file.replace(/\.md$/, '');
+            if (selectedAgents.length > 0 && !selectedAgents.includes(agentId))
+                continue;
+            (0, fs_1.copyFileSync)((0, path_1.join)(agentTemplatesDir, file), (0, path_1.join)(agentTargetDir, file));
+            agents++;
+        }
+    }
+    // Deploy persona templates
+    const personaTemplatesDir = (0, path_1.join)(templatesDir, 'personas');
+    const personaTargetDir = (0, path_1.join)(agentTargetDir, 'personas');
+    if ((0, fs_1.existsSync)(personaTemplatesDir)) {
+        (0, fs_1.mkdirSync)(personaTargetDir, { recursive: true });
+        for (const file of (0, fs_1.readdirSync)(personaTemplatesDir)) {
+            if (!file.endsWith('.md'))
+                continue;
+            (0, fs_1.copyFileSync)((0, path_1.join)(personaTemplatesDir, file), (0, path_1.join)(personaTargetDir, file));
+            personas++;
+        }
+    }
+    // Deploy command templates
+    const cmdTemplatesDir = (0, path_1.join)(templatesDir, 'commands', 'specrails');
+    const cmdTargetDir = (0, path_1.join)(targetDir, 'commands', 'specrails');
+    if ((0, fs_1.existsSync)(cmdTemplatesDir)) {
+        (0, fs_1.mkdirSync)(cmdTargetDir, { recursive: true });
+        for (const file of (0, fs_1.readdirSync)(cmdTemplatesDir)) {
+            if (!file.endsWith('.md'))
+                continue;
+            (0, fs_1.copyFileSync)((0, path_1.join)(cmdTemplatesDir, file), (0, path_1.join)(cmdTargetDir, file));
+            commands++;
+        }
+    }
+    return { agents, commands, personas };
+}
+// Full install: 7-phase enrichment flow (claude /specrails:enrich)
+exports.CHECKPOINTS = [
+    { key: 'base_install', name: 'Base installation' },
+    { key: 'repo_analysis', name: 'Repository analysis' },
+    { key: 'stack_conventions', name: 'Stack & conventions' },
+    { key: 'product_discovery', name: 'Product discovery' },
+    { key: 'agent_generation', name: 'Agent generation' },
+    { key: 'command_config', name: 'Command configuration' },
+    { key: 'final_verification', name: 'Final verification' },
+];
+// Quick install: 3-phase non-interactive flow (npx init --from-config)
+exports.QUICK_CHECKPOINTS = [
+    { key: 'config_written', name: 'Config written' },
+    { key: 'base_install', name: 'Base installation' },
+    { key: 'quick_complete', name: 'Quick install complete' },
+];
+function checkFilesystem(projectPath) {
+    const dir = SPECRAILS_DIR;
+    const hasBaseInstall = (0, fs_1.existsSync)((0, path_1.join)(projectPath, '.specrails', 'specrails-version')) ||
+        (0, fs_1.existsSync)((0, path_1.join)(projectPath, '.specrails-version'));
+    const hasSetupTemplates = (0, fs_1.existsSync)((0, path_1.join)(projectPath, '.specrails', 'setup-templates')) ||
+        (0, fs_1.existsSync)((0, path_1.join)(projectPath, dir, 'setup-templates'));
+    const hasRules = (0, fs_1.existsSync)((0, path_1.join)(projectPath, dir, 'rules')) &&
+        hasFiles((0, path_1.join)(projectPath, dir, 'rules'), /\.md$/);
+    const hasPersonas = (0, fs_1.existsSync)((0, path_1.join)(projectPath, dir, 'agents', 'personas')) &&
+        hasFiles((0, path_1.join)(projectPath, dir, 'agents', 'personas'), /\.md$/);
+    const hasAgents = (0, fs_1.existsSync)((0, path_1.join)(projectPath, dir, 'agents')) &&
+        hasFiles((0, path_1.join)(projectPath, dir, 'agents'), /^sr-.*\.md$/);
+    const hasCommands = (((0, fs_1.existsSync)((0, path_1.join)(projectPath, dir, 'commands', 'sr')) && hasFiles((0, path_1.join)(projectPath, dir, 'commands', 'sr'), /\.md$/)) ||
+        ((0, fs_1.existsSync)((0, path_1.join)(projectPath, dir, 'commands', 'specrails')) && hasFiles((0, path_1.join)(projectPath, dir, 'commands', 'specrails'), /\.md$/)));
+    const hasCLAUDE = (0, fs_1.existsSync)((0, path_1.join)(projectPath, 'CLAUDE.md'));
+    return {
+        base_install: hasBaseInstall,
+        // repo_analysis: detected when setup templates exist and CLAUDE.md is written
+        // (Claude writes CLAUDE.md after analyzing the repo)
+        repo_analysis: hasBaseInstall && (hasCLAUDE || hasSetupTemplates),
+        // stack_conventions: detected when rules files are generated
+        stack_conventions: hasRules,
+        product_discovery: hasPersonas,
+        agent_generation: hasAgents,
+        command_config: hasCommands,
+        // Final verification: agents + commands must exist (manifest from install.sh is unreliable —
+        // it's created during scaffolding before /setup generates the actual artifacts)
+        final_verification: hasAgents && hasCommands,
+    };
+}
+function hasFiles(dir, pattern) {
+    try {
+        return (0, fs_1.readdirSync)(dir).some((f) => pattern.test(f));
+    }
+    catch {
+        return false;
+    }
+}
+// ─── Enrich.md content resolver (shared by start + resume enrich paths) ─────
+/**
+ * Reads the enrich command's body from the project's specrails dir, falling
+ * back across the three known locations:
+ *   1. `.claude/commands/sr/enrich.md`        (modern; written by core ≥ 4.2)
+ *   2. `.claude/commands/specrails/enrich.md` (legacy; written by core 4.1.x)
+ *   3. `.claude/commands/setup.md`            (very legacy; before enrich rename)
+ *
+ * For codex projects the .codex/skills/<name>/SKILL.md layout is read by the
+ * codex CLI directly when the slash command is forwarded — when the legacy
+ * codex flow needs the literal content (synthetic-session resume), the same
+ * .claude/ paths are consulted because specrails-core scaffolds both trees.
+ *
+ * Returns an empty string when no file is found; callers fall back to passing
+ * the literal slash command and let the CLI surface the missing-command error.
+ */
+function readEnrichMdContent(projectPath) {
+    const enrichMdPathSr = (0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'sr', 'enrich.md');
+    const enrichMdPathSpecrails = (0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'specrails', 'enrich.md');
+    const legacyMdPath = (0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'setup.md');
+    for (const p of [enrichMdPathSr, enrichMdPathSpecrails, legacyMdPath]) {
+        try {
+            return (0, fs_1.readFileSync)(p, 'utf-8');
+        }
+        catch { /* try next */ }
+    }
+    return '';
+}
+// ─── Stream-based checkpoint detection ───────────────────────────────────────
+function detectCheckpointFromText(text) {
+    const hits = [];
+    // Match phase headers from Claude's /specrails:enrich output (and legacy /setup)
+    if (/phase\s*1|codebase\s*analysis|repository\s*analysis/i.test(text)) {
+        hits.push({ key: 'repo_analysis', detail: 'Analyzing codebase...' });
+    }
+    if (/phase\s*2|user\s*personas|product\s*discovery/i.test(text)) {
+        hits.push({ key: 'product_discovery', detail: 'Generating personas...' });
+    }
+    if (/phase\s*3|configuration|agent\s*selection|backlog\s*provider/i.test(text)) {
+        hits.push({ key: 'stack_conventions', detail: 'Configuring stack...' });
+    }
+    if (/generating\s*all\s*files|writing.*agent|sr-architect|sr-developer|sr-reviewer/i.test(text)) {
+        hits.push({ key: 'agent_generation', detail: 'Generating agents...' });
+    }
+    if (/command\s*selection|installing.*commands|\.claude\/commands\/(sr|specrails)/i.test(text)) {
+        hits.push({ key: 'command_config', detail: 'Configuring commands...' });
+    }
+    // TUI output patterns from specrails-core init --from-config.
+    // Covers both the retired bash installer (✓ config loaded, reading
+    // install-config.yaml) and the Node installer ≥ v4.2.0 (Loaded
+    // install config from <path>, Phase 1 / 2 / 3 step headers, final
+    // `init complete` sentinel).
+    if (/✓\s*config\s*loaded|reading.*install-config|loaded\s*install\s*config|from-config/i.test(text)) {
+        hits.push({ key: 'config_written' });
+    }
+    if (/installing\s*specrails|phase\s*2\s*&\s*3|placing\s*agents/i.test(text)) {
+        hits.push({ key: 'agent_generation', detail: 'Installing specrails artefacts...' });
+    }
+    if (/writing\s*manifest|wrote\s+.*specrails-manifest/i.test(text)) {
+        hits.push({ key: 'final_verification' });
+    }
+    if (/✓\s*installed|installation\s*complete|init\s*complete|update\s*complete/i.test(text)) {
+        hits.push({ key: 'quick_complete' });
+    }
+    // File path detection in tool_use events
+    if (text.includes('.specrails-version') || text.includes('specrails/specrails-version'))
+        hits.push({ key: 'base_install' });
+    if (text.includes('/agents/personas/') && text.includes('.md')) {
+        hits.push({ key: 'product_discovery', detail: 'Writing personas...' });
+    }
+    // Claude path: .claude/agents/sr-<name>.md
+    if (/\/agents\/sr-[^/]+\.md/.test(text)) {
+        hits.push({ key: 'agent_generation', detail: 'Writing agents...' });
+    }
+    // Codex path: .codex/skills/sr-<name>/SKILL.md (rail skills ship in
+    // specrails-core 4.6.0+ — see openspec/.../specs/setup-wizard… for the
+    // checkpoint protocol shared across providers).
+    if (/\.codex\/skills\/sr-[^/]+\/SKILL\.md/.test(text)) {
+        hits.push({ key: 'agent_generation', detail: 'Writing agent skills...' });
+    }
+    if ((text.includes('/commands/sr/') || text.includes('/commands/specrails/')) && text.includes('.md')) {
+        hits.push({ key: 'command_config', detail: 'Writing commands...' });
+    }
+    // Codex enrich/doctor skills (the non-rail commands) also indicate
+    // command_config progress.
+    if (/\.codex\/skills\/(enrich|doctor)\/SKILL\.md/.test(text)) {
+        hits.push({ key: 'command_config', detail: 'Writing codex command skills...' });
+    }
+    if (text.includes('/rules/') && text.includes('.md')) {
+        hits.push({ key: 'stack_conventions', detail: 'Writing conventions...' });
+    }
+    // Codex sandbox / approval policy lives inside .codex/config.toml
+    // (top-level `sandbox_mode` + `approval_policy` keys, per codex
+    // 0.128.0+). There is no separate Starlark rules file.
+    if (/\.codex\/config\.toml/.test(text)) {
+        hits.push({ key: 'stack_conventions', detail: 'Writing codex sandbox config...' });
+    }
+    if (text.includes('.specrails-manifest.json') || text.includes('specrails/specrails-manifest.json')) {
+        hits.push({ key: 'final_verification' });
+    }
+    return hits;
+}
+exports.EMPTY_SUMMARY = {
+    agents: 0,
+    specrailsCommands: 0,
+    opsxCommands: 0,
+    personas: 0,
+    legacySrRemoved: 0,
+    tier: 'quick',
+    provider: 'claude',
+};
+const MIN_NODE_NATIVE_CORE_VERSION = '4.1.0';
+function compareSemver(a, b) {
+    const aParts = a.trim().split('.').map((n) => parseInt(n, 10));
+    const bParts = b.trim().split('.').map((n) => parseInt(n, 10));
+    if (aParts.length < 3 || bParts.length < 3)
+        return null;
+    if ([...aParts, ...bParts].some((n) => Number.isNaN(n)))
+        return null;
+    for (let i = 0; i < 3; i++) {
+        if (aParts[i] > bParts[i])
+            return 1;
+        if (aParts[i] < bParts[i])
+            return -1;
+    }
+    return 0;
+}
+function validateInstalledCore(projectPath) {
+    const reasons = [];
+    const versionCandidates = [
+        (0, path_1.join)(projectPath, '.specrails', 'specrails-version'),
+        (0, path_1.join)(projectPath, '.specrails-version'),
+    ];
+    for (const candidate of versionCandidates) {
+        if (!(0, fs_1.existsSync)(candidate))
+            continue;
+        try {
+            const raw = (0, fs_1.readFileSync)(candidate, 'utf-8').trim();
+            const cmp = compareSemver(raw, MIN_NODE_NATIVE_CORE_VERSION);
+            if (cmp !== null && cmp < 0) {
+                reasons.push(`installed specrails-core version ${raw} is older than required ${MIN_NODE_NATIVE_CORE_VERSION}`);
+            }
+            break;
+        }
+        catch {
+            reasons.push(`failed to read installed specrails-core version from ${candidate}`);
+            break;
+        }
+    }
+    const legacyMarkers = [
+        { path: (0, path_1.join)(projectPath, '.specrails', 'bin', 'doctor.sh'), reason: 'legacy bash doctor detected' },
+        {
+            path: (0, path_1.join)(projectPath, '.specrails', 'setup-templates', 'settings', 'integration-contract.json'),
+            reason: 'legacy integration-contract copy detected in setup-templates',
+        },
+    ];
+    for (const marker of legacyMarkers) {
+        if ((0, fs_1.existsSync)(marker.path))
+            reasons.push(marker.reason);
+    }
+    return { ok: reasons.length === 0, reasons };
+}
+function formatLegacyInstallError(reasons) {
+    return [
+        'Installed specrails-core is legacy; expected the Node-native installer.',
+        '',
+        ...reasons.map((reason) => `- ${reason}`),
+    ].join('\n');
+}
+function computeSummary(projectPath, tier, provider = 'claude') {
+    let agents = 0;
+    let personas = 0;
+    let specrailsCommands = 0;
+    let opsxCommands = 0;
+    try {
+        if (provider === 'codex') {
+            // Codex layout: every artefact ships as a SKILL under `.codex/skills/`.
+            // - agents  = rail personas (`skills/rails/sr-*/SKILL.md`) + orchestrator
+            //             skills at the root with an `sr-` prefix (sr-implement,
+            //             sr-batch-implement, …)
+            // - opsxCommands     = `skills/openspec-*/SKILL.md`
+            // - specrailsCommands = everything else under `skills/` (ported claude
+            //   slash commands like propose-spec, explore-spec, retry, doctor,
+            //   enrich, vpc-drift, …)
+            // - personas = 0 today; codex VPC pass not implemented yet.
+            const skillsDir = (0, path_1.join)(projectPath, '.codex', 'skills');
+            if ((0, fs_1.existsSync)(skillsDir)) {
+                // Rails (always counted as agents).
+                const railsDir = (0, path_1.join)(skillsDir, 'rails');
+                if ((0, fs_1.existsSync)(railsDir)) {
+                    for (const entry of (0, fs_1.readdirSync)(railsDir)) {
+                        if ((0, fs_1.existsSync)((0, path_1.join)(railsDir, entry, 'SKILL.md')))
+                            agents++;
+                    }
+                }
+                // Top-level skill dirs.
+                for (const entry of (0, fs_1.readdirSync)(skillsDir)) {
+                    if (entry === 'rails')
+                        continue;
+                    if (!(0, fs_1.existsSync)((0, path_1.join)(skillsDir, entry, 'SKILL.md')))
+                        continue;
+                    if (/^sr-/.test(entry))
+                        agents++;
+                    else if (/^openspec-/.test(entry))
+                        opsxCommands++;
+                    else
+                        specrailsCommands++;
+                }
+            }
+        }
+        else {
+            // Claude layout (unchanged).
+            const dir = SPECRAILS_DIR;
+            const agentsDir = (0, path_1.join)(projectPath, dir, 'agents');
+            if ((0, fs_1.existsSync)(agentsDir)) {
+                const files = (0, fs_1.readdirSync)(agentsDir);
+                agents = files.filter((f) => /^sr-.*\.md$/.test(f)).length;
+                const personasDir = (0, path_1.join)(agentsDir, 'personas');
+                if ((0, fs_1.existsSync)(personasDir)) {
+                    personas = (0, fs_1.readdirSync)(personasDir).filter((f) => f.endsWith('.md')).length;
+                }
+            }
+            const commandsDirSpecrails = (0, path_1.join)(projectPath, dir, 'commands', 'specrails');
+            const commandsDirOpsx = (0, path_1.join)(projectPath, dir, 'commands', 'opsx');
+            if ((0, fs_1.existsSync)(commandsDirSpecrails)) {
+                specrailsCommands = (0, fs_1.readdirSync)(commandsDirSpecrails).filter((f) => f.endsWith('.md')).length;
+            }
+            if ((0, fs_1.existsSync)(commandsDirOpsx)) {
+                opsxCommands = (0, fs_1.readdirSync)(commandsDirOpsx).filter((f) => f.endsWith('.md')).length;
+            }
+        }
+    }
+    catch {
+        // non-fatal
+    }
+    return { agents, specrailsCommands, opsxCommands, personas, legacySrRemoved: 0, tier, provider };
+}
+/**
+ * Deletes the deprecated `.claude/commands/sr/` directory (if present) and returns
+ * the number of `.md` files that were removed. Safe to call even if the directory
+ * does not exist. Never throws — errors are logged at info level.
+ */
+function sweepLegacySrCommands(projectPath) {
+    const srDir = (0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'sr');
+    try {
+        if (!(0, fs_1.existsSync)(srDir))
+            return 0;
+        const files = (0, fs_1.readdirSync)(srDir).filter((f) => f.endsWith('.md'));
+        const count = files.length;
+        (0, fs_1.rmSync)(srDir, { recursive: true, force: true });
+        console.info(`[SetupManager] Swept ${count} legacy /specrails:* command(s) from ${srDir}`);
+        return count;
+    }
+    catch (err) {
+        console.info(`[SetupManager] sweepLegacySrCommands failed (non-fatal): ${err}`);
+        return 0;
+    }
+}
+// ─── Core contract validation ────────────────────────────────────────────────
+async function validateCoreContract() {
+    const contractPath = await (0, core_compat_1.findCoreContract)();
+    if (!contractPath) {
+        // specrails-core does not yet ship integration-contract.json (planned in RFC-003).
+        // Fall back silently to runtime defaults — Specrails works fine without the contract.
+        console.debug('[Specrails] integration-contract.json not found — using runtime defaults');
+        return;
+    }
+    let contract;
+    try {
+        const raw = require('fs').readFileSync(contractPath, 'utf-8');
+        contract = JSON.parse(raw);
+    }
+    catch {
+        console.debug('[Specrails] integration-contract.json failed to parse — using runtime defaults');
+        return;
+    }
+    if (contract.checkpoints) {
+        const missingCheckpoints = contract.checkpoints.filter((c) => !exports.CHECKPOINTS.some((cp) => cp.key === c));
+        const extraCheckpoints = exports.CHECKPOINTS
+            .filter((cp) => !contract.checkpoints.includes(cp.key))
+            .map((cp) => cp.key);
+        if (missingCheckpoints.length > 0 || extraCheckpoints.length > 0) {
+            console.warn('[Specrails] ⚠️  specrails-core contract checkpoint mismatch:');
+            if (missingCheckpoints.length > 0)
+                console.warn(`  Checkpoints in Core but not in the app: ${missingCheckpoints.join(', ')}`);
+            if (extraCheckpoints.length > 0)
+                console.warn(`  Checkpoints in the app but not in Core: ${extraCheckpoints.join(', ')}`);
+        }
+    }
+}
+// ─── SetupManager ─────────────────────────────────────────────────────────────
+const INSTALL_LOG_BUFFER_MAX = 2000;
+function formatBufferedInstallError(baseMessage, logBuffer) {
+    const recentLines = logBuffer
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-8);
+    if (recentLines.length === 0)
+        return baseMessage;
+    return [
+        baseMessage,
+        '',
+        'Recent output:',
+        ...recentLines.map((line) => `- ${line}`),
+    ].join('\n');
+}
+class SetupManager {
+    _broadcast;
+    _onSessionCaptured;
+    _onSetupDone;
+    // Map from projectId → active child processes
+    _installProcesses;
+    _setupProcesses;
+    // Track checkpoint states per project
+    _checkpoints;
+    // Track checkpoint start times
+    _checkpointStart;
+    // Ring buffer for install log lines — allows clients to recover log on reconnect
+    _installLogBuffer;
+    // Track each project's chosen AI provider for binary selection
+    _projectProviders;
+    // Track each project's install tier (quick vs full)
+    _projectTiers;
+    // Track project names for codex context header injection
+    _projectNames;
+    constructor(broadcast, onSessionCaptured, onSetupDone) {
+        this._broadcast = broadcast;
+        this._onSessionCaptured = onSessionCaptured;
+        this._onSetupDone = onSetupDone;
+        this._installProcesses = new Map();
+        this._setupProcesses = new Map();
+        this._checkpoints = new Map();
+        this._checkpointStart = new Map();
+        this._pollTimers = new Map();
+        this._installLogBuffer = new Map();
+        this._projectProviders = new Map();
+        this._projectTiers = new Map();
+        this._projectNames = new Map();
+    }
+    // ─── Full Install: TUI installer (npx specrails-core) ────────────────────────
+    startInstall(projectId, projectPath) {
+        if (this._installProcesses.has(projectId)) {
+            console.warn(`[SetupManager] install already running for ${projectId}`);
+            return;
+        }
+        const configPath = (0, path_1.join)(projectPath, '.specrails', 'install-config.yaml');
+        const hasConfig = (0, fs_1.existsSync)(configPath);
+        const parsedConfig = hasConfig ? readInstallConfig(projectPath) : null;
+        const tier = parsedConfig?.tier ?? 'full';
+        this._projectTiers.set(projectId, tier);
+        // Pull provider out of the just-written install-config.yaml so the
+        // completion-summary path can label tiles correctly (codex → "Skills"
+        // etc.). Without this, summary.provider stays undefined and the client
+        // renders the claude labels with 0/0/0 counts because the codex skill
+        // walker never gets selected.
+        if (hasConfig) {
+            try {
+                const text = (0, fs_1.readFileSync)(configPath, 'utf-8');
+                const m = text.match(/^provider:\s*(\w+)/m);
+                if (m && (m[1] === 'claude' || m[1] === 'codex')) {
+                    this._projectProviders.set(projectId, m[1]);
+                }
+            }
+            catch {
+                // Ignore — falls back to claude default downstream.
+            }
+        }
+        this._initCheckpoints(projectId);
+        const missingPrerequisites = (0, setup_prerequisites_1.formatMissingSetupPrerequisites)();
+        if (missingPrerequisites) {
+            this._broadcast({
+                type: 'setup_error',
+                projectId,
+                error: missingPrerequisites,
+            });
+            return;
+        }
+        const probe = probeCoreRuntimeVersion(projectPath);
+        if (!probe.ok) {
+            this._broadcast({
+                type: 'setup_error',
+                projectId,
+                error: `Failed to verify specrails-core runtime before install: ${probe.error ?? 'unknown error'}`,
+            });
+            return;
+        }
+        console.log(`[SetupManager] core runtime probe: ${probe.bin} -> ${probe.version}`);
+        const probeCmp = compareSemver(probe.version, MIN_NODE_NATIVE_CORE_VERSION);
+        if (probeCmp !== null && probeCmp < 0) {
+            this._broadcast({
+                type: 'setup_error',
+                projectId,
+                error: `Resolved specrails-core@${probe.version} is legacy; expected Node-native >= ${MIN_NODE_NATIVE_CORE_VERSION}.`,
+            });
+            return;
+        }
+        let spawnConfigPath = null;
+        if (hasConfig) {
+            try {
+                spawnConfigPath = writeSpawnInstallConfig(projectId, (0, fs_1.readFileSync)(configPath, 'utf-8'));
+            }
+            catch (err) {
+                console.warn(`[SetupManager] Failed to write temp install-config.yaml: ${err}`);
+            }
+        }
+        const initArgs = hasConfig
+            ? ['--yes', '--from-config', spawnConfigPath ?? configPath]
+            : ['--yes', '--root-dir', projectPath];
+        const child = spawnCoreInit(initArgs, projectPath);
+        this._installProcesses.set(projectId, child);
+        this._installLogBuffer.set(projectId, []);
+        // spawnCoreInit uses shell:false on POSIX, so a spawn failure emits 'error'
+        // (and NOT 'close') — without this handler the temp config file leaks and
+        // the unhandled 'error' event would crash the app.
+        /* c8 ignore start -- spawn-failure path; exercised manually, not in CI */
+        child.on('error', (err) => {
+            console.error(`[SetupManager] core spawn failed for ${projectId}: ${err.message}`);
+            this._installProcesses.delete(projectId);
+            if (spawnConfigPath) {
+                try {
+                    (0, fs_1.rmSync)(spawnConfigPath, { force: true });
+                }
+                catch { /* non-fatal */ }
+            }
+            this._broadcast({
+                type: 'setup_error',
+                projectId,
+                error: `Failed to launch specrails-core: ${err.message}`,
+            });
+        });
+        /* c8 ignore stop */
+        const stdoutReader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+        const stderrReader = (0, readline_1.createInterface)({ input: child.stderr, crlfDelay: Infinity });
+        const appendLog = (line) => {
+            const buf = this._installLogBuffer.get(projectId) ?? [];
+            buf.push(line);
+            if (buf.length > INSTALL_LOG_BUFFER_MAX)
+                buf.splice(0, buf.length - INSTALL_LOG_BUFFER_MAX);
+            this._installLogBuffer.set(projectId, buf);
+        };
+        stdoutReader.on('line', (line) => {
+            appendLog(line);
+            this._broadcast({ type: 'setup_log', projectId, line, stream: 'stdout' });
+            const hits = detectCheckpointFromText(line);
+            for (const hit of hits) {
+                this._advanceCheckpoint(projectId, hit.key, hit.detail);
+            }
+        });
+        stderrReader.on('line', (line) => {
+            appendLog(line);
+            this._broadcast({ type: 'setup_log', projectId, line, stream: 'stderr' });
+        });
+        child.on('close', (code) => {
+            if (spawnConfigPath) {
+                try {
+                    (0, fs_1.rmSync)(spawnConfigPath, { force: true });
+                }
+                catch { /* non-fatal */ }
+            }
+            this._installProcesses.delete(projectId);
+            if (code === 0) {
+                const validation = validateInstalledCore(projectPath);
+                if (!validation.ok) {
+                    this._broadcast({
+                        type: 'setup_error',
+                        projectId,
+                        error: formatLegacyInstallError(validation.reasons),
+                    });
+                    return;
+                }
+                this._advanceCheckpoint(projectId, 'base_install');
+                this._completeCheckpoint(projectId, 'base_install');
+                const legacySrRemoved = sweepLegacySrCommands(projectPath);
+                const summary = { ...computeSummary(projectPath, tier, this._projectProviders.get(projectId) ?? 'claude'), legacySrRemoved };
+                this._broadcast({
+                    type: 'setup_install_done',
+                    projectId,
+                    timestamp: new Date().toISOString(),
+                    summary,
+                });
+                validateCoreContract().catch(() => { });
+            }
+            else {
+                const logBuffer = this._installLogBuffer.get(projectId) ?? [];
+                this._broadcast({
+                    type: 'setup_error',
+                    projectId,
+                    error: formatBufferedInstallError(`npx specrails-core exited with code ${code ?? 'unknown'}`, logBuffer),
+                });
+            }
+        });
+    }
+    // ─── Enrich: claude -p "/specrails:enrich --from-config" ────────────────────
+    startEnrich(projectId, projectPath, provider, projectName) {
+        if (this._setupProcesses.has(projectId)) {
+            console.warn(`[SetupManager] enrich already running for ${projectId}`);
+            return;
+        }
+        if (provider)
+            this._projectProviders.set(projectId, provider);
+        if (projectName)
+            this._projectNames.set(projectId, projectName);
+        this._projectTiers.set(projectId, 'full');
+        this._initCheckpoints(projectId);
+        // Pre-create the directory structure that /specrails:enrich will write to.
+        // Claude Code's Write tool does not create parent directories automatically —
+        // if a target directory doesn't exist the write fails and Claude reports a
+        // misleading "write permissions aren't enabled" error.  Creating the dirs
+        // here ensures enrich runs transparently without any user intervention.
+        try {
+            (0, fs_1.mkdirSync)((0, path_1.join)(projectPath, SPECRAILS_DIR, 'agents', 'personas'), { recursive: true });
+            (0, fs_1.mkdirSync)((0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'sr'), { recursive: true });
+            (0, fs_1.mkdirSync)((0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'specrails'), { recursive: true });
+            (0, fs_1.mkdirSync)((0, path_1.join)(projectPath, SPECRAILS_DIR, 'rules'), { recursive: true });
+        }
+        catch (err) {
+            console.warn(`[SetupManager] Failed to pre-create enrich directories: ${err}`);
+        }
+        const configPath = (0, path_1.join)(projectPath, '.specrails', 'install-config.yaml');
+        const hasConfig = (0, fs_1.existsSync)(configPath);
+        const enrichCmd = hasConfig ? '/specrails:enrich --from-config' : '/specrails:enrich';
+        this._spawnSetupWithAdapter(projectId, projectPath, {
+            action: 'setup-enrich',
+            prompt: enrichCmd,
+            provider,
+        });
+    }
+    /** @deprecated Use startEnrich() instead */
+    startSetup(projectId, projectPath, provider) {
+        return this.startEnrich(projectId, projectPath, provider);
+    }
+    resumeEnrich(projectId, projectPath, sessionId, userMessage, provider) {
+        if (this._setupProcesses.has(projectId)) {
+            console.warn(`[SetupManager] enrich already running for ${projectId}`);
+            return;
+        }
+        if (provider)
+            this._projectProviders.set(projectId, provider);
+        const resolvedProvider = (provider ?? this._projectProviders.get(projectId));
+        const adapter = (0, providers_1.getAdapter)(resolvedProvider ?? 'claude');
+        // Synthetic codex session ids (from before §10) can't be resumed against
+        // a real codex thread — detect and fall back to a fresh enrich respawn
+        // that folds enrich.md content + the user reply, matching the legacy UX.
+        const isSyntheticSession = sessionId.startsWith('codex-') && !/^[0-9a-f]{8}-[0-9a-f]{4}/i.test(sessionId);
+        if (adapter.id === 'codex' && isSyntheticSession) {
+            const enrichContent = readEnrichMdContent(projectPath);
+            const prompt = enrichContent
+                ? `${enrichContent}\n\n---\nIMPORTANT: This is a continuation of a previous enrich run. Check which artifacts already exist in the project before regenerating anything. The user responded to your question with:\n\n${userMessage}`
+                : userMessage;
+            this._spawnSetupWithAdapter(projectId, projectPath, {
+                action: 'setup-enrich',
+                prompt,
+                provider: resolvedProvider,
+            });
+            return;
+        }
+        // Modern path: real session id (claude or post-§10 codex) — use the
+        // adapter's resume action.
+        this._spawnSetupWithAdapter(projectId, projectPath, {
+            action: 'setup-enrich-resume',
+            prompt: userMessage,
+            sessionId,
+            provider: resolvedProvider,
+        });
+    }
+    /** @deprecated Use resumeEnrich() instead */
+    resumeSetup(projectId, projectPath, sessionId, userMessage, provider) {
+        return this.resumeEnrich(projectId, projectPath, sessionId, userMessage, provider);
+    }
+    // Active filesystem poll timers per project
+    _pollTimers;
+    _startFilesystemPoll(projectId, projectPath) {
+        this._stopFilesystemPoll(projectId);
+        const timer = setInterval(() => {
+            this._syncFilesystemCheckpoints(projectId, projectPath);
+        }, 3000);
+        this._pollTimers.set(projectId, timer);
+    }
+    _stopFilesystemPoll(projectId) {
+        const timer = this._pollTimers.get(projectId);
+        if (timer) {
+            clearInterval(timer);
+            this._pollTimers.delete(projectId);
+        }
+    }
+    /**
+     * Adapter-driven enrich spawn. Provider-aware prompt resolution
+     * (slash command for claude vs file-content fold for codex), real
+     * thread_id capture from `session-started` events (no more synthetic
+     * `codex-<id>-<ts>` ids), uniform stream parsing via
+     * `adapter.parseStreamLine`.
+     */
+    _spawnSetupWithAdapter(projectId, projectPath, opts) {
+        const resolvedProvider = opts.provider ?? (0, core_compat_1.detectCLISync)();
+        if (resolvedProvider === null) {
+            console.warn('[SetupManager] No AI CLI detected. Falling back to claude.');
+        }
+        const adapter = (0, providers_1.getAdapter)(resolvedProvider ?? 'claude');
+        // Provider-aware prompt resolution:
+        //   - claude: pass the slash command unresolved so the CLI looks up
+        //     `.claude/commands/specrails/enrich.md` natively. Honours the
+        //     skills-resolution priority over CLAUDE.md.
+        //   - codex: no slash-command support; fold the enrich.md content into
+        //     the prompt with the PROJECT context header so codex knows the cwd.
+        let effectivePrompt = opts.prompt;
+        if (!adapter.capabilities.systemPromptArg &&
+            (opts.prompt === '/specrails:enrich' || opts.prompt === '/specrails:enrich --from-config')) {
+            const enrichContent = readEnrichMdContent(projectPath);
+            if (enrichContent) {
+                const projectName = this._projectNames.get(projectId);
+                effectivePrompt = projectName
+                    ? `PROJECT: ${projectName}\nCWD: ${projectPath}\n\n---\n\n${enrichContent}`
+                    : enrichContent;
+            }
+            else {
+                console.warn(`[SetupManager] Could not read enrich.md or setup.md — falling back to literal prompt`);
+            }
+        }
+        const args = adapter.buildArgs(opts.action, {
+            prompt: effectivePrompt,
+            model: adapter.defaultModel(),
+            sessionId: opts.sessionId,
+        });
+        // No OTEL env injection here — SetupManager spawns drive the initial project
+        // setup wizard, not repeatable pipeline jobs. Telemetry is scoped to
+        // QueueManager pipeline runs only.
+        const child = (0, cli_prompt_1.spawnAiCli)(adapter.binary, args, {
+            cwd: projectPath,
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        this._setupProcesses.set(projectId, child);
+        /* c8 ignore start -- spawn-failure path; exercised manually, not in CI */
+        child.on('error', (err) => {
+            console.error(`[SetupManager] ${adapter.binary} spawn failed for ${projectId}: ${err.message}`);
+            this._setupProcesses.delete(projectId);
+            this._stopFilesystemPoll(projectId);
+            this._broadcast({
+                type: 'setup_error',
+                projectId,
+                error: `Failed to launch ${adapter.binary}: ${err.message}`,
+            });
+        });
+        /* c8 ignore stop */
+        // Start periodic filesystem polling for checkpoint detection
+        this._startFilesystemPoll(projectId, projectPath);
+        let capturedSessionId = null;
+        const stdoutReader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+        const stderrReader = (0, readline_1.createInterface)({ input: child.stderr, crlfDelay: Infinity });
+        stdoutReader.on('line', (line) => {
+            const ev = adapter.parseStreamLine(line);
+            if (!ev) {
+                // Non-parseable line — emit as raw log.
+                if (line)
+                    this._broadcast({ type: 'setup_log', projectId, line, stream: 'stdout' });
+                return;
+            }
+            switch (ev.kind) {
+                case 'session-started': {
+                    if (!capturedSessionId) {
+                        capturedSessionId = ev.sessionId;
+                        this._onSessionCaptured?.(projectId, ev.sessionId);
+                    }
+                    break;
+                }
+                case 'text-delta': {
+                    // Run checkpoint detection over the assistant text and surface it
+                    // both to the collapsible log viewer and the wizard chat panel.
+                    this._broadcast({ type: 'setup_log', projectId, line: ev.text, stream: 'stdout' });
+                    this._broadcast({ type: 'setup_chat', projectId, text: ev.text, role: 'assistant' });
+                    const hits = detectCheckpointFromText(ev.text);
+                    for (const hit of hits) {
+                        this._advanceCheckpoint(projectId, hit.key, hit.detail);
+                    }
+                    // Also sync filesystem (cheap mtime/exists checks, see helper).
+                    this._syncFilesystemCheckpoints(projectId, projectPath);
+                    break;
+                }
+                case 'tool-use': {
+                    this._broadcast({ type: 'setup_log', projectId, line: `[tool] ${ev.name}`, stream: 'stdout' });
+                    // Tool inputs commonly mention the paths being written — feed the
+                    // input preview into the checkpoint detector so writes to
+                    // .claude/agents/sr-*.md or .codex/skills/sr-*/SKILL.md advance
+                    // the checkpoint state immediately.
+                    const hits = detectCheckpointFromText(ev.inputPreview);
+                    for (const hit of hits) {
+                        this._advanceCheckpoint(projectId, hit.key, hit.detail);
+                    }
+                    break;
+                }
+                case 'result': {
+                    // Claude's `result` event also carries session_id; use it as a
+                    // backstop if `session-started` wasn't observed earlier.
+                    const sid = ev.payload.session_id;
+                    if (sid && !capturedSessionId) {
+                        capturedSessionId = sid;
+                        this._onSessionCaptured?.(projectId, sid);
+                    }
+                    break;
+                }
+                case 'other':
+                    // Other event types (system progress markers) — already broadcast
+                    // implicitly through the line itself if useful. Skip.
+                    break;
+            }
+        });
+        stderrReader.on('line', (line) => {
+            this._broadcast({ type: 'setup_log', projectId, line, stream: 'stderr' });
+        });
+        child.on('close', (code) => {
+            this._setupProcesses.delete(projectId);
+            this._stopFilesystemPoll(projectId);
+            // Final filesystem sync
+            this._syncFilesystemCheckpoints(projectId, projectPath);
+            if (code === 0) {
+                // Sync filesystem checkpoints
+                this._syncFilesystemCheckpoints(projectId, projectPath);
+                // Check if setup is truly complete — real artifacts must exist
+                const hasAgents = (0, fs_1.existsSync)((0, path_1.join)(projectPath, SPECRAILS_DIR, 'agents')) &&
+                    hasFiles((0, path_1.join)(projectPath, SPECRAILS_DIR, 'agents'), /^sr-.*\.md$/);
+                const hasCommands = (((0, fs_1.existsSync)((0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'sr')) && hasFiles((0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'sr'), /\.md$/)) ||
+                    ((0, fs_1.existsSync)((0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'specrails')) && hasFiles((0, path_1.join)(projectPath, SPECRAILS_DIR, 'commands', 'specrails'), /\.md$/)));
+                const isComplete = hasAgents && hasCommands;
+                if (isComplete) {
+                    const legacySrRemoved = sweepLegacySrCommands(projectPath);
+                    const tier = this._projectTiers.get(projectId) ?? 'full';
+                    const summary = { ...computeSummary(projectPath, tier, this._projectProviders.get(projectId) ?? 'claude'), legacySrRemoved };
+                    this._onSetupDone?.(projectId);
+                    this._broadcast({
+                        type: 'setup_complete',
+                        projectId,
+                        sessionId: capturedSessionId ?? undefined,
+                        summary,
+                    });
+                }
+                else {
+                    // Claude finished one turn but setup isn't done yet.
+                    // Emit turn_done so the wizard knows to wait for user input.
+                    this._broadcast({
+                        type: 'setup_turn_done',
+                        projectId,
+                        sessionId: capturedSessionId ?? undefined,
+                    });
+                }
+            }
+            else {
+                this._onSetupDone?.(projectId);
+                this._broadcast({
+                    type: 'setup_error',
+                    projectId,
+                    error: `${adapter.binary} enrich exited with code ${code ?? 'unknown'}`,
+                });
+            }
+        });
+    }
+    _initCheckpoints(projectId) {
+        const tier = this._projectTiers.get(projectId) ?? 'full';
+        const defs = tier === 'quick' ? exports.QUICK_CHECKPOINTS : exports.CHECKPOINTS;
+        const statuses = new Map();
+        const starts = new Map();
+        for (const def of defs) {
+            statuses.set(def.key, { key: def.key, name: def.name, status: 'pending' });
+        }
+        this._checkpoints.set(projectId, statuses);
+        this._checkpointStart.set(projectId, starts);
+    }
+    _advanceCheckpoint(projectId, key, detail) {
+        const statuses = this._checkpoints.get(projectId);
+        if (!statuses)
+            return;
+        const checkpoint = statuses.get(key);
+        if (!checkpoint || checkpoint.status === 'done')
+            return;
+        const starts = this._checkpointStart.get(projectId);
+        // When a later checkpoint starts, auto-complete all earlier ones
+        const tier = this._projectTiers.get(projectId) ?? 'full';
+        const checkpointDefs = tier === 'quick' ? exports.QUICK_CHECKPOINTS : exports.CHECKPOINTS;
+        const checkpointKeys = checkpointDefs.map((c) => c.key);
+        const targetIdx = checkpointKeys.indexOf(key);
+        for (let i = 0; i < targetIdx; i++) {
+            const prevKey = checkpointKeys[i];
+            const prev = statuses.get(prevKey);
+            if (prev && prev.status !== 'done') {
+                this._completeCheckpoint(projectId, prevKey);
+            }
+        }
+        if (checkpoint.status === 'pending') {
+            checkpoint.status = 'running';
+            starts.set(key, Date.now());
+            if (detail)
+                checkpoint.detail = detail;
+            this._broadcast({ type: 'setup_checkpoint', projectId, checkpoint: key, status: 'running', detail });
+        }
+    }
+    _completeCheckpoint(projectId, key) {
+        const statuses = this._checkpoints.get(projectId);
+        if (!statuses)
+            return;
+        const checkpoint = statuses.get(key);
+        if (!checkpoint || checkpoint.status === 'done')
+            return;
+        const starts = this._checkpointStart.get(projectId);
+        const startTime = starts.get(key) ?? Date.now();
+        const duration_ms = Date.now() - startTime;
+        starts.delete(key);
+        checkpoint.status = 'done';
+        checkpoint.duration_ms = duration_ms;
+        this._broadcast({ type: 'setup_checkpoint', projectId, checkpoint: key, status: 'done', duration_ms });
+    }
+    _syncFilesystemCheckpoints(projectId, projectPath) {
+        const statuses = this._checkpoints.get(projectId);
+        if (!statuses)
+            return;
+        const fsChecks = checkFilesystem(projectPath);
+        for (const [key, exists] of Object.entries(fsChecks)) {
+            if (!exists)
+                continue;
+            const cp = statuses.get(key);
+            if (!cp)
+                continue;
+            if (cp.status === 'pending') {
+                // Fast-path: mark running then done immediately
+                this._advanceCheckpoint(projectId, key);
+                this._completeCheckpoint(projectId, key);
+            }
+            else if (cp.status === 'running') {
+                this._completeCheckpoint(projectId, key);
+            }
+        }
+    }
+    // ─── Checkpoint poll endpoint ─────────────────────────────────────────────────
+    getCheckpointStatus(projectId, projectPath) {
+        // Sync from filesystem before returning
+        this._syncFilesystemCheckpoints(projectId, projectPath);
+        const tier = this._projectTiers.get(projectId) ?? 'full';
+        const defs = tier === 'quick' ? exports.QUICK_CHECKPOINTS : exports.CHECKPOINTS;
+        const statuses = this._checkpoints.get(projectId);
+        if (!statuses) {
+            // Return all-pending if install hasn't started
+            return defs.map((def) => ({ key: def.key, name: def.name, status: 'pending' }));
+        }
+        return defs.map((def) => statuses.get(def.key) ?? { key: def.key, name: def.name, status: 'pending' });
+    }
+    getInstallLog(projectId) {
+        return this._installLogBuffer.get(projectId) ?? [];
+    }
+    // ─── Abort ────────────────────────────────────────────────────────────────────
+    abort(projectId) {
+        this._stopFilesystemPoll(projectId);
+        this._projectProviders.delete(projectId);
+        this._projectTiers.delete(projectId);
+        this._onSetupDone?.(projectId);
+        const installChild = this._installProcesses.get(projectId);
+        if (installChild?.pid) {
+            this._terminateWithEscalation(installChild.pid);
+            this._installProcesses.delete(projectId);
+        }
+        const setupChild = this._setupProcesses.get(projectId);
+        if (setupChild?.pid) {
+            this._terminateWithEscalation(setupChild.pid);
+            this._setupProcesses.delete(projectId);
+        }
+    }
+    /**
+     * SIGTERM a process tree, then escalate to SIGKILL after a grace window if it
+     * is still alive — mirroring QueueManager._kill. The Map entry is deleted
+     * immediately by the caller, so the pid is captured locally here; without the
+     * escalation a child that ignores SIGTERM (npm/npx scaffolding, a hung CLI)
+     * would be orphaned for the host's lifetime with no remaining handle.
+     */
+    _terminateWithEscalation(pid) {
+        try {
+            (0, tree_kill_1.default)(pid, 'SIGTERM');
+        }
+        catch { /* best-effort */ }
+        const grace = setTimeout(() => {
+            try {
+                (0, tree_kill_1.default)(pid, 'SIGKILL', () => { });
+            }
+            catch { /* best-effort */ }
+        }, 5000);
+        if (typeof grace.unref === 'function')
+            grace.unref();
+    }
+    isInstalling(projectId) {
+        return this._installProcesses.has(projectId);
+    }
+    isEnriching(projectId) {
+        return this._setupProcesses.has(projectId);
+    }
+    /** @deprecated Use isEnriching() instead */
+    isSettingUp(projectId) {
+        return this.isEnriching(projectId);
+    }
+    getInstallTier(projectId) {
+        return this._projectTiers.get(projectId);
+    }
+    getSummary(projectPath) {
+        const config = readInstallConfig(projectPath);
+        const tier = config?.tier ?? 'quick';
+        // Provider is authoritative from install-config.yaml when present; we
+        // do NOT fall back to filesystem heuristics because both `.codex/` and
+        // `.claude/` can legitimately coexist (e.g. a project that's been
+        // re-init'd) and a generic `existsSync` probe would mis-route.
+        let provider = 'claude';
+        try {
+            const text = (0, fs_1.readFileSync)((0, path_1.join)(projectPath, '.specrails', 'install-config.yaml'), 'utf-8');
+            const m = text.match(/^provider:\s*(\w+)/m);
+            if (m && m[1] === 'codex')
+                provider = 'codex';
+        }
+        catch {
+            // Missing install-config — stay on claude default.
+        }
+        return computeSummary(projectPath, tier, provider);
+    }
+}
+exports.SetupManager = SetupManager;