@open-agent-toolkit/cli 0.2.51 → 0.2.53

package/dist/engine/execute-plan.js

@@ -1,14 +1,60 @@
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
-import { copyDirectory, copySingleFile, createSymlink } from '../fs/io.js';
+import { copyDirectory, copySingleFile, copySingleFileNoClobber, createCollectionSymlinkNoClobber, createSymlink, createSymlinkNoClobber, removeCollectionSymlinkIfUnchanged, writeFileNoClobber, } from '../fs/io.js';
 import { computeContentHash, computeStringHash } from '../manifest/hash.js';
-import { addEntry, findEntry, removeEntry, saveManifest, } from '../manifest/manager.js';
+import { saveManifest as persistManifest } from '../manifest/manager.js';
+import { collectionProofMatches, projectCollectionOwnership, proveCollectionIdentity, } from './collection-sync.js';
 import { insertMarker, writeDirectorySentinel } from './markers.js';
 import { assertSafeProviderMutationPath } from './provider-path-safety.js';
 const DEFAULT_EXECUTE_SYNC_PLAN_DEPENDENCIES = {};
 function mutatesProviderPath(entry) {
     return entry.operation !== 'skip' && entry.operation !== 'detach';
 }
+function operationEvidence(scope, entry, status, failure) {
+    return {
+        scope,
+        provider: entry.provider,
+        contentKind: entry.canonical.type,
+        asset: entry.canonical.name,
+        action: entry.operation,
+        status,
+        ...(failure ? { failure } : {}),
+    };
+}
+function classifyFailure(error, destinationPolicy) {
+    if (hasErrorCode(error, 'E_DEFERRED_DIRECTORY_TRANSITION_UNSAFE')) {
+        return {
+            status: 'failed',
+            failure: 'Manual recovery required: deferred collection-directory transitions are unavailable on this runtime. Disable the provider and run sync to detach OAT ownership, then verify and remove the preserved alias before managing the provider directory externally. Automatic publication requires an identity-bound, non-following primitive.',
+        };
+    }
+    if (destinationPolicy === 'preserve-existing' &&
+        hasErrorCode(error, 'EEXIST')) {
+        return {
+            status: 'failed',
+            failure: 'Destination appeared after collection clearance; preserved unmanaged content. Resolve the destination and retry sync.',
+        };
+    }
+    if (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT') {
+        return {
+            status: 'missing',
+            failure: 'Canonical or provider input was missing; restore it and retry sync.',
+        };
+    }
+    return {
+        status: 'failed',
+        failure: 'Operation failed; inspect local verbose diagnostics and retry sync.',
+    };
+}
+function hasErrorCode(error, code) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === code);
+}
 async function assertSafeEntryProviderPath(entry) {
     const scopeRoot = inferScopeRoot(resolve(entry.canonical.canonicalPath));
     await assertSafeProviderMutationPath(scopeRoot, entry.providerPath);
@@ -71,19 +117,41 @@ async function applyCopyMarker(entry) {
         throw error;
     }
 }
