openplanr 3.2.0 → 3.4.0

package/dist/services/runtime-manager-service.js

@@ -5,596 +5,28 @@
  * drift. Entry points: `previewSetup`, `applySetup`, `rollbackRuntime`, `removeRuntime`,
  * `runtimeDoctor`. Host plugin commands belong to the `claude-plugin` and `codex-plugin` services.
  */
-import { spawnSync } from 'node:child_process';
-import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, constants as fsConstants, lstatSync, readdirSync, readFileSync, realpathSync, } from 'node:fs';
-import { mkdir, open, readFile, rename, rm, unlink, writeFile, } from 'node:fs/promises';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { mkdir, open, readFile, rm, unlink } from 'node:fs/promises';
 import path from 'node:path';
-import { validateJson } from '../../lib/json-schema.mjs';
 import { CLI_NODE_REMEDIATION, cliNodeVersionMessage, supportsCliNodeVersion, } from '../../lib/node-runtime.mjs';
-import { planrHome, userHome } from '../../lib/planr-home.mjs';
-import { CLI_COMMAND, getPackageRoot, PLANNING_FOLDER } from '../utils/constants.js';
-import { spliceManagedBlock } from '../utils/splice-managed-block.js';
-import { applyBundledClaudePluginIntegration, claudePluginUninstallCommand, inspectBundledClaudePluginIntegration, } from './claude-plugin-service.js';
+import { CLI_COMMAND } from '../utils/constants.js';
+import { applyBundledClaudePluginIntegration, duplicateClaudePluginDiagnostic, inspectBundledClaudePluginIntegration, } from './claude-plugin-service.js';
 import { applyCodexPluginIntegration, inspectCodexPluginIntegration, } from './codex-plugin-service.js';
 import { resolvePipelinePackage } from './pipeline-package-service.js';
-import { readOpenPlanrVersion } from './provenance-service.js';
-import { effectiveCodexHome, inspectCodexSkillDiscovery, } from './runtime-manager/codex-discovery.js';
-import { classifyComponentDrift as classifyRuntimeComponentDrift, diagnoseManagedRuntimeFiles, diagnoseRetiredCommandSkills, diagnoseRuntimeProvenance, pluginDocuments, } from './runtime-manager/doctor.js';
-import { migrateLegacyGlobalRuntimeState, } from './runtime-manager/global-state.js';
-import { inventoryManagedSkillFiles, planCodexUserBundleTransition, } from './runtime-manager/install-plan.js';
-import { detectInstalledRuntimes, inspectRuntimeProjectContext, listInstalledRuntimeAdapters, planningFolderConflict, } from './runtime-manager/inventory.js';
-import { caseVariantOf, describePackageDrift, inspectRuntimeLocator, inspectRuntimePackage, inspectThinRule, retainedPackageDrift, runtimeLocator, thinDiscoveryMetadata, thinSkillEntry, } from './runtime-manager/runtime-package.js';
+import { effectiveCodexHome } from './runtime-manager/codex-discovery.js';
+import { runtimeDoctor as inspectRuntimeDoctor } from './runtime-manager/doctor.js';
+import { RuntimeManagerError } from './runtime-manager/errors.js';
+import { decodeStoredRuntimeState, inferRuntimeScope, loadState, projectUsesUserRuntime, runtimeStateBytes, } from './runtime-manager/global-state.js';
+import { actionBytes, buildActions, normalizeInstallScope, planCodexUserBundleTransition, runtimeLockManifestDigest, skillInstallMode, skillInstallModes, } from './runtime-manager/install-plan.js';
+import { detectInstalledRuntimes, inspectRuntimeProjectContext, listInstalledRuntimeAdapters, planningFolderConflict, readRegistry, } from './runtime-manager/inventory.js';
+import { planRetiredClaudeProjectAgents, planRetiredCursorProjectRules, } from './runtime-manager/legacy-adapters.js';
+import { canonicalProjectPath, codexSkillsRoot, pathIsWithin, planrCustodyAnchor, projectKey, runtimeRoot, statePath, userHome, } from './runtime-manager/paths.js';
+import { bundledHostRoot as resolveBundledHostRoot, } from './runtime-manager/runtime-package.js';
+import { assertActionCustody, assertApprovedTargetCustody, assertBackupDirectoryCustody, assertClosedBackupManifest, assertClosedBackupTree, assertMutableOwnedTarget, assertProfessionalSkillTransition, assertRequestedProjectBinding, assertUserOwnedTarget, atomicWrite, backupManifestIdentity, createBackup, hash, immutableRuntimeTarget, ownershipHash, readBackupEntryBytes, readCustodiedRegularFile, restoreBackup, } from './runtime-manager/storage.js';
 export { classifyComponentDrift } from './runtime-manager/doctor.js';
