openplanr 1.25.3 → 2.0.1

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

@@ -1,17 +1,36 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from 'node:fs';
-import { copyFile, mkdir, open, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises';
+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 os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { spliceManagedBlock } from '../utils/splice-managed-block.js';
-import { applyClaudePluginIntegration, inspectClaudePluginIntegration, OPENPLANR_SKILLS_VERSION, } from './claude-plugin-service.js';
-import { diagnoseOperatingBoard } from './operate/doctor.js';
-import { purgeAbandonedOperatingScratch } from './operate/maintenance.js';
-import { listAbandonedOperatingScratch, } from './operate/scratch.js';
-import { resolveOperatingPaths } from './operate/workspace.js';
+import { applyBundledClaudePluginIntegration, 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 { classifyComponentDrift as classifyRuntimeComponentDrift, diagnoseManagedRuntimeFiles, diagnoseRuntimeProvenance, } 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, } from './runtime-manager/inventory.js';
+export { classifyComponentDrift } from './runtime-manager/doctor.js';
+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;
@@ -25,40 +44,6 @@ export class RuntimeManagerError extends Error {
         return { ok: false, code: this.code, problem: this.message, recovery: this.recovery };
     }
 }
-const executable = {
-    'claude-code': 'claude',
-    codex: 'codex',
-    cursor: 'cursor',
-};
-const skillNames = [
-    'planr-plan',
-    'planr-design',
-    'planr-ship',
-    'planr-dashboard',
-    'planr-sync',
-    'planr-doctor',
-    'planr-artifact',
-    'planr-operate',
-];
-/**
- * FR5: derive an installed command/skill name from the persisted prefix choice.
- * `bare` strips the leading `planr-` namespace (`planr-plan` → `plan`); `namespaced`
- * keeps today's names verbatim, so an install that never opts in is byte-identical
- * to before this toggle existed.
- */
-function applyCommandPrefix(name, commandPrefix) {
-    return commandPrefix === 'bare' && name.startsWith('planr-') ? name.slice('planr-'.length) : name;
-}
-/**
- * Rewrite only the frontmatter `name:` line of a copied Codex skill so its embedded
- * identifier matches the bare install directory. The match is anchored to the line
- * start and consumes the whole `planr-…` name, so a `planr-` mention elsewhere in the
- * body is never touched; a non-global replace only rewrites the first (frontmatter)
- * line.
- */
-function rewriteSkillFrontmatterName(content, installName) {
-    return content.replace(/^name:[ \t]*planr-[\w-]+[ \t]*$/mu, `name: ${installName}`);
-}
 function hash(value) {
     return createHash('sha256').update(value).digest('hex');
 }
@@ -75,8 +60,19 @@ function managedBlockBytes(content, marker = 'runtime') {
 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(path.resolve(projectDir)).slice(0, 16);
+    return hash(canonicalProjectPath(projectDir)).slice(0, 16);
 }
 export function runtimeRoot() {
     return path.join(userHome(), '.planr', 'runtime');
@@ -87,38 +83,451 @@ function userHome() {
 function statePath() {
     return path.join(runtimeRoot(), 'state.json');
 }
-function detectCommand(command) {
-    const result = spawnSync(command, ['--version'], { encoding: 'utf8', windowsHide: true });
-    return !result.error && result.status === 0;
+function codexSkillsRoot() {
+    return path.join(userHome(), '.codex', 'skills');
 }
-export function inspectProjectContext(projectDir) {
-    const resolved = path.resolve(projectDir);
-    if (existsSync(path.join(resolved, '.planr', 'config.json'))) {
-        return { valid: true, path: resolved, reason: 'planr' };
+function backupsRoot() {
+    return path.join(userHome(), '.planr', '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(), userHome(), code, 'Global runtime ownership');
+        return;
+    }
+    if (pathIsWithin(target, codexSkillsRoot())) {
+        assertApprovedTargetCustody(target, codexSkillsRoot(), userHome(), 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, userHome(), 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 git = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
-        cwd: resolved,
-        encoding: 'utf8',
-        windowsHide: true,
+    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 } : {}),
+        };
     });
-    if (!git.error && git.status === 0 && git.stdout.trim() === 'true') {
-        return { valid: true, path: resolved, reason: 'git' };
+    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, userHome(), 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') {
+    if (pathIsWithin(file.target, runtimeRoot())) {
+        assertApprovedTargetCustody(file.target, runtimeRoot(), userHome(), code, 'Global runtime ownership');
+        return;
+    }
+    if (runtime === 'codex' && pathIsWithin(file.target, codexSkillsRoot())) {
+        assertApprovedTargetCustody(file.target, codexSkillsRoot(), userHome(), 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) {
+    for (const runtime of ['claude-code', 'codex', 'cursor']) {
+        for (const file of state.userBundles?.[runtime]?.ownedFiles ?? []) {
+            assertUserOwnedTarget(file, runtime);
+        }
+    }
+    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);
+            }
+            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) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new RuntimeManagerError(code, 'Runtime ownership state is not one closed object.');
     }
-    return { valid: false, path: resolved, reason: 'none' };
+    const state = value;
+    if (Object.keys(state).some((key) => !['projects', 'schemaVersion', 'userBundles'].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',
+            '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' ||
+            !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))) {
+            throw new RuntimeManagerError(code, 'Runtime global ownership bundle is invalid.');
+        }
+    }
+    const decoded = value;
+    assertRuntimeStateCustody(decoded);
+    return decoded;
+}
+function isUserOwnedFile(file, runtime) {
+    if (file.scope)
+        return file.scope === 'user';
+    if (pathIsWithin(file.target, runtimeRoot()))
+        return true;
+    return runtime === 'codex' && pathIsWithin(file.target, codexSkillsRoot());
+}
+function projectUsesUserRuntime(project, runtime) {
+    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) {
+    if (!projectUsesUserRuntime(project, 'codex'))
+        return undefined;
+    if (project.commandPrefix)
+        return project.commandPrefix;
+    const roots = project.ownedFiles
+        .filter((file) => file.runtime === 'codex' && pathIsWithin(file.target, codexSkillsRoot()))
+        .map((file) => path.relative(codexSkillsRoot(), 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 function inspectProjectContext(projectDir) {
+    return inspectRuntimeProjectContext(projectDir);
 }
 export function detectRuntimes() {
-    return Object.keys(executable).map((runtime) => ({
-        runtime,
-        installed: detectCommand(executable[runtime]),
-        command: executable[runtime],
-    }));
+    return detectInstalledRuntimes();
 }
 export function listRuntimeAdapters() {
-    const pipeline = resolvePipelinePackage(false);
-    if (!pipeline)
-        return [];
-    const registry = JSON.parse(readFileSync(pipeline.adapterRegistryPath, 'utf8'));
-    return registry.adapters.map((adapter) => structuredClone(adapter));
+    return listInstalledRuntimeAdapters();
 }
 function assertNodeVersion() {
     const major = Number(process.versions.node.split('.')[0]);
@@ -148,20 +557,54 @@ function chooseRuntimes(choice) {
     return detected;
 }
 function readRegistry() {
-    const pipeline = resolvePipelinePackage();
-    if (!pipeline)
-        throw new RuntimeManagerError('E_PIPELINE_NOT_INSTALLED', 'Pipeline missing.');
+    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    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: pipeline.root,
-        version: pipeline.version,
-        registry: JSON.parse(readFileSync(pipeline.adapterRegistryPath, 'utf8')),
+        root,
+        version: document.pipelineVersion,
+        pluginVersion: document.pluginVersion,
+        registry: document,
     };
 }
-function managedContent(text) {
-    return text
-        .replace(/^<!-- openplanr:runtime:start -->\s*/m, '')
-        .replace(/\s*<!-- openplanr:runtime:end -->\s*$/m, '')
-        .trim();
+function bundledHostRoot(host) {
+    const cliRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    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;
+}
+function bundledSkillAssets(runtime) {
+    if (runtime === 'cursor') {
+        const rulesRoot = path.join(bundledHostRoot('cursor'), 'openplanr', 'rules');
+        return inventoryRegularFiles(rulesRoot).map((absolutePath) => {
+            const relativePath = path.relative(rulesRoot, absolutePath);
+            const first = relativePath.split(path.sep)[0];
+            const skillId = first.endsWith('.mdc') ? first.slice(0, -'.mdc'.length) : first;
+            return {
+                skillId,
+                targetName: skillId,
+                relativePath,
+                content: readFileSync(absolutePath),
+            };
+        });
+    }
+    const host = runtime === 'claude-code' ? 'claude' : 'openai';
+    const skillsRoot = path.join(bundledHostRoot(host), 'openplanr', 'skills');
+    return inventoryRegularFiles(skillsRoot).map((absolutePath) => {
+        const sourcePath = path.relative(skillsRoot, absolutePath);
+        const [skillId, ...segments] = sourcePath.split(path.sep);
+        return {
+            skillId,
+            targetName: skillId,
+            relativePath: segments.join(path.sep),
+            content: readFileSync(absolutePath),
+        };
+    });
 }
 function actionBytes(action) {
     if (action.kind === 'file')
@@ -190,10 +633,28 @@ function normalizeInstallScope(adapter, requested) {
 }
 function inferRuntimeScope(files, runtime) {
     const owned = files.filter((file) => file.runtime === runtime);
-    const hasUser = owned.some((file) => file.scope === 'user' || (!file.scope && file.target.startsWith(runtimeRoot())));
-    const hasProject = owned.some((file) => file.scope === 'project' || (!file.scope && !file.target.startsWith(runtimeRoot())));
+    const hasUser = owned.some((file) => isUserOwnedFile(file, runtime));
+    const hasProject = owned.some((file) => !isUserOwnedFile(file, runtime));
     return hasUser && hasProject ? 'both' : hasUser ? 'user' : 'project';
 }
+function skillInstallMode(runtime, options) {
+    if (runtime === 'claude-code')
+        return 'unified-plugin';
+    if (runtime === 'cursor')
+        return 'project-rule';
+    return options.skillMode ?? (options.scope === 'project' ? 'project-rule' : 'direct');
+}
+function skillInstallModes(runtimes, options) {
+    return Object.fromEntries(runtimes.map((runtime) => [runtime, skillInstallMode(runtime, options)]));
+}
+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);
@@ -207,17 +668,18 @@ function buildRuntimeLock(options, runtimes, runtimeScopes, registry, pipelineVe
             installScope,
         };
     });
-    const digestInput = JSON.stringify({
-        protocol: registry.protocolVersion,
-        pipelineVersion,
-        adapters,
-    });
+    const skillModes = skillInstallModes(runtimes, options);
     const components = {
         cli: options.cliVersion,
         pipeline: pipelineVersion,
-        skills: OPENPLANR_SKILLS_VERSION,
+        skills: readRegistry().pluginVersion,
     };
-    const manifestDigest = `sha256:${hash(digestInput)}`;
+    const manifestDigest = runtimeLockManifestDigest({
+        protocolVersion: registry.protocolVersion,
+        pipelineVersion,
+        adapters,
+        skillModes,
+    });
     const lockPath = path.join(options.projectDir, '.planr', 'runtime-lock.json');
     if (existsSync(lockPath)) {
         try {
@@ -240,12 +702,13 @@ function buildRuntimeLock(options, runtimes, runtimeScopes, registry, pipelineVe
         protocolVersion: registry.protocolVersion,
         components,
         adapters,
+        skillModes,
     }, null, 2)}\n`);
 }
-function buildActions(options, runtimes, runtimeScopes, commandPrefix) {
+function buildActions(options, runtimes, runtimeScopes) {
     if (options.minimal)
         return [];
-    const { root, version, registry } = readRegistry();
+    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 planr-pipeline@${options.version} and rerun setup.`);
     }
