@aiwg/cli 2026.10.1 → 2026.10.4

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) {
@@ -410,6 +476,45 @@ export const setupHandler = {
     description: 'CLI helper for agent-led repository policy and tracker setup',
     category: 'project',
     aliases: [],
+    async help() {
+        return {
+            exitCode: 0,
+            rawOutput: true,
+            message: `Usage: aiwg setup project [options]
+
+Options:
+  --target <dir>                  Project directory
+  --yes                           Confirm writes without prompting
+  --dry-run                       Preview the setup plan
+  --non-interactive               Disable prompts
+  --json                          Emit the plan as JSON
+  --primary <remote>              Primary repository remote
+  --issue-tracker <remote>        Internal issue tracker remote
+  --customer-issue-tracker <remote>  Customer issue tracker remote
+  --ci <remote>                   CI remote
+  --issue-provider <provider>     Internal tracker provider
+  --customer-issue-provider <provider>  Customer tracker provider
+  --delivery-mode <mode>          Delivery policy
+  --default-branch <branch>        Default branch
+  --require-ci-green <boolean>    Require passing CI
+  --auto-close-issues <boolean>   Close delivered issues
+  --issue-comment-on-cycle <boolean>  Report issue cycles
+  --force-push-policy <policy>    Force-push policy
+  --require-signed-commits <boolean>  Require signed commits
+  --committer-name <name>         Committer identity
+  --committer-email <email>       Committer email
+  --signing-format <format>       Signing format
+  --signing-key <key>             Signing key
+  --signing-enforce <commits|tags|all>  Signing enforcement
+  --tracker-actor-login <login>   Internal tracker actor
+  --tracker-actor-via <via>       Internal tracker access method
+  --customer-tracker-actor-login <login>  Customer tracker actor
+  --customer-tracker-actor-via <via>  Customer tracker access method
+  --worker-dispatch <choice>      Worker dispatch policy
+  --providers <ids>               Comma-separated provider IDs
+`,
+        };
+    },
     async execute(ctx) {
         const [subcommand] = ctx.args;
         if (subcommand && subcommand !== 'project' && !subcommand.startsWith('--')) {
@@ -420,12 +525,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 +570,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 +591,24 @@ 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 (options.workerDispatchChoice === 'enable')
+                ui.info('Next: aiwg doctor --probe-workers --qualify.');
+            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/steward.js

@@ -204,6 +204,7 @@ async function handleSteward(args, ctx) {
   aiwg steward — Provider capability awareness and command routing
 
   Usage:
+    aiwg steward decision-offload [--json]         Offline advisory readiness and adoption report
     aiwg steward capabilities --provider <name>   Capabilities for a specific provider
     aiwg steward capabilities --feature <name>    Provider support matrix for a feature
     aiwg steward capabilities --all               Full matrix (all providers x features)
@@ -231,6 +232,16 @@ async function handleSteward(args, ctx) {
 `);
         return;
     }
+    if (subcommand === 'decision-offload') {
+        const unknown = args.slice(1).filter(arg => arg !== '--json');
+        if (unknown.length)
+            throw new AiwgError({ code: 'ERR_USAGE_UNKNOWN_ARGUMENT',
+                message: `Unknown decision-offload argument: ${unknown[0]}`, exitCode: EXIT_CODES.USAGE });
+        const { buildDecisionOffloadSnapshot } = await import('../../decision/offload.js');
+        const decisionOffload = await buildDecisionOffloadSnapshot({ projectRoot: ctx?.cwd ?? process.cwd(), frameworkRoot: ctx?.frameworkRoot });
+        console.log(JSON.stringify(args.includes('--json') ? { decisionOffload } : decisionOffload, null, 2));
+        return;
+    }
     if (subcommand === 'permissions') {
         const operation = args[1];
         // `<namespace> --help` must reach the same usage block bare invocation prints (#2533).

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

@@ -21,6 +21,8 @@ import { sessionHandler } from "./session.js";
 import { feedbackHandler } from "./feedback.js";
 import { handlerResultFromError } from "../errors.js";
 import { getProjectDir } from "../../config/aiwg-config.js";
+import { deployedSkillRoots } from "../../providers/deployed-skill-roots.js";
+import { releaseSkillOwnership } from "../../providers/skill-ownership.mjs";
 import { formatDeployedWorkspaceSignalPlan, readWorkspaceSignalPlan } from "../workspace-signals.js";
 import * as path from "node:path";
 import * as fsSync from "node:fs";
@@ -32,6 +34,9 @@ export const quickrefHandler = {
     description: 'Generate and deploy an always-visible project quickref',
     category: 'project',
     aliases: [],
+    async help() {
+        return { exitCode: 0, message: 'Usage: aiwg quickref generate|deploy --project [--provider <id>] [--dry-run]', rawOutput: true };
+    },
     async execute(ctx) {
         const action = ctx.args.find(arg => !arg.startsWith('-')) ?? 'generate';
         if (!ctx.args.includes('--project')) {
@@ -147,6 +152,11 @@ export const mcpHandler = {
     description: "AIWG MCP server commands (serve, install, add, remove, update, list, inject, info)",
     category: "mcp",
     aliases: ["mcp", "aiwg-mcp"],
+    async help() {
+        const { main } = await import("../../mcp/cli.mjs");
+        await main(["--help"]);
+        return { exitCode: 0 };
+    },
     async execute(ctx) {
         try {
             // Dynamic import to avoid loading MCP dependencies unless needed
@@ -647,7 +657,15 @@ async function removeUserScopeDeploy(args) {
                     continue;
                 }
                 try {
-                    await fs.rm(target, { recursive: true, force: true });
+                    if (type === 'skills') {
+                        const { resolveFrameworkDir } = await import('./use.js');
+                        const released = releaseSkillOwnership(target, { frameworkSlug: resolveFrameworkDir(positional) ?? positional });
+                        if (released === null)
+                            continue;
+                    }
+                    else {
+                        await fs.rm(target, { recursive: true, force: true });
+                    }
                     deletedHere++;
                     totalDeleted++;
                 }
@@ -699,7 +717,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';
@@ -768,6 +788,33 @@ export const removeHandler = {
                 const projectDir = getProjectDir({ cwd: ctx.cwd }, ctx.args);
                 const config = await readAiwgConfig(projectDir);
                 const entry = config?.installed?.[positionalArg];
+                if (config && entry && entry.source !== 'project-local') {
+                    const fs = await import('node:fs/promises');
+                    const { resolveFrameworkDir } = await import('./use.js');
+                    const frameworkSlug = resolveFrameworkDir(positionalArg) ?? positionalArg;
+                    const dryRun = ctx.args.includes('--dry-run');
+                    const providers = Object.keys(entry.deployedTo).filter(p => !providerParse.provider || p === providerParse.provider);
+                    if (providerParse.provider && providers.length === 0) {
+                        return { exitCode: 1, message: `Error: '${positionalArg}' is not deployed for provider '${providerParse.provider}'.` };
+                    }
+                    let released = 0;
+                    for (const provider of providers) {
+                        for (const root of deployedSkillRoots(projectDir, provider)) {
+                            for (const name of await fs.readdir(root).catch(() => [])) {
+                                if (releaseSkillOwnership(path.join(root, name), { frameworkSlug }, { dryRun }) !== null)
+                                    released++;
+                            }
+                        }
+                        if (!dryRun && !ctx.args.includes('--keep-registry'))
+                            delete entry.deployedTo[provider];
+                    }
+                    if (!dryRun && !ctx.args.includes('--keep-registry')) {
+                        if (Object.keys(entry.deployedTo).length === 0)
+                            delete config.installed[positionalArg];
+                        await writeAiwgConfig(projectDir, config);
+                    }
+                    return { exitCode: 0, message: `${dryRun ? 'Would release' : 'Released'} ${released} skill ownership receipt(s); operator files preserved.` };
+                }
                 if (config && entry?.source === 'project-local') {
                     const force = ctx.args.includes('--force');
                     const dryRun = ctx.args.includes('--dry-run');
@@ -1300,12 +1347,17 @@ export const indexHandler = {
     description: "Artifact index commands (build, query, deps, stats)",
     category: "index",
     aliases: [],
+    async help() {
+        const { printIndexUsage } = await import("../../artifacts/cli.js");
+        printIndexUsage();
+        return { exitCode: 0 };
+    },
     async execute(ctx) {
         try {
             const { main } = await import("../../artifacts/cli.js");
             await main(ctx.args);
             return {
-                exitCode: 0,
+                exitCode: Number(process.exitCode ?? 0),
             };
         }
         catch (error) {
@@ -1324,6 +1376,11 @@ export const corpusHandler = {
     description: "Research-corpus tools (radar-init, radar-status, radar-report)",
     category: "index",
     aliases: [],
+    async help() {
+        const { corpusMain } = await import("../../artifacts/corpus-tools/cli.js");
+        await corpusMain(["--help"]);
+        return { exitCode: 0 };
+    },
     async execute(ctx) {
         try {
             const { corpusMain } = await import("../../artifacts/corpus-tools/cli.js");

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/uhp.js

@@ -76,6 +76,9 @@ export const uhpHandler = {
     description: 'Inspect and smoke-test an explicitly selected experimental UHP endpoint profile',
     category: 'toolsmith',
     aliases: [],
+    async help() {
+        return { exitCode: 0, message: usage(), rawOutput: true };
+    },
     async execute(ctx) {
         try {
             return await executeUhp(ctx);