-const runtimeLockSchema = JSON.parse(readFileSync(new URL('../../lib/runtime-lock.schema.json', import.meta.url), 'utf8'));
-// Setup and global help remain available when the optional pipeline package is absent.
-function validateRuntimeLockContract(value) {
-    return validateJson(value, runtimeLockSchema);
-}
-const RETIRED_CURSOR_WORKFLOW_RULES = [
-    'planr-pipeline.mdc',
-    'planr-pipeline-plan.mdc',
-    'planr-pipeline-ship.mdc',
-];
-const RETIRED_CURSOR_AGENT_RULES = [
-    'backend-agent.md',
-    'db-agent.md',
-    'designer-agent.md',
-    'devops-agent.md',
-    'doc-gen-agent.md',
-    'entity-scaffold-agent.md',
-    'frontend-agent.md',
-    'qa-agent.md',
-    'specification-agent.md',
-];
-export class RuntimeManagerError extends Error {
-    code;
-    recovery;
-    constructor(code, message, recovery) {
-        super(message);
-        this.code = code;
-        this.recovery = recovery;
-        this.name = 'RuntimeManagerError';
-    }
-    toJSON() {
-        return { ok: false, code: this.code, problem: this.message, recovery: this.recovery };
-    }
-}
-function hash(value) {
-    return createHash('sha256').update(value).digest('hex');
-}
-function managedBlockBytes(content, marker = 'runtime') {
-    const text = Buffer.isBuffer(content) ? content.toString('utf8') : content;
-    const begin = `<!-- ##planr-${marker}:begin##`;
-    const end = `<!-- ##planr-${marker}:end## -->`;
-    const start = text.indexOf(begin);
-    const finish = text.indexOf(end, start);
-    if (start === -1 || finish === -1)
-        return Buffer.alloc(0);
-    return Buffer.from(text.slice(start, finish + end.length));
-}
-function ownershipHash(content, kind, marker) {
-    return hash(kind === 'managed-block' ? managedBlockBytes(content, marker) : content);
-}
-function canonicalProjectPath(projectDir) {
-    const resolved = path.resolve(projectDir);
-    try {
-        return realpathSync(resolved);
-    }
-    catch (cause) {
-        if (cause.code === 'ENOENT')
-            return resolved;
-        throw cause;
-    }
-}
-function projectKey(projectDir) {
-    return hash(canonicalProjectPath(projectDir)).slice(0, 16);
-}
-/** Canonical native homes select only Codex ownership, never another agent's state. */
-function codexProfileKey() {
-    const selected = effectiveCodexHome();
-    const defaultHome = path.resolve(userHome(), '.codex');
-    return selected === defaultHome ? undefined : hash(selected).slice(0, 16);
-}
-export function runtimeRoot() {
-    return path.join(planrHome(), 'runtime');
-}
-function codexRuntimeRoot(nativeHome = effectiveCodexHome()) {
-    const defaultHome = path.resolve(userHome(), '.codex');
-    return nativeHome === defaultHome
-        ? runtimeRoot()
-        : path.join(runtimeRoot(), 'profiles', `codex-${hash(nativeHome).slice(0, 16)}`);
-}
-function codexBookkeepingTarget(target, nativeHome) {
-    const root = codexRuntimeRoot(nativeHome);
-    return pathIsWithin(target, root) && !pathIsWithin(target, path.join(root, 'profiles'));
-}
-function statePath() {
-    return path.join(runtimeRoot(), 'state.json');
-}
-function codexSkillsRoot() {
-    return path.join(effectiveCodexHome(), 'skills');
-}
-/** Explicit OpenPlanr homes may be outside the native user's home; custody starts at their real existing boundary. */
-function planrCustodyAnchor() {
-    const configured = path.resolve(planrHome());
-    if (pathIsWithin(configured, userHome()))
-        return userHome();
-    let boundary = configured;
-    while (!existsSync(boundary) && path.dirname(boundary) !== boundary)
-        boundary = path.dirname(boundary);
-    return boundary;
-}
-function backupsRoot() {
-    return path.join(planrHome(), 'backups');
-}
-function projectBackupsRoot(projectDir) {
-    return path.join(backupsRoot(), projectKey(projectDir));
-}
-function pathIsWithin(candidate, root) {
-    const relative = path.relative(path.resolve(root), path.resolve(candidate));
-    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
-}
-function assertApprovedTargetCustody(target, approvedRoot, anchor, code, label) {
-    const selected = path.resolve(target);
-    const root = path.resolve(approvedRoot);
-    const boundary = path.resolve(anchor);
-    if (!pathIsWithin(selected, root) || !pathIsWithin(root, boundary)) {
-        throw new RuntimeManagerError(code, `${label} target ${selected} leaves its approved root ${root}.`, 'Restore valid runtime ownership state and keep managed targets inside the exact approved bundle root.');
-    }
-    let canonicalBoundary;
-    try {
-        const boundaryMetadata = lstatSync(boundary);
-        if (boundaryMetadata.isSymbolicLink() || !boundaryMetadata.isDirectory())
-            throw new Error('invalid boundary');
-        canonicalBoundary = realpathSync(boundary);
-    }
-    catch (cause) {
-        if (cause.code === 'ENOENT')
-            return;
-        throw new RuntimeManagerError(code, `${label} boundary ${boundary} is unavailable, non-directory, or symbolic.`, 'Use one real user/project root and replace symbolic managed-root parents before retrying.');
-    }
-    let current = boundary;
-    const segments = path.relative(boundary, selected).split(path.sep).filter(Boolean);
-    for (const [index, segment] of segments.entries()) {
-        current = path.join(current, segment);
-        let metadata;
-        try {
-            metadata = lstatSync(current);
-        }
-        catch (cause) {
-            if (cause.code === 'ENOENT')
-                return;
-            throw cause;
-        }
-        if (metadata.isSymbolicLink()) {
-            throw new RuntimeManagerError(code, `${label} target ${selected} traverses symbolic component ${current}.`, 'Replace symbolic managed-root parents with real directories before retrying.');
-        }
-        const isLeaf = index === segments.length - 1;
-        if (!isLeaf && !metadata.isDirectory()) {
-            throw new RuntimeManagerError(code, `${label} target ${selected} traverses non-directory component ${current}.`, 'Repair the managed bundle root before retrying.');
-        }
-        const canonical = realpathSync(current);
-        if (canonical !== canonicalBoundary &&
-            !canonical.startsWith(`${canonicalBoundary}${path.sep}`)) {
-            throw new RuntimeManagerError(code, `${label} target ${selected} escapes its canonical boundary.`, 'Repair the managed bundle root before retrying.');
-        }
-    }
-}
-function assertMutableOwnedTarget(target, projectDir, code) {
-    if (pathIsWithin(target, runtimeRoot())) {
-        assertApprovedTargetCustody(target, runtimeRoot(), planrCustodyAnchor(), code, 'Global runtime ownership');
-        return;
-    }
-    if (pathIsWithin(target, codexSkillsRoot())) {
-        assertApprovedTargetCustody(target, codexSkillsRoot(), effectiveCodexHome(), code, 'Global Codex bundle ownership');
-        return;
-    }
-    if (pathIsWithin(target, projectDir)) {
-        assertApprovedTargetCustody(target, projectDir, projectDir, code, 'Project runtime ownership');
-        return;
-    }
-    throw new RuntimeManagerError(code, `Managed mutation target ${path.resolve(target)} is outside every approved runtime root.`, 'Restore a valid ownership/backup manifest before retrying.');
-}
-function assertBackupDirectoryCustody(selected, projectDir, code, requireExisting = false) {
-    const directory = path.resolve(selected);
-    const approvedRoot = path.resolve(projectBackupsRoot(projectDir));
-    if (path.dirname(directory) !== approvedRoot) {
-        throw new RuntimeManagerError(code, `Runtime backup ${directory} is not one direct child of ${approvedRoot}.`, 'Select only the exact project backup created by OpenPlanr.');
-    }
-    assertApprovedTargetCustody(directory, approvedRoot, planrCustodyAnchor(), code, 'Runtime backup');
-    if (requireExisting) {
-        let metadata;
-        try {
-            metadata = lstatSync(directory);
-        }
-        catch {
-            throw new RuntimeManagerError(code, `Runtime backup ${directory} is unavailable.`);
-        }
-        if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
-            throw new RuntimeManagerError(code, `Runtime backup ${directory} is not one real directory.`);
-        }
-    }
-    return directory;
-}
-function backupEntryPath(directory, index, target) {
-    return path.join(directory, 'files', `${String(index).padStart(3, '0')}-${path.basename(target)}`);
-}
-function backupManifestIdentity(manifest) {
-    return `sha256:${hash(JSON.stringify({
-        schemaVersion: manifest.schemaVersion,
-        projectDir: manifest.projectDir,
-        createdAt: manifest.createdAt,
-        files: manifest.files.map(({ target, backup, existed, beforeHash, afterHash }) => ({
-            target,
-            existed,
-            ...(backup ? { backup } : {}),
-            ...(beforeHash ? { beforeHash } : {}),
-            ...(path.resolve(target) === path.resolve(statePath())
-                ? {}
-                : { expectedAfterHash: afterHash ?? null }),
-        })),
-    }))}`;
-}
-function assertClosedBackupManifest(value, directory, projectDir, code, requireFinalStateHash = false) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        throw new RuntimeManagerError(code, 'Runtime backup manifest is not one closed object.');
-    }
-    const manifest = value;
-    if (JSON.stringify(Object.keys(manifest).sort()) !==
-        JSON.stringify(['createdAt', 'files', 'projectDir', 'schemaVersion']) ||
-        manifest.schemaVersion !== '1.0.0' ||
-        typeof manifest.projectDir !== 'string' ||
-        canonicalProjectPath(manifest.projectDir) !== canonicalProjectPath(projectDir) ||
-        typeof manifest.createdAt !== 'string' ||
-        manifest.createdAt.length > 64 ||
-        Number.isNaN(Date.parse(manifest.createdAt)) ||
-        !Array.isArray(manifest.files) ||
-        manifest.files.length > 10_000) {
-        throw new RuntimeManagerError(code, 'Runtime backup manifest identity is invalid.');
-    }
-    const seenTargets = new Set();
-    const files = manifest.files.map((candidate, index) => {
-        if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)) {
-            throw new RuntimeManagerError(code, 'Runtime backup manifest contains a non-object entry.');
-        }
-        const entry = candidate;
-        const keys = Object.keys(entry).sort();
-        if (keys.some((key) => !['afterHash', 'backup', 'beforeHash', 'existed', 'target'].includes(key)) ||
-            !keys.includes('existed') ||
-            !keys.includes('target') ||
-            typeof entry.target !== 'string' ||
-            path.resolve(entry.target) !== entry.target ||
-            typeof entry.existed !== 'boolean' ||
-            (entry.afterHash !== undefined &&
-                (typeof entry.afterHash !== 'string' || !/^[a-f0-9]{64}$/u.test(entry.afterHash)))) {
-            throw new RuntimeManagerError(code, 'Runtime backup manifest entry is invalid.');
-        }
-        assertMutableOwnedTarget(entry.target, projectDir, code);
-        if (seenTargets.has(entry.target)) {
-            throw new RuntimeManagerError(code, `Runtime backup repeats target ${entry.target}.`);
-        }
-        seenTargets.add(entry.target);
-        if (entry.existed) {
-            const expected = backupEntryPath(directory, index, entry.target);
-            if (typeof entry.backup !== 'string' ||
-                path.resolve(entry.backup) !== expected ||
-                typeof entry.beforeHash !== 'string' ||
-                !/^[a-f0-9]{64}$/u.test(entry.beforeHash)) {
-                throw new RuntimeManagerError(code, `Runtime backup source for ${entry.target} is not exactly bound to its manifest slot.`);
-            }
-            assertApprovedTargetCustody(entry.backup, path.join(directory, 'files'), directory, code, 'Runtime backup file');
-        }
-        else if (entry.backup !== undefined || entry.beforeHash !== undefined) {
-            throw new RuntimeManagerError(code, `Runtime backup records bytes for absent target ${entry.target}.`);
-        }
-        return {
-            target: entry.target,
-            existed: entry.existed,
-            ...(typeof entry.backup === 'string' ? { backup: entry.backup } : {}),
-            ...(typeof entry.beforeHash === 'string' ? { beforeHash: entry.beforeHash } : {}),
-            ...(typeof entry.afterHash === 'string' ? { afterHash: entry.afterHash } : {}),
-        };
-    });
-    const stateEntries = files.filter((entry) => path.resolve(entry.target) === path.resolve(statePath()));
-    if (files.length === 0 || stateEntries.length !== 1) {
-        throw new RuntimeManagerError(code, 'Runtime backup manifest must bind exactly one global ownership-state target.');
-    }
-    const [stateEntry] = stateEntries;
-    if ((requireFinalStateHash && !stateEntry.afterHash) ||
-        (!stateEntry.existed && files.every((entry) => entry === stateEntry))) {
-        throw new RuntimeManagerError(code, 'Runtime backup manifest does not bind one complete setup transition.');
-    }
-    return {
-        schemaVersion: '1.0.0',
-        projectDir: manifest.projectDir,
-        createdAt: manifest.createdAt,
-        files,
-    };
-}
-function assertClosedBackupTree(directory, manifest, projectDir, code) {
-    assertBackupDirectoryCustody(directory, projectDir, code, true);
-    const expectedFiles = new Set([
-        path.join(directory, 'migration-manifest.json'),
-        ...manifest.files.flatMap((entry) => (entry.backup ? [entry.backup] : [])),
-    ].map((entry) => path.resolve(entry)));
-    const actualFiles = new Set();
-    const walk = (current) => {
-        assertApprovedTargetCustody(current, directory, planrCustodyAnchor(), code, 'Runtime backup tree');
-        for (const entry of readdirSync(current, { withFileTypes: true })) {
-            const absolute = path.join(current, entry.name);
-            const metadata = lstatSync(absolute);
-            if (metadata.isSymbolicLink() || (!metadata.isDirectory() && !metadata.isFile())) {
-                throw new RuntimeManagerError(code, `Runtime backup tree contains an unsupported entry at ${absolute}.`);
-            }
-            if (metadata.isDirectory())
-                walk(absolute);
-            else
-                actualFiles.add(path.resolve(absolute));
-        }
-    };
-    walk(directory);
-    if (actualFiles.size !== expectedFiles.size ||
-        [...actualFiles].some((entry) => !expectedFiles.has(entry))) {
-        throw new RuntimeManagerError(code, 'Runtime backup tree does not exactly match its closed manifest.');
-    }
-}
-async function readCustodiedRegularFile(target, custody, code, label, maxBytes = 64 * 1024 * 1024) {
-    custody();
-    let handle;
-    try {
-        handle = await open(target, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
-    }
-    catch (cause) {
-        throw new RuntimeManagerError(code, `${label} ${target} cannot be opened as a real file: ${cause instanceof Error ? cause.message : String(cause)}`);
-    }
-    try {
-        const metadata = await handle.stat();
-        if (!metadata.isFile() || metadata.size > maxBytes) {
-            throw new RuntimeManagerError(code, `${label} ${target} is not one bounded regular file.`);
-        }
-        const bytes = await handle.readFile();
-        custody();
-        return bytes;
-    }
-    finally {
-        await handle.close();
-    }
-}
-async function readBackupEntryBytes(directory, entry, _projectDir, code) {
-    if (!entry.backup || !entry.beforeHash) {
-        throw new RuntimeManagerError(code, `Runtime backup for ${entry.target} has no byte custody.`);
-    }
-    const bytes = await readCustodiedRegularFile(entry.backup, () => assertApprovedTargetCustody(entry.backup, path.join(directory, 'files'), directory, code, 'Runtime backup file'), code, 'Runtime backup file');
-    if (hash(bytes) !== entry.beforeHash) {
-        throw new RuntimeManagerError(code, `Runtime backup bytes for ${entry.target} do not match their recorded hash.`);
-    }
-    return bytes;
-}
-function assertUserOwnedTarget(file, runtime, code = 'E_RUNTIME_STATE_INVALID', nativeHome = effectiveCodexHome()) {
-    const approvedRoot = runtime === 'codex' ? codexRuntimeRoot(nativeHome) : runtimeRoot();
-    if (runtime === 'codex'
-        ? codexBookkeepingTarget(file.target, nativeHome)
-        : pathIsWithin(file.target, approvedRoot)) {
-        assertApprovedTargetCustody(file.target, approvedRoot, planrCustodyAnchor(), code, 'Global runtime ownership');
-        return;
-    }
-    if (runtime === 'codex' && pathIsWithin(file.target, path.join(nativeHome, 'skills'))) {
-        assertApprovedTargetCustody(file.target, path.join(nativeHome, 'skills'), nativeHome, code, 'Global Codex bundle ownership');
-        return;
-    }
-    throw new RuntimeManagerError(code, `Global ${runtime} ownership target ${path.resolve(file.target)} is outside every approved bundle root.`, 'Restore valid global ownership state before setup, rollback, retirement, or removal.');
-}
-function assertActionCustody(actions, projectDir) {
-    for (const action of actions) {
-        if (action.scope === 'user') {
-            assertUserOwnedTarget(action, action.runtime, 'E_MIGRATION_CONFLICT');
-        }
-        else {
-            assertApprovedTargetCustody(action.target, projectDir, projectDir, 'E_MIGRATION_CONFLICT', 'Project runtime ownership');
-        }
-    }
-}
-function assertRuntimeStateCustody(state, nativeHome = effectiveCodexHome()) {
-    for (const runtime of ['claude-code', 'codex', 'cursor']) {
-        for (const file of state.userBundles?.[runtime]?.ownedFiles ?? []) {
-            assertUserOwnedTarget(file, runtime, 'E_RUNTIME_STATE_INVALID', nativeHome);
-        }
-    }
-    for (const project of Object.values(state.projects)) {
-        for (const file of project.ownedFiles) {
-            const runtime = file.runtime;
-            if (file.scope === 'user' || (runtime !== 'core' && isUserOwnedFile(file, runtime))) {
-                assertUserOwnedTarget(file, runtime, 'E_RUNTIME_STATE_INVALID', nativeHome);
-            }
-            else {
-                assertApprovedTargetCustody(file.target, project.projectDir, project.projectDir, 'E_RUNTIME_STATE_INVALID', 'Project runtime ownership');
-            }
-        }
-    }
-}
-function assertRuntimeStateValue(value, code = 'E_RUNTIME_STATE_INVALID', allowLegacyProjectKeys = false, nativeHome = effectiveCodexHome(), inspectCustody = true) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        throw new RuntimeManagerError(code, 'Runtime ownership state is not one closed object.');
-    }
-    const state = value;
-    if (Object.keys(state).some((key) => !['projects', 'schemaVersion', 'userBundles', 'codexProfiles'].includes(key)) ||
-        !['1.0.0', '2.0.0'].includes(String(state.schemaVersion)) ||
-        state.projects === null ||
-        typeof state.projects !== 'object' ||
-        Array.isArray(state.projects) ||
-        (state.userBundles !== undefined &&
-            (state.userBundles === null ||
-                typeof state.userBundles !== 'object' ||
-                Array.isArray(state.userBundles)))) {
-        throw new RuntimeManagerError(code, 'Runtime ownership state identity is invalid.');
-    }
-    const legacyProjectKeysAllowed = allowLegacyProjectKeys && state.schemaVersion === '1.0.0';
-    const runtimeIds = new Set(['claude-code', 'codex', 'cursor']);
-    const assertOwnedFile = (candidate) => {
-        if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate))
-            return false;
-        const file = candidate;
-        return (Object.keys(file).every((key) => ['hash', 'kind', 'marker', 'runtime', 'scope', 'target'].includes(key)) &&
-            ['claude-code', 'codex', 'core', 'cursor'].includes(String(file.runtime)) &&
-            ['file', 'managed-block'].includes(String(file.kind)) &&
-            (file.scope === undefined || ['user', 'project'].includes(String(file.scope))) &&
-            (file.marker === undefined || typeof file.marker === 'string') &&
-            typeof file.target === 'string' &&
-            path.resolve(file.target) === file.target &&
-            typeof file.hash === 'string' &&
-            /^[a-f0-9]{64}$/u.test(file.hash));
-    };
-    const canonicalProjects = new Set();
-    for (const [key, project] of Object.entries(state.projects)) {
-        if (project === null || typeof project !== 'object' || Array.isArray(project)) {
-            throw new RuntimeManagerError(code, 'Runtime project ownership record is invalid.');
-        }
-        const record = project;
-        const canonicalProject = typeof record.projectDir === 'string' ? canonicalProjectPath(record.projectDir) : '';
-        if (Object.keys(record).some((key) => ![
-            'activeRuntime',
-            'backupDir',
-            'backupManifestHash',
-            'commandPrefix',
-            'codexHome',
-            'ownedFiles',
-            'projectDir',
-            'runtimeScopes',
-            'runtimes',
-            'skillModes',
-            'updatedAt',
-        ].includes(key)) ||
-            typeof record.projectDir !== 'string' ||
-            path.resolve(record.projectDir) !== record.projectDir ||
-            (!legacyProjectKeysAllowed && key !== projectKey(canonicalProject)) ||
-            canonicalProjects.has(canonicalProject) ||
-            typeof record.updatedAt !== 'string' ||
-            (record.codexHome !== undefined &&
-                (typeof record.codexHome !== 'string' ||
-                    path.resolve(record.codexHome) !== record.codexHome)) ||
-            !Array.isArray(record.runtimes) ||
-            record.runtimes.some((runtime) => !runtimeIds.has(runtime)) ||
-            !Array.isArray(record.ownedFiles) ||
-            record.ownedFiles.some((file) => !assertOwnedFile(file)) ||
-            (record.backupDir !== undefined && typeof record.backupDir !== 'string') ||
-            (record.backupManifestHash !== undefined &&
-                (typeof record.backupManifestHash !== 'string' ||
-                    !/^sha256:[a-f0-9]{64}$/u.test(record.backupManifestHash))) ||
-            (record.commandPrefix !== undefined &&
-                !['bare', 'namespaced'].includes(String(record.commandPrefix))) ||
-            (record.skillModes !== undefined &&
-                (record.skillModes === null ||
-                    typeof record.skillModes !== 'object' ||
-                    Array.isArray(record.skillModes) ||
-                    Object.entries(record.skillModes).some(([runtime, mode]) => !runtimeIds.has(runtime) ||
-                        !['direct', 'unified-plugin', 'project-rule'].includes(String(mode))))) ||
-            (record.activeRuntime !== undefined && !runtimeIds.has(record.activeRuntime))) {
-            throw new RuntimeManagerError(code, 'Runtime project ownership record is invalid.');
-        }
-        canonicalProjects.add(canonicalProject);
-    }
-    const bundles = (state.userBundles ?? {});
-    if (Object.keys(bundles).some((runtime) => !runtimeIds.has(runtime))) {
-        throw new RuntimeManagerError(code, 'Runtime global ownership bundle identity is invalid.');
-    }
-    for (const [runtime, candidate] of Object.entries(bundles)) {
-        if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)) {
-            throw new RuntimeManagerError(code, 'Runtime global ownership bundle is invalid.');
-        }
-        const bundle = candidate;
-        if (Object.keys(bundle).some((key) => ![
-            'commandPrefix',
-            'installMode',
-            'ownedFiles',
-            'pipelineVersion',
-            'runtime',
-            'scope',
-            'updatedAt',
-        ].includes(key)) ||
-            bundle.runtime !== runtime ||
-            bundle.scope !== 'user' ||
-            typeof bundle.updatedAt !== 'string' ||
-            typeof bundle.pipelineVersion !== 'string' ||
-            !['bare', 'namespaced'].includes(String(bundle.commandPrefix)) ||
-            (bundle.installMode !== undefined &&
-                !['direct', 'unified-plugin', 'project-rule'].includes(String(bundle.installMode))) ||
-            !Array.isArray(bundle.ownedFiles) ||
-            bundle.ownedFiles.some((file) => !assertOwnedFile(file)) ||
-            (runtime === 'codex' &&
-                bundle.ownedFiles.some((file) => {
-                    const target = file.target;
-                    return (!codexBookkeepingTarget(target, nativeHome) &&
-                        !pathIsWithin(target, path.join(nativeHome, 'skills')));
-                }))) {
-            throw new RuntimeManagerError(code, 'Runtime global ownership bundle is invalid.');
-        }
-    }
-    if (state.codexProfiles !== undefined) {
-        if (!state.codexProfiles ||
-            typeof state.codexProfiles !== 'object' ||
-            Array.isArray(state.codexProfiles))
-            throw new RuntimeManagerError(code, 'Codex profile ownership is invalid.');
-        for (const [key, candidate] of Object.entries(state.codexProfiles)) {
-            if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
-                throw new RuntimeManagerError(code, 'Codex profile ownership is invalid.');
-            const profile = candidate;
-            if (Object.keys(profile).some((field) => !['home', 'bundle'].includes(field)) ||
-                typeof profile.home !== 'string' ||
-                path.resolve(profile.home) !== profile.home ||
-                hash(profile.home).slice(0, 16) !== key)
-                throw new RuntimeManagerError(code, 'Codex profile identity is invalid.');
-            // Decode every record, but only inspect the selected native home's filesystem.
-            if (profile.bundle !== undefined)
-                assertRuntimeStateValue({ schemaVersion: '2.0.0', projects: {}, userBundles: { codex: profile.bundle } }, code, false, profile.home, profile.home === effectiveCodexHome());
-        }
-    }
-    const decoded = value;
-    if (inspectCustody)
-        assertRuntimeStateCustody(decoded, nativeHome);
-    return decoded;
-}
-function isUserOwnedFile(file, runtime, nativeHome = effectiveCodexHome()) {
-    if (file.scope)
-        return file.scope === 'user';
-    if (pathIsWithin(file.target, runtimeRoot()))
-        return true;
-    return runtime === 'codex' && pathIsWithin(file.target, path.join(nativeHome, 'skills'));
-}
-function projectUsesUserRuntime(project, runtime, nativeHome = effectiveCodexHome()) {
-    if (runtime === 'codex' &&
-        (project.codexHome ?? path.resolve(userHome(), '.codex')) !== nativeHome)
-        return false;
-    if (!project.runtimes.includes(runtime))
-        return false;
-    const recorded = project.runtimeScopes?.[runtime];
-    if (recorded)
-        return recorded === 'user' || recorded === 'both';
-    return project.ownedFiles.some((file) => file.runtime === runtime && isUserOwnedFile(file, runtime));
-}
-function assertRequestedProjectBinding(projectDir, key, project) {
-    const canonical = canonicalProjectPath(projectDir);
-    if (key !== projectKey(canonical) || canonicalProjectPath(project.projectDir) !== canonical) {
-        throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', 'Runtime ownership state is bound to a different canonical project.', 'Repair the project ownership record before preview, rollback, removal, or cleanup.');
-    }
-}
-function inferLegacyCodexPrefix(project, nativeHome = effectiveCodexHome()) {
-    if (!projectUsesUserRuntime(project, 'codex', nativeHome))
-        return undefined;
-    if (project.commandPrefix)
-        return project.commandPrefix;
-    const roots = project.ownedFiles
-        .filter((file) => file.runtime === 'codex' && pathIsWithin(file.target, path.join(nativeHome, 'skills')))
-        .map((file) => path.relative(path.join(nativeHome, 'skills'), file.target).split(path.sep)[0])
-        .filter(Boolean);
-    if (roots.length === 0)
-        return 'namespaced';
-    const modes = new Set(roots.map((name) => (name.startsWith('planr-') ? 'namespaced' : 'bare')));
-    if (modes.size !== 1) {
-        throw new RuntimeManagerError('E_RUNTIME_PREFIX_CONFLICT', `Legacy Codex ownership for ${project.projectDir} mixes bare and namespaced skill targets.`, 'Choose one global Codex prefix, move the other skill tree aside, and rerun setup.');
-    }
-    return [...modes][0];
-}
+export { RuntimeManagerError } from './runtime-manager/errors.js';
+export { previewHomeProjectCleanup } from './runtime-manager/global-state.js';
+export { runtimeRoot } from './runtime-manager/paths.js';
 export function inspectProjectContext(projectDir) {
     return inspectRuntimeProjectContext(projectDir);
 }
