@aiwg/cli 2026.10.1 → 2026.10.4

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

@@ -17,6 +17,7 @@ import { getFrameworkRoot } from '../../channel/manager.mjs';
 import { updateInstallation } from '../../update/service.mjs';
 import { useHandler as useFrameworkHandler } from './use.js';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { argsTerminatorIndex, hasPositionalOrSwitch, requireFlagValue, valueTokenIndexes } from '../flag-parsing.js';
 import { checkCollisions, } from '../../smiths/skillsmith/collision-detector.js';
 import { renderUseDeploymentResult, verifyConfiguredDeployments, } from '../services/deployment-verification.js';
 /**
@@ -326,6 +327,62 @@ export const validateMetadataHandler = {
         return result;
     },
 };
+/**
+ * A directory is a deployed skill only if it carries a SKILL.md manifest —
+ * the same marker `isOwnedByNamespace()` in collision-detector.ts reads for
+ * ownership. Harness container/bucket directories (e.g. Claude Code's own
+ * `.claude/skills/synced/` sync storage, which holds UUID-named dirs with
+ * `manifest.json`, not SKILL.md) have no manifest of their own and must
+ * never be reported as a colliding skill (#278).
+ *
+ * A container directory without its own SKILL.md is still descended exactly
+ * one level: a real skill nested inside it (`<container>/<skill>/SKILL.md`)
+ * is reported as `<container>/<skill>`, while the container itself never is.
+ */
+async function hasSkillManifest(dirPath) {
+    try {
+        await fsp.access(path.join(dirPath, 'SKILL.md'));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function collectDeployedSkillDirNames(skillsDir) {
+    let topEntries;
+    try {
+        topEntries = await fsp.readdir(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    for (const entry of topEntries) {
+        if (!entry.isDirectory())
+            continue;
+        const dirPath = path.join(skillsDir, entry.name);
+        if (await hasSkillManifest(dirPath)) {
+            names.push(entry.name);
+            continue;
+        }
+        let nestedEntries;
+        try {
+            nestedEntries = await fsp.readdir(dirPath, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const nested of nestedEntries) {
+            if (!nested.isDirectory())
+                continue;
+            const nestedPath = path.join(dirPath, nested.name);
+            if (await hasSkillManifest(nestedPath)) {
+                names.push(path.join(entry.name, nested.name));
+            }
+        }
+    }
+    return names;
+}
 /**
  * #1156 Phase 1 — Validate the per-user registry at `~/.aiwg/installed.json`.
  *
@@ -450,8 +507,14 @@ Options:
   --bundle <name>       Limit deployment verification to one bundle
   --scope <scope>       Verification scope: project or user
   --user                Alias for --scope user
+  --qualify             With --probe-workers, record installation and configured model/role approval
+  --yes                 Confirm worker qualification without a terminal
+  --dry-run             With --probe-workers, preview qualification without writes
+  --cli NAME            Limit worker probes/qualification to one configured CLI
+  --decision-offload    Show offline advisory decision readiness and adoption report
+  --probe-workers       Run bounded worker CLI version probes (default: config-only, no subprocess)
   --project-local       Include project-local artifact diagnostics
-  --json                Emit machine-readable deployment verification output
+  --json                Emit machine-readable output (with --probe-workers: one worker-probe record per CLI; with --deployment: deployment verification; with --decision-offload: offline snapshot)
   --verbose, -v         Include verbose diagnostics
   --help, -h            Show this help
 `;
@@ -477,28 +540,63 @@ export const doctorHandler = {
         return { exitCode: 0, message: DOCTOR_HELP, rawOutput: true };
     },
     async execute(ctx) {
-        if (ctx.args.includes('--help') || ctx.args.includes('-h')) {
+        // Validate before any early-return mode: deployment and user-scope doctor
+        // never invoke doctor.mjs, so they must enforce the same flag contract.
+        const valueFlags = ['--provider', '--bundle', '--scope', '--context-baseline', '--context-budget-tokens', '--cli'];
+        const knownFlags = new Set([
+            ...valueFlags, '--all-providers', '--probe-workers', '--qualify', '--yes', '--dry-run', '--no-budget-check', '--strict-context', '--json',
+            '--decision-offload', '--deployment', '--user', '--verbose', '-v', '--project-local', '--quiet', '--help', '-h',
+        ]);
+        const hasSwitch = (name) => hasPositionalOrSwitch(ctx.args, name, valueFlags);
+        const values = new Map();
+        try {
+            for (const flag of valueFlags) {
+                values.set(flag, requireFlagValue(ctx.args, { rejectEmpty: true, precedence: 'last' }, flag));
+            }
+            const consumed = valueTokenIndexes(ctx.args, valueFlags);
+            for (let i = 0; i < argsTerminatorIndex(ctx.args); i += 1) {
+                const token = ctx.args[i];
+                if (consumed.has(i) || !token.startsWith('-'))
+                    continue;
+                const name = token.split('=')[0];
+                if (!knownFlags.has(name) || (token.includes('=') && !valueFlags.includes(name))) {
+                    throw new Error(`Unknown flag: ${name}`);
+                }
+            }
+            if (hasSwitch('--decision-offload') && (hasSwitch('--probe-workers') || hasSwitch('--deployment') || hasSwitch('--user') || values.get('--scope') !== undefined)) {
+                throw new Error('--decision-offload is a separate offline mode; do not combine it with worker, deployment or user-scope checks');
+            }
+            if (['--qualify', '--cli', '--yes', '--dry-run'].some(flag => hasSwitch(flag) || values.get(flag)) && !hasSwitch('--probe-workers')) {
+                throw new Error('--qualify, --cli, --yes and --dry-run require --probe-workers');
+            }
+            if (hasSwitch('--json') && !hasSwitch('--probe-workers') && !hasSwitch('--deployment') && !hasSwitch('--decision-offload')) {
+                throw new Error('--json requires --probe-workers or --deployment or --decision-offload');
+            }
+        }
+        catch (error) {
+            return { exitCode: 2, message: `${error instanceof Error ? error.message : String(error)}. See 'aiwg doctor --help'.` };
+        }
+        if (hasSwitch('--help') || hasSwitch('-h')) {
             return { exitCode: 0, message: DOCTOR_HELP, rawOutput: true };
         }
-        if (ctx.args.includes('--deployment')) {
-            const providerIndex = ctx.args.indexOf('--provider');
-            const bundleIndex = ctx.args.indexOf('--bundle');
-            const scopeIndex = ctx.args.indexOf('--scope');
-            const scopeValue = scopeIndex >= 0 ? ctx.args[scopeIndex + 1] : undefined;
+        if (hasSwitch('--deployment')) {
+            const scopeValue = values.get('--scope');
             if (scopeValue && scopeValue !== 'project' && scopeValue !== 'user') {
                 return { exitCode: 2, message: `Invalid deployment verification scope: ${scopeValue}` };
             }
             const result = await verifyConfiguredDeployments(ctx.cwd || process.cwd(), {
-                provider: providerIndex >= 0 ? ctx.args[providerIndex + 1] : undefined,
-                bundle: bundleIndex >= 0 ? ctx.args[bundleIndex + 1] : undefined,
+                provider: values.get('--provider'),
+                bundle: values.get('--bundle'),
                 scope: scopeValue,
             }, ctx.frameworkRoot);
+            const { rulePinState } = await import('../../rules/pin-state.js');
+            const pins = rulePinState(ctx.cwd, ctx.frameworkRoot);
             return {
                 exitCode: result.exitCode,
-                message: ctx.args.includes('--json')
-                    ? JSON.stringify(result, null, 2)
-                    : renderUseDeploymentResult(result),
-                rawOutput: ctx.args.includes('--json'),
+                message: hasSwitch('--json')
+                    ? JSON.stringify({ ...result, rule_pins: { rules: pins.rules, warnings: pins.warnings } }, null, 2)
+                    : renderUseDeploymentResult(result) + '\n' + pins.rules.map(rule => `${rule.name}: pinned kernel (canonical ${rule.canonical_activation})`).concat(pins.warnings).join('\n'),
+                rawOutput: hasSwitch('--json'),
             };
         }
         // #1156 Phase 1 — `aiwg doctor --scope user` / `aiwg doctor --user`
@@ -506,15 +604,20 @@ export const doctorHandler = {
         // running the project-scope diagnostics. Operators need this to verify
         // their user-scope deployments from any cwd, including shells with no
         // project at all.
-        const userScopeRequested = ctx.args.includes('--user') ||
-            (ctx.args.includes('--scope') && ctx.args[ctx.args.indexOf('--scope') + 1] === 'user');
-        if (userScopeRequested) {
-            return await runUserScopeDoctor(ctx.args.includes('--verbose') || ctx.args.includes('-v'));
+        const userScopeRequested = hasSwitch('--user') || values.get('--scope') === 'user';
+        if (userScopeRequested && !hasSwitch('--probe-workers')) {
+            return await runUserScopeDoctor(hasSwitch('--verbose') || hasSwitch('-v'));
         }
-        const frameworkRoot = await getFrameworkRoot();
+        const frameworkRoot = hasSwitch('--decision-offload') ? ctx.frameworkRoot : await getFrameworkRoot();
         const runner = createScriptRunner(frameworkRoot);
         // Run core doctor diagnostics
         const result = await runner.run('tools/cli/doctor.mjs', ctx.args, { cwd: ctx.cwd });
+        // Machine-readable worker probes (#3066): tools/cli/doctor.mjs already
+        // printed exactly one JSON document (or a usage error) on its own
+        // stdio — every section below writes human-readable text, so returning
+        // here keeps stdout to the JSON document alone.
+        if (hasSwitch('--decision-offload') || hasSwitch('--json') || hasSwitch('--qualify') || hasSwitch('--cli') || hasSwitch('--dry-run') || result.exitCode === 2)
+            return result;
         let agentSkillsFailure = false;
         try {
             const { inspectGrokBuildNative } = await import('../../mcp/grok-build-config.mjs');
@@ -562,14 +665,7 @@ export const doctorHandler = {
         try {
             const projectDir = ctx.cwd || process.cwd();
             const skillsDir = path.join(projectDir, '.claude', 'skills');
-            let deployedSkillNames = [];
-            try {
-                const entries = await fsp.readdir(skillsDir, { withFileTypes: true });
-                deployedSkillNames = entries.filter(e => e.isDirectory()).map(e => e.name);
-            }
-            catch {
-                // No .claude/skills — nothing to check
-            }
+            const deployedSkillNames = await collectDeployedSkillDirNames(skillsDir);
             if (deployedSkillNames.length > 0) {
                 const collisions = await checkCollisions({
                     platform: 'claude',
@@ -718,6 +814,9 @@ export const contextFirewallHandler = {
     description: 'Audit provider context and manage its reviewed baseline',
     category: 'maintenance',
     aliases: ['-context-firewall', '--context-firewall'],
+    async help() {
+        return { exitCode: 0, message: CONTEXT_FIREWALL_HELP, rawOutput: true };
+    },
     async execute(ctx) {
         if (ctx.args.includes('--help') || ctx.args.includes('-h')) {
             return { exitCode: 0, message: CONTEXT_FIREWALL_HELP };

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

@@ -55,6 +55,9 @@ function collectFingerprint(versionInfo) {
     const loggerInfo = getLoggerInfo();
     const fp = {
         version: versionInfo.version,
+        launcherVersion: versionInfo.launcherVersion ?? versionInfo.version,
+        runtimeVersion: versionInfo.runtimeVersion ?? versionInfo.version,
+        runtimePath: versionInfo.runtimePath ?? versionInfo.packageRoot,
         channel: versionInfo.devMode ? 'dev' : versionInfo.channel,
         packageRoot: versionInfo.packageRoot,
         node: process.version,
@@ -132,6 +135,11 @@ async function displayVersion(opts) {
     }
     ui.blank();
     console.log(`  ${ui.brandMark()} ${ui.bold('aiwg')}  ${ui.bold(fp.version)}  ${ui.channelLabel(fp.channel)}`);
+    if (info.devMode || fp.launcherVersion !== fp.runtimeVersion) {
+        ui.dim(`    launcher: ${fp.launcherVersion}`);
+        ui.dim(`    runtime: ${fp.runtimeVersion}`);
+        ui.dim(`    runtime path: ${fp.runtimePath}`);
+    }
     if (!opts.verbose) {
         if (fp.git)
             ui.dim(`    git: ${fp.git.sha} (${fp.git.branch})`);

package/dist/src/cli/prompt-utils.js

@@ -127,6 +127,78 @@ export async function askChoice(rl, prompt, options, fallback, signal) {
         return pick;
     }, pick, label, promptTimeoutMs(), signal);
 }
+/**
+ * Prompt for a strict, distinguishable consent answer. Two differences from
+ * {@link askYesNo}, both deliberately scoped to this helper so no existing
+ * `askYesNo` call site changes behavior:
+ *
+ * 1. **Strict parsing**: only a trimmed, case-insensitive `y` or `yes`
+ *    counts as yes. `askYesNo`'s `startsWith('y')` would also accept
+ *    `yesterday` or `yolo` — too loose for an irreversible opt-in.
+ * 2. **Answered vs. not-answered**: the caller gets a {@link ConsentOutcome}
+ *    instead of a bare boolean, so a timeout or a closed/EOF'd stdin (the
+ *    `rl.on('close', ...)` listener settles immediately — it does not wait
+ *    out the timeout) is distinguishable from an actual "no" answer. A
+ *    caller that records a persistent decline must only do so for
+ *    `{ kind: 'answered', value: false }`.
+ *
+ * Signal abort still rejects (same contract as {@link askWithTimeout}).
+ */
+export function askConsent(rl, question, timeoutMs = promptTimeoutMs(), signal) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            clearTimeout(timer);
+            rl.removeListener('close', onClose);
+            signal?.removeEventListener('abort', onAbort);
+        };
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            ui.warn(`  No input within ${Math.round(timeoutMs / 1000)}s — leaving the setting unchanged.`);
+            cleanup();
+            resolve({ kind: 'timeout' });
+        }, timeoutMs);
+        // See askWithTimeout: unref so a closed event loop never waits on this.
+        timer.unref?.();
+        // Stdin closing (EOF, piped input exhausted, or the interface being
+        // closed elsewhere) must settle immediately, not after the full
+        // timeout — a closed stdin must never hang a consent prompt.
+        const onClose = () => {
+            if (settled)
+                return;
+            settled = true;
+            ui.warn('  Input closed before an answer — leaving the setting unchanged.');
+            cleanup();
+            resolve({ kind: 'closed' });
+        };
+        rl.on('close', onClose);
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            try {
+                rl.close();
+            }
+            catch { /* already closed */ }
+            reject(signal.reason ?? new Error('Aborted'));
+        };
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        rl.question(question, (answer) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve({ kind: 'answered', value: ['y', 'yes'].includes(answer.trim().toLowerCase()) });
+        });
+    });
+}
 /**
  * Prompt for a labeled selection from a list of options. Renders each option
  * as a numbered line before asking. Users can respond by number (1-based) or

package/dist/src/cli/provider-resolution.js

@@ -19,6 +19,17 @@ function uniqueProviders(providers) {
     }
     return result;
 }
+/**
+ * Sources that say which harness this process is actually running under.
+ * `config`, `deployment` and `default` describe the project, not the session:
+ * a project deployed for one provider is still not "inside" that provider
+ * when a command is run from a plain terminal.
+ */
+const SESSION_PROVIDER_SOURCES = new Set(['explicit', 'env', 'runtime-env', 'process']);
+/** True when a resolution came from the running session rather than project state. */
+export function isSessionProviderResolution(resolution) {
+    return resolution.provider != null && SESSION_PROVIDER_SOURCES.has(resolution.source);
+}
 function detectProviderFromRuntimeEnv(env) {
     const definitions = [...listProviderDefinitions()].sort((a, b) => (a.detection.runtimeEnvPriority ?? Number.MAX_SAFE_INTEGER) - (b.detection.runtimeEnvPriority ?? Number.MAX_SAFE_INTEGER));
     for (const definition of definitions) {

package/dist/src/cli/router.js

@@ -75,6 +75,15 @@ export function getHookRegistry() {
  * ```
  */
 export async function run(args, options = {}) {
+    // Scheduled index maintenance has no hooks, telemetry, or deployment side effects.
+    if (args[0] === 'index' && args[1] === 'refresh'
+        && !args.includes('--help') && !args.includes('-h')) {
+        const { runIndexRefresh } = await import('../artifacts/index-refresh.js');
+        const report = await runIndexRefresh(args.slice(2), options.cwd ?? process.cwd(), options.signal);
+        if (report.totals.errors)
+            process.exit(1);
+        return;
+    }
     const started = process.hrtime.bigint();
     const registry = await initRouter();
     // Normalize `help <command>` into the same non-executing help path.
@@ -320,7 +329,12 @@ async function logCommandInvocation(input) {
  * @returns Handler context
  */
 async function buildContext(args, rawArgs, options) {
-    const frameworkRoot = await getFrameworkRoot({ createIfMissing: !args.includes('--dry-run') });
+    const readOnlyRuleInventory = rawArgs[0] === 'rules' && ['inventory', 'list'].includes(args[0]);
+    const readOnlyOffloadReport = (['doctor', '-doctor', '--doctor'].includes(rawArgs[0] ?? '') && args.includes('--decision-offload'))
+        || (rawArgs[0] === 'steward' && args[0] === 'decision-offload');
+    const frameworkRoot = await getFrameworkRoot({
+        createIfMissing: !args.includes('--dry-run') && !readOnlyRuleInventory && !readOnlyOffloadReport,
+    });
     const ctx = {
         args,
         rawArgs,

package/dist/src/cli/services/deployment-verification.js

@@ -1,5 +1,6 @@
 import { access, readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { loadPrebuiltDeploymentIndex } from '../../artifacts/prebuilt-deployment.js';
 import { loadGraphIndexFile } from '../../artifacts/index-reader.js';
 import { readAiwgConfig } from '../../config/aiwg-config.js';
 import { readUserRegistry } from '../../config/user-registry.js';
@@ -102,7 +103,7 @@ export function normalizeFrameworkDiscoveryInventory(stats) {
     };
 }
 function frameworkDiscoveryInventory(frameworkRoot) {
-    const stats = loadGraphIndexFile(frameworkRoot, 'stats.json', 'framework');
+    const stats = loadPrebuiltDeploymentIndex(frameworkRoot, { strictRoot: true })?.stats ?? loadGraphIndexFile(frameworkRoot, 'stats.json', 'framework');
     return stats ? normalizeFrameworkDiscoveryInventory(stats) : null;
 }
 const BUNDLE_INDEX_TOKENS = {
@@ -510,9 +511,11 @@ export async function verifyProviderDeployment(options) {
     const frameworkBundles = options.requestedBundles.filter((bundle) => !projectLocalBundles.includes(bundle));
     const indexesToVerify = [];
     if (frameworkBundles.length > 0) {
+        const prebuilt = loadPrebuiltDeploymentIndex(options.frameworkRoot, { strictRoot: true });
         indexesToVerify.push({
-            index: loadGraphIndexFile(options.frameworkRoot, 'metadata.json', 'framework'),
-            stats: loadGraphIndexFile(options.frameworkRoot, 'stats.json', 'framework'),
+            index: prebuilt?.index ?? loadGraphIndexFile(options.frameworkRoot, 'metadata.json', 'framework'),
+            stats: prebuilt?.stats ?? loadGraphIndexFile(options.frameworkRoot, 'stats.json', 'framework'),
+            prebuiltValidated: Boolean(prebuilt),
             graph: 'framework',
             bundles: frameworkBundles,
         });
@@ -521,11 +524,12 @@ export async function verifyProviderDeployment(options) {
         const graph = options.scope === 'user' ? 'user' : 'project';
         indexesToVerify.push({
             index: loadGraphIndexFile(options.projectRoot, 'metadata.json', graph),
+            stats: loadGraphIndexFile(options.projectRoot, 'stats.json', graph),
             graph,
             bundles: projectLocalBundles,
         });
     }
-    for (const { index, stats, graph, bundles } of indexesToVerify) {
+    for (const { index, stats, graph, bundles, prebuiltValidated } of indexesToVerify) {
         if (!index || !index.entries || Object.keys(index.entries).length === 0) {
             findings.push(finding(normalized, `index-unreadable:${graph}`, 'blocking', `The ${graph} capability index is missing, unreadable, or empty.`, `Run aiwg index build --graph ${graph}, then re-run the same aiwg use command.`));
             continue;
@@ -550,11 +554,14 @@ export async function verifyProviderDeployment(options) {
         if (!surfacePresent) {
             findings.push(finding(normalized, `index-surface-missing:${graph}`, 'blocking', `The ${graph} capability index does not contain the requested bundle surface.`, `Rebuild the ${graph} index from the selected AIWG source and re-run aiwg use.`, { requestedBundles: bundles, entryCount: entryPaths.length }));
         }
-        if (options.invocationStartedAt) {
-            const builtAt = Date.parse(index.builtAt);
+        if (options.invocationStartedAt && !prebuiltValidated) {
+            // No-op builds preserve metadata bytes and record the refresh in stats.
+            const refreshedAt = Math.max(...[index.builtAt, stats?.builtAt]
+                .map((timestamp) => Date.parse(timestamp ?? ''))
+                .filter(Number.isFinite));
             const startedAt = Date.parse(options.invocationStartedAt);
-            if (!Number.isFinite(builtAt) || builtAt + 2_000 < startedAt) {
-                findings.push(finding(normalized, `index-stale:${graph}`, 'blocking', `The ${graph} capability index was not refreshed during this deployment.`, `Re-run aiwg use after correcting the ${graph} index build failure.`, { graph, builtAt: index.builtAt, invocationStartedAt: options.invocationStartedAt }));
+            if (!Number.isFinite(refreshedAt) || refreshedAt + 2_000 < startedAt) {
+                findings.push(finding(normalized, `index-stale:${graph}`, 'blocking', `The ${graph} capability index was not refreshed during this deployment.`, `Re-run aiwg use after correcting the ${graph} index build failure.`, { graph, builtAt: index.builtAt, statsBuiltAt: stats?.builtAt, invocationStartedAt: options.invocationStartedAt }));
             }
         }
     }
@@ -569,7 +576,7 @@ export async function verifyProviderDeployment(options) {
         }
         const requiredContext = [
             path.join(options.projectRoot, 'WORKSPACE.md'),
-            path.join(options.projectRoot, 'AIWG.md'),
+            ...(definition?.paths.contextFiles.aiwgMd === false ? [] : [path.join(options.projectRoot, 'AIWG.md')]),
             path.join(options.projectRoot, '.aiwg', 'AIWG.md'),
         ];
         for (const contextPath of requiredContext) {
@@ -773,9 +780,12 @@ export async function buildDeploymentStatusProbe(projectRoot, frameworkRoot = pr
     const notConfigured = result.requestedBundles.length === 0
         && result.findings.length > 0
         && result.findings.every((item) => item.id === 'deployment-not-configured');
+    const { rulePinState } = await import('../../rules/pin-state.js');
+    const rulePins = rulePinState(projectRoot, frameworkRoot);
     const engaged = result.outcome === 'ready' || result.outcome === 'ready-restart-required' || result.outcome === 'degraded';
     return {
         schema: 'aiwg.status.probe.v1',
+        rule_pins: { rules: rulePins.rules, warnings: rulePins.warnings },
         generated_at: result.generatedAt,
         project_root: result.projectRoot,
         engaged,

package/dist/src/cli/services/provider-prepare-coordinator.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+export async function prepareProviderDeployments(frameworkRoot, jobs) {
+    const deployerUrl = pathToFileURL(path.join(frameworkRoot, 'tools', 'agents', 'deploy-agents.mjs')).href;
+    const deployer = await import(deployerUrl);
+    // Commands-to-skills migration is interactive and changes provider inputs.
+    // Run it serially in the coordinator before the shared snapshot is created;
+    // finalization then only applies post-deploy mirrors/pruning/config writes.
+    for (const job of jobs)
+        await deployer.main(job.args, { preflightOnly: true });
+    const url = pathToFileURL(path.join(frameworkRoot, 'tools', 'agents', 'providers', 'provider-prepare-coordinator.mjs')).href;
+    const coordinator = await import(url);
+    const sourceIndex = jobs[0]?.args.findIndex(arg => arg === '--source') ?? -1;
+    const srcRoot = sourceIndex >= 0 && jobs[0]?.args[sourceIndex + 1]
+        ? path.resolve(jobs[0].args[sourceIndex + 1])
+        : frameworkRoot;
+    return coordinator.prepareProviderDeployments({ srcRoot, jobs, maxConcurrency: 2 });
+}
+export async function finalizePreparedProvider(frameworkRoot, args) {
+    const url = pathToFileURL(path.join(frameworkRoot, 'tools', 'agents', 'deploy-agents.mjs')).href;
+    const deployer = await import(url);
+    await deployer.main(args, { finalizeOnly: true });
+}
+//# sourceMappingURL=provider-prepare-coordinator.js.map

package/dist/src/cli/skill-usage.js

@@ -3,7 +3,7 @@ import { createReadStream, existsSync } from 'fs';
 import { createHash } from 'crypto';
 import { createInterface } from 'readline';
 import path from 'path';
-import os from 'os';
+import { getUserStateDir } from '../config/user-state.js';
 import { readAiwgConfig } from '../config/aiwg-config.js';
 import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath, projectControlPath, } from '../config/project-artifacts.js';
 const DEFAULT_MAX_BYTES = 1_048_576;
@@ -487,8 +487,7 @@ function resolveUsagePath(scope, projectRoot, env) {
             return null;
         return projectAiwgPath(projectRoot, 'telemetry', 'skill-usage.jsonl');
     }
-    const stateHome = env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
-    return path.join(stateHome, 'aiwg', 'skill-usage.jsonl');
+    return path.join(getUserStateDir(env), 'skill-usage.jsonl');
 }
 async function appendBoundedJsonl(filePath, event, maxBytes) {
     await mkdir(path.dirname(filePath), { recursive: true });