@@ -257,21 +720,36 @@ function buildActions(options, runtimes, runtimeScopes, commandPrefix) {
         const scope = normalizeInstallScope(adapter, runtimeScopes[runtime] ?? options.scope ?? 'user');
         const installUser = (scope === 'user' || scope === 'both') && adapter.installScopes.includes('user');
         const installProject = (scope === 'project' || scope === 'both') && adapter.installScopes.includes('project');
+        let skillAssets;
+        try {
+            skillAssets = bundledSkillAssets(runtime);
+        }
+        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 (installUser) {
             if (runtime === 'codex') {
-                for (const name of skillNames) {
-                    const installName = applyCommandPrefix(name, commandPrefix);
-                    const source = readFileSync(path.join(root, 'adapters', 'codex', 'skills', name, 'SKILL.md'));
-                    const content = installName === name
-                        ? source
-                        : Buffer.from(rewriteSkillFrontmatterName(source.toString('utf8'), installName));
+                const mode = skillInstallMode(runtime, options);
+                if (mode === 'direct') {
+                    for (const asset of skillAssets) {
+                        actions.push({
+                            runtime,
+                            scope: 'user',
+                            target: path.join(userHome(), '.codex', 'skills', 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(userHome(), '.codex', 'skills', installName, 'SKILL.md'),
-                        content,
+                        target: path.join(runtimeRoot(), 'install-modes', 'codex.json'),
+                        content: Buffer.from(`${JSON.stringify({ schemaVersion: '1.0.0', runtime, mode, sourceVersion: version }, null, 2)}\n`),
                         kind: 'file',
-                        description: `Install Codex skill ${installName}`,
+                        description: `Record Codex ${mode} skill installation mode`,
                     });
                 }
             }
@@ -286,60 +764,55 @@ function buildActions(options, runtimes, runtimeScopes, commandPrefix) {
         }
         if (installProject) {
             if (runtime === 'codex') {
-                actions.push({
-                    runtime,
-                    scope: 'project',
-                    target: path.join(options.projectDir, 'AGENTS.md'),
-                    content: Buffer.from(managedContent(readFileSync(path.join(root, 'adapters', 'codex', 'project-guidance.md'), 'utf8'))),
-                    kind: 'managed-block',
-                    marker: 'pipeline',
-                    description: 'Update concise Codex project policy',
-                });
+                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') {
-                // Cursor rules carry the equivalent prefix adjustment: the installed target
-                // basename is derived through `applyCommandPrefix` while the read path stays
-                // the canonical pipeline source. The current rule set uses the product name
-                // (`openplanr…`), not per-verb `planr-` command names, so this is a no-op for
-                // today's files and only takes effect for any future `planr-`-prefixed rule.
-                actions.push({
-                    runtime,
-                    scope: 'project',
-                    target: path.join(options.projectDir, '.cursor', 'rules', `${applyCommandPrefix('openplanr', commandPrefix)}.mdc`),
-                    content: readFileSync(path.join(root, 'adapters', 'cursor', 'rules', 'openplanr.mdc')),
-                    kind: 'file',
-                    description: 'Install portable Cursor project rule',
-                });
-                actions.push({
-                    runtime,
-                    scope: 'project',
-                    target: path.join(options.projectDir, '.cursor', 'rules', `${applyCommandPrefix('openplanr-operate', commandPrefix)}.mdc`),
-                    content: readFileSync(path.join(root, 'adapters', 'cursor', 'rules', 'openplanr-operate.mdc')),
-                    kind: 'file',
-                    description: 'Install Cursor Operating Board rule',
-                });
-                const roleRegistry = JSON.parse(readFileSync(path.join(root, 'registry', 'roles.json'), 'utf8'));
-                for (const role of roleRegistry.roles) {
+                for (const asset of skillAssets) {
                     actions.push({
                         runtime,
                         scope: 'project',
-                        target: path.join(options.projectDir, '.cursor', 'rules', 'openplanr-roles', `${applyCommandPrefix(role.id, commandPrefix)}.md`),
-                        content: Buffer.from(`# ${role.id}\n\nCapability tier: \`${role.capability}\`\nPhase: \`${role.phase}\`\nActivation: \`${role.activation}\`\n\n- ${role.writeBoundary}\n`),
+                        target: path.join(options.projectDir, '.cursor', 'rules', 'openplanr', asset.relativePath),
+                        content: asset.content,
                         kind: 'file',
-                        description: `Install Cursor role ${role.id}`,
+                        custody: 'professional-skill',
+                        description: `Install Cursor rule asset ${asset.relativePath}`,
                     });
                 }
             }
             else {
-                actions.push({
-                    runtime,
-                    scope: 'project',
-                    target: path.join(options.projectDir, 'CLAUDE.md'),
-                    content: Buffer.from('Use the native planr-pipeline plugin for PLAN, Design, SHIP, dashboard, sync, and doctor. Portable procedures and deterministic state are supplied by planr-pipeline. PLAN and SHIP remain separate user actions.'),
-                    kind: 'managed-block',
-                    marker: 'pipeline',
-                    description: 'Update Claude Code project policy',
-                });
+                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: readFileSync(absolutePath),
+                        kind: 'file',
+                        description: `Install project Claude role agent ${relativePath}`,
+                    });
+                }
             }
         }
     }
@@ -363,27 +836,136 @@ function operationFor(action) {
         return 'create';
     return hash(readFileSync(action.target)) === hash(actionBytes(action)) ? 'unchanged' : 'update';
 }
-async function loadState() {
-    try {
-        return JSON.parse(await readFile(statePath(), 'utf8'));
+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/'));
     }
-    catch {
-        return { schemaVersion: '1.0.0', projects: {} };
+    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 `planr 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',
+            },
+        ];
+    });
+}
+function inventoryRegularFiles(root) {
+    return inventoryManagedSkillFiles(root, (message, recovery) => {
+        throw new RuntimeManagerError('E_MIGRATION_CONFLICT', message, recovery);
+    });
+}
+function planUserBundleTransition(state, actions) {
+    const existing = state.userBundles?.codex?.ownedFiles ?? [];
+    return planCodexUserBundleTransition({
+        actions,
+        existing,
+        skillsRoot: codexSkillsRoot(),
+        pathIsWithin,
+        assertUserOwnedTarget,
+        ownershipHash,
+        hash,
+        actionBytes,
+        conflict: (message, recovery) => {
+            throw new RuntimeManagerError('E_MIGRATION_CONFLICT', message, recovery);
+        },
+    });
 }
 /**
- * FR5: resolve the effective command-naming choice for a setup run. An explicit
- * `--prefix`/`--no-prefix` (`options.prefix` is a boolean) wins and is what gets
- * persisted; when the flag is omitted (`undefined`) the previously persisted choice
- * is read back from on-disk state, defaulting to `namespaced` for a project with no
- * prior record. This is what makes the choice survive across separate invocations
- * and upgrades without ever silently renaming what the user types.
+ * Applies the Codex bundle's adopt-only-if-identical ownership rule to the four
+ * project-scoped Cursor professional assets. Unknown bytes are user-owned, while
+ * recorded assets may advance only when their current bytes still match state.
  */
+function assertCursorProfessionalSkillTransition(state, projectDir, actions) {
+    const desired = actions.filter((action) => action.runtime === 'cursor' &&
+        action.scope === 'project' &&
+        action.custody === 'professional-skill');
+    if (desired.length === 0)
+        return;
+    const tracked = new Map((state.projects[projectKey(projectDir)]?.ownedFiles ?? [])
+        .filter((file) => file.runtime === 'cursor')
+        .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 Cursor professional skill target ${action.target}.`, 'Preserve or move the existing entry outside the managed Cursor rules 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 Cursor 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.');
+        }
+    }
+}
+async function loadState() {
+    assertApprovedTargetCustody(statePath(), runtimeRoot(), userHome(), 'E_RUNTIME_STATE_INVALID', 'Runtime ownership state');
+    try {
+        const state = assertRuntimeStateValue(JSON.parse(await readFile(statePath(), 'utf8')), 'E_RUNTIME_STATE_INVALID', true);
+        migrateLegacyGlobalRuntimeState(state, {
+            inferRuntimeScope,
+            inferLegacyCodexPrefix,
+            isUserOwnedFile,
+            projectKey,
+            conflict: (code, message, recovery) => {
+                throw new RuntimeManagerError(code, message, recovery);
+            },
+        });
+        return assertRuntimeStateValue(state);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { 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) {
-    if (options.prefix !== undefined)
-        return options.prefix ? 'namespaced' : 'bare';
-    const state = await loadState();
-    return state.projects[projectKey(options.projectDir)]?.commandPrefix ?? 'namespaced';
+    return skillInstallMode('codex', options) === 'direct' ? 'bare' : 'namespaced';
 }
 async function atomicWrite(target, content) {
     await mkdir(path.dirname(target), { recursive: true });
@@ -393,34 +975,75 @@ async function atomicWrite(target, content) {
 }
 async function createBackup(projectDir, actions) {
     const stamp = new Date().toISOString().replaceAll(':', '-');
-    const dir = path.join(userHome(), '.planr', 'backups', projectKey(projectDir), stamp);
+    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 });
+    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 = path.join(dir, 'files', `${String(index).padStart(3, '0')}-${path.basename(action.target)}`);
-            await mkdir(path.dirname(backup), { recursive: true });
-            await copyFile(action.target, backup);
+            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(await readFile(action.target));
+            entry.beforeHash = hash(bytes);
         }
         manifest.files.push(entry);
     }