@@ -630,446 +62,11 @@ function chooseRuntimes(choice) {
     }
     return detected;
 }
-function readRegistry() {
-    const root = getPackageRoot();
-    const registryPath = path.join(root, 'lib', 'host-packages', 'adapter-registry.json');
-    if (!existsSync(registryPath)) {
-        throw new RuntimeManagerError('E_HOST_PACKAGE_MISSING', 'The OpenPlanr host-package inventory is missing.', 'Reinstall the OpenPlanr utility CLI or run the workspace skill generator.');
-    }
-    const document = JSON.parse(readFileSync(registryPath, 'utf8'));
-    return {
-        root,
-        version: document.pipelineVersion,
-        pluginVersion: document.pluginVersion,
-        registry: document,
-    };
-}
-export function bundledHostRoot(host) {
-    const cliRoot = getPackageRoot();
-    const root = path.join(cliRoot, 'lib', 'host-packages', host);
-    if (!existsSync(root) || lstatSync(root).isSymbolicLink() || !lstatSync(root).isDirectory()) {
-        throw new RuntimeManagerError('E_HOST_PACKAGE_MISSING', `The bundled ${host} OpenPlanr package is missing or unsafe.`, 'Reinstall the OpenPlanr utility CLI or run the workspace skill generator.');
-    }
-    return root;
-}
-/** Setup and doctor word a second `planr` plugin identically; neither removes it. */
-function duplicateClaudePluginDiagnostic(inspection) {
-    const managed = inspection.plugins.map((plugin) => plugin.id).join(', ');
-    const duplicates = inspection.duplicatePluginIds;
-    return {
-        message: `Duplicate Claude plugin detected: ${duplicates.join(', ')} installed beside the setup-managed ${managed}; both expose the same /planr commands`,
-        fix: `Keep one plugin. To keep the setup-managed ${managed}, run: ${duplicates
-            .map(claudePluginUninstallCommand)
-            .join(' && ')}`,
-    };
-}
-function bundledRuntimePackage(runtime) {
-    const host = runtime === 'claude-code' ? 'claude' : runtime === 'codex' ? 'openai' : 'cursor';
-    try {
-        return inspectRuntimePackage(path.join(bundledHostRoot(host), 'openplanr'), path.join(runtimeRoot(), 'packages'), host, readRegistry().pluginVersion, false);
-    }
-    catch (cause) {
-        throw new RuntimeManagerError('E_RUNTIME_PACKAGE_INVALID', `The exact ${runtime} runtime package could not be verified: ${cause instanceof Error ? cause.message : String(cause)}`, 'Reinstall the OpenPlanr CLI or regenerate its host packages.');
-    }
-}
-/** Compares the retained copy of the bundled package with its reviewed bytes. */
-function retainedRuntimePackageDrift(runtime, runtimePackage) {
-    try {
-        return retainedPackageDrift(runtimePackage);
-    }
-    catch (cause) {
-        throw new RuntimeManagerError('E_RUNTIME_PACKAGE_INVALID', `The ${runtime} runtime package ${runtimePackage.version} at ${runtimePackage.root} could not be inspected: ${cause instanceof Error ? cause.message : String(cause)}`, 'Remove the symbolic link or other unsupported entry it names, then rerun the command.');
-    }
-}
-function bundledSkillAssets(runtime, runtimePackage = bundledRuntimePackage(runtime)) {
-    const assets = [];
-    const rootName = runtime === 'cursor' ? 'rules' : 'skills';
-    for (const file of runtimePackage.files) {
-        const segments = file.relativePath.split('/');
-        if (segments[0] !== rootName)
-            continue;
-        if (runtime === 'cursor') {
-            if (segments.length !== 2 || !segments[1].endsWith('.mdc'))
-                continue;
-            const skillId = segments[1].slice(0, -'.mdc'.length);
-            assets.push({
-                skillId,
-                targetName: skillId,
-                relativePath: segments[1],
-                content: thinSkillEntry(file.content, runtimeLocator(runtimePackage, file.relativePath)),
-            });
-            continue;
-        }
-        const [, skillId, ...relative] = segments;
-        const relativePath = relative.join('/');
-        if (relativePath === 'SKILL.md') {
-            const locator = runtimeLocator(runtimePackage, file.relativePath);
-            assets.push({
-                skillId,
-                targetName: skillId,
-                relativePath,
-                content: thinSkillEntry(file.content, locator),
-            });
-            assets.push({
-                skillId,
-                targetName: skillId,
-                relativePath: 'openplanr.install.json',
-                content: Buffer.from(`${JSON.stringify(locator, null, 2)}\n`),
-            });
-        }
-        else if (relativePath === 'openplanr.skill.json' || relativePath === 'agents/openai.yaml') {
-            assets.push({
-                skillId,
-                targetName: skillId,
-                relativePath,
-                content: thinDiscoveryMetadata(relativePath, file.content),
-            });
-        }
-    }
-    return assets;
-}
-function actionBytes(action) {
-    if (action.kind === 'file')
-        return action.content;
-    const existing = existsSync(action.target) ? readFileSync(action.target, 'utf8') : '';
-    const spliced = spliceManagedBlock(existing, action.marker ?? 'runtime', action.content.toString('utf8'));
-    return Buffer.from(spliced.endsWith('\n') ? spliced : `${spliced}\n`);
-}
-function runtimeMarker(runtime, pipelineVersion) {
-    return Buffer.from(`${JSON.stringify({ schemaVersion: '1.0.0', runtime, pipelineVersion, managedBy: 'openplanr' }, null, 2)}\n`);
-}
-function normalizeInstallScope(adapter, requested) {
-    const supportsUser = adapter.installScopes.includes('user');
-    const supportsProject = adapter.installScopes.includes('project');
-    if (requested === 'user' && !supportsUser) {
-        throw new RuntimeManagerError('E_SCOPE_UNSUPPORTED', `OpenPlanr's ${adapter.id} integration currently requires project scope.`, `Change into your project, then run \`${CLI_COMMAND} setup --runtime ${adapter.id} --scope project\`. To initialize a new project there, run \`${CLI_COMMAND} init\` first.`);
-    }
-    if (requested === 'project' && !supportsProject) {
-        throw new RuntimeManagerError('E_SCOPE_UNSUPPORTED', `${adapter.id} does not support project-scope installation.`);
-    }
-    if (requested !== 'both')
-        return requested;
-    if (supportsUser && supportsProject)
-        return 'both';
-    return supportsProject ? 'project' : 'user';
-}
-function inferRuntimeScope(files, runtime, nativeHome = effectiveCodexHome()) {
-    const owned = files.filter((file) => file.runtime === runtime);
-    const hasUser = owned.some((file) => isUserOwnedFile(file, runtime, nativeHome));
-    const hasProject = owned.some((file) => !isUserOwnedFile(file, runtime, nativeHome));
-    return hasUser && hasProject ? 'both' : hasUser ? 'user' : 'project';
-}
-function skillInstallMode(runtime, options, scope) {
-    if (runtime === 'claude-code')
-        return 'unified-plugin';
-    if (runtime === 'cursor')
-        return 'project-rule';
-    if (scope === 'project' && options.projectSkillMode)
-        return options.projectSkillMode;
-    return options.skillMode ?? (options.scope === 'project' ? 'project-rule' : 'direct');
-}
-function skillInstallModes(runtimes, options, scope) {
-    return Object.fromEntries(runtimes.map((runtime) => [runtime, skillInstallMode(runtime, options, scope)]));
-}
-function runtimeLockManifestDigest(input) {
-    return `sha256:${hash(JSON.stringify({
-        protocol: input.protocolVersion,
-        pipelineVersion: input.pipelineVersion,
-        adapters: input.adapters,
-        ...(input.skillModes ? { skillModes: input.skillModes } : {}),
-    }))}`;
-}
-function buildRuntimeLock(options, runtimes, runtimeScopes, registry, pipelineVersion) {
-    const adapters = runtimes.map((runtime) => {
-        const adapter = registry.adapters.find((entry) => entry.id === runtime);
-        if (!adapter)
-            throw new RuntimeManagerError('E_ADAPTER_MISSING', `Adapter ${runtime} is absent.`);
-        const installScope = normalizeInstallScope(adapter, runtimeScopes[runtime] ?? options.scope ?? 'user');
-        return {
-            runtime,
-            version: adapter.version,
-            capabilityLevel: adapter.capabilityLevel,
-            installScope,
-        };
-    });
-    const skillModes = skillInstallModes(runtimes, options, 'project');
-    const components = {
-        cli: options.cliVersion,
-        pipeline: pipelineVersion,
-        skills: readRegistry().pluginVersion,
-    };
-    const manifestDigest = runtimeLockManifestDigest({
-        protocolVersion: registry.protocolVersion,
-        pipelineVersion,
-        adapters,
-        skillModes,
-    });
-    const lockPath = path.join(options.projectDir, PLANNING_FOLDER, 'runtime-lock.json');
-    if (existsSync(lockPath)) {
-        try {
-            const existing = JSON.parse(readFileSync(lockPath, 'utf8'));
-            if (existing.manifestDigest === manifestDigest &&
-                existing.protocolVersion === registry.protocolVersion &&
-                JSON.stringify(existing.components) === JSON.stringify(components) &&
-                JSON.stringify(existing.adapters) === JSON.stringify(adapters) &&
-                validateRuntimeLockContract(existing).length === 0) {
-                return readFileSync(lockPath);
-            }
-        }
-        catch {
-            // Invalid locks are replaced after backup during setup.
-        }
-    }
-    const lock = {
-        schemaVersion: '1.0.0',
-        generatedAt: new Date().toISOString(),
-        manifestDigest,
-        protocolVersion: registry.protocolVersion,
-        components,
-        adapters,
-        skillModes,
-    };
-    const errors = validateRuntimeLockContract(lock);
-    if (errors.length) {
-        throw new RuntimeManagerError('E_RUNTIME_LOCK_INVALID', `Generated runtime lock does not match the supported contract: ${errors[0].path} ${errors[0].detail}`, 'Reinstall the OpenPlanr CLI or regenerate its bundled runtime adapters.');
-    }
-    return Buffer.from(`${JSON.stringify(lock, null, 2)}\n`);
-}
-function buildActions(options, runtimes, runtimeScopes, retainedProject, packageRestores = []) {
-    if (options.minimal)
-        return [];
-    const { version, registry } = readRegistry();
-    if (options.version && options.version !== version) {
-        throw new RuntimeManagerError('E_VERSION_UNAVAILABLE', `Installed pipeline ${version} does not match requested ${options.version}.`, `Install an OpenPlanr CLI release that bundles workflow assets ${options.version}, then rerun setup.`);
-    }
-    const actions = [];
-    for (const runtime of runtimes) {
-        const adapter = registry.adapters.find((entry) => entry.id === runtime);
-        if (!adapter)
-            throw new RuntimeManagerError('E_ADAPTER_MISSING', `Adapter ${runtime} is absent.`);
-        const scope = normalizeInstallScope(adapter, runtimeScopes[runtime] ?? options.scope ?? 'user');
-        const installUser = (scope === 'user' || scope === 'both' || options.userScopeRuntimes?.includes(runtime)) &&
-            adapter.installScopes.includes('user');
-        const installProject = (scope === 'project' || scope === 'both') && adapter.installScopes.includes('project');
-        const userDiscovery = installUser &&
-            (runtime === 'claude-code' ||
-                (runtime === 'codex' && skillInstallMode(runtime, options) !== 'project-rule'));
-        const usesThinEntries = (installProject && !userDiscovery) ||
-            (installUser && runtime === 'codex' && skillInstallMode(runtime, options) === 'direct');
-        let skillAssets;
-        let runtimePackage;
-        try {
-            runtimePackage = bundledRuntimePackage(runtime);
-            skillAssets = bundledSkillAssets(runtime, runtimePackage);
-        }
-        catch (cause) {
-            throw new RuntimeManagerError('E_SKILL_DISTRIBUTION_INVALID', `The generated ${runtime} skill distribution is invalid: ${cause instanceof Error ? cause.message : String(cause)}`, 'Reinstall the OpenPlanr utility CLI or regenerate the host packages.');
-        }
-        if (usesThinEntries) {
-            const drift = retainedRuntimePackageDrift(runtime, runtimePackage);
-            if (drift.changed.length > 0 || drift.unexpected.length > 0) {
-                if (!options.restoreRuntimePackages) {
-                    throw new RuntimeManagerError('E_RUNTIME_PACKAGE_CHANGED', `Files in the ${runtime} runtime package ${runtimePackage.version} were changed outside OpenPlanr: ${describePackageDrift(drift)}.`, `Run \`${CLI_COMMAND} doctor --fix\` to restore the package from this CLI; the changed files are backed up first.`);
-                }
-                // A restore never deletes a name that could open a packaged file.
-                const reviewed = runtimePackage.files.map((file) => file.relativePath);
-                const caseVariants = drift.unexpected.filter((file) => caseVariantOf(file, reviewed));
-                if (caseVariants.length > 0) {
-                    throw new RuntimeManagerError('E_RUNTIME_PACKAGE_CHANGED', `Files in the ${runtime} runtime package ${runtimePackage.version} differ from packaged files only by letter case: ${caseVariants.join(', ')}.`, `OpenPlanr does not delete them. Remove them by hand, then rerun \`${CLI_COMMAND} doctor --fix\`.`);
-                }
-                packageRestores.push({
-                    runtime,
-                    version: runtimePackage.version,
-                    root: runtimePackage.root,
-                    ...drift,
-                });
-            }
-            for (const file of runtimePackage.files) {
-                actions.push({
-                    runtime: 'core',
-                    scope: 'user',
-                    target: path.join(runtimePackage.root, file.relativePath),
-                    content: file.content,
-                    kind: 'file',
-                    custody: 'runtime-package',
-                    description: `Retain exact ${runtime} runtime package ${file.relativePath}`,
-                });
-            }
-        }
-        if (installUser) {
-            if (runtime === 'codex') {
-                const mode = skillInstallMode(runtime, options);
-                if (mode === 'direct') {
-                    for (const asset of skillAssets) {
-                        actions.push({
-                            runtime,
-                            scope: 'user',
-                            target: path.join(codexSkillsRoot(), asset.targetName, asset.relativePath),
-                            content: asset.content,
-                            kind: 'file',
-                            description: `Install Codex skill asset ${asset.targetName}/${asset.relativePath}`,
-                        });
-                    }
-                }
-                if (mode !== 'project-rule') {
-                    actions.push({
-                        runtime,
-                        scope: 'user',
-                        target: path.join(codexRuntimeRoot(), 'install-modes', 'codex.json'),
-                        content: Buffer.from(`${JSON.stringify({ schemaVersion: '1.0.0', runtime, mode, sourceVersion: version }, null, 2)}\n`),
-                        kind: 'file',
-                        description: `Record Codex ${mode} skill installation mode`,
-                    });
-                }
-            }
-            actions.push({
-                runtime,
-                scope: 'user',
-                target: path.join(runtime === 'codex' ? codexRuntimeRoot() : runtimeRoot(), 'adapters', `${runtime}.json`),
-                content: runtimeMarker(runtime, version),
-                kind: 'file',
-                description: `Record ${runtime} adapter installation`,
-            });
-        }
-        if (installProject) {
-            if (userDiscovery) {
-                actions.push({
-                    runtime,
-                    scope: 'project',
-                    target: path.join(options.projectDir, PLANNING_FOLDER, 'runtime-policy', `${runtime}.json`),
-                    content: Buffer.from(`${JSON.stringify({ schemaVersion: '1.0.0', runtime, discovery: 'user', mode: skillInstallMode(runtime, options), packageDigest: runtimePackage.digest, packageVersion: runtimePackage.version }, null, 2)}\n`),
-                    kind: 'file',
-                    custody: 'professional-skill',
-                    description: `Bind project policy to the existing ${runtime} user discovery`,
-                });
-                continue;
-            }
-            if (runtime === 'codex') {
-                for (const asset of skillAssets) {
-                    actions.push({
-                        runtime,
-                        scope: 'project',
-                        target: path.join(options.projectDir, '.agents', 'skills', asset.targetName, asset.relativePath),
-                        content: asset.content,
-                        kind: 'file',
-                        custody: 'professional-skill',
-                        description: `Install project Codex skill asset ${asset.targetName}/${asset.relativePath}`,
-                    });
-                }
-            }
-            else if (runtime === 'cursor') {
-                for (const asset of skillAssets) {
-                    actions.push({
-                        runtime,
-                        scope: 'project',
-                        target: path.join(options.projectDir, '.cursor', 'rules', 'openplanr', asset.relativePath),
-                        content: asset.content,
-                        kind: 'file',
-                        custody: 'professional-skill',
-                        description: `Install Cursor rule asset ${asset.relativePath}`,
-                    });
-                }
-            }
-            else {
-                for (const asset of skillAssets) {
-                    actions.push({
-                        runtime,
-                        scope: 'project',
-                        target: path.join(options.projectDir, '.claude', 'skills', asset.targetName, asset.relativePath),
-                        content: asset.content,
-                        kind: 'file',
-                        custody: 'professional-skill',
-                        description: `Install project Claude skill asset ${asset.targetName}/${asset.relativePath}`,
-                    });
-                }
-                const agentsRoot = path.join(bundledHostRoot('claude'), 'openplanr', 'agents');
-                for (const absolutePath of inventoryRegularFiles(agentsRoot)) {
-                    const relativePath = path.relative(agentsRoot, absolutePath);
-                    actions.push({
-                        runtime,
-                        scope: 'project',
-                        target: path.join(options.projectDir, '.claude', 'agents', relativePath),
-                        content: Buffer.from(readFileSync(absolutePath, 'utf8').replaceAll('${CLAUDE_PLUGIN_ROOT}', runtimePackage.root)),
-                        kind: 'file',
-                        custody: 'professional-skill',
-                        description: `Install project Claude role agent ${relativePath}`,
-                    });
-                }
-            }
-        }
-    }
-    const lockRuntimes = [...new Set([...(retainedProject?.runtimes ?? []), ...runtimes])];
-    const lockScopes = { ...retainedProject?.runtimeScopes, ...runtimeScopes };
-    if (lockRuntimes.some((runtime) => {
-        const scope = lockScopes[runtime] ?? options.scope ?? 'user';
-        return scope === 'project' || scope === 'both';
-    })) {
-        actions.push({
-            runtime: 'core',
-            scope: 'project',
-            target: path.join(options.projectDir, PLANNING_FOLDER, 'runtime-lock.json'),
-            content: buildRuntimeLock({
-                ...options,
-                projectSkillMode: options.projectSkillMode ?? retainedProject?.skillModes?.codex,
-            }, lockRuntimes, lockScopes, registry, version),
-            kind: 'file',
-            description: 'Write exact runtime compatibility lock',
-        });
-    }
-    return actions;
-}
 function operationFor(action) {
     if (!existsSync(action.target))
         return 'create';
     return hash(readFileSync(action.target)) === hash(actionBytes(action)) ? 'unchanged' : 'update';
 }
