@aiwg/cli 2026.10.0 → 2026.10.3

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

@@ -1,26 +1,42 @@
-import { spawnSync } from 'child_process';
+import { boundedSpawnSync } from '../../process/bounded-child-process.mjs';
 import { existsSync } from 'fs';
 import { emptyConfig, FORCE_PUSH_POLICY_ALIAS_NOTE, normalizeForcePushPolicy as normalizeForcePushPolicyShared, getConfigPath, getProjectDir, readAiwgConfig, resolveRemoteProvider, VALID_PROVIDERS, writeAiwgConfig, } from '../../config/aiwg-config.js';
 import { AiwgError, EXIT_CODES } from '../errors.js';
-import { askChoice, askString, askYesNo, createPromptInterface } from '../prompt-utils.js';
+import { askChoice, askConsent, askString, askYesNo, createPromptInterface } from '../prompt-utils.js';
 import * as ui from '../ui.js';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
 import { normalizeProviderDefinitionId } from '../../providers/provider-definitions.js';
+import { isInteractive } from '../env.js';
+import { requireFlagValue as strictFlagValue, MissingFlagValueError } from '../flag-parsing.js';
+import { detectInstalledWorkerClis, evaluateWorkerDispatchOffer, workerDispatchOfferHintWithArg, workerDispatchOfferQuestion, WORKER_DISPATCH_ARG_VALUES, } from '../../models/worker-dispatch-offer.js';
 const DELIVERY_MODES = ['pr-required', 'feature-branch', 'direct'];
 const FORCE_PUSH_POLICIES = ['never', 'own-branch-only', 'allowed'];
 const ISSUE_PROVIDERS = ['gitea', 'github', 'local'];
 const SIGNING_FORMATS = ['openpgp', 'ssh', 'x509'];
 const TRACKER_VIA = ['tea', 'gh', 'mcp', 'api'];