-    await atomicWrite(path.join(dir, 'migration-manifest.json'), Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`));
+    const manifestPath = path.join(dir, 'migration-manifest.json');
+    assertApprovedTargetCustody(manifestPath, dir, userHome(), '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 };
 }
+async function restoreBackup(backup) {
+    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 (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 (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);
+        }
+        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';
     if (!['user', 'project', 'both'].includes(scope)) {
         throw new RuntimeManagerError('E_SCOPE_INVALID', `Install scope "${options.scope}" is invalid.`, 'Choose user, project, or both.');
     }
+    if (options.skillMode &&
+        !['direct', 'unified-plugin', 'project-rule'].includes(options.skillMode)) {
+        throw new RuntimeManagerError('E_SKILL_MODE_INVALID', `Skill installation mode "${options.skillMode}" is invalid.`, 'Choose direct, unified-plugin, or project-rule.');
+    }
     const projectContext = inspectProjectContext(options.projectDir);
     if ((scope === 'project' || scope === 'both') && !projectContext.valid) {
         throw new RuntimeManagerError('E_PROJECT_CONTEXT_REQUIRED', `Project-scoped setup requires a Git worktree or initialized OpenPlanr project; ${projectContext.path} is neither.`, 'Change into a project, run `planr init`, or use `planr setup --scope user`.');
@@ -467,17 +1090,39 @@ export async function previewSetup(options) {
                 throw new RuntimeManagerError('E_ADAPTER_MISSING', `Adapter ${runtime} is absent.`);
             runtimeScopes[runtime] = normalizeInstallScope(adapter, runtimeScopes[runtime] ?? options.scope ?? 'user');
         }
+        if (runtimes.includes('codex')) {
+            const codexScope = runtimeScopes.codex ?? scope;
+            const mode = skillInstallMode('codex', options);
+            if (mode === 'project-rule' && !['project', 'both'].includes(codexScope)) {
+                throw new RuntimeManagerError('E_SKILL_MODE_SCOPE', 'Codex project-rule mode requires project or both scope.', 'Use --scope project or --scope both.');
+            }
+            if (mode !== 'project-rule' && !['user', 'both'].includes(codexScope)) {
+                throw new RuntimeManagerError('E_SKILL_MODE_SCOPE', `Codex ${mode} mode requires user or both scope.`, 'Use --scope user or --scope both.');
+            }
+        }
     }
     const commandPrefix = await resolveCommandPrefix(options);
-    const actions = buildActions(options, runtimes, runtimeScopes, commandPrefix);
+    const actions = buildActions(options, runtimes, runtimeScopes);
+    assertActionCustody(actions, options.projectDir);
+    const retiredProjectRules = planRetiredCursorProjectRules(options.projectDir, runtimes, runtimeScopes);
+    const needsTransitionState = runtimes.includes('codex') ||
+        actions.some((action) => (action.runtime === 'codex' && action.scope === 'user') ||
+            action.custody === 'professional-skill');
+    const transitionState = needsTransitionState ? await loadState() : undefined;
+    if (transitionState) {
+        assertCursorProfessionalSkillTransition(transitionState, options.projectDir, actions);
+    }
+    const userBundleTransition = runtimes.includes('codex')
+        ? planUserBundleTransition(transitionState, actions)
+        : { retired: [] };
     const manageClaudePlugins = options.manageExternalRuntimes !== false &&
         !options.minimal &&
         runtimes.includes('claude-code') &&
         ['user', 'both'].includes(runtimeScopes['claude-code'] ?? scope) &&
         (Boolean(options.claudeCommandRunner) ||
             detectRuntimes().some((runtime) => runtime.runtime === 'claude-code' && runtime.installed));
-    const claudeInspection = manageClaudePlugins && pipeline
-        ? inspectClaudePluginIntegration(pipeline.version, options.claudeCommandRunner)
+    const claudeInspection = manageClaudePlugins
+        ? inspectBundledClaudePluginIntegration(bundledHostRoot('claude'), options.claudeCommandRunner)
         : undefined;
     const runtimeDiagnostics = [];
     if (claudeInspection) {
@@ -512,11 +1157,63 @@ export async function previewSetup(options) {
             });
         }
     }
+    const codexMode = runtimes.includes('codex') ? skillInstallMode('codex', options) : undefined;
+    const previousCodexMode = transitionState?.userBundles?.codex?.installMode ??
+        (transitionState?.userBundles?.codex ? 'direct' : undefined) ??
+        transitionState?.projects[projectKey(options.projectDir)]?.skillModes?.codex;
+    const manageCodexPlugin = Boolean(codexMode &&
+        options.manageExternalRuntimes !== false &&
+        (detectRuntimes().some((runtime) => runtime.runtime === 'codex' && runtime.installed) ||
+            options.codexCommandRunner));
+    const codexInspection = manageCodexPlugin
+        ? inspectCodexPluginIntegration(bundledHostRoot('openai'), codexMode, previousCodexMode, options.codexCommandRunner)
+        : undefined;
+    if (codexInspection) {
+        if (codexInspection.error) {
+            runtimeDiagnostics.push({
+                runtime: 'codex',
+                status: 'fail',
+                message: `Codex plugin state could not be inspected: ${codexInspection.error}`,
+                fix: 'Repair the Codex marketplace state, then rerun planr setup --dry-run.',
+            });
+        }
+        else if (codexInspection.duplicates.length > 0) {
+            runtimeDiagnostics.push({
+                runtime: 'codex',
+                status: 'warn',
+                message: `Duplicate OpenPlanr Codex plugin discovery detected: ${codexInspection.duplicates.join(', ')}`,
+                fix: 'Remove or disable the unrelated duplicate after confirming which installation should remain active.',
+            });
+        }
+        else if (codexInspection.ready) {
+            runtimeDiagnostics.push({
+                runtime: 'codex',
+                status: 'pass',
+                message: `Codex ${codexMode} discovery is current`,
+            });
+        }
+        else if (codexInspection.operations.length > 0) {
+            runtimeDiagnostics.push({
+                runtime: 'codex',
+                status: 'warn',
+                message: `Codex will switch to ${codexMode} discovery after confirmation`,
+            });
+        }
+    }
+    if (userBundleTransition.retired.length > 0 && previousCodexMode !== codexMode) {
+        runtimeDiagnostics.push({
+            runtime: 'codex',
+            status: 'warn',
+            message: `${userBundleTransition.retired.length} manifest-owned direct Codex asset(s) will be retired`,
+            fix: 'Rerun with --replace-managed after reviewing this dry-run.',
+        });
+    }
     return {
         ok: true,
         dryRun: Boolean(options.dryRun),
         minimal: Boolean(options.minimal),
         commandPrefix,
+        skillModes: skillInstallModes(runtimes, options),
         runtimes,
         runtimeScopes,
         scope,
@@ -529,14 +1226,33 @@ export async function previewSetup(options) {
             .map((item) => item.runtime),
         scopeIncompatibleRuntimes,
         projectContext,
-        actions: actions.map((action) => ({
-            runtime: action.runtime,
-            scope: action.scope,
-            target: action.target,
-            operation: operationFor(action),
-            description: action.description,
-        })),
-        runtimeOperations: claudeInspection?.operations ?? [],
+        actions: [
+            ...actions.map((action) => ({
+                runtime: action.runtime,
+                scope: action.scope,
+                target: action.target,
+                operation: operationFor(action),
+                description: action.description,
+            })),
+            ...retiredProjectRules.map((action) => ({
+                runtime: action.runtime,
+                scope: action.scope,
+                target: action.target,
+                operation: 'retire',
+                description: action.description,
+            })),
+            ...userBundleTransition.retired.map((file) => ({
+                runtime: file.runtime,
+                scope: file.scope ?? 'user',
+                target: file.target,
+                operation: 'retire',
+                description: 'Retire a previously owned global Codex skill asset',
+            })),
+        ],
+        runtimeOperations: [
+            ...(claudeInspection?.operations ?? []),
+            ...(codexInspection?.operations ?? []),
+        ],
         runtimeDiagnostics,
     };
 }
@@ -544,6 +1260,7 @@ export async function applySetup(options) {
     const preview = await previewSetup(options);
     if (options.dryRun || options.minimal)
         return preview;
+    assertApprovedTargetCustody(runtimeRoot(), runtimeRoot(), userHome(), 'E_MIGRATION_CONFLICT', 'Global runtime root');
     await mkdir(runtimeRoot(), { recursive: true });
     const lockPath = path.join(runtimeRoot(), 'setup.lock');
     let lockHandle;
@@ -553,22 +1270,69 @@ export async function applySetup(options) {
     catch {
         throw new RuntimeManagerError('E_SETUP_BUSY', 'Another OpenPlanr setup or migration is already running.', 'Wait for it to finish. If no process is running, remove the verified stale setup lock.');
     }
+    let backup;
     try {
         const commandPrefix = await resolveCommandPrefix(options);
-        const actions = buildActions(options, preview.runtimes, preview.runtimeScopes, commandPrefix);
+        const actions = buildActions(options, preview.runtimes, preview.runtimeScopes);
+        assertActionCustody(actions, options.projectDir);
+        const retiredProjectRules = planRetiredCursorProjectRules(options.projectDir, preview.runtimes, preview.runtimeScopes);
+        const state = await loadState();
+        const previousCodexMode = state.userBundles?.codex?.installMode ??
+            (state.userBundles?.codex ? 'direct' : undefined) ??
+            state.projects[projectKey(options.projectDir)]?.skillModes?.codex;
+        assertCursorProfessionalSkillTransition(state, options.projectDir, actions);
+        const transition = preview.runtimes.includes('codex')
+            ? planUserBundleTransition(state, actions)
+            : { retired: [] };
+        const replacesPlugin = preview.runtimeOperations.some((operation) => operation.runtime === 'codex' && operation.kind === 'remove');
+        const replacesClaudePlugin = preview.runtimeOperations.some((operation) => operation.runtime === 'claude-code' && operation.kind === 'remove');
+        const desiredCodexMode = preview.skillModes.codex;
+        const changesInstallMode = Boolean(previousCodexMode && desiredCodexMode && previousCodexMode !== desiredCodexMode);
+        if (((changesInstallMode && transition.retired.length > 0) ||
+            replacesPlugin ||
+            replacesClaudePlugin) &&
+            !options.replaceManaged) {
+            throw new RuntimeManagerError('E_INSTALL_MODE_CONFLICT', 'Changing OpenPlanr discovery mode would retire existing OpenPlanr-managed content.', 'Review planr setup --dry-run, then rerun with --replace-managed to replace only OpenPlanr-owned content.');
+        }
         const changed = actions.filter((action) => operationFor(action) !== 'unchanged');
-        let backup;
-        if (changed.length > 0) {
-            try {
-                backup = await createBackup(options.projectDir, changed);
-            }
-            catch (cause) {
-                throw new RuntimeManagerError('E_BACKUP_FAILED', `Could not create byte-for-byte migration backup: ${cause instanceof Error ? cause.message : String(cause)}`, 'No setup files were changed. Fix backup permissions and rerun setup.');
-            }
+        const retirementActions = transition.retired.map((file) => ({
+            runtime: file.runtime,
+            scope: 'user',
+            target: file.target,
+            content: Buffer.alloc(0),
+            kind: file.kind,
+            marker: file.marker,
+            description: 'Retire a previously owned global Codex skill asset',
+        }));
+        const stateAction = {
+            runtime: 'core',
+            scope: 'user',
+            target: statePath(),
+            content: Buffer.alloc(0),
+            kind: 'file',
+            description: 'Update global runtime ownership state',
+        };
+        const backupTargets = [
+            ...changed,
+            ...retirementActions,
+            ...retiredProjectRules,
+            stateAction,
+        ].filter((action, index, list) => list.findIndex((candidate) => candidate.target === action.target) === index);
+        try {
+            backup = await createBackup(options.projectDir, backupTargets);
+        }
+        catch (cause) {
+            throw new RuntimeManagerError('E_BACKUP_FAILED', `Could not create byte-for-byte setup backup: ${cause instanceof Error ? cause.message : String(cause)}`, 'No setup files were changed. Fix backup permissions and rerun setup.');
+        }
+        try {
             const owned = [];
             for (const action of actions) {
                 const content = actionBytes(action);
-                await atomicWrite(action.target, content);
+                if (operationFor(action) !== 'unchanged')
+                    await atomicWrite(action.target, content);
+                if (hash(readFileSync(action.target)) !== hash(content)) {
+                    throw new RuntimeManagerError('E_SETUP_VERIFY_FAILED', `Installed bytes failed verification at ${action.target}.`);
+                }
                 owned.push({
                     runtime: action.runtime,
                     scope: action.scope,
@@ -577,65 +1341,118 @@ export async function applySetup(options) {
                     marker: action.marker,
                     hash: ownershipHash(content, action.kind, action.marker),
                 });
-                const backupEntry = backup.manifest.files.find((entry) => entry.target === action.target);
-                if (backupEntry)
-                    backupEntry.afterHash = hash(content);
+                const entry = backup.manifest.files.find((candidate) => candidate.target === action.target);
+                if (entry)
+                    entry.afterHash = hash(content);
+            }
+            for (const retired of transition.retired) {
+                assertUserOwnedTarget(retired, 'codex', 'E_RUNTIME_STATE_INVALID');
+                if (existsSync(retired.target))
+                    await unlink(retired.target);
+            }
+            for (const retired of retiredProjectRules) {
+                assertMutableOwnedTarget(retired.target, options.projectDir, 'E_MIGRATION_CONFLICT');
+                if (!existsSync(retired.target))
+                    continue;
+                const metadata = lstatSync(retired.target);
+                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.');
+                }
+                await unlink(retired.target);
+            }
+            const updatedAt = new Date().toISOString();
+            state.schemaVersion = '2.0.0';
+            state.userBundles ??= {};
+            for (const runtime of preview.runtimes) {
+                const userOwned = owned.filter((file) => file.runtime === runtime && file.scope === 'user');
+                if (userOwned.length === 0) {
+                    if (runtime === 'codex' && transition.retired.length > 0)
+                        delete state.userBundles.codex;
+                    continue;
+                }
+                state.userBundles[runtime] = {
+                    runtime,
+                    scope: 'user',
+                    updatedAt,
+                    pipelineVersion: preview.pipelineVersion ?? 'planning-only',
+                    commandPrefix: runtime === 'codex' ? commandPrefix : 'namespaced',
+                    installMode: preview.skillModes[runtime],
+                    ownedFiles: userOwned,
+                };
             }
-            await atomicWrite(path.join(backup.dir, 'migration-manifest.json'), Buffer.from(`${JSON.stringify(backup.manifest, null, 2)}\n`));
-            const state = await loadState();
             state.projects[projectKey(options.projectDir)] = {
                 projectDir: path.resolve(options.projectDir),
-                updatedAt: new Date().toISOString(),
+                updatedAt,
                 backupDir: backup.dir,
+                backupManifestHash: backupManifestIdentity(backup.manifest),
                 runtimes: preview.runtimes,
                 runtimeScopes: preview.runtimeScopes,
-                commandPrefix,
+                skillModes: preview.skillModes,
                 ...(preview.runtimes.length === 1 ? { activeRuntime: preview.runtimes[0] } : {}),
-                ownedFiles: owned,
+                ownedFiles: owned.filter((file) => file.scope === 'project'),
             };
-            await atomicWrite(statePath(), Buffer.from(`${JSON.stringify(state, null, 2)}\n`));
-        }
-        let appliedRuntimeOperations;
-        let restartRequired = false;
-        if (preview.runtimeOperations.length > 0 && preview.pipelineVersion) {
-            const inspection = inspectClaudePluginIntegration(preview.pipelineVersion, options.claudeCommandRunner);
-            if (inspection.error) {
-                throw new RuntimeManagerError('E_CLAUDE_PLUGIN_INSPECTION_FAILED', `Could not inspect Claude plugins: ${inspection.error}`, 'Update Claude Code, then rerun `planr setup --runtime claude --scope user`.');
-            }
-            try {
-                const result = applyClaudePluginIntegration(preview.pipelineVersion, inspection, options.claudeCommandRunner);
+            const stateBytes = Buffer.from(`${JSON.stringify(state, null, 2)}\n`);
+            await atomicWrite(statePath(), stateBytes);
+            const stateBackup = backup.manifest.files.find((entry) => entry.target === statePath());
+            if (stateBackup)
+                stateBackup.afterHash = hash(stateBytes);
+            const backupManifestPath = path.join(backup.dir, 'migration-manifest.json');
+            assertApprovedTargetCustody(backupManifestPath, backup.dir, userHome(), 'E_RUNTIME_STATE_INVALID', 'Runtime backup manifest');
+            await atomicWrite(backupManifestPath, Buffer.from(`${JSON.stringify(backup.manifest, null, 2)}\n`));
+            assertClosedBackupTree(backup.dir, assertClosedBackupManifest(backup.manifest, backup.dir, options.projectDir, 'E_RUNTIME_STATE_INVALID', true), options.projectDir, 'E_RUNTIME_STATE_INVALID');
+            let appliedRuntimeOperations;
+            let restartRequired = false;
+            const claudeOperations = preview.runtimeOperations.filter((operation) => operation.runtime === 'claude-code');
+            if (claudeOperations.length > 0) {
+                const inspection = inspectBundledClaudePluginIntegration(bundledHostRoot('claude'), options.claudeCommandRunner);
+                if (inspection.error) {
+                    throw new RuntimeManagerError('E_CLAUDE_PLUGIN_INSPECTION_FAILED', `Could not inspect Claude plugins: ${inspection.error}`);
+                }
+                let result;
+                try {
+                    result = applyBundledClaudePluginIntegration(bundledHostRoot('claude'), inspection, options.claudeCommandRunner);
+                }
+                catch (cause) {
+                    throw new RuntimeManagerError('E_CLAUDE_PLUGIN_UPDATE_FAILED', cause instanceof Error ? cause.message : String(cause));
+                }
                 appliedRuntimeOperations = result.operations;
                 restartRequired = result.restartRequired;
             }
-            catch (cause) {
-                const detail = cause instanceof Error ? cause.message : String(cause);
-                // `setup` is the install path for every runtime, so a mid-apply plugin
-                // failure must never leave the owned files written earlier in this same
-                // call in a half-migrated state a rerun cannot tell apart from a fresh
-                // install. Those writes happened under `backup`; restore them from it
-                // before surfacing the failure, and name every restored path so the
-                // report states plainly what was undone. When nothing was written yet
-                // (`backup` undefined) there is nothing to restore — throw unchanged.
-                if (backup) {
-                    let restored;
-                    try {
-                        ({ restored } = await rollbackRuntime(options.projectDir, backup.dir));
-                    }
-                    catch (rollbackCause) {
-                        const rollbackDetail = rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause);
-                        throw new RuntimeManagerError('E_CLAUDE_PLUGIN_UPDATE_FAILED', `Claude plugin update failed: ${detail}`, `Automatic restore from ${backup.dir} also failed (${rollbackDetail}); the OpenPlanr files written this run may be partially applied. Restore them from that backup, then run \`planr runtime update claude --scope user\`.`);
-                    }
-                    throw new RuntimeManagerError('E_CLAUDE_PLUGIN_UPDATE_FAILED', `Claude plugin update failed: ${detail}`, `Restored ${restored.length} file(s) to their pre-setup state: ${restored.join(', ')}. Run \`planr runtime update claude --scope user\` after checking Claude Code marketplace access, then rerun setup.`);
+            const codexOperations = preview.runtimeOperations.filter((operation) => operation.runtime === 'codex');
+            if (codexOperations.length > 0) {
+                const inspection = inspectCodexPluginIntegration(bundledHostRoot('openai'), preview.skillModes.codex ?? 'direct', previousCodexMode, options.codexCommandRunner);
+                if (inspection.error)
+                    throw new RuntimeManagerError('E_CODEX_PLUGIN_INSPECTION_FAILED', inspection.error);
+                try {
+                    const result = applyCodexPluginIntegration(bundledHostRoot('openai'), inspection, options.codexCommandRunner);
+                    appliedRuntimeOperations = [...(appliedRuntimeOperations ?? []), ...result.operations];
+                    restartRequired ||= result.restartRequired;
+                }
+                catch (cause) {
+                    throw new RuntimeManagerError('E_CODEX_PLUGIN_UPDATE_FAILED', cause instanceof Error ? cause.message : String(cause));
                 }
-                throw new RuntimeManagerError('E_CLAUDE_PLUGIN_UPDATE_FAILED', `Claude plugin update failed: ${detail}`, 'Run `planr runtime update claude --scope user` after checking Claude Code marketplace access.');
             }