-function isRetiredGeneratedCursorRule(target, content) {
-    const source = content.toString('utf8');
-    const parent = path.basename(path.dirname(target));
-    if (parent === 'agents') {
-        const [header, provenance] = source.split(/\r?\n/u);
-        return (header ===
-            '> **Cursor adapter — synthesized from planr-pipeline.** Agent role system prompt (body-only). Used by `/cursor/rules/planr-pipeline.mdc` for Composer subagent dispatch.' &&
-            provenance.startsWith('> Source: `planr-pipeline/agents/'));
-    }
-    const generatedFooter = source.trimEnd().split(/\r?\n/u).at(-1) ?? '';
-    const deprecatedAlias = '---\ndescription: Deprecated OpenPlanr pipeline alias\nalwaysApply: false\n---\n\nThis compatibility alias is deprecated. Use the portable `openplanr.mdc` rule.\n';
-    return ((generatedFooter.startsWith(`*Generated by \`${CLI_COMMAND} rules generate --target cursor --scope pipeline\`.`) &&
-        generatedFooter.endsWith('*')) ||
-        source === deprecatedAlias);
-}
-function planRetiredCursorProjectRules(projectDir, runtimes, runtimeScopes) {
-    if (!runtimes.includes('cursor') ||
-        !['project', 'both'].includes(runtimeScopes.cursor ?? 'project')) {
-        return [];
-    }
-    const rulesRoot = path.join(projectDir, '.cursor', 'rules');
-    const candidates = [
-        ...RETIRED_CURSOR_WORKFLOW_RULES.map((name) => path.join(rulesRoot, name)),
-        ...RETIRED_CURSOR_AGENT_RULES.map((name) => path.join(rulesRoot, 'agents', name)),
-    ];
-    return candidates.flatMap((target) => {
-        if (!existsSync(target))
-            return [];
-        const metadata = lstatSync(target);
-        if (metadata.isSymbolicLink() || !metadata.isFile()) {
-            throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Retired Cursor workflow path is not one regular generated file: ${target}.`, 'Move the foreign path aside and rerun setup.');
-        }
-        const content = readFileSync(target);
-        if (!isRetiredGeneratedCursorRule(target, content))
-            return [];
-        return [
-            {
-                runtime: 'cursor',
-                scope: 'project',
-                target,
-                content,
-                kind: 'file',
-                description: 'Retire an unreachable generated Cursor workflow copy',
-            },
-        ];
-    });
-}
 /** Files added to a retained runtime package; a restore removes them after the backup. */
 function planPackageRetirements(restores) {
     return restores.flatMap((restore) => restore.unexpected.map((file) => {
@@ -1085,11 +82,6 @@ function planPackageRetirements(restores) {
         };
     }));
 }
-function inventoryRegularFiles(root) {
-    return inventoryManagedSkillFiles(root, (message, recovery) => {
-        throw new RuntimeManagerError('E_MIGRATION_CONFLICT', message, recovery);
-    });
-}
 /** A deliberate scope narrowing retires only unchanged, previously owned project bytes. */
 function planScopeRetirements(options, project, runtimes, actions) {
     if (!project)
@@ -1137,222 +129,9 @@ function planUserBundleTransition(state, actions) {
         },
     });
 }
-/** Preserve modified or unknown professional project assets for every coding agent. */
-function assertProfessionalSkillTransition(state, projectDir, actions) {
-    const desired = actions.filter((action) => action.scope === 'project' && action.custody === 'professional-skill');
-    if (desired.length === 0)
-        return;
-    const tracked = new Map((state.projects[projectKey(projectDir)]?.ownedFiles ?? []).map((file) => [
-        path.resolve(file.target),
-        file,
-    ]));
-    for (const action of desired) {
-        assertMutableOwnedTarget(action.target, projectDir, 'E_MIGRATION_CONFLICT');
-        if (!existsSync(action.target))
-            continue;
-        const metadata = lstatSync(action.target);
-        if (metadata.isSymbolicLink() || !metadata.isFile()) {
-            throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Refusing to replace non-file professional skill target ${action.target}.`, 'Preserve or move the existing entry outside the managed skill directory before rerunning setup.');
-        }
-        const currentHash = ownershipHash(readFileSync(action.target), action.kind, action.marker);
-        const owned = tracked.get(path.resolve(action.target));
-        if (owned) {
-            if (currentHash !== owned.hash) {
-                throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Refusing to replace modified managed professional skill ${action.target}.`, 'Preserve the modified file or restore the last managed bytes before rerunning setup.');
-            }
-            continue;
-        }
-        const expectedHash = ownershipHash(actionBytes(action), action.kind, action.marker);
-        if (currentHash !== expectedHash) {
-            throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Refusing to overwrite unknown Cursor professional skill bytes at ${action.target}.`, 'Move the user-owned file aside or explicitly reconcile it before rerunning setup.');
-        }
-    }
-}
-const defaultCodexBundles = new WeakMap();
-function selectCodexProfile(state) {
-    const key = codexProfileKey();
-    if (!key)
-        return state;
-    defaultCodexBundles.set(state, state.userBundles?.codex);
-    state.userBundles ??= {};
-    const bundle = state.codexProfiles?.[key]?.bundle;
-    if (bundle)
-        state.userBundles.codex = bundle;
-    else
-        delete state.userBundles.codex;
-    return state;
-}
-/** One shared ownership file and setup lock serialize all native profiles. */
-function runtimeStateBytes(state) {
-    const key = codexProfileKey();
-    if (!key)
-        return Buffer.from(`${JSON.stringify(state, null, 2)}\n`);
-    if (!defaultCodexBundles.has(state))
-        throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', 'Codex profile state lost its default bundle.');
-    const stored = {
-        ...state,
-        userBundles: { ...state.userBundles },
-        codexProfiles: { ...state.codexProfiles },
-    };
-    stored.codexProfiles[key] = {
-        home: effectiveCodexHome(),
-        ...(state.userBundles?.codex ? { bundle: state.userBundles.codex } : {}),
-    };
-    const defaultBundle = defaultCodexBundles.get(state);
-    if (defaultBundle)
-        stored.userBundles.codex = defaultBundle;
-    else
-        delete stored.userBundles.codex;
-    return Buffer.from(`${JSON.stringify(stored, null, 2)}\n`);
-}
-function decodeStoredRuntimeState(value, allowLegacyProjectKeys = false) {
-    const defaultHome = path.resolve(userHome(), '.codex');
-    const state = assertRuntimeStateValue(value, 'E_RUNTIME_STATE_INVALID', allowLegacyProjectKeys, defaultHome);
-    migrateLegacyGlobalRuntimeState(state, {
-        inferRuntimeScope: (files, runtime) => inferRuntimeScope(files, runtime, defaultHome),
-        inferLegacyCodexPrefix: (project) => inferLegacyCodexPrefix(project, defaultHome),
-        isUserOwnedFile: (file, runtime) => isUserOwnedFile(file, runtime, defaultHome),
-        projectKey,
-        conflict: (code, message, recovery) => {
-            throw new RuntimeManagerError(code, message, recovery);
-        },
-    });
-    return assertRuntimeStateValue(selectCodexProfile(state));
-}
-async function loadState() {
-    assertApprovedTargetCustody(statePath(), runtimeRoot(), planrCustodyAnchor(), 'E_RUNTIME_STATE_INVALID', 'Runtime ownership state');
-    try {
-        return decodeStoredRuntimeState(JSON.parse(await readFile(statePath(), 'utf8')), true);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            return selectCodexProfile({ schemaVersion: '2.0.0', projects: {}, userBundles: {} });
-        }
-        if (error instanceof RuntimeManagerError)
-            throw error;
-        throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', `Runtime ownership state is invalid: ${error instanceof Error ? error.message : String(error)}`, 'Restore the recorded state backup before running setup again.');
-    }
-}
 async function resolveCommandPrefix(options) {
     return skillInstallMode('codex', options) === 'direct' ? 'bare' : 'namespaced';
 }