+/**
+ * A value-taking flag present without a usable value is a usage error, not
+ * "not given" (#3062 review item 11) — delegates to the shared strict
+ * parser, translating its `MissingFlagValueError` into this file's own
+ * `AiwgError`/`EXIT_CODES.USAGE` convention. `precedence: 'first'` matches
+ * this command's own pre-#3062 behavior (a hand-rolled loop that returned
+ * on the first match) — unchanged by the shared parser's second-round fix
+ * (#3062 second review, finding 4).
+ */
 function flagValue(args, ...names) {
-    for (let i = 0; i < args.length; i += 1) {
-        if (names.includes(args[i] ?? '')) {
-            const value = args[i + 1];
-            if (!value || value.startsWith('--'))
-                return undefined;
-            return value;
+    try {
+        return strictFlagValue(args, {}, ...names);
+    }
+    catch (err) {
+        if (err instanceof MissingFlagValueError) {
+            throw new AiwgError({
+                code: 'ERR_USAGE_MISSING_FLAG_VALUE',
+                message: `${err.message}.`,
+                exitCode: EXIT_CODES.USAGE,
+            });
         }
+        throw err;
     }
-    return undefined;
 }
 function boolFlag(args, name) {
     return args.includes(name);
@@ -92,6 +108,10 @@ export function parseSetupProjectOptions(ctx) {
         trackerActorVia: parseEnum(flagValue(args, '--tracker-actor-via'), TRACKER_VIA, '--tracker-actor-via'),
         customerTrackerActorLogin: flagValue(args, '--customer-tracker-actor-login'),
         customerTrackerActorVia: parseEnum(flagValue(args, '--customer-tracker-actor-via'), TRACKER_VIA, '--customer-tracker-actor-via'),
+        // #3062: answers the worker-dispatch question directly, with or without
+        // a terminal, and suppresses the interactive question below (see
+        // `SetupProjectOptions.workerDispatchChoice`'s doc comment).
+        workerDispatchChoice: parseEnum(flagValue(args, '--worker-dispatch'), WORKER_DISPATCH_ARG_VALUES, '--worker-dispatch'),
         providers: (() => {
             const providers = parseStringList(flagValue(args, '--providers'));
             return providers ? normalizeProviders(providers) : undefined;
@@ -99,7 +119,7 @@ export function parseSetupProjectOptions(ctx) {
     };
 }
 export function detectGitRemotes(projectDir) {
-    const result = spawnSync('git', ['-C', projectDir, 'remote', '-v'], {
+    const result = boundedSpawnSync('git', ['-C', projectDir, 'remote', '-v'], 'quick', {
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
     });
@@ -122,21 +142,21 @@ export function detectGitRemotes(projectDir) {
     return [...byName.values()];
 }
 function detectDefaultBranch(projectDir) {
-    const symbolic = spawnSync('git', ['-C', projectDir, 'symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], {
+    const symbolic = boundedSpawnSync('git', ['-C', projectDir, 'symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], 'quick', {
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
     });
     const fromOrigin = symbolic.stdout.trim().replace(/^origin\//, '');
     if (symbolic.status === 0 && fromOrigin)
         return fromOrigin;
-    const branch = spawnSync('git', ['-C', projectDir, 'branch', '--show-current'], {
+    const branch = boundedSpawnSync('git', ['-C', projectDir, 'branch', '--show-current'], 'quick', {
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
     });
     return branch.stdout.trim() || 'main';
 }
 function gitConfig(projectDir, key) {
-    const result = spawnSync('git', ['-C', projectDir, 'config', '--get', key], {
+    const result = boundedSpawnSync('git', ['-C', projectDir, 'config', '--get', key], 'quick', {
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
     });
@@ -321,6 +341,19 @@ export async function buildSetupProjectPlan(options) {
     }
     base.remotes = remotesConfig;
     base.delivery = delivery;
+    // #3050: apply an already-made worker-dispatch opt-in choice (from the
+    // interactive wizard), then recompute whether any surface should still
+    // offer/hint it — a choice just applied here always clears the offer.
+    // The decline is a setup/onboarding preference, not worker policy, so it
+    // lives in `setup`, not in the frozen `parallelism` contract fragment
+    // (B-OG-29).
+    if (options.workerDispatchChoice === 'enable') {
+        base.parallelism = { ...base.parallelism, worker_dispatch: true };
+    }
+    else if (options.workerDispatchChoice === 'decline') {
+        base.setup = { ...base.setup, worker_dispatch_offer: 'declined' };
+    }
+    const workerDispatchOffer = evaluateWorkerDispatchOffer(base.parallelism, base.setup, detectInstalledWorkerClis());
     if (primaryRemote?.provider === 'unknown' && issueProvider !== 'local') {
         warnings.push(`Remote '${primary}' is self-hosted or unknown; provider '${issueProvider}' was selected explicitly/defaulted.`);
     }
@@ -347,9 +380,10 @@ export async function buildSetupProjectPlan(options) {
         issueProvider,
         warnings,
         diff: formatPreviewDiff(existing, base),
+        workerDispatchOffer,
     };
 }
-async function applyInteractivePrompts(plan, rl, signal) {
+export async function applyInteractivePrompts(plan, rl, signal, supplied = {}) {
     const remoteNames = plan.remotes.map(r => r.name);
     const current = plan.next;
     console.log('');
@@ -360,28 +394,59 @@ async function applyInteractivePrompts(plan, rl, signal) {
     }
     if (plan.remotes.length === 0)
         console.log('  (none)');
-    const primary = remoteNames.length > 0
+    // #3062 review item 10: a value already supplied by flag is never
+    // re-asked — only the fields `supplied` leaves `undefined` prompt here.
+    // `??`'s right-hand side is only evaluated when the left is nullish, so
+    // a supplied value skips the corresponding `ask*` call entirely.
+    const primary = supplied.primary ?? (remoteNames.length > 0
         ? await askChoice(rl, `Primary remote [${current.remotes?.primary}]: `, remoteNames, current.remotes?.primary, signal)
-        : await askString(rl, `Primary remote [${current.remotes?.primary}]: `, current.remotes?.primary ?? 'origin', signal);
-    const issueProvider = await askChoice(rl, `Issue provider (${ISSUE_PROVIDERS.join('/')}): `, ISSUE_PROVIDERS, plan.issueProvider, signal);
+        : await askString(rl, `Primary remote [${current.remotes?.primary}]: `, current.remotes?.primary ?? 'origin', signal));
+    const issueProvider = supplied.issueProvider
+        ?? await askChoice(rl, `Issue provider (${ISSUE_PROVIDERS.join('/')}): `, ISSUE_PROVIDERS, plan.issueProvider, signal);
     const issueTracker = issueProvider === 'local'
         ? 'local'
-        : remoteNames.length > 0
+        : supplied.issueTracker ?? (remoteNames.length > 0
             ? await askChoice(rl, `Issue tracker remote [${current.remotes?.issue_tracker}]: `, remoteNames, current.remotes?.issue_tracker, signal)
-            : await askString(rl, `Issue tracker remote [${current.remotes?.issue_tracker}]: `, current.remotes?.issue_tracker ?? primary, signal);
-    const ci = remoteNames.length > 0
+            : await askString(rl, `Issue tracker remote [${current.remotes?.issue_tracker}]: `, current.remotes?.issue_tracker ?? primary, signal));
+    const ci = supplied.ci ?? (remoteNames.length > 0
         ? await askChoice(rl, `CI remote [${current.remotes?.ci}]: `, remoteNames, current.remotes?.ci, signal)
-        : await askString(rl, `CI remote [${current.remotes?.ci}]: `, current.remotes?.ci ?? primary, signal);
-    const deliveryMode = await askChoice(rl, `Delivery mode (${DELIVERY_MODES.join('/')}): `, DELIVERY_MODES, current.delivery?.mode, signal);
-    const defaultBranch = await askString(rl, `Default branch [${current.delivery?.default_branch}]: `, current.delivery?.default_branch ?? 'main', signal);
-    const requireCiGreen = await askYesNo(rl, 'Require CI green before done? [Y/n]: ', current.delivery?.require_ci_green ?? true, signal);
-    const autoCloseIssues = await askYesNo(rl, 'Auto-close linked issues from delivery? [Y/n]: ', current.delivery?.auto_close_issues ?? true, signal);
-    const forcePushPolicy = await askChoice(rl, `Force-push policy (${FORCE_PUSH_POLICIES.join('/')}): `, FORCE_PUSH_POLICIES, current.delivery?.force_push_policy, signal);
-    const requireSignedCommits = await askYesNo(rl, 'Require signed delivery commits? [y/N]: ', current.delivery?.require_signed_commits ?? false, signal);
-    const providersRaw = await askString(rl, `Providers [${current.providers.join(',')}]: `, current.providers.join(','), signal);
+        : await askString(rl, `CI remote [${current.remotes?.ci}]: `, current.remotes?.ci ?? primary, signal));
+    const deliveryMode = supplied.deliveryMode
+        ?? await askChoice(rl, `Delivery mode (${DELIVERY_MODES.join('/')}): `, DELIVERY_MODES, current.delivery?.mode, signal);
+    const defaultBranch = supplied.defaultBranch
+        ?? await askString(rl, `Default branch [${current.delivery?.default_branch}]: `, current.delivery?.default_branch ?? 'main', signal);
+    const requireCiGreen = supplied.requireCiGreen
+        ?? await askYesNo(rl, 'Require CI green before done? [Y/n]: ', current.delivery?.require_ci_green ?? true, signal);
+    const autoCloseIssues = supplied.autoCloseIssues
+        ?? await askYesNo(rl, 'Auto-close linked issues from delivery? [Y/n]: ', current.delivery?.auto_close_issues ?? true, signal);
+    const forcePushPolicy = supplied.forcePushPolicy
+        ?? await askChoice(rl, `Force-push policy (${FORCE_PUSH_POLICIES.join('/')}): `, FORCE_PUSH_POLICIES, current.delivery?.force_push_policy, signal);
+    const requireSignedCommits = supplied.requireSignedCommits
+        ?? await askYesNo(rl, 'Require signed delivery commits? [y/N]: ', current.delivery?.require_signed_commits ?? false, signal);
+    const providers = supplied.providers
+        ?? parseProviders(await askString(rl, `Providers [${current.providers.join(',')}]: `, current.providers.join(','), signal), current.providers);
+    // #3050: offer direct worker dispatch, only when there is something to
+    // offer (two or more worker CLIs detected, dispatch not already on or
+    // declined), and only in a context where the answer could actually be
+    // acted on: CI and dry-run never prompt (review item 5) — an unattended
+    // CI run could otherwise stall on a prompt timeout, and a dry-run would
+    // ask a question whose answer is never written. Both cases fall back to
+    // the informational hint at the end of `execute()` instead (via
+    // `plan.workerDispatchOffer.shouldOffer` staying true on the rebuilt plan).
+    // Strict/distinguishable consent (review items 2 and 4): only an actually
+    // answered "no" is recorded as a persistent decline. An explicit
+    // `--worker-dispatch` already answers this directly (#3062) — skip the
+    // question the same way as every other supplied field.
+    let workerDispatchChoice = supplied.workerDispatchChoice;
+    if (!workerDispatchChoice && plan.workerDispatchOffer.shouldOffer && process.env.CI !== 'true' && !supplied.dryRun) {
+        console.log('');
+        const outcome = await askConsent(rl, workerDispatchOfferQuestion(plan.workerDispatchOffer.detected), undefined, signal);
+        if (outcome.kind === 'answered')
+            workerDispatchChoice = outcome.value ? 'enable' : 'decline';
+    }
     return {
         projectDir: plan.projectDir,
-        providers: parseProviders(providersRaw, current.providers),
+        providers,
         primary,
         issueProvider,
         issueTracker,
@@ -392,6 +457,7 @@ async function applyInteractivePrompts(plan, rl, signal) {
         autoCloseIssues,
         forcePushPolicy,
         requireSignedCommits,
+        ...(workerDispatchChoice ? { workerDispatchChoice } : {}),
     };
 }
 function printPlan(plan) {
@@ -420,12 +486,32 @@ export const setupHandler = {
         }
         const args = subcommand === 'project' ? ctx.args.slice(1) : ctx.args;
         const options = parseSetupProjectOptions({ ...ctx, args });
+        // #3062 review item 12: the one shared interactive decision (TTY, TERM,
+        // CI, DEBIAN_FRONTEND) — this used to check only `process.stdin.isTTY &&
+        // process.stdout.isTTY`, so a CI job with a pseudo-terminal could still
+        // reach these prompts.
+        const canPrompt = isInteractive(options.nonInteractive);
+        // #3062 second review, finding 6: refuse before any child process runs
+        // — `buildSetupProjectPlan()` below makes four `git` calls on its own,
+        // and this exact refusal used to happen only after building (and
+        // printing) the full plan. A write that can never be confirmed (no
+        // `--yes`, no terminal, not a dry run) is known from `options` alone.
+        if (!options.dryRun && !options.yes && !canPrompt) {
+            throw new AiwgError({
+                code: 'ERR_NON_INTERACTIVE_CONFIRMATION_REQUIRED',
+                message: 'Refusing to write project setup in a non-interactive context without --yes.',
+                hint: 'Re-run with `aiwg setup project --yes` or use `--dry-run` to preview only.',
+                exitCode: EXIT_CODES.USAGE,
+            });
+        }
         let plan = await buildSetupProjectPlan(options);
-        const canPrompt = !options.nonInteractive && process.stdin.isTTY && process.stdout.isTTY;
         if (!options.yes && canPrompt) {
             const rl = createPromptInterface();
             try {
-                const prompted = await applyInteractivePrompts(plan, rl, ctx.signal);
+                // #3062 review item 10: every field already supplied by flag is
+                // passed straight through so it is never re-asked — only genuinely
+                // missing ones prompt.
+                const prompted = await applyInteractivePrompts(plan, rl, ctx.signal, options);
                 plan = await buildSetupProjectPlan({ ...options, ...prompted });
             }
             finally {
@@ -445,6 +531,19 @@ export const setupHandler = {
                 exitCode: EXIT_CODES.CONFIG,
             });
         }
+        // #3050: non-interactive/--yes/CI/dry-run runs never prompt — the
+        // question above already applied a choice when it was asked (which
+        // clears `shouldOffer` on the rebuilt plan), so `shouldOffer` is only
+        // ever still true here when nothing asked. In `--json` mode the offer
+        // is structured data on the JSON object, never a separate
+        // human-readable line — a stray print after the JSON would make
+        // `setup project --json` unparseable (review item 6).
+        // #3062: an explicit `--worker-dispatch` argument clears `shouldOffer`
+        // the same way an answered prompt does, so `applied_choice` (alongside
+        // the top-level `dry_run` flag) is how `--json --dry-run` reports what
+        // the argument would have written — `previewBlocks()` deliberately
+        // excludes `parallelism`/`setup` (an unrelated, pre-existing contract),
+        // so this field carries that information instead of widening it.
         if (options.json) {
             console.log(JSON.stringify({
                 project_dir: plan.projectDir,
@@ -453,21 +552,22 @@ export const setupHandler = {
                 issue_provider: plan.issueProvider,
                 warnings: plan.warnings,
                 config: previewBlocks(plan.next),
+                worker_dispatch_offer: plan.workerDispatchOffer.shouldOffer
+                    ? { should_offer: true, detected: plan.workerDispatchOffer.detected,
+                        hint: workerDispatchOfferHintWithArg(plan.workerDispatchOffer.detected) }
+                    : { should_offer: false, ...(options.workerDispatchChoice ? { applied_choice: options.workerDispatchChoice } : {}) },
             }, null, 2));
         }
         else {
             printPlan(plan);
+            if (plan.workerDispatchOffer.shouldOffer) {
+                ui.info(workerDispatchOfferHintWithArg(plan.workerDispatchOffer.detected));
+            }
         }
         if (options.dryRun)
             return { exitCode: 0 };
-        if (!options.yes && !canPrompt) {
-            throw new AiwgError({
-                code: 'ERR_NON_INTERACTIVE_CONFIRMATION_REQUIRED',
-                message: 'Refusing to write project setup in a non-interactive context without --yes.',
-                hint: 'Re-run with `aiwg setup project --yes` or use `--dry-run` to preview only.',
-                exitCode: EXIT_CODES.USAGE,
-            });
-        }
+        // The `!options.yes && !canPrompt` refusal above (review finding 6)
+        // already covers this exact condition before any git call ran.
         if (!options.yes && canPrompt) {
             const rl = createPromptInterface();
             try {

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

@@ -699,7 +699,9 @@ export const removeHandler = {
         // adapter validates receipt hashes and preserves operator modifications.
         const nativeRemovalProvider = parseRemoveProvider(ctx.args);
         if (firstRemovePositional(ctx.args) === 'omp' && nativeRemovalProvider.provider === 'omp') {
-            const { uninstall } = await import('../../../tools/agents/providers/omp.mjs');
+            // Loaded from the package root, not by a path relative to this file: the
+            // compiled handler sits one directory deeper than its source.
+            const { uninstall } = (await import(pathToFileURL(path.join(await getFrameworkRoot(), 'tools/agents/providers/omp.mjs')).href));
             const { getProjectDir } = await import('../../config/aiwg-config.js');
             const dryRun = ctx.args.includes('--dry-run');
             const scope = ctx.args.includes('--user') || isScopeUser(ctx.args) ? 'user' : 'project';

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

@@ -16,15 +16,25 @@ import { join, basename, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
 import { normalizeProviderDefinitionId } from '../../providers/provider-definitions.js';
+import { isSessionProviderResolution, resolveActiveProvider } from '../provider-resolution.js';
 // ── Provider Detection ───────────────────────────────────────
-function detectProvider(args) {
+async function detectProvider(args, cwd) {
     const providerFlag = parseFlag(args, '--provider');
     if (providerFlag)
         return normalizeProviderDefinitionId(providerFlag) ?? providerFlag;
-    // Claude Code sets CLAUDE_CODE_VERSION; API key presence is secondary heuristic
-    const isClaudeCode = process.env.CLAUDE_CODE_VERSION !== undefined ||
-        process.env.ANTHROPIC_API_KEY !== undefined;
-    return isClaudeCode ? 'claude' : 'unknown';
+    // Resolved through the same shared provider-resolution path `runtime-info`
+    // and `steward capabilities` use (`resolveActiveProvider` -> the `claude`
+    // provider's `detection.env` markers in provider-definitions.ts) so none
+    // of them disagree about which provider the current session is running
+    // under (#2623, #2627, #3054). The ad-hoc `CLAUDE_CODE_VERSION`/
+    // `ANTHROPIC_API_KEY` check this replaced was stale (neither is set by
+    // current Claude Code) and `ANTHROPIC_API_KEY` was a false positive for
+    // any non-Claude session with that key set.
+    // Only a session signal counts. Native team dispatch needs the command to
+    // be running inside that harness; project configuration alone does not
+    // establish that.
+    const resolution = await resolveActiveProvider({ cwd });
+    return isSessionProviderResolution(resolution) ? (resolution.provider ?? 'unknown') : 'unknown';
 }
 function isNativeTeamsProvider(provider) {
     // Only Claude Code has native agent team support
@@ -154,7 +164,7 @@ async function teamRunOmp(ctx) {
     }
 }
 async function teamRun(ctx) {
-    if (['omp', 'oh-my-pi'].includes(detectProvider(ctx.args)))
+    if (['omp', 'oh-my-pi'].includes(await detectProvider(ctx.args, ctx.cwd)))
         return teamRunOmp(ctx);
     const positional = getPositionalArgs(ctx.args);
     const slug = positional[0];
@@ -162,7 +172,7 @@ async function teamRun(ctx) {
         ui.error('Usage: aiwg team run <name> [--provider <p>] [--objective "<text>"]');
         return { exitCode: 1 };
     }
-    const provider = detectProvider(ctx.args);
+    const provider = await detectProvider(ctx.args, ctx.cwd);
     const objective = parseFlag(ctx.args, '--objective') || `Execute ${slug} team workflow`;
     const team = await loadTeam(slug, ctx.frameworkRoot, ctx.cwd);
     if (!team) {
@@ -221,7 +231,7 @@ async function teamRun(ctx) {
 // ── Subcommand: list ─────────────────────────────────────────
 async function teamList(ctx) {
     const json = hasFlag(ctx.args, '--json');
-    const provider = detectProvider(ctx.args);
+    const provider = await detectProvider(ctx.args, ctx.cwd);
     const teams = await listAllTeams(ctx.frameworkRoot, ctx.cwd);
     if (json) {
         console.log(JSON.stringify(teams.map(t => ({

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

@@ -145,6 +145,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++) {
@@ -1291,6 +1296,7 @@ async function deployOneProjectLocalBundle(opts) {
             '--deploy-version', projectLocalDeployVersion(bundle),
             ...modelArgs,
         ];
+        args.push(...collectUseScopeDeployArgs(ctx.args));
         if (dryRun)
             args.push('--dry-run');
         if (verbose)
@@ -2031,6 +2037,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)
@@ -2975,6 +2982,8 @@ export class UseHandler {
             }
             const runner = createScriptRunner(frameworkRoot);
             const addonBaseArgs = ['--deploy-commands', '--deploy-skills', '--deploy-rules'];
+            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
@@ -3253,6 +3262,8 @@ export class UseHandler {
                     + ` (active: ${process.env.AIWG_USER_REGISTRY_PATH})`);
             }
         }
+        if (scope === 'user' && !deployArgs.includes('--scope'))
+            deployArgs.push('--scope', 'user');
         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');
         const deployFilteredArgs = removeFlagWithOptionalValue(filteredArgs, '--harness-agents');
         // Pass --quiet to suppress deploy-agents.mjs header/footer in default mode (#460)
@@ -3430,6 +3441,8 @@ export class UseHandler {
         }
         // Build common args for addon deployments (inherit provider and target)
         const addonBaseArgs = ['--deploy-commands', '--deploy-skills', '--deploy-rules'];
+        if (scope === 'user')
+            addonBaseArgs.push('--scope', 'user');
         if (bulkKernelOnly)
             addonBaseArgs.push('--kernel-only');
         addonBaseArgs.push(...modelDeployArgs);

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,9 @@ Options:
   --bundle <name>       Limit deployment verification to one bundle
   --scope <scope>       Verification scope: project or user
   --user                Alias for --scope user
+  --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)
   --verbose, -v         Include verbose diagnostics
   --help, -h            Show this help
 `;
@@ -477,28 +535,55 @@ 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'];
+        const knownFlags = new Set([
+            ...valueFlags, '--all-providers', '--probe-workers', '--no-budget-check', '--strict-context', '--json',
+            '--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('--json') && !hasSwitch('--probe-workers') && !hasSwitch('--deployment')) {
+                throw new Error('--json requires --probe-workers or --deployment');
+            }
+        }
+        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);
             return {
                 exitCode: result.exitCode,
-                message: ctx.args.includes('--json')
+                message: hasSwitch('--json')
                     ? JSON.stringify(result, null, 2)
                     : renderUseDeploymentResult(result),
-                rawOutput: ctx.args.includes('--json'),
+                rawOutput: hasSwitch('--json'),
             };
         }
         // #1156 Phase 1 — `aiwg doctor --scope user` / `aiwg doctor --user`
@@ -506,15 +591,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 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('--json') || result.exitCode === 2)
+            return result;
         let agentSkillsFailure = false;
         try {
             const { inspectGrokBuildNative } = await import('../../mcp/grok-build-config.mjs');
@@ -562,14 +652,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',