+            return {
+                ...preview,
+                backupDir: backup.dir,
+                ...(appliedRuntimeOperations ? { appliedRuntimeOperations } : {}),
+                restartRequired,
+            };
+        }
+        catch (cause) {
+            let restored;
+            try {
+                restored = await restoreBackup(backup);
+            }
+            catch (rollbackCause) {
+                throw new RuntimeManagerError('E_SETUP_ROLLBACK_FAILED', `Setup failed and automatic restore also failed: ${rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause)}`, `Restore the exact previous files from ${backup.dir}.`);
+            }
+            const detail = cause instanceof Error ? cause.message : String(cause);
+            const causeCode = cause?.code;
+            throw new RuntimeManagerError(typeof causeCode === 'string' ? causeCode : 'E_SETUP_TRANSACTION_FAILED', detail, `Restored ${restored.length} file(s) to their exact pre-setup bytes: ${restored.join(', ')}.`);
         }
-        return {
-            ...preview,
-            ...(backup ? { backupDir: backup.dir } : {}),
-            ...(appliedRuntimeOperations ? { appliedRuntimeOperations } : {}),
-            restartRequired,
-        };
     }
     finally {
         await lockHandle.close();
@@ -653,42 +1470,132 @@ function removeManagedBlock(existing, marker) {
 }
 export async function rollbackRuntime(projectDir, backupDir) {
     const state = await loadState();
-    const project = state.projects[projectKey(projectDir)];
-    const selected = backupDir ?? project?.backupDir;
-    if (!selected)
+    const key = projectKey(projectDir);
+    const project = state.projects[key];
+    const recorded = project?.backupDir;
+    const selected = backupDir ?? recorded;
+    if (!selected || !recorded)
         throw new RuntimeManagerError('E_ROLLBACK_NOT_FOUND', 'No runtime backup is recorded for this project.');
-    const manifest = JSON.parse(await readFile(path.join(selected, 'migration-manifest.json'), 'utf8'));
+    assertRequestedProjectBinding(projectDir, key, project);
+    if (path.resolve(selected) !== path.resolve(recorded)) {
+        throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', 'The selected runtime backup is not the exact backup recorded for this project.', 'Use the current project-owned backup recorded by OpenPlanr.');
+    }
+    const directory = assertBackupDirectoryCustody(selected, projectDir, 'E_RUNTIME_STATE_INVALID', true);
+    const manifestPath = path.join(directory, 'migration-manifest.json');
+    const manifestBytes = await readCustodiedRegularFile(manifestPath, () => assertApprovedTargetCustody(manifestPath, directory, userHome(), 'E_RUNTIME_STATE_INVALID', 'Runtime backup manifest'), 'E_RUNTIME_STATE_INVALID', 'Runtime backup manifest', 4 * 1024 * 1024);
+    let manifestValue;
+    try {
+        manifestValue = JSON.parse(manifestBytes.toString('utf8'));
+    }
+    catch {
+        throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', 'Runtime backup manifest is not valid JSON.');
+    }
+    const manifest = assertClosedBackupManifest(manifestValue, directory, projectDir, 'E_RUNTIME_STATE_INVALID', true);
+    if (project.backupManifestHash !== backupManifestIdentity(manifest)) {
+        throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', 'The selected runtime backup no longer matches its recorded manifest identity.', 'Use the exact unmodified backup created by the recorded setup transaction.');
+    }
+    assertClosedBackupTree(directory, manifest, projectDir, 'E_RUNTIME_STATE_INVALID');
+    const restoreBytes = new Map();
+    for (const entry of manifest.files) {
+        assertMutableOwnedTarget(entry.target, projectDir, 'E_RUNTIME_STATE_INVALID');
+        if (entry.existed) {
+            restoreBytes.set(entry.target, await readBackupEntryBytes(directory, entry, projectDir, 'E_RUNTIME_STATE_INVALID'));
+        }
+    }
     const restored = [];
     const retainedShared = [];
-    const key = projectKey(projectDir);
+    const stateEntry = manifest.files.find((entry) => path.resolve(entry.target) === path.resolve(statePath()));
+    if (!stateEntry?.afterHash) {
+        throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', 'Runtime backup has no final ownership-state hash.');
+    }
+    // Global ownership state may legitimately advance when another project reuses
+    // the same user bundle. The current state was already structurally decoded,
+    // target-confined, and used to authenticate this project's manifest identity;
+    // rollback therefore merges it instead of requiring stale raw state bytes.
+    let previousState;
+    if (stateEntry?.existed && stateEntry.backup) {
+        const previousStateBytes = restoreBytes.get(stateEntry.target);
+        if (!previousStateBytes) {
+            throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', 'Backup preflight lost the validated ownership-state bytes.');
+        }
+        try {
+            previousState = assertRuntimeStateValue(JSON.parse(previousStateBytes.toString('utf8')));
+        }
+        catch (cause) {
+            if (cause instanceof RuntimeManagerError)
+                throw cause;
+            throw new RuntimeManagerError('E_RUNTIME_STATE_INVALID', 'Backed-up runtime ownership state is not valid JSON.');
+        }
+    }
+    const bundleRuntimeByTarget = new Map();
+    for (const source of [state, previousState]) {
+        for (const runtime of ['claude-code', 'codex', 'cursor']) {
+            for (const file of source?.userBundles?.[runtime]?.ownedFiles ?? []) {
+                bundleRuntimeByTarget.set(path.resolve(file.target), runtime);
+            }
+        }
+    }
+    const otherProjectUsesUserRuntime = (runtime) => Object.entries(state.projects).some(([otherKey, otherProject]) => otherKey !== key && projectUsesUserRuntime(otherProject, runtime));
     const sharedTargets = new Set(manifest.files
-        .filter((entry) => Object.entries(state.projects).some(([otherKey, otherProject]) => otherKey !== key &&
-        otherProject.ownedFiles.some((owned) => owned.target === entry.target)))
+        .filter((entry) => {
+        const bundleRuntime = bundleRuntimeByTarget.get(path.resolve(entry.target));
+        return ((bundleRuntime !== undefined && otherProjectUsesUserRuntime(bundleRuntime)) ||
+            Object.entries(state.projects).some(([otherKey, otherProject]) => otherKey !== key &&
+                otherProject.ownedFiles.some((owned) => owned.target === entry.target)));
+    })
         .map((entry) => entry.target));
     for (const entry of manifest.files) {
-        if (!sharedTargets.has(entry.target) &&
-            !entry.existed &&
-            existsSync(entry.target) &&
-            entry.afterHash &&
-            hash(await readFile(entry.target)) !== entry.afterHash) {
-            throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Refusing to remove modified file ${entry.target}.`, 'Restore it manually or choose a different backup.');
+        if (path.resolve(entry.target) === path.resolve(statePath()) || sharedTargets.has(entry.target))
+            continue;
+        const targetExists = existsSync(entry.target);
+        const targetChanged = entry.afterHash
+            ? !targetExists || hash(await readFile(entry.target)) !== entry.afterHash
+            : targetExists;
+        if (targetChanged) {
+            throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Refusing to restore changed file ${entry.target}.`, 'Restore it manually or choose a different backup.');
         }
     }
-    for (const entry of manifest.files) {
+    for (const entry of [...manifest.files].reverse()) {
+        if (path.resolve(entry.target) === path.resolve(statePath()))
+            continue;
         if (sharedTargets.has(entry.target)) {
             retainedShared.push(entry.target);
             continue;
         }
         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 });
-            await copyFile(entry.backup, entry.target);
+            assertMutableOwnedTarget(entry.target, projectDir, 'E_RUNTIME_STATE_INVALID');
+            await atomicWrite(entry.target, bytes);
         }
         else if (existsSync(entry.target)) {
             await unlink(entry.target);
         }
         restored.push(entry.target);
     }