-async function atomicWrite(target, content, verifyCurrent) {
-    await mkdir(path.dirname(target), { recursive: true });
-    verifyCurrent?.();
-    const stagedPackage = immutableRuntimeTarget(target);
-    const stagingRoot = path.join(runtimeRoot(), 'setup-staging');
-    if (stagedPackage) {
-        assertApprovedTargetCustody(stagingRoot, runtimeRoot(), planrCustodyAnchor(), 'E_MIGRATION_CONFLICT', 'Runtime package staging');
-        await mkdir(stagingRoot, { recursive: true });
-    }
-    const temp = stagedPackage
-        ? path.join(stagingRoot, `${randomUUID()}.tmp`)
-        : `${target}.${process.pid}.tmp`;
-    const verifyStaging = () => {
-        if (stagedPackage)
-            assertApprovedTargetCustody(temp, runtimeRoot(), planrCustodyAnchor(), 'E_MIGRATION_CONFLICT', 'Runtime package staging');
-    };
-    let staged = false;
-    try {
-        verifyStaging();
-        await writeFile(temp, content, { mode: 0o600, flag: 'wx' });
-        staged = true;
-        verifyCurrent?.();
-        verifyStaging();
-        await rename(temp, target);
-        staged = false;
-    }
-    finally {
-        if (staged) {
-            verifyStaging();
-            await unlink(temp);
-        }
-    }
-}
-/** Immutable packages are retained beyond discovery rollback, including pins held by other projects or runs. */
-function immutableRuntimeTarget(target) {
-    return pathIsWithin(target, path.join(runtimeRoot(), 'packages'));
-}
-async function createBackup(projectDir, actions) {
-    const stamp = new Date().toISOString().replaceAll(':', '-');
-    const dir = assertBackupDirectoryCustody(path.join(projectBackupsRoot(projectDir), stamp), projectDir, 'E_BACKUP_FAILED');
-    const manifest = {
-        schemaVersion: '1.0.0',
-        projectDir: path.resolve(projectDir),
-        createdAt: new Date().toISOString(),
-        files: [],
-    };
-    await mkdir(dir, { recursive: true, mode: 0o700 });
-    assertBackupDirectoryCustody(dir, projectDir, 'E_BACKUP_FAILED', true);
-    for (const [index, action] of actions.entries()) {
-        assertMutableOwnedTarget(action.target, projectDir, 'E_MIGRATION_CONFLICT');
-        const entry = { target: action.target, existed: existsSync(action.target) };
-        if (entry.existed) {
-            const backup = backupEntryPath(dir, index, action.target);
-            const bytes = await readCustodiedRegularFile(action.target, () => assertMutableOwnedTarget(action.target, projectDir, 'E_MIGRATION_CONFLICT'), 'E_BACKUP_FAILED', 'Managed setup source');
-            assertApprovedTargetCustody(backup, path.join(dir, 'files'), dir, 'E_BACKUP_FAILED', 'Runtime backup file');
-            await mkdir(path.dirname(backup), { recursive: true, mode: 0o700 });
-            assertApprovedTargetCustody(path.dirname(backup), path.join(dir, 'files'), dir, 'E_BACKUP_FAILED', 'Runtime backup files directory');
-            await atomicWrite(backup, bytes);
-            assertApprovedTargetCustody(backup, path.join(dir, 'files'), dir, 'E_BACKUP_FAILED', 'Runtime backup file');
-            entry.backup = backup;
-            entry.beforeHash = hash(bytes);
-        }
-        manifest.files.push(entry);
-    }
-    const manifestPath = path.join(dir, 'migration-manifest.json');
-    assertApprovedTargetCustody(manifestPath, dir, planrCustodyAnchor(), 'E_BACKUP_FAILED', 'Runtime backup manifest');
-    await atomicWrite(manifestPath, Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`));
-    assertClosedBackupTree(dir, assertClosedBackupManifest(manifest, dir, projectDir, 'E_BACKUP_FAILED'), projectDir, 'E_BACKUP_FAILED');
-    return { dir, manifest };
-}
-function assertRestoreTargetIdentity(entry, retiredTargets) {
-    const present = existsSync(entry.target);
-    const currentHash = present ? hash(readFileSync(entry.target)) : undefined;
-    const matches = present
-        ? currentHash === entry.beforeHash || currentHash === entry.afterHash
-        : !entry.existed || retiredTargets.has(entry.target);
-    if (!matches)
-        throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Concurrent bytes prevent automatic restoration: ${entry.target}.`, 'Your current files were preserved. Compare the retained backup before retrying.');
-}
-async function restoreBackup(backup, retiredTargets) {
-    const directory = assertBackupDirectoryCustody(backup.dir, backup.manifest.projectDir, 'E_RUNTIME_STATE_INVALID', true);
-    const manifest = assertClosedBackupManifest(backup.manifest, directory, backup.manifest.projectDir, 'E_RUNTIME_STATE_INVALID');
-    assertClosedBackupTree(directory, manifest, backup.manifest.projectDir, 'E_RUNTIME_STATE_INVALID');
-    const restoreBytes = new Map();
-    for (const entry of manifest.files) {
-        assertMutableOwnedTarget(entry.target, manifest.projectDir, 'E_RUNTIME_STATE_INVALID');
-        if (immutableRuntimeTarget(entry.target))
-            continue;
-        assertRestoreTargetIdentity(entry, retiredTargets);
-        if (entry.existed) {
-            restoreBytes.set(entry.target, await readBackupEntryBytes(directory, entry, manifest.projectDir, 'E_RUNTIME_STATE_INVALID'));
-        }
-    }
-    const restored = [];
-    for (const entry of [...manifest.files].reverse()) {
-        if (immutableRuntimeTarget(entry.target))
-            continue;
-        const verifyCurrent = () => {
-            assertMutableOwnedTarget(entry.target, manifest.projectDir, 'E_RUNTIME_STATE_INVALID');
-            assertRestoreTargetIdentity(entry, retiredTargets);
-        };
-        verifyCurrent();
-        if (entry.existed && entry.backup) {
-            const bytes = restoreBytes.get(entry.target);
-            if (!bytes)
-                throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', 'Backup preflight lost validated bytes.');
-            await mkdir(path.dirname(entry.target), { recursive: true });
-            assertMutableOwnedTarget(entry.target, manifest.projectDir, 'E_RUNTIME_STATE_INVALID');
-            await atomicWrite(entry.target, bytes, verifyCurrent);
-        }
-        else if (existsSync(entry.target)) {
-            await unlink(entry.target);
-        }
-        restored.push(entry.target);
-    }
-    return restored;
-}
 export async function previewSetup(options) {
     assertNodeVersion();
     const scope = options.scope ?? 'user';
@@ -1456,7 +235,10 @@ export async function previewSetup(options) {
     const packageRetirements = planPackageRetirements(packageRestores);
     assertActionCustody([...actions, ...packageRetirements], options.projectDir);
     const scopeRetirements = planScopeRetirements(options, (await loadState()).projects[projectKey(options.projectDir)], runtimes, actions);
-    const retiredProjectRules = planRetiredCursorProjectRules(options.projectDir, runtimes, runtimeScopes);
+    const retiredProjectRules = [
+        ...planRetiredCursorProjectRules(options.projectDir, runtimes, runtimeScopes),
+        ...planRetiredClaudeProjectAgents(options.projectDir, runtimes, runtimeScopes),
+    ];
     const needsTransitionState = runtimes.includes('codex') ||
         actions.some((action) => (action.runtime === 'codex' && action.scope === 'user') ||
             action.custody === 'professional-skill');
@@ -1681,7 +463,10 @@ export async function applySetup(options) {
         assertActionCustody([...actions, ...packageRetirements], options.projectDir);
         const restoredPackageTargets = new Set(packageRestores.flatMap((restore) => restore.changed.map((file) => path.join(restore.root, file))));
         const scopeRetirements = planScopeRetirements(options, state.projects[projectKey(options.projectDir)], preview.runtimes, actions);
-        const retiredProjectRules = planRetiredCursorProjectRules(options.projectDir, preview.runtimes, preview.runtimeScopes);
+        const retiredProjectRules = [
+            ...planRetiredCursorProjectRules(options.projectDir, preview.runtimes, preview.runtimeScopes),
+            ...planRetiredClaudeProjectAgents(options.projectDir, preview.runtimes, preview.runtimeScopes),
+        ];
         const previousCodexMode = state.userBundles?.codex?.installMode ??
             (state.userBundles?.codex ? 'direct' : undefined) ??
             state.projects[projectKey(options.projectDir)]?.skillModes?.codex;
@@ -1825,7 +610,7 @@ export async function applySetup(options) {
                 if (metadata.isSymbolicLink() ||
                     !metadata.isFile() ||
                     hash(readFileSync(retired.target)) !== hash(retired.content)) {
-                    throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Retired Cursor workflow bytes changed during setup: ${retired.target}.`, 'The setup transaction restored the pre-setup bytes; inspect the file and rerun.');
+                    throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Retired project adapter bytes changed during setup: ${retired.target}.`, 'The setup transaction restored the pre-setup bytes; inspect the file and rerun.');
                 }
                 await unlink(retired.target);
                 retiredTargets.add(retired.target);
@@ -2200,18 +985,6 @@ export async function removeRuntime(runtime, projectDir) {
     await atomicWrite(statePath(), runtimeStateBytes(state));
     return { ok: true, removed, retainedShared };
 }
-function homeProjectRecord(state) {
-    return state.projects[projectKey(userHome())];
-}
-export async function previewHomeProjectCleanup() {
-    const state = await loadState();
-    const key = projectKey(userHome());
-    const project = homeProjectRecord(state);
-    if (!project || canonicalProjectPath(project.projectDir) !== canonicalProjectPath(userHome()))
-        return [];
-    assertRequestedProjectBinding(userHome(), key, project);
-    return project.ownedFiles.filter((file) => file.scope === 'project').map((file) => file.target);
-}
 export async function managedRuntimesForProject(projectDir) {
     const state = await loadState();
     const key = projectKey(projectDir);
@@ -2303,449 +1076,13 @@ export async function cleanupHomeProjectInstall() {
     await atomicWrite(statePath(), runtimeStateBytes(state));
     return { ok: true, removed };
 }
-export async function runtimeDoctor(projectDir, options = {}) {
-    const diagnostics = [];
-    const repairs = [];
-    let lockedAdapters;
-    const supportedNode = supportsCliNodeVersion(process.versions.node);
-    diagnostics.push({
-        code: 'node-version',
-        status: supportedNode ? 'pass' : 'fail',
-        message: supportedNode
-            ? `Node.js ${process.versions.node}`
-            : cliNodeVersionMessage(process.versions.node),
-        ...(!supportedNode ? { fix: CLI_NODE_REMEDIATION } : {}),
-    });
-    const state = await loadState();
-    const installed = state.projects[projectKey(projectDir)];
-    const detectedRuntimes = detectRuntimes();
-    for (const result of detectedRuntimes) {
-        const configured = installed?.runtimes.includes(result.runtime) ?? false;
-        diagnostics.push({
-            code: `runtime-${result.runtime}`,
-            status: result.installed || !configured ? 'pass' : 'warn',
-            message: result.installed
-                ? `${result.runtime} detected`
-                : configured
-                    ? `${result.runtime} is configured but not detected`
-                    : `${result.runtime} is not installed or configured`,
-            ...(!result.installed && configured
-                ? { fix: `Install ${result.command} only if you intend to use this adapter.` }
-                : {}),
-        });
-    }
-    const pipeline = resolvePipelinePackage(false);
-    diagnostics.push({
-        code: 'pipeline-package',
-        status: pipeline ? 'pass' : 'warn',
-        message: pipeline
-            ? `Optional deterministic pipeline utilities ${pipeline.version}`
-            : 'Optional deterministic pipeline utilities are not installed',
-        ...(!pipeline
-            ? { fix: 'Install optional dependencies only if you need pipeline utilities.' }
-            : {}),
-    });
-    const registry = listRuntimeAdapters();
-    for (const adapter of registry) {
-        const detected = detectedRuntimes.find((entry) => entry.runtime === adapter.id)?.installed;
-        const configured = installed?.runtimes.includes(adapter.id) ?? false;
-        if (!detected && !configured)
-            continue;
-        const mode = adapter.capabilities?.interactiveQuestions;
-        diagnostics.push({
-            code: `runtime-interaction-${adapter.id}`,
-            status: mode ? 'pass' : 'fail',
-            message: mode
-                ? `${adapter.id} uses ${mode} host-native questions`
-                : `${adapter.id} does not declare a host-native question capability`,
-            ...(!mode ? { fix: 'Reinstall the OpenPlanr utility CLI host package.' } : {}),
-        });
-    }
-    try {
-        const counts = {
-            claude: new Set(bundledSkillAssets('claude-code').map(({ skillId }) => skillId)).size,
-            codex: new Set(bundledSkillAssets('codex').map(({ skillId }) => skillId)).size,
-            cursor: new Set(bundledSkillAssets('cursor').map(({ skillId }) => skillId)).size,
-        };
-        const uniqueCounts = new Set(Object.values(counts));
-        const current = uniqueCounts.size === 1 && counts.claude > 0;
-        diagnostics.push({
-            code: 'host-skill-packages',
-            status: current ? 'pass' : 'fail',
-            message: current
-                ? `Claude Code, Codex, and Cursor each expose all ${counts.claude} host-native skills`
-                : `Host skill package membership drifted (${JSON.stringify(counts)})`,
-            ...(!current ? { fix: 'Reinstall the CLI or regenerate its host packages.' } : {}),
-        });
-    }
-    catch (cause) {
-        diagnostics.push({
-            code: 'host-skill-packages',
-            status: 'fail',
-            message: cause instanceof Error ? cause.message : String(cause),
-            fix: 'Reinstall the CLI or regenerate its host packages.',
-        });
-    }
-    const claudeManagedAtUserScope = Object.values(state.projects).some((project) => project.runtimes.includes('claude-code') &&
-        ['user', 'both'].includes(project.runtimeScopes?.['claude-code'] ??
-            inferRuntimeScope(project.ownedFiles, 'claude-code')));
-    const pluginSkillDocuments = [];
-    const claudeDetected = Boolean(options.claudeCommandRunner) ||
-        (detectedRuntimes.find((runtime) => runtime.runtime === 'claude-code')?.installed ?? false);
-    if (claudeDetected && claudeManagedAtUserScope) {
-        const inspection = inspectBundledClaudePluginIntegration(bundledHostRoot('claude'), options.claudeCommandRunner);
-        if (inspection.error) {
-            diagnostics.push({
-                code: 'runtime-claude-plugins',
-                status: 'fail',
-                message: `Claude plugin state could not be inspected: ${inspection.error}`,
-                fix: `Update Claude Code, then run \`${CLI_COMMAND} runtime update claude --scope user\`.`,
-            });
-        }
-        else {
-            for (const root of [
-                ...inspection.plugins.flatMap((plugin) => plugin.installPath ?? []),
-                ...inspection.duplicatePluginPaths,
-            ]) {
-                pluginSkillDocuments.push(...pluginDocuments('claude-code', root));
-            }
-            const drift = inspection.plugins.filter((plugin) => !plugin.installed ||
-                !plugin.enabled ||
-                !plugin.identityValid ||
-                plugin.installedVersion !== plugin.expectedVersion);
-            diagnostics.push({
-                code: 'runtime-claude-plugins',
-                status: inspection.ready ? 'pass' : 'fail',
-                message: inspection.ready
-                    ? `Claude plugins match compatibility versions (${inspection.plugins
-                        .map((plugin) => `${plugin.name} ${plugin.expectedVersion}`)
-                        .join(', ')})`
-                    : `Claude plugin drift detected: ${drift
-                        .map((plugin) => `${plugin.id} ${plugin.installedVersion ?? 'missing'} → ${plugin.expectedVersion}${!plugin.identityValid ? ' (invalid identity)' : ''}`)
-                        .join(', ')}`,
-                ...(!inspection.ready
-                    ? {
-                        fix: `Run \`${CLI_COMMAND} runtime update claude --scope user\` and restart Claude Code.`,
-                    }
-                    : {}),
-            });
-            if (inspection.staleMarketplacePath) {
-                diagnostics.push({
-                    code: 'runtime-claude-marketplace-path',
-                    status: 'fail',
-                    message: `The local OpenPlanr Claude marketplace points to another install: ${inspection.staleMarketplacePath}, not ${bundledHostRoot('claude')}`,
-                    fix: `Run \`${CLI_COMMAND} setup --runtime claude --scope user\` to point it at this install.`,
-                });
-            }
-            if (inspection.legacyPluginIds.length > 0) {
-                diagnostics.push({
-                    code: 'runtime-claude-legacy-plugin',
-                    status: 'warn',
-                    message: `Legacy Claude plugin installation detected: ${inspection.legacyPluginIds.join(', ')}`,
-                    fix: 'Verify `planr@openplanr-local`, then remove the legacy plugin from Claude Code.',
-                });
-            }
-            if (inspection.duplicatePluginIds.length > 0) {
-                diagnostics.push({
-                    code: 'runtime-claude-duplicate-plugin',
-                    status: 'warn',
-                    ...duplicateClaudePluginDiagnostic(inspection),
-                });
-            }
-        }
-    }
-    const expectsProjectLock = installed?.ownedFiles.some((file) => file.scope === 'project') ?? false;
-    const lock = path.join(projectDir, PLANNING_FOLDER, 'runtime-lock.json');
-    if (!existsSync(lock)) {
-        // User-scope setup is recorded under the directory it ran in but serves every project.
-        const managed = Boolean(installed) ||
-            Object.values(state.projects).some((project) => project.runtimes.some((runtime) => projectUsesUserRuntime(project, runtime)));
-        const lockStatus = expectsProjectLock ? 'warn' : managed ? 'pass' : 'warn';
-        diagnostics.push({
-            code: 'runtime-lock',
-            status: lockStatus,
-            message: expectsProjectLock
-                ? 'Project runtime lock missing'
-                : managed
-                    ? 'User-scope setup does not require a project runtime lock'
-                    : 'No managed runtime setup found for this directory',
-            ...(expectsProjectLock
-                ? { fix: `Run \`${CLI_COMMAND} setup --scope project\`.` }
-                : !managed
-                    ? { fix: `Run \`${CLI_COMMAND} setup\`.` }
-                    : {}),
-        });
-    }
-    else {
-        try {
-            const value = JSON.parse(readFileSync(lock, 'utf8'));
-            const errors = validateRuntimeLockContract(value);
-            if (errors.length) {
-                throw new RuntimeManagerError('E_RUNTIME_LOCK_INVALID', 'Project runtime lock does not match the supported contract.');
-            }
-            lockedAdapters = value.adapters;
-            const cliVersion = readOpenPlanrVersion();
-            const cliDrift = value.components?.cli !== cliVersion;
-            const componentDrift = cliDrift ||
-                (pipeline && value.components?.pipeline !== pipeline.version) ||
-                value.components?.skills !== readRegistry().pluginVersion;
-            const expectedDigest = runtimeLockManifestDigest({
-                protocolVersion: value.protocolVersion,
-                pipelineVersion: value.components?.pipeline,
-                adapters: value.adapters,
-                skillModes: value.skillModes,
-            });
-            const digestDrift = value.manifestDigest !== expectedDigest;
-            const registry = listRuntimeAdapters();
-            const adapterDrift = (value.adapters ?? []).some((locked) => {
-                const current = registry.find((adapter) => adapter.id === locked.runtime);
-                return (!current ||
-                    current.version !== locked.version ||
-                    current.capabilityLevel !== locked.capabilityLevel);
-            });
-            // An OpenPlanr upgrade advances the CLI version the lock recorded.
-            // When the CLI component trails the installed build and nothing that
-            // governs runtime dispatch (runtime adapters, manifest digest)
-            // diverged, the lock is simply behind an expected upgrade — surface it as
-            // an informational `warn`, not a `fail` implying the board is broken. A
-            // digest/adapter drift, or a component drift that does not include the CLI
-            // (for example a pinned obsolete skill bundle), remains a genuine `fail`.
-            // The warn/fail derivation lives in the single `classifyComponentDrift`
-            // helper so `openplanr upgrade status` reuses this exact distinction rather
-            // than re-deriving it; a digest/adapter drift is doctor's
-            // flavour of an incompatible tuple.
-            const { drift, genuineDrift, upgradeOnlyDrift, status } = classifyRuntimeComponentDrift({
-                cliDrift,
-                componentDrift: Boolean(componentDrift),
-                incompatibleDrift: digestDrift || adapterDrift,
-            });
-            diagnostics.push({
-                code: drift ? 'lock-drift' : 'runtime-lock',
-                status,
-                message: genuineDrift
-                    ? `Runtime lock drift detected (components: ${componentDrift}, digest: ${digestDrift}, adapters: ${adapterDrift})`
-                    : upgradeOnlyDrift
-                        ? `Runtime lock component versions trail an OpenPlanr upgrade (components: ${componentDrift}); this is expected after upgrading and does not affect runtime execution`
-                        : drift
-                            ? `Runtime lock drift detected (components: ${componentDrift}, digest: ${digestDrift}, adapters: ${adapterDrift})`
-                            : 'Project runtime lock matches installed component versions',
-                ...(drift
-                    ? {
-                        fix: upgradeOnlyDrift
-                            ? `Run \`${CLI_COMMAND} runtime update all --scope project\` to refresh the lock to the upgraded component versions.`
-                            : `Run \`${CLI_COMMAND} runtime update all --scope project\`.`,
-                    }
-                    : {}),
-            });
-        }
-        catch {
-            diagnostics.push({
-                code: 'runtime-lock-invalid',
-                status: 'fail',
-                message: 'Project runtime lock is not valid JSON or does not match the supported contract',
-                fix: `Run \`${CLI_COMMAND} setup --scope project\` after reviewing the existing lock.`,
-            });
-        }
-    }
-    if (installed) {
-        if (lockedAdapters) {
-            const lockedState = lockedAdapters
-                .map((adapter) => `${adapter.runtime}:${adapter.installScope}`)
-                .sort();
-            const installedState = installed.runtimes
-                .map((runtime) => `${runtime}:${installed.runtimeScopes?.[runtime] ?? inferRuntimeScope(installed.ownedFiles, runtime)}`)
-                .sort();
-            const stateDrift = JSON.stringify(lockedState) !== JSON.stringify(installedState);
-            diagnostics.push({
-                code: stateDrift ? 'lock-state-drift' : 'lock-state',
-                status: stateDrift ? 'fail' : 'pass',
-                message: stateDrift
-                    ? 'Runtime lock adapters do not match the managed installation state'
-                    : 'Runtime lock adapters match the managed installation state',
-                ...(stateDrift
-                    ? { fix: `Run \`${CLI_COMMAND} setup --dry-run\`, then approve the repair.` }
-                    : {}),
-            });
-        }
-    }
-    else if (lockedAdapters?.length) {
-        diagnostics.push({
-            code: 'runtime-state-missing',
-            status: 'warn',
-            message: 'The project has a runtime lock but this machine has no managed adapter state',
-            fix: `Run \`${CLI_COMMAND} setup\` to install the locked runtime adapters on this machine.`,
-        });
-    }
-    const globallyOwned = Object.values(state.userBundles ?? {}).flatMap((bundle) => bundle?.ownedFiles ?? []);
-    const managedFiles = [
-        ...(installed?.ownedFiles ?? []),
-        ...globallyOwned.filter((file, index, files) => files.findIndex((candidate) => candidate.target === file.target) === index),
-    ];
-    const managedFileDiagnostic = diagnoseManagedRuntimeFiles(managedFiles, ownershipHash);
-    if (managedFileDiagnostic)
-        diagnostics.push(managedFileDiagnostic);
-    const commandDiagnostic = diagnoseRetiredCommandSkills([...managedFiles, ...pluginSkillDocuments], options.commandRoots ?? [], managedBlockBytes);
-    if (commandDiagnostic)
-        diagnostics.push(commandDiagnostic);
-    const verifiedPackages = new Map();
-    const closureFailures = [];
-    for (const file of managedFiles) {
-        try {
-            if (path.basename(file.target) === 'openplanr.install.json')
-                inspectRuntimeLocator(path.dirname(file.target), verifiedPackages);
-            else if (file.runtime === 'cursor' && file.target.endsWith('.mdc'))
-                inspectThinRule(file.target, verifiedPackages);
-        }
-        catch (cause) {
-            closureFailures.push(`${file.target}: ${cause instanceof Error ? cause.message : String(cause)}`);
-        }
-    }
-    if (verifiedPackages.size || closureFailures.length)
-        diagnostics.push({
-            code: 'runtime-package-custody',
-            status: closureFailures.length ? 'fail' : 'pass',
-            message: closureFailures.length
-                ? `Pinned runtime package verification failed: ${closureFailures.join('; ')}`
-                : 'Pinned runtime packages match their complete content inventories',
-            ...(closureFailures.length
-                ? {
-                    fix: `Run \`${CLI_COMMAND} doctor --fix\` to preview the repair; changed package files are backed up before anything is replaced.`,
-                }
-                : {}),
-        });
-    let codexDiscovery;
-    const codexBundle = state.userBundles?.codex;
-    if (options.codexCommandRunner ||
-        detectedRuntimes.some((runtime) => runtime.runtime === 'codex' && runtime.installed)) {
-        const configuredMode = codexBundle?.installMode ?? installed?.skillModes?.codex ?? 'direct';
-        const inspection = inspectCodexPluginIntegration(bundledHostRoot('openai'), configuredMode, configuredMode, options.codexCommandRunner);
-        codexDiscovery = inspectCodexSkillDiscovery({
-            hostPackageRoot: bundledHostRoot('openai'),
-            projectDir,
-            mode: configuredMode,
-            packageVersion: readOpenPlanrVersion(),
-            ownershipStatePath: statePath(),
-            activePlugin: inspection.installed
-                ? { id: inspection.pluginId, version: inspection.installedVersion }
-                : undefined,
-        });
-        diagnostics.push({
-            code: 'runtime-codex-profile',
-            status: 'pass',
-            message: `Effective Codex profile: ${codexDiscovery.effectiveHome}; ownership: ${statePath()}`,
-        });
-        const stale = codexDiscovery.skills.filter((skill) => skill.resolution === 'stale');
-        const ambiguous = codexDiscovery.skills.filter((skill) => skill.resolution === 'ambiguous');
-        const missing = codexDiscovery.skills.filter((skill) => skill.resolution === 'missing');
-        const unreadable = codexDiscovery.skills.filter((skill) => skill.resolution === 'unreadable');
-        const oldCaches = codexDiscovery.skills.filter((skill) => skill.copies.some((copy) => copy.kind === 'plugin-cache' && !copy.current && copy.enabled !== true));
-        if (stale.length ||
-            ambiguous.length ||
-            missing.length ||
-            unreadable.length ||
-            codexDiscovery.issues.length) {
-            diagnostics.push({
-                code: 'runtime-codex-skill-resolution',
-                status: 'warn',
-                message: `${stale.length} stale skill(s), ${missing.length} missing skill(s), ${unreadable.length} unreadable skill(s), ${ambiguous.length} multiple discovery path(s), ${oldCaches.length} skill(s) with inactive cached copies. CLI package ${codexDiscovery.packageVersion}; per-skill and Protocol versions, paths and closure hashes are in doctor --json. An already-open session may retain earlier skills.`,
-                fix: `Run \`${CLI_COMMAND} setup --runtime codex --dry-run\` in this profile, review the installer repair, then restart Codex. Do not delete plugin caches by hand.`,
-            });
-        }
-        if (oldCaches.length > 0) {
-            diagnostics.push({
-                code: 'runtime-codex-cache-history',
-                status: 'pass',
-                message: `${oldCaches.length} skill(s) have inactive cached copies. These do not imply enabled duplicates; restart Codex if an open session still shows earlier skills.`,
-            });
-        }
-        const directSkillFiles = codexBundle?.ownedFiles.filter((file) => pathIsWithin(file.target, codexSkillsRoot()))
-            .length ?? 0;
-        if (inspection.error) {
-            diagnostics.push({
-                code: 'runtime-codex-plugin',
-                status: 'warn',
-                message: `Codex plugin state could not be inspected: ${inspection.error}`,
-                fix: `Run \`${CLI_COMMAND} setup --runtime codex --dry-run\` for an exact repair preview.`,
-            });
-        }
-        else {
-            diagnostics.push({
-                code: 'runtime-codex-install-mode',
-                status: inspection.ready ? 'pass' : 'warn',
-                message: inspection.ready
-                    ? `Codex ${configuredMode} discovery is current`
-                    : inspection.operations.length > 0
-                        ? `Codex ${configuredMode} discovery needs repair: ${inspection.operations.map((operation) => operation.description).join('; ')}`
-                        : `Codex ${configuredMode} discovery has conflicting enabled registrations: ${inspection.duplicates.join(', ')}`,
-                ...(inspection.ready
-                    ? {}
-                    : {
-                        fix: `Run \`${CLI_COMMAND} doctor --fix\` to preview repairs while preserving your saved discovery choice.`,
-                    }),
-            });
-            if ((directSkillFiles > 0 && inspection.installed) || inspection.duplicates.length > 0) {
-                diagnostics.push({
-                    code: 'runtime-codex-duplicate-discovery',
-                    status: 'warn',
-                    message: `Codex has duplicate OpenPlanr discovery ownership${inspection.duplicates.length ? `: ${inspection.duplicates.join(', ')}` : ' across direct skills and the unified plugin'}`,
-                    fix: 'Choose direct or unified-plugin mode, preview setup, and use --replace-managed only for manifest-owned content.',
-                });
-            }
-        }
-    }
-    const accidentalHomeFiles = await previewHomeProjectCleanup();
-    if (accidentalHomeFiles.length > 0) {
-        diagnostics.push({
-            code: 'home-project-install',
-            status: 'warn',
-            message: `${accidentalHomeFiles.length} project-scoped managed file(s) were installed in the home directory`,
-            fix: `Run \`${CLI_COMMAND} doctor --fix\` to preview and remove only recorded OpenPlanr-owned project content.`,
-        });
-    }
-    const provenanceDiagnostic = diagnoseRuntimeProvenance(projectDir);
-    if (provenanceDiagnostic)
-        diagnostics.push(provenanceDiagnostic);
-    if (pipeline) {
-        // The child gets the resolved home only, so it does not repeat the OPENPLANR_HOME warning.
-        const { OPENPLANR_HOME: _deprecatedHome, ...inheritedEnvironment } = process.env;
-        const result = spawnSync(process.execPath, [
-            path.join(pipeline.root, 'scripts', 'doctor.mjs'),
-            '--json',
-            ...(options.pipelineRepair === 'preview' ? ['--repair-preview'] : []),
-            ...(options.pipelineRepair === 'apply' ? ['--fix'] : []),
-        ], {
-            cwd: projectDir,
-            encoding: 'utf8',
-            windowsHide: true,
-            env: { ...inheritedEnvironment, PLANR_HOME: planrHome() },
-        });
-        try {
-            const report = JSON.parse(result.stdout);
-            repairs.push(...(report.repairs ?? []));
-            for (const check of report.checks ?? []) {
-                if (check.status === 'ok')
-                    continue;
-                diagnostics.push({
-                    code: `pipeline-${check.id}`,
-                    status: check.status,
-                    message: check.message,
-                    ...(check.fix ? { fix: check.fix } : {}),
-                });
-            }
-        }
-        catch {
-            diagnostics.push({
-                code: 'pipeline-doctor-unavailable',
-                status: 'warn',
-                message: 'The pipeline doctor did not return valid JSON',
-                fix: `Run \`${CLI_COMMAND} doctor\` for direct diagnostics.`,
-            });
-        }
-    }
-    const fail = diagnostics.some((item) => item.status === 'fail');
-    return { ok: !fail, diagnostics, repairs, ...(codexDiscovery ? { codexDiscovery } : {}) };
-}
 export async function clearRuntimeStateForTests(root) {
     await rm(root, { recursive: true, force: true });
 }
+export function bundledHostRoot(host) {
+    return resolveBundledHostRoot(host);
+}
+export async function runtimeDoctor(projectDir, options = {}) {
+    return inspectRuntimeDoctor(projectDir, options);
+}
 //# sourceMappingURL=runtime-manager-service.js.map