-async function applyEntry(planEntry, manifest) {
+async function applyEntry(planEntry, manifest, destinationPolicy, copyDirectoryImpl, createSymlinkNoClobberImpl) {
     switch (planEntry.operation) {
         case 'create_symlink':
         case 'update_symlink': {
+            if (destinationPolicy === 'preserve-existing') {
+                if (!planEntry.canonical.isFile) {
+                    throw Object.assign(new Error('Deferred collection-directory publication is unavailable on this runtime.'), { code: 'E_DEFERRED_DIRECTORY_TRANSITION_UNSAFE' });
+                }
+                await createSymlinkNoClobberImpl(planEntry.canonical.canonicalPath, planEntry.providerPath, planEntry.canonical.isFile);
+                const manifestEntry = await toManifestEntry(planEntry, 'symlink');
+                return addManifestEntry(manifest, manifestEntry);
+            }
             if (planEntry.operation === 'update_symlink') {
                 await rm(planEntry.providerPath, { recursive: true, force: true });
             }
             const strategyUsed = await createSymlink(planEntry.canonical.canonicalPath, planEntry.providerPath, undefined, planEntry.canonical.isFile);
             const manifestEntry = await toManifestEntry(planEntry, strategyUsed);
-            return addEntry(manifest, manifestEntry);
+            return addManifestEntry(manifest, manifestEntry);
         }
         case 'create_copy':
         case 'update_copy': {
+            if (destinationPolicy === 'preserve-existing') {
+                if (planEntry.canonical.isFile &&
+                    planEntry.renderedContent !== undefined) {
+                    await writeFileNoClobber(planEntry.providerPath, planEntry.renderedContent);
+                }
+                else if (planEntry.canonical.isFile) {
+                    await copySingleFileNoClobber(planEntry.canonical.canonicalPath, planEntry.providerPath);
+                }
+                else {
+                    throw Object.assign(new Error('Deferred collection-directory publication is unavailable on this runtime.'), { code: 'E_DEFERRED_DIRECTORY_TRANSITION_UNSAFE' });
+                }
+                const manifestEntry = await toManifestEntry(planEntry, 'copy');
+                return addManifestEntry(manifest, manifestEntry);
+            }
             if (planEntry.operation === 'update_copy') {
                 await rm(planEntry.providerPath, { recursive: true, force: true });
             }
@@ -96,20 +164,20 @@ async function applyEntry(planEntry, manifest) {
                 await copySingleFile(planEntry.canonical.canonicalPath, planEntry.providerPath);
             }
             else {
-                await copyDirectory(planEntry.canonical.canonicalPath, planEntry.providerPath);
+                await copyDirectoryImpl(planEntry.canonical.canonicalPath, planEntry.providerPath);
                 await applyCopyMarker(planEntry);
             }
             const manifestEntry = await toManifestEntry(planEntry, 'copy');
-            return addEntry(manifest, manifestEntry);
+            return addManifestEntry(manifest, manifestEntry);
         }
         case 'remove': {
             await rm(planEntry.providerPath, { recursive: true, force: true });
             const { canonicalPath } = resolveManifestPaths(planEntry);
-            return removeEntry(manifest, canonicalPath, planEntry.provider);
+            return removeManifestEntry(manifest, canonicalPath, planEntry.provider);
         }
         case 'detach': {
             const { canonicalPath } = resolveManifestPaths(planEntry);
-            return removeEntry(manifest, canonicalPath, planEntry.provider);
+            return removeManifestEntry(manifest, canonicalPath, planEntry.provider);
         }
         case 'skip': {
             return manifest;
@@ -118,50 +186,414 @@ async function applyEntry(planEntry, manifest) {
             return manifest;
     }
 }
+function addManifestEntry(manifest, entry) {
+    return {
+        ...manifest,
+        entries: [
+            ...manifest.entries.filter((candidate) => !(candidate.canonicalPath === entry.canonicalPath &&
+                candidate.provider === entry.provider)),
+            entry,
+        ],
+        lastUpdated: new Date().toISOString(),
+    };
+}
+function removeManifestEntry(manifest, canonicalPath, provider) {
+    const entries = manifest.entries.filter((entry) => !(entry.canonicalPath === canonicalPath && entry.provider === provider));
+    return entries.length === manifest.entries.length
+        ? manifest
+        : { ...manifest, entries, lastUpdated: new Date().toISOString() };
+}
 async function ensureSkipEntryManaged(planEntry, manifest) {
     const { canonicalPath } = resolveManifestPaths(planEntry);
-    const existing = findEntry(manifest, canonicalPath, planEntry.provider);
+    const existing = manifest.entries.find((entry) => entry.canonicalPath === canonicalPath &&
+        entry.provider === planEntry.provider);
     if (existing) {
         return manifest;
     }
     const manifestEntry = await toManifestEntry(planEntry, planEntry.strategy);
-    return addEntry(manifest, manifestEntry);
+    return addManifestEntry(manifest, manifestEntry);
+}
+function detachCollectionOwnership(manifest, plan) {
+    const scopeRoot = inferScopeRoot(plan.canonicalDir);
+    const canonicalDir = relative(scopeRoot, plan.canonicalDir).replaceAll('\\', '/');
+    const providerDir = relative(scopeRoot, plan.providerDir).replaceAll('\\', '/');
+    const detachedIds = new Set(manifest.collections
+        .filter((collection) => collection.provider === plan.provider &&
+        collection.contentType === plan.contentType &&
+        collection.canonicalDir === canonicalDir &&
+        collection.providerDir === providerDir)
+        .map(({ id }) => id));
+    if (detachedIds.size === 0) {
+        return manifest;
+    }
+    return {
+        ...manifest,
+        collections: manifest.collections.filter(({ id }) => !detachedIds.has(id)),
+        entries: manifest.entries.filter((entry) => entry.strategy !== 'collection' ||
+            entry.collectionId === undefined ||
+            !detachedIds.has(entry.collectionId)),
+        lastUpdated: new Date().toISOString(),
+    };
+}
+async function executeCollectionTransaction(plans, manifest, blockedDeferredDirectoryTransitions, dependencies, manifestPath, beforeMutation) {
+    const passiveResults = plans
+        .filter(({ action }) => action === 'fallback-per-entry' || action === 'reject-collection')
+        .map((plan) => ({
+        provider: plan.provider,
+        contentType: plan.contentType,
+        action: plan.action,
+        ownership: plan.ownership,
+        status: plan.action === 'fallback-per-entry' ? 'fallback' : 'rejected',
+        reason: plan.reason,
+    }));
+    const actionable = plans.filter(({ action }) => action === 'create-collection-link' ||
+        action === 'adopt-collection-link' ||
+        action === 'inherit-collection');
+    const detachments = plans.filter(({ action }) => action === 'detach-collection');
+    if (actionable.length === 0 && detachments.length === 0) {
+        return {
+            manifest,
+            results: passiveResults,
+            attempted: false,
+            persisted: false,
+        };
+    }
+    const verified = new Map();
+    const createdCollections = [];
+    const removedTransitionPlans = new Set();
+    const absentTransitionPlans = new Set();
+    const blockedTransitionResults = new Map();
+    let nextManifest = manifest;
+    try {
+        await beforeMutation();
+        for (const plan of actionable) {
+            const current = await dependencies.proveCollectionIdentity({
+                root: inferScopeRoot(plan.canonicalDir),
+                canonicalDir: plan.canonicalDir,
+                providerDir: plan.providerDir,
+            });
+            if (!collectionProofMatches(plan.proof, current)) {
+                throw new Error('collection identity changed after planning; preserved destination');
+            }
+            verified.set(plan, current);
+            if (plan.action === 'create-collection-link') {
+                if (current.status !== 'absent') {
+                    throw new Error('collection destination is no longer absent');
+                }
+                const created = await dependencies.createCollectionSymlinkNoClobber(plan.canonicalDir, plan.providerDir, {
+                    scopeRoot: inferScopeRoot(plan.canonicalDir),
+                    expectedParent: current.providerParent,
+                });
+                createdCollections.push({ plan, created });
+                const rescanned = await dependencies.proveCollectionIdentity({
+                    root: inferScopeRoot(plan.canonicalDir),
+                    canonicalDir: plan.canonicalDir,
+                    providerDir: plan.providerDir,
+                });
+                if (rescanned.status !== 'exact-link') {
+                    throw new Error('created collection alias did not verify as exact');
+                }
+                verified.set(plan, rescanned);
+            }
+            const proof = verified.get(plan);
+            if (proof?.status !== 'exact-link') {
+                throw new Error('collection alias exact identity is unavailable');
+            }
+            nextManifest = await projectCollectionOwnership(nextManifest, plan, proof);
+        }
+        for (const plan of detachments) {
+            if (!plan.transitionToPerEntry) {
+                nextManifest = detachCollectionOwnership(nextManifest, plan);
+                continue;
+            }
+            const blockTransition = (status, reason) => {
+                blockedTransitionResults.set(plan, {
+                    provider: plan.provider,
+                    contentType: plan.contentType,
+                    action: plan.action,
+                    ownership: plan.ownership,
+                    status,
+                    reason,
+                });
+            };
+            if (blockedDeferredDirectoryTransitions.has(`${plan.provider}::${plan.contentType}`)) {
+                blockTransition('rejected', `Manual recovery required: deferred collection-directory transitions are unavailable on this runtime, so collection ownership was preserved. Run "oat providers set --scope ${plan.scope} --disabled ${plan.provider}" and then "oat sync --scope ${plan.scope}" to detach OAT ownership. Then verify and remove the preserved alias before managing the provider directory externally. Automatic publication requires an identity-bound, non-following primitive.`);
+                continue;
+            }
+            if (plan.proof.status === 'absent') {
+                try {
+                    const current = await dependencies.proveCollectionIdentity({
+                        root: inferScopeRoot(plan.canonicalDir),
+                        canonicalDir: plan.canonicalDir,
+                        providerDir: plan.providerDir,
+                    });
+                    if (current.status !== 'absent' ||
+                        !collectionProofMatches(plan.proof, current)) {
+                        blockTransition('rejected', 'collection transition blocked; the manually cleared destination changed after planning, so ownership and child operations were preserved');
+                        continue;
+                    }
+                    absentTransitionPlans.add(plan);
+                    nextManifest = detachCollectionOwnership(nextManifest, plan);
+                }
+                catch {
+                    blockTransition('rejected', 'collection transition blocked; destination absence could not be safely re-proven, so ownership and child operations were preserved');
+                }
+                continue;
+            }
+            if (plan.ownership !== 'oat-created' ||
+                plan.proof.status !== 'exact-link' ||
+                plan.createdLink === undefined) {
+                blockTransition('rejected', 'collection transition blocked; exact durable creation identity is unavailable, so ownership and the alias were preserved');
+                continue;
+            }
+            try {
+                const current = await dependencies.proveCollectionIdentity({
+                    root: inferScopeRoot(plan.canonicalDir),
+                    canonicalDir: plan.canonicalDir,
+                    providerDir: plan.providerDir,
+                });
+                if (current.status !== 'exact-link' ||
+                    !collectionProofMatches(plan.proof, current) ||
+                    current.providerLink.device !== plan.createdLink.device ||
+                    current.providerLink.inode !== plan.createdLink.inode ||
+                    current.linkText !== plan.createdLink.linkText) {
+                    blockTransition('rejected', 'collection transition blocked; alias identity changed after planning, so ownership and the replacement path were preserved');
+                    continue;
+                }
+                const removed = await dependencies.removeCollectionSymlinkIfUnchanged(plan.providerDir, plan.createdLink);
+                if (!removed) {
+                    blockTransition('partial', 'collection transition blocked; this runtime cannot safely unlink the exact alias, so ownership and child operations were preserved; remove the alias manually, then replan and retry');
+                    continue;
+                }
+                removedTransitionPlans.add(plan);
+                nextManifest = detachCollectionOwnership(nextManifest, plan);
+            }
+            catch {
+                blockTransition('rejected', 'collection transition blocked; alias identity could not be safely re-proven, so ownership and the provider path were preserved');
+            }
+        }
+        const hasManifestMutation = actionable.length > 0 ||
+            detachments.some((plan) => !plan.transitionToPerEntry) ||
+            removedTransitionPlans.size > 0 ||
+            absentTransitionPlans.size > 0;
+        if (hasManifestMutation) {
+            await dependencies.saveManifest(manifestPath, nextManifest);
+        }
+        const detachmentResults = [];
+        for (const plan of detachments) {
+            const blocked = blockedTransitionResults.get(plan);
+            if (blocked) {
+                detachmentResults.push(blocked);
+                continue;
+            }
+            if (plan.transitionToPerEntry) {
+                detachmentResults.push({
+                    provider: plan.provider,
+                    contentType: plan.contentType,
+                    action: plan.action,
+                    ownership: plan.ownership,
+                    status: 'changed',
+                    reason: absentTransitionPlans.has(plan)
+                        ? 'manually cleared collection destination remained absent through apply; ownership detached and per-entry reconciliation may proceed'
+                        : 'exact durably identified collection alias was removed before ownership detachment; per-entry reconciliation may proceed',
+                });
+                continue;
+            }
+            let reason = plan.reason;
+            let status = 'changed';
+            if (plan.ownership === 'oat-created' &&
+                plan.proof.status === 'exact-link' &&
+                plan.createdLink !== undefined) {
+                try {
+                    const current = await dependencies.proveCollectionIdentity({
+                        root: inferScopeRoot(plan.canonicalDir),
+                        canonicalDir: plan.canonicalDir,
+                        providerDir: plan.providerDir,
+                    });
+                    if (current.status === 'exact-link' &&
+                        collectionProofMatches(plan.proof, current) &&
+                        current.providerLink.device === plan.createdLink.device &&
+                        current.providerLink.inode === plan.createdLink.inode &&
+                        current.linkText === plan.createdLink.linkText) {
+                        const removed = await dependencies.removeCollectionSymlinkIfUnchanged(plan.providerDir, plan.createdLink);
+                        if (!removed) {
+                            status = 'partial';
+                            reason =
+                                'collection ownership detached, but this runtime cannot safely unlink the exact alias; the alias was preserved for manual removal';
+                        }
+                    }
+                    else {
+                        reason =
+                            'collection ownership detached; alias identity changed after planning and was preserved';
+                    }
+                }
+                catch {
+                    status = 'partial';
+                    reason =
+                        'collection ownership detached; alias removal could not be proven safe and was preserved';
+                }
+            }
+            else if (plan.ownership === 'oat-created') {
+                reason =
+                    'collection ownership detached; durable creation identity was unavailable and the alias was preserved';
+            }
+            detachmentResults.push({
+                provider: plan.provider,
+                contentType: plan.contentType,
+                action: plan.action,
+                ownership: plan.ownership,
+                status,
+                reason,
+            });
+        }
+        return {
+            manifest: nextManifest,
+            results: [
+                ...passiveResults,
+                ...actionable.map((plan) => ({
+                    provider: plan.provider,
+                    contentType: plan.contentType,
+                    action: plan.action,
+                    ownership: plan.ownership,
+                    status: plan.action === 'inherit-collection'
+                        ? 'current'
+                        : 'changed',
+                    reason: plan.reason,
+                })),
+                ...detachmentResults,
+            ],
+            attempted: true,
+            persisted: hasManifestMutation,
+        };
+    }
+    catch (error) {
+        const rollback = await Promise.all([...createdCollections]
+            .reverse()
+            .map(({ plan, created }) => dependencies.removeCollectionSymlinkIfUnchanged(plan.providerDir, created)));
+        const partial = rollback.some((removed) => !removed) || removedTransitionPlans.size > 0;
+        const guardedCreationUnavailable = hasErrorCode(error, 'E_COLLECTION_LINK_UNSAFE');
+        return {
+            manifest,
+            results: [
+                ...passiveResults,
+                ...actionable.map((plan) => ({
+                    provider: plan.provider,
+                    contentType: plan.contentType,
+                    action: plan.action,
+                    ownership: plan.ownership,
+                    status: partial ? 'partial' : 'failed',
+                    reason: guardedCreationUnavailable
+                        ? 'collection creation is disabled because this runtime cannot create a link relative to a securely guarded parent; configure explicit symlink/copy per-entry sync or create the exact collection alias manually and retry for adoption'
+                        : partial
+                            ? 'collection transaction failed; automatic rollback unlink is unavailable, so any created alias was preserved for manual recovery'
+                            : 'collection transaction failed; newly created links were rolled back',
+                })),
+                ...detachments.map((plan) => {
+                    const blocked = blockedTransitionResults.get(plan);
+                    if (blocked)
+                        return blocked;
+                    return {
+                        provider: plan.provider,
+                        contentType: plan.contentType,
+                        action: plan.action,
+                        ownership: plan.ownership,
+                        status: removedTransitionPlans.has(plan)
+                            ? 'partial'
+                            : 'failed',
+                        reason: removedTransitionPlans.has(plan)
+                            ? 'exact alias was safely removed, but manifest ownership could not be detached; no per-entry child operations were attempted'
+                            : 'collection transaction failed before ownership detachment',
+                    };
+                }),
+            ],
+            attempted: true,
+            persisted: false,
+        };
+    }
 }
 export async function executeSyncPlan(plan, manifest, manifestPath, dependencies = DEFAULT_EXECUTE_SYNC_PLAN_DEPENDENCIES) {
+    const saveManifest = dependencies.saveManifest ?? persistManifest;
+    const collectionDependencies = {
+        saveManifest,
+        createCollectionSymlinkNoClobber: dependencies.createCollectionSymlinkNoClobber ??
+            createCollectionSymlinkNoClobber,
+        removeCollectionSymlinkIfUnchanged: dependencies.removeCollectionSymlinkIfUnchanged ??
+            removeCollectionSymlinkIfUnchanged,
+        proveCollectionIdentity: dependencies.proveCollectionIdentity ?? proveCollectionIdentity,
+    };
     let nextManifest = manifest;
     let beforeFirstMutationCalled = false;
-    const result = {
-        applied: 0,
-        failed: 0,
-        skipped: 0,
-    };
+    const operationResults = [];
     const operations = [...plan.entries, ...plan.removals];
+    const beforeMutation = async () => {
+        if (!beforeFirstMutationCalled) {
+            beforeFirstMutationCalled = true;
+            await dependencies.beforeFirstMutation?.();
+        }
+    };
     for (const operation of operations) {
-        if (mutatesProviderPath(operation)) {
+        if (mutatesProviderPath(operation) &&
+            !operation.deferredUntilCollectionDetached) {
             await assertSafeEntryProviderPath(operation);
         }
     }
+    const blockedDeferredDirectoryTransitions = new Set(operations
+        .filter((operation) => (operation.operation === 'create_copy' ||
+        operation.operation === 'create_symlink') &&
+        operation.deferredUntilCollectionDetached &&
+        !operation.canonical.isFile)
+        .map((operation) => `${operation.provider}::${operation.canonical.type}`));
+    const collectionTransaction = await executeCollectionTransaction(plan.collections ?? [], nextManifest, blockedDeferredDirectoryTransitions, collectionDependencies, manifestPath, beforeMutation);
+    nextManifest = collectionTransaction.manifest;
+    const blockedTransitions = new Map(collectionTransaction.results
+        .filter(({ action, status }) => action === 'detach-collection' && status !== 'changed')
+        .map((result) => [
+        `${result.provider}::${result.contentType}`,
+        result.reason,
+    ]));
     for (const operation of operations) {
+        if (operation.deferredUntilCollectionDetached &&
+            blockedTransitions.has(`${operation.provider}::${operation.canonical.type}`)) {
+            operationResults.push(operationEvidence(plan.scope, operation, 'failed', blockedTransitions.get(`${operation.provider}::${operation.canonical.type}`) ??
+                'Collection alias could not be safely cleared; resolve the reported collection conflict and retry.'));
+            continue;
+        }
         if (operation.operation === 'skip') {
             nextManifest = await ensureSkipEntryManaged(operation, nextManifest);
-            result.skipped += 1;
+            operationResults.push(operationEvidence(plan.scope, operation, 'current'));
             continue;
         }
+        const destinationPolicy = operation.deferredUntilCollectionDetached
+            ? 'preserve-existing'
+            : 'ordinary';
         try {
             if (mutatesProviderPath(operation)) {
-                if (!beforeFirstMutationCalled) {
-                    beforeFirstMutationCalled = true;
-                    await dependencies.beforeFirstMutation?.();
-                }
+                await beforeMutation();
                 await assertSafeEntryProviderPath(operation);
             }
-            nextManifest = await applyEntry(operation, nextManifest);
-            result.applied += 1;
+            nextManifest = await applyEntry(operation, nextManifest, destinationPolicy, dependencies.copyDirectory ?? copyDirectory, dependencies.createSymlinkNoClobber ?? createSymlinkNoClobber);
+            operationResults.push(operationEvidence(plan.scope, operation, 'changed'));
         }
-        catch {
-            result.failed += 1;
+        catch (error) {
+            const failure = classifyFailure(error, destinationPolicy);
+            operationResults.push(operationEvidence(plan.scope, operation, failure.status, failure.failure));
         }
     }
-    await saveManifest(manifestPath, nextManifest);
-    return result;
+    const entryApplySucceeded = operationResults.some(({ status }) => status === 'changed' || status === 'current');
+    const successfulNoOperationApply = operations.length === 0 && !collectionTransaction.attempted;
+    if (entryApplySucceeded || successfulNoOperationApply) {
+        await saveManifest(manifestPath, nextManifest);
+    }
+    const collectionApplied = collectionTransaction.results.filter(({ status }) => status === 'changed').length;
+    const collectionFailed = collectionTransaction.results.filter(({ status }) => status === 'failed' || status === 'partial' || status === 'rejected').length;
+    const collectionSkipped = collectionTransaction.results.filter(({ status }) => status === 'current' || status === 'fallback').length;
+    return {
+        applied: operationResults.filter(({ status }) => status === 'changed').length +
+            collectionApplied,
+        failed: operationResults.filter(({ status }) => status === 'failed' || status === 'missing').length + collectionFailed,
+        skipped: operationResults.filter(({ status }) => status === 'current').length +
+            collectionSkipped,
+        operations: operationResults,
+        collectionResults: collectionTransaction.results,
+    };
 }

package/dist/engine/index.d.ts

@@ -6,5 +6,5 @@ export type { HookInstallInfo, HookStatus } from './hook.js';
 export { hasMarker, insertMarker, OAT_DIRECTORY_SENTINEL, OAT_MARKER_PREFIX, writeDirectorySentinel, } from './markers.js';
 export { assertSafeProviderMutationPath } from './provider-path-safety.js';
 export type { CanonicalEntry } from './scanner.js';
-export { scanBundledManagedAgents, scanBundledManagedCodexAgents, scanCanonical, } from './scanner.js';
+export { materializationCanonicalPathAllowed, mergeUserScopeMaterializationEntries, 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,EACL,iCAAiC,EACjC,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,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,OAAO,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AACxE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,wBAAwB,EACxB,6BAA6B,EAC7B,aAAa,GACd,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iCAAiC,EACjC,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,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,OAAO,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AACxE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EACL,mCAAmC,EACnC,oCAAoC,EACpC,wBAAwB,EACxB,6BAA6B,EAC7B,aAAa,GACd,MAAM,WAAW,CAAC"}

package/dist/engine/index.js

@@ -4,4 +4,4 @@ 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 { assertSafeProviderMutationPath } from './provider-path-safety.js';
-export { scanBundledManagedAgents, scanBundledManagedCodexAgents, scanCanonical, } from './scanner.js';
+export { materializationCanonicalPathAllowed, mergeUserScopeMaterializationEntries, scanBundledManagedAgents, scanBundledManagedCodexAgents, scanCanonical, } from './scanner.js';

package/dist/engine/provider-path-safety.d.ts

@@ -1,2 +1,3 @@
 export declare function assertSafeProviderMutationPath(scopeRoot: string, providerPath: string): Promise<void>;
+export declare function assertSafeProviderCollectionPath(scopeRoot: string, canonicalDir: string, providerDir: string): Promise<void>;
 //# sourceMappingURL=provider-path-safety.d.ts.map

package/dist/engine/provider-path-safety.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-path-safety.d.ts","sourceRoot":"","sources":["../../src/engine/provider-path-safety.ts"],"names":[],"mappings":"AAiBA,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAuDf"}
+{"version":3,"file":"provider-path-safety.d.ts","sourceRoot":"","sources":["../../src/engine/provider-path-safety.ts"],"names":[],"mappings":"AAiBA,wBAAsB,8BAA8B,CAClD,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAuDf;AAYD,wBAAsB,gCAAgC,CACpD,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/engine/provider-path-safety.js

@@ -52,3 +52,18 @@ export async function assertSafeProviderMutationPath(scopeRoot, providerPath) {
         }
     }
 }
+function isNestedPath(parent, candidate) {
+    const relativePath = relative(resolve(parent), resolve(candidate));
+    return (relativePath === '' ||
+        (!isAbsolute(relativePath) &&
+            relativePath !== '..' &&
+            !relativePath.startsWith(`..${sep}`)));
+}
+export async function assertSafeProviderCollectionPath(scopeRoot, canonicalDir, providerDir) {
+    if (isNestedPath(canonicalDir, providerDir) ||
+        isNestedPath(providerDir, canonicalDir)) {
+        throw new Error('Canonical and provider collection paths must not be nested.');
+    }
+    await assertSafeProviderMutationPath(scopeRoot, canonicalDir);
+    await assertSafeProviderMutationPath(scopeRoot, providerDir);
+}

package/dist/engine/scanner.d.ts

@@ -1,4 +1,4 @@
-import { type Scope } from '../shared/types.js';
+import { type CanonicalScanTarget, type Scope } from '../shared/types.js';
 type ConcreteScope = Exclude<Scope, 'all'>;
 export interface CanonicalEntry {
     name: string;
@@ -7,8 +7,15 @@ export interface CanonicalEntry {
     isFile: boolean;
 }
 export declare function scanBundledManagedAgents(): Promise<CanonicalEntry[]>;
+/**
+ * User-scope Codex/Cursor materialization reads the bundled managed role files,
+ * not the installed copies under `~/.agents/agents/`. Concatenating both lists
+ * produces the same Cursor/Codex role name twice and aborts the whole sync.
+ */
+export declare function mergeUserScopeMaterializationEntries(canonicalEntries: CanonicalEntry[], bundledManagedAgents: CanonicalEntry[]): CanonicalEntry[];
+export declare function materializationCanonicalPathAllowed(scopeRoot: string, canonicalEntry: CanonicalEntry, allowedCanonicalPaths?: string[]): boolean;
 /** @deprecated Use scanBundledManagedAgents for provider-neutral materialization. */
 export declare const scanBundledManagedCodexAgents: typeof scanBundledManagedAgents;
-export declare function scanCanonical(basePath: string, scope: ConcreteScope): Promise<CanonicalEntry[]>;
+export declare function scanCanonical(basePath: string, scope: ConcreteScope, targets?: readonly CanonicalScanTarget[]): 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,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"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../../src/engine/scanner.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,mBAAmB,EACxB,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;;;;GAIG;AACH,wBAAgB,oCAAoC,CAClD,gBAAgB,EAAE,cAAc,EAAE,EAClC,oBAAoB,EAAE,cAAc,EAAE,GACrC,cAAc,EAAE,CAqBlB;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,cAAc,EAC9B,qBAAqB,CAAC,EAAE,MAAM,EAAE,GAC/B,OAAO,CAqBT;AAED,qFAAqF;AACrF,eAAO,MAAM,6BAA6B,iCAA2B,CAAC;AAEtE,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,SAAS,mBAAmB,EAAE,GACvC,OAAO,CAAC,cAAc,EAAE,CAAC,CA6C3B"}