-    delete state.projects[key];
+    const affectedRuntimes = new Set([
+        ...(project?.runtimes ?? []),
+        ...[...bundleRuntimeByTarget.entries()]
+            .filter(([target]) => manifest.files.some((entry) => path.resolve(entry.target) === target))
+            .map(([, runtime]) => runtime),
+    ]);
+    state.userBundles ??= {};
+    for (const runtime of affectedRuntimes) {
+        if (otherProjectUsesUserRuntime(runtime))
+            continue;
+        const previous = previousState?.userBundles?.[runtime];
+        if (previous)
+            state.userBundles[runtime] = previous;
+        else
+            delete state.userBundles[runtime];
+    }
+    const previousProject = previousState?.projects?.[key];
+    if (previousProject)
+        state.projects[key] = previousProject;
+    else
+        delete state.projects[key];
     await atomicWrite(statePath(), Buffer.from(`${JSON.stringify(state, null, 2)}\n`));
     return { ok: true, restored, retainedShared };
 }
@@ -698,17 +1605,22 @@ export async function removeRuntime(runtime, projectDir) {
     const project = state.projects[key];
     if (!project)
         throw new RuntimeManagerError('E_RUNTIME_STATE_MISSING', 'No managed runtime installation is recorded for this project.');
+    assertRequestedProjectBinding(projectDir, key, project);
     const removed = [];
     const retainedShared = [];
     const runtimeFiles = project.ownedFiles.filter((file) => file.runtime === runtime);
-    const sharedTargets = new Set(runtimeFiles
-        .filter((file) => Object.entries(state.projects).some(([otherKey, otherProject]) => otherKey !== key &&
-        otherProject.ownedFiles.some((owned) => owned.runtime === runtime && owned.target === file.target)))
+    const globalFiles = state.userBundles?.[runtime]?.ownedFiles ?? [];
+    const hasOtherUserOwner = Object.entries(state.projects).some(([otherKey, otherProject]) => otherKey !== key && projectUsesUserRuntime(otherProject, runtime));
+    const removalFiles = [...runtimeFiles, ...globalFiles];
+    const sharedTargets = new Set(removalFiles
+        .filter((file) => (hasOtherUserOwner && globalFiles.some((global) => global.target === file.target)) ||
+        Object.entries(state.projects).some(([otherKey, otherProject]) => otherKey !== key &&
+            otherProject.ownedFiles.some((owned) => owned.runtime === runtime && owned.target === file.target)))
         .map((file) => file.target));
     const lockFile = project.ownedFiles.find((file) => file.runtime === 'core' && file.target.endsWith('runtime-lock.json'));
     // Validate every owned byte before mutating anything so a late conflict cannot
     // leave the installation half-removed.
-    for (const file of runtimeFiles) {
+    for (const file of removalFiles) {
         if (!existsSync(file.target) || sharedTargets.has(file.target))
             continue;
         const current = await readFile(file.target);
@@ -729,7 +1641,7 @@ export async function removeRuntime(runtime, projectDir) {
             throw new RuntimeManagerError('E_MIGRATION_CONFLICT', `Refusing to update invalid runtime lock ${lockFile.target}.`, 'Repair or roll back the runtime lock before removing the adapter.');
         }
     }
-    for (const file of runtimeFiles) {
+    for (const file of removalFiles) {
         if (!existsSync(file.target))
             continue;
         if (sharedTargets.has(file.target)) {
@@ -745,14 +1657,20 @@ export async function removeRuntime(runtime, projectDir) {
         }
         removed.push(file.target);
     }
+    if (!hasOtherUserOwner && state.userBundles)
+        delete state.userBundles[runtime];
     project.ownedFiles = project.ownedFiles.filter((file) => file.runtime !== runtime);
     project.runtimes = project.runtimes.filter((item) => item !== runtime);
     if (project.runtimeScopes)
         delete project.runtimeScopes[runtime];
+    if (project.skillModes)
+        delete project.skillModes[runtime];
     project.activeRuntime = project.runtimes.length === 1 ? project.runtimes[0] : undefined;
     project.updatedAt = new Date().toISOString();
     if (lockFile && lock) {
         lock.adapters = lock.adapters.filter((adapter) => adapter.runtime !== runtime);
+        if (lock.skillModes)
+            delete lock.skillModes[runtime];
         if (lock.adapters.length === 0) {
             await unlink(lockFile.target);
             project.ownedFiles = project.ownedFiles.filter((file) => file !== lockFile);
@@ -760,11 +1678,12 @@ export async function removeRuntime(runtime, projectDir) {
         }
         else {
             lock.generatedAt = new Date().toISOString();
-            lock.manifestDigest = `sha256:${hash(JSON.stringify({
-                protocol: lock.protocolVersion,
+            lock.manifestDigest = runtimeLockManifestDigest({
+                protocolVersion: lock.protocolVersion,
                 pipelineVersion: lock.components.pipeline,
                 adapters: lock.adapters,
-            }))}`;
+                skillModes: lock.skillModes,
+            });
             const content = Buffer.from(`${JSON.stringify(lock, null, 2)}\n`);
             await atomicWrite(lockFile.target, content);
             lockFile.hash = hash(content);
@@ -783,52 +1702,32 @@ function homeProjectRecord(state) {
 }
 export async function previewHomeProjectCleanup() {
     const state = await loadState();
+    const key = projectKey(userHome());
     const project = homeProjectRecord(state);
-    if (!project || path.resolve(project.projectDir) !== path.resolve(userHome()))
+    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();
-    return [...(state.projects[projectKey(projectDir)]?.runtimes ?? [])];
+    const key = projectKey(projectDir);
+    const project = state.projects[key];
+    if (project)
+        assertRequestedProjectBinding(projectDir, key, project);
+    return [...(project?.runtimes ?? [])];
 }
 export function isOpenPlanrHome(projectDir) {
-    return path.resolve(projectDir) === path.resolve(userHome());
-}
-/**
- * FR7 (SPEC-005): the `doctor --fix` view of OpenPlanr-owned scratch that a
- * session left behind without finalizing. Reuses the machine-local operate root
- * that `runtimeDoctor` already diagnoses (`<home>/.planr`) so the preview and the
- * warning name the same abandoned cycles. This is a read: it lists ONLY scratch a
- * valid `openplanr-operate-scratch` ownership manifest confirms this project wrote
- * and whose lease window has lapsed — never an unrelated file that merely landed
- * under the scratch root.
- */
-export async function previewAbandonedOperateScratch(projectDir) {
-    const paths = resolveOperatingPaths(projectDir, { localRoot: path.join(userHome(), '.planr') });
-    return listAbandonedOperatingScratch(paths);
-}
-/**
- * FR7 (SPEC-005): the `doctor --fix` repair for abandoned OpenPlanr-owned scratch.
- * Delegates to the single owned-only cleanup (`purgeAbandonedOperatingScratch`)
- * that `planr operate cache purge` also calls — there is no second cleanup path.
- * It removes ONLY scratch a valid ownership manifest confirms this project wrote
- * whose lease has lapsed, and never broadens to anything else found under the
- * scratch tree, so a false positive can never delete a user's unrelated data.
- */
-export async function purgeAbandonedOperateScratch(projectDir) {
-    return purgeAbandonedOperatingScratch({
-        projectRoot: projectDir,
-        localRoot: path.join(userHome(), '.planr'),
-    });
+    return canonicalProjectPath(projectDir) === canonicalProjectPath(userHome());
 }
 export async function cleanupHomeProjectInstall() {
     const state = await loadState();
     const key = projectKey(userHome());
     const project = state.projects[key];
-    if (!project || path.resolve(project.projectDir) !== path.resolve(userHome())) {
+    if (!project || canonicalProjectPath(project.projectDir) !== canonicalProjectPath(userHome())) {
         return { ok: true, removed: [] };
     }
+    assertRequestedProjectBinding(userHome(), key, project);
     const projectFiles = project.ownedFiles.filter((file) => file.scope === 'project');
     for (const file of projectFiles) {
         if (!existsSync(file.target))
@@ -873,34 +1772,6 @@ export async function cleanupHomeProjectInstall() {
     await atomicWrite(statePath(), Buffer.from(`${JSON.stringify(state, null, 2)}\n`));
     return { ok: true, removed };
 }
-/**
- * The single warn-vs-fail classification for a drifted component tuple.
- *
- * `doctor`'s runtime-lock diagnostic and `planr upgrade status`
- * (`reconcileInstalledTuple`) both call this, so the
- * `upgradeOnlyDrift`-versus-`genuineDrift` distinction (SPEC-006 FR3) is
- * defined once rather than re-derived. A CLI that merely trails an upgrade
- * (`upgradeOnlyDrift`) is a `warn`; a genuinely incompatible tuple
- * (`incompatibleDrift`, doctor's digest/adapter drift) is a `fail`; any other
- * drift with no explaining CLI advance is also a `fail`.
- *
- * The math is a literal extraction of the former inline block, so every
- * pre-existing `runtime-manager-service.test.ts` assertion is the proof the
- * behaviour was preserved.
- */
-export function classifyComponentDrift(input) {
-    const drift = input.componentDrift || input.incompatibleDrift;
-    const genuineDrift = input.incompatibleDrift;
-    const upgradeOnlyDrift = drift && !genuineDrift && input.cliDrift;
-    const status = genuineDrift
-        ? 'fail'
-        : upgradeOnlyDrift
-            ? 'warn'
-            : drift
-                ? 'fail'
-                : 'pass';
-    return { drift, genuineDrift, upgradeOnlyDrift, status };
-}
 export async function runtimeDoctor(projectDir, options = {}) {
     const diagnostics = [];
     const repairs = [];
@@ -934,36 +1805,61 @@ export async function runtimeDoctor(projectDir, options = {}) {
     diagnostics.push({
         code: 'pipeline-package',
         status: pipeline ? 'pass' : 'warn',
-        message: pipeline ? `planr-pipeline ${pipeline.version}` : 'Planning-only installation',
-        ...(!pipeline ? { fix: 'Install openplanr without omitting optional dependencies.' } : {}),
+        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.' }
+            : {}),
     });
-    if (pipeline) {
-        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} declares ${mode} guided questions with native → chat → terminal → handoff fallback`
-                    : `${adapter.id} does not declare a guided interaction capability`,
-                ...(!mode
-                    ? { fix: 'Install the exact compatible planr-pipeline release and rerun setup.' }
-                    : {}),
-            });
-        }
+    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 claudeDetected = Boolean(options.claudeCommandRunner) ||
         (detectedRuntimes.find((runtime) => runtime.runtime === 'claude-code')?.installed ?? false);
-    if (pipeline && claudeDetected && claudeManagedAtUserScope) {
-        const inspection = inspectClaudePluginIntegration(pipeline.version, options.claudeCommandRunner);
+    if (claudeDetected && claudeManagedAtUserScope) {
+        const inspection = inspectBundledClaudePluginIntegration(bundledHostRoot('claude'), options.claudeCommandRunner);
         if (inspection.error) {
             diagnostics.push({
                 code: 'runtime-claude-plugins',
@@ -996,7 +1892,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
                     code: 'runtime-claude-legacy-plugin',
                     status: 'warn',
                     message: `Legacy Claude plugin installation detected: ${inspection.legacyPluginIds.join(', ')}`,
-                    fix: 'Verify `openplanr@openplanr`, then remove the legacy plugin from Claude Code.',
+                    fix: 'Verify `planr@openplanr-local`, then remove the legacy plugin from Claude Code.',
                 });
             }
         }
@@ -1028,12 +1924,13 @@ export async function runtimeDoctor(projectDir, options = {}) {
             const cliDrift = value.components?.cli !== cliVersion;
             const componentDrift = cliDrift ||
                 (pipeline && value.components?.pipeline !== pipeline.version) ||
-                value.components?.skills !== OPENPLANR_SKILLS_VERSION;
-            const expectedDigest = `sha256:${hash(JSON.stringify({
-                protocol: value.protocolVersion,
+                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) => {
@@ -1044,7 +1941,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
             });
             // FR11: an OpenPlanr upgrade advances the CLI version the lock recorded.
             // When the CLI component trails the installed build and nothing that
-            // governs Operating Board dispatch (runtime adapters, manifest digest)
+            // 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
@@ -1053,7 +1950,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
             // helper so `planr upgrade status` reuses this exact distinction (SPEC-006
             // FR3) rather than re-deriving it; a digest/adapter drift is doctor's
             // flavour of an incompatible tuple.
-            const { drift, genuineDrift, upgradeOnlyDrift, status } = classifyComponentDrift({
+            const { drift, genuineDrift, upgradeOnlyDrift, status } = classifyRuntimeComponentDrift({
                 cliDrift,
                 componentDrift: Boolean(componentDrift),
                 incompatibleDrift: digestDrift || adapterDrift,
@@ -1064,7 +1961,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 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 Operating Board execution`
+                        ? `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',
@@ -1104,143 +2001,60 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 ...(stateDrift ? { fix: 'Run `planr setup --dry-run`, then approve the repair.' } : {}),
             });
         }
-        const conflicts = [];
-        const missing = [];
-        for (const file of installed.ownedFiles) {
-            if (!existsSync(file.target))
-                missing.push(file.target);
-            else if (ownershipHash(readFileSync(file.target), file.kind, file.marker) !== file.hash)
-                conflicts.push(file.target);
-        }
+    }
+    else if (lockedAdapters?.length) {
         diagnostics.push({
-            code: conflicts.length ? 'migration-conflict' : 'managed-files',
-            status: conflicts.length ? 'fail' : missing.length ? 'warn' : 'pass',
-            message: conflicts.length
-                ? `${conflicts.length} managed file(s) changed outside setup`
-                : missing.length
-                    ? `${missing.length} managed file(s) are missing`
-                    : 'Managed runtime files match recorded ownership hashes',
-            ...(conflicts.length || missing.length
-                ? { fix: 'Run `planr setup --dry-run`, then explicitly approve repair or rollback.' }
-                : {}),
+            code: 'runtime-state-missing',
+            status: 'warn',
+            message: 'The project has a runtime lock but this machine has no managed adapter state',
+            fix: 'Run `planr setup` to install the locked runtime adapters on this machine.',
         });
-        const installedSkills = installed.ownedFiles.filter((file) => file.runtime === 'codex' && file.target.endsWith(`${path.sep}SKILL.md`));
-        if (installedSkills.length > 0) {
-            const supported = new Set(['artifact', 'doctor', 'operate', 'pipeline']);
-            const violations = [];
-            for (const skill of installedSkills) {
-                if (!existsSync(skill.target))
-                    continue;
-                const content = readFileSync(skill.target, 'utf8');
-                if (/`planr-pipeline\s+[^`]+`/u.test(content)) {
-                    violations.push(`${skill.target}: invokes planr-pipeline directly`);
-                }
-                for (const match of content.matchAll(/`planr\s+([a-z][\w-]*)(?:\s|`)/gu)) {
-                    if (!supported.has(match[1])) {
-                        violations.push(`${skill.target}: unknown planr command ${match[1]}`);
-                    }
-                }
-            }
-            diagnostics.push({
-                code: 'skill-commands',
-                status: violations.length > 0 ? 'fail' : 'pass',
-                message: violations.length > 0
-                    ? `${violations.length} installed skill command reference(s) are invalid`
-                    : 'Installed Codex skills reference public planr commands only',
-                ...(violations.length > 0
-                    ? { fix: 'Run `planr setup --runtime codex --scope user` to refresh managed skills.' }
-                    : {}),
-            });
-        }
-        // FR5: locate the operate skill by the name the installer actually wrote, derived
-        // from the same persisted prefix through the same helper. A `--no-prefix` install
-        // lives at `.codex/skills/operate/SKILL.md`, not the namespaced literal; without
-        // this the find misses the bare install, so the content contract below never runs
-        // while doctor still reports ok. The default keeps namespaced installs unchanged.
-        const operateSkillName = applyCommandPrefix('planr-operate', installed.commandPrefix ?? 'namespaced');
-        const operateSkill = installedSkills.find((skill) => path.basename(path.dirname(skill.target)) === operateSkillName);
-        if (installed.runtimes.includes('codex') && !operateSkill) {
-            diagnostics.push({
-                code: 'operate-skill',
-                status: 'warn',
-                message: `The installed Codex adapter is missing the ${operateSkillName} skill`,
-                fix: 'Run `planr setup --runtime codex --scope user` to install the managed skill.',
-            });
-        }
-        else if (operateSkill && existsSync(operateSkill.target)) {
-            const content = readFileSync(operateSkill.target, 'utf8');
-            const valid = new RegExp(String.raw `^name:\s*${operateSkillName}$`, 'mu').test(content) &&
-                /`planr operate(?:\s|`)/u.test(content) &&
-                /# Planr Operate — Codex-native workflow/u.test(content) &&
-                /planr operate inspect --json/u.test(content) &&
-                /bare `\$planr-operate`/u.test(content) &&
-                /Never dump a questionnaire/u.test(content) &&
-                /compact context review/u.test(content) &&
-                /If the user says “find it from the project,” continue investigating/u.test(content) &&
-                /`status`, `report`, `context show`/u.test(content) &&
-                /operating-advisor-response@1\.4/u.test(content) &&
-                /CEO, CTO, CPO, CMO, COO, then \[Chair\]/u.test(content) &&
-                /runtimeBinding: required/u.test(content) &&
-                /crossRuntimeFallback: false/u.test(content) &&
-                /harness prepare\|record\|finalize\|resume\|cancel/u.test(content) &&
-                /Never invoke another vendor runtime/u.test(content) &&
-                !/`planr-pipeline\s+[^`]+`/u.test(content) &&
-                /Never deploy, publish, spend, contact customers/u.test(content);
-            diagnostics.push({
-                code: 'operate-skill',
-                status: valid ? 'pass' : 'fail',
-                message: valid
-                    ? `Installed ${operateSkillName} skill references the public CLI and preserves the SHIP boundary`
-                    : `Installed ${operateSkillName} skill does not satisfy the functional command contract`,
-                ...(!valid
-                    ? { fix: 'Run `planr setup --runtime codex --scope user` to refresh the managed skill.' }
-                    : {}),
-            });
-        }
-        const cursorOperateRule = installed.ownedFiles.find((file) => file.runtime === 'cursor' && path.basename(file.target) === 'openplanr-operate.mdc');
-        if (installed.runtimes.includes('cursor') && !cursorOperateRule) {
+    }
+    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 codexBundle = state.userBundles?.codex;
+    if (detectRuntimes().some((runtime) => runtime.runtime === 'codex' && runtime.installed)) {
+        const configuredMode = codexBundle?.installMode ?? installed?.skillModes?.codex ?? 'direct';
+        const inspection = inspectCodexPluginIntegration(bundledHostRoot('openai'), configuredMode, configuredMode);
+        const directSkillFiles = codexBundle?.ownedFiles.filter((file) => pathIsWithin(file.target, codexSkillsRoot()))
+            .length ?? 0;
+        if (inspection.error) {
             diagnostics.push({
-                code: 'operate-cursor-rule',
+                code: 'runtime-codex-plugin',
                 status: 'warn',
-                message: 'The installed Cursor adapter is missing the Operating Board rule',
-                fix: 'Run `planr setup --runtime cursor --scope project` to install the managed rule.',
+                message: `Codex plugin state could not be inspected: ${inspection.error}`,
+                fix: 'Run `planr setup --runtime codex --dry-run` for an exact repair preview.',
             });
         }
-        else if (cursorOperateRule && existsSync(cursorOperateRule.target)) {
-            const content = readFileSync(cursorOperateRule.target, 'utf8');
-            const valid = /# OpenPlanr Operate — Cursor-native workflow/u.test(content) &&
-                /planr operate inspect\s+--json/u.test(content) &&
-                /one complete Cursor-bound cycle/u.test(content) &&
-                /Never dump a questionnaire/u.test(content) &&
-                /v1\.4 response/u.test(content) &&
-                /runtimeBinding: required/u.test(content) &&
-                /crossRuntimeFallback: false/u.test(content) &&
-                /internal `harness` lifecycle invisibly/u.test(content) &&
-                /Never invoke another vendor runtime/u.test(content) &&
-                !/`planr-pipeline\s+[^`]+`/u.test(content) &&
-                /do not approve, accept, apply, PLAN, SHIP/u.test(content);
+        else {
             diagnostics.push({
-                code: 'operate-cursor-rule',
-                status: valid ? 'pass' : 'fail',
-                message: valid
-                    ? 'Installed Cursor Operating Board rule references the public CLI and preserves the SHIP boundary'
-                    : 'Installed Cursor Operating Board rule does not satisfy the functional command contract',
-                ...(!valid
-                    ? {
-                        fix: 'Run `planr setup --runtime cursor --scope project` to refresh the managed rule.',
-                    }
-                    : {}),
+                code: 'runtime-codex-install-mode',
+                status: inspection.ready ? 'pass' : 'warn',
+                message: inspection.ready
+                    ? `Codex ${configuredMode} discovery is current`
+                    : `Codex ${configuredMode} discovery has ${inspection.operations.length} pending repair operation(s)`,
+                ...(inspection.ready
+                    ? {}
+                    : {
+                        fix: 'Run `planr setup --runtime codex --dry-run`, then apply the reviewed repair.',
+                    }),
             });
+            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.',
+                });
+            }
         }
     }
-    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 `planr setup` to install the locked runtime adapters on this machine.',
-        });
-    }
     const accidentalHomeFiles = await previewHomeProjectCleanup();
     if (accidentalHomeFiles.length > 0) {
         diagnostics.push({
@@ -1250,40 +2064,9 @@ export async function runtimeDoctor(projectDir, options = {}) {
             fix: 'Run `planr doctor --fix` to preview and remove only recorded OpenPlanr-owned project content.',
         });
     }
-    const provenancePath = path.join(projectDir, '.planr', 'provenance.jsonl');
-    if (existsSync(provenancePath)) {
-        const invalidLines = [];
-        const lines = readFileSync(provenancePath, 'utf8').split(/\r?\n/);
-        for (const [index, line] of lines.entries()) {
-            if (!line.trim())
-                continue;
-            try {
-                const event = JSON.parse(line);
-                if (!event.event_id || !event.producer?.product)
-                    invalidLines.push(index + 1);
-            }
-            catch {
-                invalidLines.push(index + 1);
-            }
-        }
-        diagnostics.push({
-            code: invalidLines.length ? 'provenance-invalid' : 'provenance',
-            status: invalidLines.length ? 'fail' : 'pass',
-            message: invalidLines.length
-                ? `Provenance contains invalid event lines: ${invalidLines.join(', ')}`
-                : 'Provenance is append-only JSONL with identifiable producers',
-            ...(invalidLines.length
-                ? {
-                    fix: 'Repair the invalid bytes, then explicitly append a recovery event. Doctor will not invent history.',
-                }
-                : {}),
-        });
-    }
-    diagnostics.push(...(await diagnoseOperatingBoard({
-        projectRoot: projectDir,
-        localRoot: path.join(userHome(), '.planr'),
-        pipelineVersion: pipeline?.version,
-    })));
+    const provenanceDiagnostic = diagnoseRuntimeProvenance(projectDir);
+    if (provenanceDiagnostic)
+        diagnostics.push(provenanceDiagnostic);
     if (pipeline) {
         const result = spawnSync(process.execPath, [
             path.join(pipeline.root, 'scripts', 'doctor.mjs'),
@@ -1315,7 +2098,7 @@ export async function runtimeDoctor(projectDir, options = {}) {
                 code: 'pipeline-doctor-unavailable',
                 status: 'warn',
                 message: 'The pipeline doctor did not return valid JSON',
-                fix: 'Run `planr pipeline doctor` for direct diagnostics.',
+                fix: 'Run `planr doctor` for direct diagnostics.',
             });
         }
     }