@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/cli/handlers/use.js

@@ -1,3 +1,4 @@
+import { trackTemporaryDirectory } from '../../utils/temporary-directory.js';
 /**
  * Use Command Handler
  *
@@ -13,9 +14,12 @@ import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import { pathToFileURL } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
+import { canDeploySkill, sameSkillOwner, extractFrameworkSlug } from '../../providers/skill-ownership.mjs';
 import { resolveOmpPaths } from '../../providers/omp-paths.mjs';
 import YAML from 'yaml';
 import { createScriptRunner } from './script-runner.js';
+import { finalizePreparedProvider, prepareProviderDeployments } from '../services/provider-prepare-coordinator.js';
 import { getFrameworkRoot, getVersionInfo } from '../../channel/manager.mjs';
 import { getRegistry } from '../../extensions/registry.js';
 import { registerDeployedExtensions } from '../../extensions/deployment-registration.js';
@@ -39,6 +43,7 @@ import { detectScope, mirrorToUserScope, rejectOpenClawProjectScope, USER_SCOPE_
 import { maybeWarnProjectIsolation } from '../project-isolation/index.js';
 import { formatWorkspaceSignalPlan, includedBundleIds, resolveWorkspaceSignalPlan, writeWorkspaceSignalPlan, } from '../workspace-signals.js';
 import { getProviderArtifactPathStrings, getProviderDefinition, getProviderKernelSkillPath, normalizeProviderDefinitionId, } from '../../providers/provider-definitions.js';
+import { deployedSkillRoots } from '../../providers/deployed-skill-roots.js';
 // Module-level guard so the iteration loops further down (which re-enter
 // execute() per framework/provider) don't re-emit the warning each pass.
 // Reset is not needed: a single CLI process is one user invocation.
@@ -47,12 +52,14 @@ let projectIsolationChecked = false;
 // collecting child-process output. The CLI is single-command-per-process;
 // recursive provider expansion shares this guard intentionally.
 let machineReadableUseDepth = 0;
+// Providers whose complete project projection is covered by the transferable
+// rule-delivery transaction. Other built-ins retain their serial deploy path.
+const PREPARABLE_BUILTIN_PROVIDERS = new Set(['claude', 'codex', 'cursor', 'hermes', 'pi', 'warp']);
 // Context-pipeline: emits WORKSPACE.md + AIWG.md + provider adapters last.
 // for non-Claude providers per ADR-1 (.aiwg/architecture/adr-agents-md-aggregation.md).
 // Distinct from agentsmith (which creates subagent personas).
 import { generate as generateContextFiles, discoverDeployedArtifacts, } from '../../smiths/context-pipeline/index.js';
 import { verifyModelWrapperDeployment } from '../../models/wrapper-deployment.js';
-import { loadGraphIndexFile } from '../../artifacts/index-reader.js';
 import { aggregateUseDeploymentResult, buildDryRunUseResult, renderUseDeploymentResult, verifyProviderDeployment, } from '../services/deployment-verification.js';
 import { finalizeProviderTransformationReceipt, providerReceiptHasLocalSources, sourceVerificationsFromSignedWebRelease, } from '../../providers/transformation-receipt-integration.js';
 import { loadResourceTrustRootFile, resolveWebRelease, } from '../../resources/web-release.js';
@@ -145,6 +152,11 @@ const MODEL_OVERRIDE_VALUE_FLAGS = new Set([
     '--model', '--reasoning-model', '--coding-model', '--efficiency-model', '--model-tier',
 ]);
 const MODEL_DEPLOY_BOOLEAN_FLAGS = new Set(['--save', '--save-user']);
+/** Forward explicit user scope to every provider deploy subprocess. */
+export function collectUseScopeDeployArgs(args) {
+    const scope = detectScope(args);
+    return scope === 'user' || args.includes('--user') ? ['--scope', 'user'] : [];
+}
 export function collectUseModelDeployArgs(args) {
     const forwarded = [];
     for (let i = 0; i < args.length; i++) {
@@ -241,7 +253,7 @@ const FRAMEWORK_DIR_MAP = {
     all: 'sdlc-complete',
 };
 /** Resolve actual framework directory name for a given user-facing name. */
-function resolveFrameworkDir(framework) {
+export function resolveFrameworkDir(framework) {
     return FRAMEWORK_DIR_MAP[framework];
 }
 /**
@@ -392,6 +404,18 @@ export function addonPath(frameworkRoot, name) {
     const folderName = resolveAddonFolderName(name);
     return path.join(frameworkRoot, 'agentic/code/addons', folderName);
 }
+/**
+ * Whether the provider's root deployment already collects every eligible
+ * addon for this mode. The caller still registers addon CLI contributions;
+ * this only suppresses redundant deploy-agents subprocesses.
+ */
+export function mainDeploymentIncludesAddons(provider, selectedMode, providerDeployArgs) {
+    return (((provider === 'claude' || provider === 'pi')
+        && ['general', 'sdlc', 'both', 'all'].includes(selectedMode))
+        || (provider === 'codex' && selectedMode === 'all'))
+        && !providerDeployArgs.some(arg => arg === '--source' || arg.startsWith('--source='))
+        && providerDeployArgs.filter(arg => arg === '--mode').length === 1;
+}
 /**
  * Resolve a selected addon's required addon dependencies in deterministic
  * dependency-first order. Optional dependencies remain descriptive and are
@@ -1042,17 +1066,11 @@ async function listBundleSkillNameCandidates(bundlePath) {
         return [];
     }
 }
-async function countDeployedBundleSkills(bundlePath, target, provider, paths) {
+async function countDeployedBundleSkills(bundlePath, target, provider) {
     const skillCandidates = await listBundleSkillNameCandidates(bundlePath);
     if (skillCandidates.length === 0)
         return 0;
-    const candidateDirs = [
-        paths.skills,
-        getProviderKernelSkillsPath(provider),
-    ]
-        .filter(Boolean)
-        .map(dir => resolveDeployPath(target, dir));
-    const uniqueCandidateDirs = [...new Set(candidateDirs)];
+    const uniqueCandidateDirs = deployedSkillRoots(target, provider);
     let count = 0;
     for (const names of skillCandidates) {
         let found = false;
@@ -1075,16 +1093,35 @@ async function countBundleDeployedArtifacts(bundlePath, target, provider) {
     return {
         agents: await countDeployedBundleFiles(bundlePath, 'agents', target, paths.agents, ['.md', '.toml']),
         commands: await countDeployedBundleFiles(bundlePath, 'commands', target, paths.commands, ['.md']),
-        skills: await countDeployedBundleSkills(bundlePath, target, provider, paths),
+        skills: await countDeployedBundleSkills(bundlePath, target, provider),
         rules: await countDeployedBundleFiles(bundlePath, 'rules', target, paths.rules, ['.md', '.mdc']),
     };
 }
 const SKILL_SUPPORT_REFERENCE = /(?:^|[\s`('"\[])((?:templates|references|scripts|assets)\/[A-Za-z0-9._@/+\-]+)(?=$|[\s`)'"\],:;])/gm;
 /** Copy one support file, preserving its executable bit. */
-async function copySkillSupportFile(source, destination) {
+async function copySkillSupportFile(source, destination, skillDir) {
     await fs.mkdir(path.dirname(destination), { recursive: true });
     await fs.copyFile(source, destination);
     await fs.chmod(destination, (await fs.stat(source)).mode & 0o777);
+    // Extend the shared copier's receipt for bundle-root assets too. Adapters
+    // without that receipt keep their own ownership and cleanup contract.
+    if (!skillDir)
+        return;
+    const manifestPath = path.join(skillDir, '.aiwg-manifest.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    if (!manifest.skillSource || !manifest.managed?.['SKILL.md'])
+        return;
+    manifest.managed[path.relative(skillDir, destination)] = {
+        ...manifest.managed['SKILL.md'],
+        hash: `sha256:${createHash('sha256').update(await fs.readFile(destination)).digest('hex')}`,
+    };
+    await fs.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
 }
 /**
  * Materialize a directory-valued support-asset reference (#2503).
@@ -1094,7 +1131,7 @@ async function copySkillSupportFile(source, destination) {
  * file modes are preserved so script packs stay executable. Empty directories
  * are still created — a reference to an empty pack is odd but not an error.
  */
-async function copySkillSupportTree(source, destination, sourceSkillMd, reference, deployFile) {
+async function copySkillSupportTree(source, destination, sourceSkillMd, reference, deployFile, skillDir) {
     await fs.mkdir(destination, { recursive: true });
     const label = reference.replace(/\/+$/, '');
     const entries = await fs.readdir(source, { withFileTypes: true });
@@ -1105,7 +1142,7 @@ async function copySkillSupportTree(source, destination, sourceSkillMd, referenc
             throw new Error(`unsafe skill support asset '${label}/${entry.name}' referenced by ${sourceSkillMd}: symbolic links are not deployed`);
         }
         if (entry.isDirectory()) {
-            await copySkillSupportTree(from, to, sourceSkillMd, `${label}/${entry.name}`, deployFile);
+            await copySkillSupportTree(from, to, sourceSkillMd, `${label}/${entry.name}`, deployFile, skillDir);
             continue;
         }
         if (!entry.isFile())
@@ -1114,7 +1151,7 @@ async function copySkillSupportTree(source, destination, sourceSkillMd, referenc
             deployFile(from, to);
             continue;
         }
-        await copySkillSupportFile(from, to);
+        await copySkillSupportFile(from, to, skillDir);
     }
 }
 /**
@@ -1135,12 +1172,9 @@ async function reconcileDeployedSkillAssets(bundlePath, target, provider, option
     catch {
         return;
     }
-    const paths = getProviderPaths(provider);
-    const kernelSkillsPath = getProviderKernelSkillsPath(provider);
     const deployRoots = provider === 'omp' && options.scope === 'user'
         ? [path.join(resolveOmpPaths({ cwd: target }).agentDir, 'skills')]
-        : [...new Set([paths.skills, kernelSkillsPath]
-                .filter((value) => Boolean(value)).map(value => resolveDeployPath(target, value)))];
+        : deployedSkillRoots(target, provider);
     for (const skillName of skillDirs) {
         const sourceSkillDir = path.join(skillsRoot, skillName);
         const sourceSkillMd = path.join(sourceSkillDir, 'SKILL.md');
@@ -1151,7 +1185,35 @@ async function reconcileDeployedSkillAssets(bundlePath, target, provider, option
         catch {
             continue;
         }
-        if (options.skipUndeployed && !(await Promise.all(deployRoots.map(root => fileExists(path.join(root, skillName, 'SKILL.md'))))).some(Boolean))
+        // Check each deployed tier independently: a foreign mirror must not block
+        // support assets for a tier already owned by this source.
+        const ownedRoots = [];
+        for (const root of deployRoots) {
+            const skillDir = path.join(root, skillName);
+            try {
+                const manifestPath = path.join(skillDir, '.aiwg-manifest.json');
+                const receipt = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+                if (!canDeploySkill(receipt, sourceSkillDir, options))
+                    continue;
+                if (!sameSkillOwner(receipt, sourceSkillDir)) {
+                    receipt.skillSource = path.resolve(sourceSkillDir);
+                    const slug = extractFrameworkSlug(sourceSkillMd);
+                    for (const record of Object.values(receipt.managed ?? {})) {
+                        if (slug)
+                            record.frameworkSlug = slug;
+                        else
+                            delete record.frameworkSlug;
+                    }
+                    await fs.writeFile(manifestPath, `${JSON.stringify(receipt, null, 2)}\n`);
+                }
+            }
+            catch { /* adapters without shared ownership receipts keep their own contract */ }
+            if (await fileExists(path.join(skillDir, 'SKILL.md')))
+                ownedRoots.push(root);
+        }
+        if (ownedRoots.length === 0)
+            continue;
+        if (options.skipUndeployed && !(await Promise.all(ownedRoots.map(root => fileExists(path.join(root, skillName, 'SKILL.md'))))).some(Boolean))
             continue;
         const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? '';
         const declaredEntrypoint = frontmatter
@@ -1194,7 +1256,7 @@ async function reconcileDeployedSkillAssets(bundlePath, target, provider, option
                 throw new Error(`skill entrypoint '${relative}' in ${sourceSkillMd} resolves to a directory; an entrypoint must be a file`);
             }
             let deployedSkillRoot;
-            for (const root of deployRoots) {
+            for (const root of ownedRoots) {
                 // The deployer may select the bulk or kernel tier; use the tier that
                 // actually contains this skill's transformed SKILL.md.
                 if (await fileExists(path.join(root, skillName, 'SKILL.md'))) {
@@ -1212,14 +1274,14 @@ async function reconcileDeployedSkillAssets(bundlePath, target, provider, option
                 })()
                 : null;
             if (sourceIsDirectory) {
-                await copySkillSupportTree(source, destination, sourceSkillMd, relative, deployFile);
+                await copySkillSupportTree(source, destination, sourceSkillMd, relative, deployFile, path.join(deployedSkillRoot, skillName));
                 continue;
             }
             if (deployFile) {
                 deployFile(source, destination);
                 continue;
             }
-            await copySkillSupportFile(source, destination);
+            await copySkillSupportFile(source, destination, path.join(deployedSkillRoot, skillName));
         }
     }
 }
@@ -1291,6 +1353,9 @@ async function deployOneProjectLocalBundle(opts) {
             '--deploy-version', projectLocalDeployVersion(bundle),
             ...modelArgs,
         ];
+        args.push(...collectUseScopeDeployArgs(ctx.args));
+        if (ctx.args.includes('--force'))
+            args.push('--force');
         if (dryRun)
             args.push('--dry-run');
         if (verbose)
@@ -1316,7 +1381,7 @@ async function deployOneProjectLocalBundle(opts) {
         exitCode = result.exitCode;
         if (exitCode === 0 && !dryRun) {
             try {
-                await reconcileDeployedSkillAssets(bundle.artifactPath, target, provider);
+                await reconcileDeployedSkillAssets(bundle.artifactPath, target, provider, { force: ctx.args.includes('--force') });
             }
             catch (error) {
                 ui.warn(`Project-local skill asset deployment failed for '${bundle.id}': ${error.message}`);
@@ -1967,18 +2032,30 @@ async function generateGlobalProjectContext(opts) {
         },
     });
 }
+/** Receipt reuse applies to complete packages; selected partial sources still need an actual build. */
+async function reconcileSelectedFrameworkSource(root) {
+    const { refreshFrameworkCapabilities, resolveFrameworkCorpusRoot } = await import('../../artifacts/framework-capabilities.js');
+    if (resolveFrameworkCorpusRoot(root)) {
+        const { loadPrebuiltDeploymentIndex } = await import('../../artifacts/prebuilt-deployment.js');
+        if (loadPrebuiltDeploymentIndex(root, { strictRoot: true }))
+            return;
+        await refreshFrameworkCapabilities(root, true, { force: true });
+        return;
+    }
+    const { buildIndex } = await import('../../artifacts/index-builder.js');
+    await buildIndex(root, { graph: 'framework', explicit: false });
+    const { syncFortemiCoreIndex } = await import('../../artifacts/fortemi-core-sync.js');
+    syncFortemiCoreIndex(root, { graph: 'framework' });
+}
 async function ensurePostDeployPhases(opts) {
-    const currentIndex = loadGraphIndexFile(opts.frameworkRoot, 'metadata.json', 'framework');
-    const builtAt = currentIndex ? Date.parse(currentIndex.builtAt) : Number.NaN;
-    const startedAt = Date.parse(opts.invocationStartedAt);
-    if (!Number.isFinite(builtAt) || builtAt + 2_000 < startedAt) {
-        try {
-            const { buildIndex } = await import('../../artifacts/index-builder.js');
-            await buildIndex(opts.frameworkRoot, { graph: 'framework', explicit: false });
-        }
-        catch {
-            // The shared verifier reports the index failure with stable remediation.
-        }
+    // Validate source files once after deployment, including uncommitted edits
+    // that the cheap HEAD/manifest receipt intentionally cannot detect. Earlier
+    // deployment/query phases can reuse that receipt instead of rescanning.
+    try {
+        await reconcileSelectedFrameworkSource(opts.frameworkRoot);
+    }
+    catch {
+        // The shared verifier reports the index failure with stable remediation.
     }
     // The Fortemi export is the default discovery backend. Rebuilding only the
     // source graph makes any existing export stale, so every successful use
@@ -1986,8 +2063,9 @@ async function ensurePostDeployPhases(opts) {
     // materializes a fresh-install cache without requiring a manual index sync.
     try {
         const { getFortemiCoreSyncStatus, syncFortemiCoreIndex, } = await import('../../artifacts/fortemi-core-sync.js');
+        const { loadPrebuiltDeploymentIndex } = await import('../../artifacts/prebuilt-deployment.js');
         const status = getFortemiCoreSyncStatus(opts.frameworkRoot, 'framework');
-        if (!status.built || status.stale) {
+        if (!loadPrebuiltDeploymentIndex(opts.frameworkRoot, { strictRoot: true }) && (!status.built || status.stale)) {
             syncFortemiCoreIndex(opts.frameworkRoot, { graph: 'framework' });
         }
     }
@@ -2031,6 +2109,7 @@ async function deploySourceDirectory(opts) {
         '--target', opts.target,
         ...opts.modelArgs,
     ];
+    args.push(...collectUseScopeDeployArgs(opts.ctx.args));
     if (opts.dryRun)
         args.push('--dry-run');
     if (opts.verbose)
@@ -2182,6 +2261,55 @@ async function deployOmpUserSource(opts) {
         counts: { agents: entries.agents.length, commands: entries.commands.length,
             skills: entries.skills.length, rules: entries.rules.length }, entries });
 }
+/** Record native home writes without mirroring or changing user-scope removal roots. */
+async function recordNativeAddonDeploy(bundlePath, target, provider, bundle) {
+    const userPaths = USER_SCOPE_PATHS[provider];
+    const paths = getProviderPaths(provider);
+    const entries = {
+        agents: [], commands: [], skills: [], rules: [],
+    };
+    for (const names of await listBundleSkillNameCandidates(bundlePath)) {
+        for (const root of deployedSkillRoots(target, provider)) {
+            let name;
+            for (const candidate of names) {
+                if (await fileExists(path.join(root, candidate, 'SKILL.md'))) {
+                    name = candidate;
+                    break;
+                }
+            }
+            if (!name)
+                continue;
+            try {
+                const receipt = JSON.parse(await fs.readFile(path.join(root, name, '.aiwg-manifest.json'), 'utf8'));
+                const sourceDir = path.join(bundlePath, 'skills', names[names.length - 1]);
+                if (!sameSkillOwner(receipt, sourceDir))
+                    continue;
+            }
+            catch { /* legacy adapters may not write a shared ownership receipt */ }
+            entries.skills.push(path.relative(userPaths.skills, path.join(root, name)));
+            break;
+        }
+    }
+    for (const kind of ['agents', 'commands', 'rules']) {
+        if (!paths[kind] || !userPaths[kind])
+            continue;
+        for (const stem of await listBundleMdStems(bundlePath, kind)) {
+            const filename = `${stem}.md`;
+            const destination = path.join(resolveDeployPath(target, paths[kind]), filename);
+            if (await fileExists(destination))
+                entries[kind].push(path.relative(userPaths[kind], destination));
+        }
+    }
+    const manifestPath = path.join(bundlePath, 'manifest.json');
+    const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    const { recordUserDeploy } = await import('../../config/user-registry.js');
+    await recordUserDeploy({
+        framework: bundle, provider, version: manifest.version ?? (await getVersionInfo()).version,
+        source: 'bundled', manifestHash: await hashManifest(manifestPath), entries,
+        counts: { agents: entries.agents.length, commands: entries.commands.length,
+            skills: entries.skills.length, rules: entries.rules.length },
+    });
+}
 async function mirrorProjectLocalBundleToUserScope(opts) {
     const paths = getProviderPaths(opts.provider);
     const resolveProjectPath = (value) => !value ? '' : path.isAbsolute(value) ? value : path.join(opts.target, value);
@@ -2262,6 +2390,7 @@ export class UseHandler {
     category = 'framework';
     aliases = [];
     orchestrationDepth = 0;
+    preparedProviderContinuations = new Set();
     async help() {
         return { exitCode: 0, message: USE_HELP, rawOutput: true };
     }
@@ -2274,12 +2403,24 @@ export class UseHandler {
             || ctx.args.includes('--workspace-signals');
         if (bypassOrchestration)
             return this.executeCore(ctx);
+        // Child deployers share one source-index snapshot for this invocation. Each
+        // addon still resolves and validates its bindings through the common query
+        // engine, without rebuilding the entire corpus on every additive pass.
+        const previousBindingCache = process.env.AIWG_RULE_BINDING_INDEX_CACHE;
+        const bindingCache = previousBindingCache || await fs.mkdtemp(path.join(os.tmpdir(), 'aiwg-use-bindings-'));
+        const removeBindingCache = previousBindingCache ? () => { } : trackTemporaryDirectory(bindingCache);
+        process.env.AIWG_RULE_BINDING_INDEX_CACHE = bindingCache;
         this.orchestrationDepth += 1;
         try {
             return await this.executeOrchestrated(ctx, requestedBundle);
         }
         finally {
             this.orchestrationDepth -= 1;
+            if (previousBindingCache === undefined)
+                delete process.env.AIWG_RULE_BINDING_INDEX_CACHE;
+            else
+                process.env.AIWG_RULE_BINDING_INDEX_CACHE = previousBindingCache;
+            removeBindingCache();
         }
     }
     async executeOrchestrated(ctx, requestedBundle) {
@@ -2355,7 +2496,6 @@ export class UseHandler {
                         projectPath: projectDir,
                         provider,
                         args: remainingArgs,
-                        invocationStartedAt: startedAt,
                     });
                 }
             }
@@ -2975,6 +3115,10 @@ export class UseHandler {
             }
             const runner = createScriptRunner(frameworkRoot);
             const addonBaseArgs = ['--deploy-commands', '--deploy-skills', '--deploy-rules'];
+            if (remainingArgs.includes('--allow-over-budget'))
+                addonBaseArgs.push('--allow-over-budget');
+            if (addonScope === 'user')
+                addonBaseArgs.push('--scope', 'user');
             // An explicitly selected upstream addon must be self-contained in the
             // project. Unlike a full framework deploy, its standard skills cannot be
             // left index-only: the user asked to install this specific bundle and
@@ -2992,6 +3136,8 @@ export class UseHandler {
             }
             if (dryRunAddon)
                 addonBaseArgs.push('--dry-run');
+            if (remainingArgs.includes('--force'))
+                addonBaseArgs.push('--force');
             const kind = isExtension ? 'extension' : 'addon';
             const activationOrder = isAddon
                 ? await resolveRequiredAddonActivationOrder(frameworkRoot, framework)
@@ -3014,7 +3160,7 @@ export class UseHandler {
                 }
                 if (!dryRunAddon) {
                     try {
-                        await reconcileDeployedSkillAssets(dependencySource, target, provider, { strictReferences: false });
+                        await reconcileDeployedSkillAssets(dependencySource, target, provider, { strictReferences: false, force: remainingArgs.includes('--force') });
                     }
                     catch (error) {
                         return {
@@ -3056,7 +3202,7 @@ export class UseHandler {
             }
             if (!dryRunAddon) {
                 try {
-                    await reconcileDeployedSkillAssets(addonSource, target, provider, { strictReferences: false });
+                    await reconcileDeployedSkillAssets(addonSource, target, provider, { strictReferences: false, force: remainingArgs.includes('--force') });
                 }
                 catch (error) {
                     return {
@@ -3109,6 +3255,14 @@ export class UseHandler {
                     message: `Failed to register CLI commands: ${error instanceof Error ? error.message : String(error)}`,
                 };
             }
+            if (!dryRunAddon && (provider === 'openclaw' || (provider === 'grokbot' && addonScope === 'user'))) {
+                try {
+                    await recordNativeAddonDeploy(addonSource, target, provider, framework);
+                }
+                catch (error) {
+                    return { exitCode: 1, message: `Addon user registry update failed: ${error instanceof Error ? error.message : String(error)}` };
+                }
+            }
             // Persist the same lifecycle record frameworks and project-local bundles
             // receive so status, refresh, doctor, and remove can account for this
             // upstream addon and every provider artifact it actually deployed.
@@ -3231,6 +3385,16 @@ export class UseHandler {
         const force = remainingArgs.includes('--force');
         const skipConflicts = remainingArgs.includes('--skip-conflicts');
         const explicitHarnessAgentSelectors = parseOpenHumanHarnessAgentSelector(remainingArgs);
+        const preparedFlag = '--aiwg-provider-main-prepared';
+        const preparedFlagIndex = remainingArgs.indexOf(preparedFlag);
+        const preparedCapability = preparedFlagIndex >= 0 ? remainingArgs[preparedFlagIndex + 1] : undefined;
+        let mainProviderPrepared = false;
+        if (preparedFlagIndex >= 0) {
+            if (!preparedCapability || !this.preparedProviderContinuations.delete(preparedCapability)) {
+                return { exitCode: 1, message: 'Invalid prepared-provider continuation capability.' };
+            }
+            mainProviderPrepared = true;
+        }
         // PUW-027 (#1128): --scope user|project per ADR-4. Default project.
         // #1156 Phase 1: --user is a shorthand for --scope user.
         let scope;
@@ -3253,7 +3417,9 @@ export class UseHandler {
                     + ` (active: ${process.env.AIWG_USER_REGISTRY_PATH})`);
             }
         }
-        const filteredArgs = deployArgs.filter(a => a !== '--no-utils' && a !== '--no-project-local' && a !== '--ci-hooks-enabled' && a !== '--force' && a !== '--skip-conflicts' && a !== '--no-harness-agents');
+        if (scope === 'user' && !deployArgs.includes('--scope'))
+            deployArgs.push('--scope', 'user');
+        const filteredArgs = removeFlagWithOptionalValue(deployArgs, preparedFlag).filter(a => a !== '--no-utils' && a !== '--no-project-local' && a !== '--ci-hooks-enabled' && a !== '--skip-conflicts' && a !== '--no-harness-agents');
         const deployFilteredArgs = removeFlagWithOptionalValue(filteredArgs, '--harness-agents');
         // Pass --quiet to suppress deploy-agents.mjs header/footer in default mode (#460)
         // Human dry-run remains verbose; machine-readable dry-run captures the
@@ -3278,8 +3444,70 @@ export class UseHandler {
                 ui.warn("No .aiwg/aiwg.config found. Run 'aiwg init', then ask your AIWG agent to configure this project properly.");
             }
         }
-        // Multi-provider: loop over providers, deploying to each in sequence
+        const targetIdx = remainingArgs.findIndex(a => a === '--target');
+        const target = targetIdx >= 0 && remainingArgs[targetIdx + 1] ? remainingArgs[targetIdx + 1] : process.cwd();
+        // Multi-provider: prepare built-in project-scope projections in at most two
+        // subprocesses, then preserve the existing provider/addon commit order.
+        // User-scope, dry-run, harness-special and project-local adapters retain the
+        // established serial path because their lifecycle is not stage-only.
         if (providers.length > 1) {
+            const preparedJobs = [];
+            let canPrepareConcurrently = !dryRun && scope === 'project' && explicitHarnessAgentSelectors.length === 0;
+            for (const [order, requested] of providers.entries()) {
+                const local = await resolveProjectLocalProviderAdapter(projectDir, requested);
+                if (local.requestedProvider) {
+                    canPrepareConcurrently = false;
+                    break;
+                }
+                const unsupported = unsupportedProviderMessage(requested);
+                if (unsupported)
+                    return { exitCode: 1, message: unsupported };
+                const resolved = resolveBuiltInProviderForUse(local.provider);
+                if (!PREPARABLE_BUILTIN_PROVIDERS.has(resolved.provider)) {
+                    canPrepareConcurrently = false;
+                    break;
+                }
+                const args = withProviderOverride([...deployFilteredArgs], resolved.provider);
+                if (framework === 'all' && !['pi', 'omp'].includes(resolved.provider)
+                    && !remainingArgs.includes('--copy-all') && !remainingArgs.includes('--copy-standard-skills'))
+                    args.push('--kernel-only');
+                preparedJobs.push({ order, provider: resolved.provider, target: path.resolve(target), args });
+            }
+            if (canPrepareConcurrently && preparedJobs.length === providers.length) {
+                if (!skipConflicts) {
+                    for (const job of preparedJobs) {
+                        const canDeploy = await runPreDeployCollisionCheck({
+                            frameworkRoot, framework, target, provider: job.provider, force, skipConflicts, verbose,
+                        });
+                        if (!canDeploy)
+                            return { exitCode: 1, message: 'Deployment blocked due to name collisions. See above for details.' };
+                    }
+                }
+                let session;
+                try {
+                    session = await prepareProviderDeployments(frameworkRoot, preparedJobs);
+                    for (const [order, requested] of providers.entries()) {
+                        await session.commit(order);
+                        const capability = randomUUID();
+                        this.preparedProviderContinuations.add(capability);
+                        try {
+                            const result = await this.execute({ ...ctx, args: [framework, '--provider', requested, preparedFlag, capability, ...remainingArgs] });
+                            if (result.exitCode !== 0)
+                                return result;
+                        }
+                        finally {
+                            this.preparedProviderContinuations.delete(capability);
+                        }
+                    }
+                    return { exitCode: 0 };
+                }
+                catch (error) {
+                    return { exitCode: 1, message: `Concurrent provider preparation failed: ${error instanceof Error ? error.message : String(error)}` };
+                }
+                finally {
+                    await session?.dispose();
+                }
+            }
             for (const p of providers) {
                 const result = await this.execute({ ...ctx, args: [framework, '--provider', p, ...remainingArgs] });
                 if (result.exitCode !== 0)
@@ -3311,8 +3539,6 @@ export class UseHandler {
             && !remainingArgs.includes('--copy-standard-skills');
         if (bulkKernelOnly)
             providerDeployArgs.push('--kernel-only');
-        const targetIdx = remainingArgs.findIndex(a => a === '--target');
-        const target = targetIdx >= 0 && remainingArgs[targetIdx + 1] ? remainingArgs[targetIdx + 1] : process.cwd();
         if ((verbose || dryRun) && projectLocalProviderResolution.requestedProvider) {
             ui.dim(`  project-local provider '${projectLocalProviderResolution.requestedProvider}' extends '${provider}'`);
         }
@@ -3401,7 +3627,19 @@ export class UseHandler {
             ui.blank();
         }
         const runner = createScriptRunner(ctx.frameworkRoot);
-        const mainResult = await runner.run('tools/agents/deploy-agents.mjs', providerDeployArgs, captureOpts);
+        let mainResult;
+        if (mainProviderPrepared) {
+            try {
+                await finalizePreparedProvider(frameworkRoot, providerDeployArgs);
+                mainResult = { exitCode: 0 };
+            }
+            catch (error) {
+                mainResult = { exitCode: 1, message: `Prepared provider finalization failed: ${error instanceof Error ? error.message : String(error)}` };
+            }
+        }
+        else {
+            mainResult = await runner.run('tools/agents/deploy-agents.mjs', providerDeployArgs, captureOpts);
+        }
         if (mainResult.exitCode !== 0) {
             return mainResult;
         }
@@ -3430,6 +3668,10 @@ export class UseHandler {
         }
         // Build common args for addon deployments (inherit provider and target)
         const addonBaseArgs = ['--deploy-commands', '--deploy-skills', '--deploy-rules'];
+        if (remainingArgs.includes('--allow-over-budget'))
+            addonBaseArgs.push('--allow-over-budget');
+        if (scope === 'user')
+            addonBaseArgs.push('--scope', 'user');
         if (bulkKernelOnly)
             addonBaseArgs.push('--kernel-only');
         addonBaseArgs.push(...modelDeployArgs);
@@ -3449,6 +3691,12 @@ export class UseHandler {
         // Deploy all addons (excluding disallow list) unless --no-utils
         if (!skipUtils) {
             const allAddons = await getAllAddons(frameworkRoot);
+            // These root collectors already deploy every eligible addon. Re-staging
+            // the entire deployment per addon duplicates that work. Codex's skills
+            // helper includes addons only in all mode; other modes retain their pass.
+            // CLI contribution registration below still runs for every addon.
+            const selectedMode = MODE_MAP[framework];
+            const mainIncludesAddons = mainDeploymentIncludesAddons(provider, selectedMode, providerDeployArgs);
             for (const addon of allAddons) {
                 if (verbose) {
                     console.log('');
@@ -3458,9 +3706,10 @@ export class UseHandler {
                 const addonArgs = quiet
                     ? ['--quiet', '--source', source, ...addonBaseArgs]
                     : ['--source', source, ...addonBaseArgs];
-                const result = await runner.run('tools/agents/deploy-agents.mjs', addonArgs, captureOpts);
-                if (result.exitCode !== 0) {
-                    return result;
+                if (!mainIncludesAddons) {
+                    const result = await runner.run('tools/agents/deploy-agents.mjs', addonArgs, captureOpts);
+                    if (result.exitCode !== 0)
+                        return result;
                 }
                 try {
                     await registerSourceCliCommands({
@@ -3677,7 +3926,14 @@ export class UseHandler {
                 // progress through; otherwise we show a single-line spinner-
                 // style message and capture the noisy stat lines.
                 ui.blank();
-                ui.info('Building capability index…');
+                const { loadPrebuiltDeploymentIndex } = await import('../../artifacts/prebuilt-deployment.js');
+                const prebuilt = loadPrebuiltDeploymentIndex(aiwgRootForIndex, { strictRoot: true });
+                ui.info(prebuilt ? 'Validating packaged capability index…' : 'Building capability index…');
+                if (!prebuilt && await fs.access(path.join(aiwgRootForIndex, 'prebuilt', 'framework-relations', 'manifest.json')).then(() => true).catch(() => false)) {
+                    const { selectPrebuiltRelations } = await import('../../artifacts/relations.js');
+                    const reason = selectPrebuiltRelations(aiwgRootForIndex).reason ?? 'packaged search index is missing, stale, or does not match the source';
+                    ui.dim(`  Packaged index unavailable: ${reason}.`);
+                }
                 ui.dim('  Indexing operational assets for agent-side lookup.');
                 const indexStart = Date.now();
                 // Capture buildIndex's own console.log noise unless verbose
@@ -3685,13 +3941,9 @@ export class UseHandler {
                 if (!verbose)
                     console.log = () => { };
                 try {
-                    const { buildIndex } = await import('../../artifacts/index-builder.js');
-                    // Build against AIWG_ROOT so stored paths resolve from any
-                    // project (#1217). The output index location is XDG-shared
-                    // regardless of build cwd.
-                    await buildIndex(aiwgRootForIndex, { graph: 'framework', explicit: false });
-                    const { syncFortemiCoreIndex } = await import('../../artifacts/fortemi-core-sync.js');
-                    syncFortemiCoreIndex(aiwgRootForIndex, { graph: 'framework' });
+                    // Validate uncommitted sources once and publish the receipt so
+                    // verification/discovery do not immediately scan the corpus again.
+                    await reconcileSelectedFrameworkSource(aiwgRootForIndex);
                     console.log = origLog;
                     const indexElapsedSec = ((Date.now() - indexStart) / 1000).toFixed(1);
                     ui.success(`Capability index ready (${indexElapsedSec}s).`);