@open-agent-toolkit/cli 0.1.73 → 0.1.76

package/dist/engine/compute-plan.js

@@ -1,8 +1,10 @@
-import { access, lstat, readFile, readlink } from 'node:fs/promises';
-import { basename, dirname, join, normalize, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { access, lstat, readdir, readFile, readlink, stat, } from 'node:fs/promises';
+import { basename, dirname, join, normalize, relative, resolve, } from 'node:path';
 import { computeContentHash, computeStringHash } from '../manifest/hash.js';
 import { findEntry } from '../manifest/manager.js';
 import { getSyncMappings } from '../providers/shared/adapter.utils.js';
+import { OAT_DIRECTORY_SENTINEL, OAT_MARKER_PREFIX } from './markers.js';
 function buildUpLevels(depth) {
     return Array.from({ length: depth }, () => '..');
 }
@@ -88,6 +90,145 @@ function createRemovalEntry(manifestEntry, scopeRoot) {
         reason: 'canonical entry no longer exists',
     };
 }
+function createRetirementEntry(manifestEntry, scopeRoot, operation, reason) {
+    return {
+        ...createRemovalEntry(manifestEntry, scopeRoot),
+        operation,
+        reason,
+    };
+}
+function manifestEntryInsideMapping(entry, mapping) {
+    if (entry.contentType !== mapping.contentType) {
+        return false;
+    }
+    const canonicalPath = normalize(entry.canonicalPath).replaceAll('\\', '/');
+    const canonicalDir = normalize(mapping.canonicalDir).replaceAll('\\', '/');
+    return (canonicalPath === canonicalDir ||
+        canonicalPath.startsWith(`${canonicalDir}/`));
+}
+async function computeManagedDirectoryCopyHash(providerPath, canonicalPath, contentType) {
+    const expectedMarker = `${OAT_MARKER_PREFIX} Source: ${canonicalPath} -->`;
+    const sentinelPath = join(providerPath, OAT_DIRECTORY_SENTINEL);
+    try {
+        const sentinel = await readFile(sentinelPath, 'utf8');
+        if (sentinel !== `${expectedMarker}\n`) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    const files = [];
+    async function collectFiles(current) {
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = join(current, entry.name);
+            if (fullPath === sentinelPath) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (!(await collectFiles(fullPath))) {
+                    return false;
+                }
+                continue;
+            }
+            if (!entry.isFile()) {
+                return false;
+            }
+            files.push(fullPath);
+        }
+        return true;
+    }
+    try {
+        if (!(await collectFiles(providerPath))) {
+            return null;
+        }
+        files.sort((left, right) => relative(providerPath, left).localeCompare(relative(providerPath, right)));
+        const markerFileName = contentType === 'skill'
+            ? 'SKILL.md'
+            : contentType === 'agent'
+                ? 'AGENT.md'
+                : null;
+        const markerPath = markerFileName
+            ? join(providerPath, markerFileName)
+            : null;
+        const hash = createHash('sha256');
+        for (const file of files) {
+            const relativePath = relative(providerPath, file);
+            let content = await readFile(file);
+            if (file === markerPath) {
+                const markerPrefix = Buffer.from(`${expectedMarker}\n`);
+                if (content.length < markerPrefix.length ||
+                    !content.subarray(0, markerPrefix.length).equals(markerPrefix)) {
+                    return null;
+                }
+                content = content.subarray(markerPrefix.length);
+            }
+            hash.update(relativePath);
+            hash.update('\0');
+            hash.update(content);
+            hash.update('\0');
+        }
+        return hash.digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+async function classifyObsoleteMappingRetirement(manifestEntry, scopeRoot) {
+    const providerPath = resolve(scopeRoot, manifestEntry.providerPath);
+    const canonicalPath = resolve(scopeRoot, manifestEntry.canonicalPath);
+    let providerStat;
+    try {
+        providerStat = await lstat(providerPath);
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return createRetirementEntry(manifestEntry, scopeRoot, 'detach', 'obsolete mapping provider path is missing; detach manifest ownership');
+        }
+        return createRetirementEntry(manifestEntry, scopeRoot, 'detach', 'obsolete mapping provider path is unverified; preserve and detach manifest ownership');
+    }
+    if (manifestEntry.strategy === 'symlink') {
+        if (providerStat.isSymbolicLink()) {
+            try {
+                const linkTarget = await readlink(providerPath);
+                const resolvedTarget = resolve(dirname(providerPath), linkTarget);
+                await stat(resolvedTarget);
+                if (resolvedTarget === canonicalPath) {
+                    return createRetirementEntry(manifestEntry, scopeRoot, 'remove', 'obsolete mapping has verified clean managed symlink');
+                }
+            }
+            catch {
+                // Broken or unreadable links are preserved and detached below.
+            }
+        }
+        return createRetirementEntry(manifestEntry, scopeRoot, 'detach', 'obsolete mapping provider path is changed or unverified; preserve and detach manifest ownership');
+    }
+    const expectedTypeMatches = manifestEntry.isFile
+        ? providerStat.isFile()
+        : providerStat.isDirectory();
+    if (expectedTypeMatches && manifestEntry.contentHash) {
+        try {
+            const currentHash = await computeContentHash(providerPath, manifestEntry.isFile);
+            if (currentHash === manifestEntry.contentHash) {
+                return createRetirementEntry(manifestEntry, scopeRoot, 'remove', 'obsolete mapping has verified clean managed copy');
+            }
+        }
+        catch {
+            // Hash failures are unverified and therefore non-destructive.
+        }
+        if (!manifestEntry.isFile) {
+            const managedHash = await computeManagedDirectoryCopyHash(providerPath, canonicalPath, manifestEntry.contentType);
+            if (managedHash === manifestEntry.contentHash) {
+                return createRetirementEntry(manifestEntry, scopeRoot, 'remove', 'obsolete mapping has verified clean managed copy');
+            }
+        }
+    }
+    return createRetirementEntry(manifestEntry, scopeRoot, 'detach', 'obsolete mapping provider path is changed or unverified; preserve and detach manifest ownership');
+}
 async function classifyOperation(canonicalEntry, providerPath, strategy, renderedContent) {
     if (strategy === 'symlink') {
         let stat;
@@ -180,16 +321,22 @@ export async function computeSyncPlan({ canonical, adapters, manifest, scope, co
     const scopeRoot = resolveScopeRoot(canonical, explicitScopeRoot);
     const seenCanonicalKeys = new Set();
     const activeProviderNames = new Set();
+    const activeMappingsByProvider = new Map();
     const canonicalFilter = allowedCanonicalPaths
         ? new Set(allowedCanonicalPaths.map((canonicalPath) => normalize(canonicalPath)))
         : null;
     for (const adapter of adapters) {
+        if (resolveStrategy(adapter, config)) {
+            activeProviderNames.add(adapter.name);
+        }
         for (const mapping of getSyncMappings(adapter, scope)) {
             const mappingStrategy = resolveStrategy(adapter, config, Boolean(mapping.transformCanonical));
             if (!mappingStrategy) {
                 continue;
             }
-            activeProviderNames.add(adapter.name);
+            const activeMappings = activeMappingsByProvider.get(adapter.name) ?? [];
+            activeMappings.push(mapping);
+            activeMappingsByProvider.set(adapter.name, activeMappings);
             for (const canonicalEntry of canonical) {
                 if (!entryContentTypeMatches(canonicalEntry, mapping.contentType)) {
                     continue;
@@ -244,7 +391,10 @@ export async function computeSyncPlan({ canonical, adapters, manifest, scope, co
             !canonicalFilter.has(normalize(manifestEntry.canonicalPath))) {
             continue;
         }
-        removals.push(createRemovalEntry(manifestEntry, scopeRoot));
+        const mappingStillExists = (activeMappingsByProvider.get(manifestEntry.provider) ?? []).some((mapping) => manifestEntryInsideMapping(manifestEntry, mapping));
+        removals.push(mappingStillExists
+            ? createRemovalEntry(manifestEntry, scopeRoot)
+            : await classifyObsoleteMappingRetirement(manifestEntry, scopeRoot));
     }
     return { scope, entries, removals };
 }

package/dist/engine/engine.types.d.ts

@@ -1,7 +1,7 @@
 import type { Scope } from '../shared/types.js';
 import type { CanonicalEntry } from './scanner.js';
 export type EngineScope = Exclude<Scope, 'all'>;
-export declare const SYNC_OPERATION_TYPES: readonly ["create_symlink", "create_copy", "update_symlink", "update_copy", "remove", "skip"];
+export declare const SYNC_OPERATION_TYPES: readonly ["create_symlink", "create_copy", "update_symlink", "update_copy", "remove", "detach", "skip"];
 export type SyncOperationType = (typeof SYNC_OPERATION_TYPES)[number];
 export interface SyncPlanEntry {
     canonical: CanonicalEntry;
@@ -13,7 +13,7 @@ export interface SyncPlanEntry {
     renderedContent?: string;
 }
 export type RemovalSyncPlanEntry = SyncPlanEntry & {
-    operation: 'remove';
+    operation: 'remove' | 'detach';
 };
 export interface SyncPlan {
     scope: EngineScope;

package/dist/engine/engine.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.types.d.ts","sourceRoot":"","sources":["../../src/engine/engine.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAEhD,eAAO,MAAM,oBAAoB,+FAOvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG;IAAE,SAAS,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE3E,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"engine.types.d.ts","sourceRoot":"","sources":["../../src/engine/engine.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAEhD,eAAO,MAAM,oBAAoB,yGAQvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,QAAQ,EAAE,SAAS,GAAG,MAAM,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG;IACjD,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;CAChC,CAAC;AAEF,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/engine/engine.types.js

@@ -4,5 +4,6 @@ export const SYNC_OPERATION_TYPES = [
     'update_symlink',
     'update_copy',
     'remove',
+    'detach',
     'skip',
 ];

package/dist/engine/execute-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute-plan.d.ts","sourceRoot":"","sources":["../../src/engine/execute-plan.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,0BAA0B,CAAC;AAExE,OAAO,KAAK,EAAE,QAAQ,EAAiB,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAG1E,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAW5D;AAuJD,wBAAsB,eAAe,CACnC,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,UAAU,CAAC,CA0BrB"}
+{"version":3,"file":"execute-plan.d.ts","sourceRoot":"","sources":["../../src/engine/execute-plan.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,0BAA0B,CAAC;AAExE,OAAO,KAAK,EAAE,QAAQ,EAAiB,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAG1E,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAW5D;AA2JD,wBAAsB,eAAe,CACnC,IAAI,EAAE,QAAQ,EACd,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,UAAU,CAAC,CA0BrB"}

package/dist/engine/execute-plan.js

@@ -98,6 +98,10 @@ async function applyEntry(planEntry, manifest) {
             const { canonicalPath } = resolveManifestPaths(planEntry);
             return removeEntry(manifest, canonicalPath, planEntry.provider);
         }
+        case 'detach': {
+            const { canonicalPath } = resolveManifestPaths(planEntry);
+            return removeEntry(manifest, canonicalPath, planEntry.provider);
+        }
         case 'skip': {
             return manifest;
         }

package/dist/engine/index.d.ts

@@ -5,5 +5,5 @@ export { configureLocalHooksPath, getHookInstallInfo, HOOK_DRIFT_WARNING, HOOK_M
 export type { HookInstallInfo, HookStatus } from './hook.js';
 export { hasMarker, insertMarker, OAT_DIRECTORY_SENTINEL, OAT_MARKER_PREFIX, writeDirectorySentinel, } from './markers.js';
 export type { CanonicalEntry } from './scanner.js';
-export { scanBundledManagedCodexAgents, scanCanonical } from './scanner.js';
+export { scanBundledManagedAgents, scanBundledManagedCodexAgents, scanCanonical, } from './scanner.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,aAAa,GACd,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EACL,SAAS,EACT,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,6BAA6B,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,aAAa,GACd,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EACL,SAAS,EACT,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,wBAAwB,EACxB,6BAA6B,EAC7B,aAAa,GACd,MAAM,WAAW,CAAC"}

package/dist/engine/index.js

@@ -3,4 +3,4 @@ export { SYNC_OPERATION_TYPES, } from './engine.types.js';
 export { executeSyncPlan } from './execute-plan.js';
 export { configureLocalHooksPath, getHookInstallInfo, HOOK_DRIFT_WARNING, HOOK_MARKER_END, HOOK_MARKER_START, HOOK_STRAY_INFO, installHook, isHookInstalled, REPO_GITHOOKS_PATH, runHookCheck, uninstallHook, } from './hook.js';
 export { hasMarker, insertMarker, OAT_DIRECTORY_SENTINEL, OAT_MARKER_PREFIX, writeDirectorySentinel, } from './markers.js';
-export { scanBundledManagedCodexAgents, scanCanonical } from './scanner.js';
+export { scanBundledManagedAgents, scanBundledManagedCodexAgents, scanCanonical, } from './scanner.js';

package/dist/engine/scanner.d.ts

@@ -6,7 +6,9 @@ export interface CanonicalEntry {
     canonicalPath: string;
     isFile: boolean;
 }
-export declare function scanBundledManagedCodexAgents(): Promise<CanonicalEntry[]>;
+export declare function scanBundledManagedAgents(): Promise<CanonicalEntry[]>;
+/** @deprecated Use scanBundledManagedAgents for provider-neutral materialization. */
+export declare const scanBundledManagedCodexAgents: typeof scanBundledManagedAgents;
 export declare function scanCanonical(basePath: string, scope: ConcreteScope): Promise<CanonicalEntry[]>;
 export {};
 //# sourceMappingURL=scanner.d.ts.map

package/dist/engine/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/engine/scanner.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,KAAK,EACX,MAAM,eAAe,CAAC;AAEvB,KAAK,aAAa,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AA0DD,wBAAsB,6BAA6B,IAAI,OAAO,CAC5D,cAAc,EAAE,CACjB,CAsBA;AAED,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,cAAc,EAAE,CAAC,CA2B3B"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/engine/scanner.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,KAAK,EACX,MAAM,eAAe,CAAC;AAEvB,KAAK,aAAa,GAAG,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AA0DD,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAsB1E;AAED,qFAAqF;AACrF,eAAO,MAAM,6BAA6B,iCAA2B,CAAC;AAEtE,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,cAAc,EAAE,CAAC,CA2B3B"}

package/dist/engine/scanner.js

@@ -43,13 +43,13 @@ async function readEntries(dirPath) {
         throw error;
     }
 }
-export async function scanBundledManagedCodexAgents() {
+export async function scanBundledManagedAgents() {
     const agentsDir = join(await resolveAssetsRoot(), 'agents');
     const entries = await readEntries(agentsDir);
     const available = new Set(entries.filter((entry) => entry.isFile).map((entry) => entry.name));
     const missing = USER_SCOPE_MANAGED_AGENT_FILES.filter((name) => !available.has(name));
     if (missing.length > 0) {
-        throw new CliError(`Bundled managed Codex role definitions are unavailable: ${missing.join(', ')}. Reinstall or rebuild OAT before running user sync.`);
+        throw new CliError(`Bundled managed role definitions are unavailable: ${missing.join(', ')}. Reinstall or rebuild OAT before running user sync.`);
     }
     return USER_SCOPE_MANAGED_AGENT_FILES.map((name) => ({
         name,
@@ -58,6 +58,8 @@ export async function scanBundledManagedCodexAgents() {
         isFile: true,
     }));
 }
+/** @deprecated Use scanBundledManagedAgents for provider-neutral materialization. */
+export const scanBundledManagedCodexAgents = scanBundledManagedAgents;
 export async function scanCanonical(basePath, scope) {
     const scopeRoot = resolve(basePath);
     const entries = [];

package/dist/manifest/manifest.types.d.ts

@@ -10,37 +10,37 @@ export declare const ManifestEntrySchema: z.ZodEffects<z.ZodObject<{
     lastSynced: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     provider: string;
+    strategy: "symlink" | "copy";
     canonicalPath: string;
     providerPath: string;
     contentType: "skill" | "agent" | "rule";
-    strategy: "symlink" | "copy";
     contentHash: string | null;
     isFile: boolean;
     lastSynced: string;
 }, {
     provider: string;
+    strategy: "symlink" | "copy";
     canonicalPath: string;
     providerPath: string;
     contentType: "skill" | "agent" | "rule";
-    strategy: "symlink" | "copy";
     contentHash: string | null;
     lastSynced: string;
     isFile?: boolean | undefined;
 }>, {
     provider: string;
+    strategy: "symlink" | "copy";
     canonicalPath: string;
     providerPath: string;
     contentType: "skill" | "agent" | "rule";
-    strategy: "symlink" | "copy";
     contentHash: string | null;
     isFile: boolean;
     lastSynced: string;
 }, {
     provider: string;
+    strategy: "symlink" | "copy";
     canonicalPath: string;
     providerPath: string;
     contentType: "skill" | "agent" | "rule";
-    strategy: "symlink" | "copy";
     contentHash: string | null;
     lastSynced: string;
     isFile?: boolean | undefined;
@@ -59,37 +59,37 @@ export declare const ManifestSchema: z.ZodEffects<z.ZodObject<{
         lastSynced: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         provider: string;
+        strategy: "symlink" | "copy";
         canonicalPath: string;
         providerPath: string;
         contentType: "skill" | "agent" | "rule";
-        strategy: "symlink" | "copy";
         contentHash: string | null;
         isFile: boolean;
         lastSynced: string;
     }, {
         provider: string;
+        strategy: "symlink" | "copy";
         canonicalPath: string;
         providerPath: string;
         contentType: "skill" | "agent" | "rule";
-        strategy: "symlink" | "copy";
         contentHash: string | null;
         lastSynced: string;
         isFile?: boolean | undefined;
     }>, {
         provider: string;
+        strategy: "symlink" | "copy";
         canonicalPath: string;
         providerPath: string;
         contentType: "skill" | "agent" | "rule";
-        strategy: "symlink" | "copy";
         contentHash: string | null;
         isFile: boolean;
         lastSynced: string;
     }, {
         provider: string;
+        strategy: "symlink" | "copy";
         canonicalPath: string;
         providerPath: string;
         contentType: "skill" | "agent" | "rule";
-        strategy: "symlink" | "copy";
         contentHash: string | null;
         lastSynced: string;
         isFile?: boolean | undefined;
@@ -98,10 +98,10 @@ export declare const ManifestSchema: z.ZodEffects<z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     entries: {
         provider: string;
+        strategy: "symlink" | "copy";
         canonicalPath: string;
         providerPath: string;
         contentType: "skill" | "agent" | "rule";
-        strategy: "symlink" | "copy";
         contentHash: string | null;
         isFile: boolean;
         lastSynced: string;
@@ -112,10 +112,10 @@ export declare const ManifestSchema: z.ZodEffects<z.ZodObject<{
 }, {
     entries: {
         provider: string;
+        strategy: "symlink" | "copy";
         canonicalPath: string;
         providerPath: string;
         contentType: "skill" | "agent" | "rule";
-        strategy: "symlink" | "copy";
         contentHash: string | null;
         lastSynced: string;
         isFile?: boolean | undefined;
@@ -126,10 +126,10 @@ export declare const ManifestSchema: z.ZodEffects<z.ZodObject<{
 }>, {
     entries: {
         provider: string;
+        strategy: "symlink" | "copy";
         canonicalPath: string;
         providerPath: string;
         contentType: "skill" | "agent" | "rule";
-        strategy: "symlink" | "copy";
         contentHash: string | null;
         isFile: boolean;
         lastSynced: string;
@@ -140,10 +140,10 @@ export declare const ManifestSchema: z.ZodEffects<z.ZodObject<{
 }, {
     entries: {
         provider: string;
+        strategy: "symlink" | "copy";
         canonicalPath: string;
         providerPath: string;
         contentType: "skill" | "agent" | "rule";
-        strategy: "symlink" | "copy";
         contentHash: string | null;
         lastSynced: string;
         isFile?: boolean | undefined;

package/dist/providers/ceiling/registry.d.ts

@@ -13,6 +13,7 @@
  * (no variant files). Every other provider is advisory by default.
  */
 export type EnforcementMechanism = 'pinned-variant' | 'model-arg' | 'none';
+export type ProviderSelectionAxis = 'model' | 'model-effort' | 'tier' | 'none';
 export type CeilingRole = 'implementer' | 'reviewer';
 export interface CeilingCompileContext {
     /** The orchestrator's own tier, used to detect above-orchestrator upgrades. */
@@ -33,6 +34,7 @@ export interface ProviderCeilingAdapter {
     supportsCeiling: boolean;
     validValues: string[];
     mechanism: EnforcementMechanism;
+    selectionAxis: ProviderSelectionAxis;
     /**
      * Compile a ceiling value into dispatch args for the given role, or `null`
      * when the value is invalid or the provider is advisory/unsupported.

package/dist/providers/ceiling/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/providers/ceiling/registry.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG,WAAW,GAAG,MAAM,CAAC;AAE3E,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,CAAC;CACV;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB,IAAI,CAAC;AAKT,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,oBAAoB,CAAC;IAChC;;;OAGG;IACH,qBAAqB,CACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,qBAAqB,GACzB,mBAAmB,CAAC;IACvB;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC;CACtE;AAMD,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAK9C,CAAC;AA4GF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAE1E"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/providers/ceiling/registry.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG,WAAW,GAAG,MAAM,CAAC;AAC3E,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/E,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,CAAC;CACV;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB,IAAI,CAAC;AAKT,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,oBAAoB,CAAC;IAChC,aAAa,EAAE,qBAAqB,CAAC;IACrC;;;OAGG;IACH,qBAAqB,CACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,qBAAqB,GACzB,mBAAmB,CAAC;IACvB;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC;CACtE;AAMD,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EAK9C,CAAC;AA6HF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAE1E"}

package/dist/providers/ceiling/registry.js

@@ -1,5 +1,7 @@
 import { VALID_CLAUDE_DISPATCH_CEILINGS, VALID_CODEX_DISPATCH_CEILINGS, } from '../../config/oat-config.js';
 import { buildCodexMaterializedTargetRoleName } from '../codex/codec/shared.js';
+import { findCursorModelPinMapping } from '../cursor/codec/catalog.js';
+import { buildCursorMaterializedRoleName } from '../cursor/codec/shared.js';
 const DIRECT_DISPATCH_ROLE_PATTERN = /^oat-(?:phase-implementer|reviewer)(?:-|$)/;
 export function isDirectDispatchRoleName(value) {
     return DIRECT_DISPATCH_ROLE_PATTERN.test(value.trim());
@@ -19,6 +21,7 @@ const codexAdapter = {
     supportsCeiling: true,
     validValues: [...VALID_CODEX_DISPATCH_CEILINGS],
     mechanism: 'pinned-variant',
+    selectionAxis: 'model-effort',
     compileToDispatchArgs(value, role, ctx) {
         if (!VALID_CODEX_DISPATCH_CEILINGS.includes(value)) {
             return null;
@@ -60,6 +63,7 @@ const claudeAdapter = {
     supportsCeiling: true,
     validValues: [...VALID_CLAUDE_DISPATCH_CEILINGS],
     mechanism: 'model-arg',
+    selectionAxis: 'tier',
     compileToDispatchArgs(value) {
         if (isDirectDispatchRoleName(value) ||
             !VALID_CLAUDE_DISPATCH_CEILINGS.includes(value)) {
@@ -76,10 +80,21 @@ const cursorAdapter = {
     provider: 'cursor',
     supportsCeiling: true,
     validValues: [],
-    mechanism: 'model-arg',
-    compileToDispatchArgs(value) {
-        const model = value.trim();
-        return model && !isDirectDispatchRoleName(model) ? { model } : null;
+    mechanism: 'pinned-variant',
+    selectionAxis: 'model',
+    compileToDispatchArgs(value, role, ctx) {
+        const model = ctx.target?.model ?? value.trim();
+        if (!model ||
+            isDirectDispatchRoleName(model) ||
+            !findCursorModelPinMapping(model)) {
+            return null;
+        }
+        return {
+            variant: buildCursorMaterializedRoleName({
+                agentName: role === 'reviewer' ? CODEX_REVIEWER_ROLE : CODEX_IMPLEMENTER_ROLE,
+                ladderModelId: model,
+            }),
+        };
     },
     // Cursor model slugs do not share a total order, so upgrade verification is
     // not meaningful here; availability is checked by the identity oracle layer.
@@ -93,6 +108,7 @@ function advisoryAdapter(provider) {
         supportsCeiling: false,
         validValues: [],
         mechanism: 'none',
+        selectionAxis: 'none',
         compileToDispatchArgs() {
             return null;
         },

package/dist/providers/codex/codec/sync-extension.d.ts

@@ -1,5 +1,6 @@
 import type { CanonicalEntry } from '../../../engine/index.js';
-export type CodexExtensionAction = 'create' | 'update' | 'remove' | 'skip';
+import { type MaterializationAction, type MaterializationApplyResult, type MaterializationContext, type MaterializationExtension, type MaterializationPlan, type MaterializationWriteOperation } from '../../shared/index.js';
+export type CodexExtensionAction = MaterializationAction;
 export type CodexExtensionTarget = 'role' | 'config';
 export interface CodexExtensionOperation {
     action: CodexExtensionAction;
@@ -8,20 +9,20 @@ export interface CodexExtensionOperation {
     reason: string;
     roleName?: string;
 }
-export interface CodexExtensionWriteOperation extends CodexExtensionOperation {
-    content?: string;
+export interface CodexExtensionWriteOperation extends MaterializationWriteOperation<'codex', CodexExtensionTarget> {
+    roleName?: string;
 }
-export interface CodexExtensionPlan {
+export interface CodexExtensionPlan extends MaterializationPlan<'codex', CodexExtensionTarget, CodexExtensionPlanMetadata> {
     operations: CodexExtensionWriteOperation[];
     managedRoles: string[];
     aggregateConfigHash: string;
 }
-export interface CodexExtensionApplyResult {
-    applied: number;
-    failed: number;
-    skipped: number;
+export interface CodexExtensionPlanMetadata {
+    managedRoles: string[];
+    aggregateConfigHash: string;
 }
-interface CodexMaterializationTargetOptions {
+export type CodexExtensionApplyResult = MaterializationApplyResult;
+export interface CodexMaterializationTargetOptions {
     userConfigDir?: string;
     projectPath?: string | null;
     env?: NodeJS.ProcessEnv;
@@ -34,5 +35,5 @@ export declare function summarizeCodexExtension(plan: CodexExtensionPlan): {
     skipped: number;
 };
 export declare function toCodexExtensionOperations(plan: CodexExtensionPlan): CodexExtensionOperation[];
-export {};
+export declare const codexMaterializationExtension: MaterializationExtension<CodexExtensionPlan, MaterializationContext<CodexMaterializationTargetOptions>>;
 //# sourceMappingURL=sync-extension.d.ts.map

package/dist/providers/codex/codec/sync-extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-extension.d.ts","sourceRoot":"","sources":["../../../../src/providers/codex/codec/sync-extension.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAyBpD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAC3E,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,4BAA6B,SAAQ,uBAAuB;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,4BAA4B,EAAE,CAAC;IAC3C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAgBD,UAAU,iCAAiC;IACzC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAqiBD,wBAAsB,gCAAgC,CACpD,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,cAAc,EAAE,EAClC,qBAAqB,CAAC,EAAE,MAAM,EAAE,EAChC,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,kBAAkB,CAAC,CAqJ7B;AAED,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,yBAAyB,CAAC,CA6BpC;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAE1E;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,kBAAkB,GAAG;IACjE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB,CAaA;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,kBAAkB,GACvB,uBAAuB,EAAE,CAQ3B"}
+{"version":3,"file":"sync-extension.d.ts","sourceRoot":"","sources":["../../../../src/providers/codex/codec/sync-extension.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAKpD,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EACnC,MAAM,mBAAmB,CAAC;AAqB3B,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AACzD,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,4BAA6B,SAAQ,6BAA6B,CACjF,OAAO,EACP,oBAAoB,CACrB;IACC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB,CAC7D,OAAO,EACP,oBAAoB,EACpB,0BAA0B,CAC3B;IACC,UAAU,EAAE,4BAA4B,EAAE,CAAC;IAC3C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AAgBnE,MAAM,WAAW,iCAAiC;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAqiBD,wBAAsB,gCAAgC,CACpD,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,cAAc,EAAE,EAClC,qBAAqB,CAAC,EAAE,MAAM,EAAE,EAChC,OAAO,GAAE,iCAAsC,GAC9C,OAAO,CAAC,kBAAkB,CAAC,CAkL7B;AAED,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,yBAAyB,CAAC,CA6BpC;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAE1E;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,kBAAkB,GAAG;IACjE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB,CAEA;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,kBAAkB,GACvB,uBAAuB,EAAE,CAQ3B;AAED,eAAO,MAAM,6BAA6B,EAAE,wBAAwB,CAClE,kBAAkB,EAClB,sBAAsB,CAAC,iCAAiC,CAAC,CAY1D,CAAC"}